oracle-of-secrets/Docs/Sprites/Enemies/PolsVoice.md

# Pols Voice Sprite Analysis

This document provides a detailed analysis of the `pols_voice.asm` sprite, outlining its properties, core routines, and behavioral patterns.

## 1. Sprite Properties

The following `!SPRID` constants define Pols Voice's fundamental characteristics:

```asm
!SPRID              = Sprite_PolsVoice
!NbrTiles           = 02  ; Number of tiles used in a frame
!Harmless           = 00  ; 00 = Sprite is Harmful,  01 = Sprite is Harmless
!HVelocity          = 00  ; Is your sprite going super fast? put 01 if it is
!Health             = 10  ; Number of Health the sprite have
!Damage             = 00  ; (08 is a whole heart), 04 is half heart
!DeathAnimation     = 00  ; 00 = normal death, 01 = no death animation
!ImperviousAll      = 00  ; 00 = Can be attack, 01 = attack will clink on it
!SmallShadow        = 00  ; 01 = small shadow, 00 = no shadow
!Shadow             = 00  ; 00 = don't draw shadow, 01 = draw a shadow
!Palette            = 00  ; Unused in this template (can be 0 to 7)
!Hitbox             = 00  ; 00 to 31, can be viewed in sprite draw tool
!Persist            = 00  ; 01 = your sprite continue to live offscreen
!Statis             = 00  ; 00 = is sprite is alive?, (kill all enemies room)
!CollisionLayer     = 00  ; 01 = will check both layer for collision
!CanFall            = 00  ; 01 sprite can fall in hole, 01 = can't fall
!DeflectArrow       = 00  ; 01 = deflect arrows
!WaterSprite        = 00  ; 01 = can only walk shallow water
!Blockable          = 00  ; 01 = can be blocked by link's shield?
!Prize              = 00  ; 00-15 = the prize pack the sprite will drop from
!Sound              = 00  ; 01 = Play different sound when taking damage
!Interaction        = 00  ; ?? No documentation
!Statue             = 00  ; 01 = Sprite is statue
!DeflectProjectiles = 00  ; 01 = Sprite will deflect ALL projectiles
!ImperviousArrow    = 00  ; 01 = Impervious to arrows
!ImpervSwordHammer  = 00  ; 01 = Impervious to sword and hammer attacks
!Boss               = 00  ; 00 = normal sprite, 01 = sprite is a boss
```
**Note:** `!Health` is set to `10` and is not dynamically determined by Link's sword level.

## 2. Core Routines

### 2.1. `Sprite_PolsVoice_Long` (Main Loop)

This is the primary entry point for Pols Voice's per-frame execution. It handles drawing, shadow rendering, and then dispatches to the main logic routine if the sprite is active.

```asm
Sprite_PolsVoice_Long:
{
  PHB : PHK : PLB
  JSR Sprite_PolsVoice_Draw
  JSL Sprite_DrawShadow
  JSL Sprite_CheckActive : BCC .SpriteIsNotActive
    JSR Sprite_PolsVoice_Main
  .SpriteIsNotActive
  PLB
  RTL
}
```

### 2.2. `Sprite_PolsVoice_Prep` (Initialization)

This routine is executed once when Pols Voice is first spawned. It initializes `SprTimerA` to `$80` and clears `SprDefl` and `SprTileDie`.

```asm
Sprite_PolsVoice_Prep:
{
  PHB : PHK : PLB
  LDA.b #$80 : STA.w SprTimerA, X
  STZ.w SprDefl, X
  STZ.w SprTileDie, X
  PLB
  RTL
}
```

### 2.3. `Sprite_PolsVoice_Main` (Behavioral State Machine)

This routine manages Pols Voice's AI through a state machine, using `SprAction, X` to determine its current behavior. It includes states for moving around and hopping around, with a unique interaction based on the flute song.

```asm
Sprite_PolsVoice_Main:
{
  JSR PolsVoice_CheckForFluteSong ; Check for flute song interaction

  %SpriteJumpTable(PolsVoice_MoveAround,
                   PolsVoice_HopAround)

  PolsVoice_MoveAround:
  {
    %StartOnFrame(0)
    %PlayAnimation(0,3,10)

    ;$09 = speed, $08 = max height
    LDA #$05 : STA $09
    LDA #$02 : STA $08
    JSL Sprite_BounceTowardPlayer
    JSL Sprite_BounceFromTileCollision
    JSL Sprite_DamageFlash_Long

    %DoDamageToPlayerSameLayerOnContact()

    JSL GetRandomInt : AND #$3F : BNE .not_done ; Random chance to change state
      LDA #$04 : STA.w SprTimerA, X
      %GotoAction(1) ; Transition to PolsVoice_HopAround
    .not_done

    JSL Sprite_CheckDamageFromPlayer : BCC .no_damage ; Check if Link damages Pols Voice
      JSL Sprite_DirectionToFacePlayer

      ; Apply the speed positive or negative speed
      LDA $0E : BPL .not_up
        LDA #$20 : STA.w SprYSpeed, X
        BRA .not_down
      .not_up
      LDA #$E0 : STA.w SprYSpeed, X
      .not_down
      LDA $0F : BPL .not_right
        LDA #$20 : STA.w SprXSpeed, X
        BRA .not_left
      .not_right
      LDA #$E0 : STA.w SprXSpeed, X
      .not_left
      LDA #$04 : STA.w SprTimerA, X
      %GotoAction(1) ; Transition to PolsVoice_HopAround
    .no_damage
    RTS
  }

  PolsVoice_HopAround:
  {
    %StartOnFrame(4)
    %PlayAnimation(4,4,10)

    JSL Sprite_MoveXyz
    JSL Sprite_BounceFromTileCollision
    JSL Sprite_DamageFlash_Long

    %DoDamageToPlayerSameLayerOnContact()

    LDA.w SprTimerA, X : BNE .not_done ; If timer A is not 0
      %GotoAction(0) ; Transition back to PolsVoice_MoveAround
    .not_done
    JSL Sprite_CheckDamageFromPlayer : BCC .no_damage ; Check if Link damages Pols Voice
      JSL Sprite_InvertSpeed_XY ; Invert speed
    .no_damage
    RTS
  }
}
```

### 2.4. `PolsVoice_CheckForFluteSong`

This routine checks if the player is currently playing the flute (`SongFlag`). If the flute is being played, Pols Voice despawns (`STZ.w SprState, X`) and forces a prize drop.

```asm
PolsVoice_CheckForFluteSong:
{
  ; If the player plays the flute
  LDA.b SongFlag : BEQ + ; Check SongFlag
    LDA.b #$03 : STA.w SprState, X ; Set sprite state to despawn
    JSL ForcePrizeDrop_long ; Force prize drop
  +
  RTS
}
```

### 2.5. `Sprite_PolsVoice_Draw` (Drawing Routine)

This routine is responsible for rendering Pols Voice's graphics. It uses the `%DrawSprite()` macro, which reads from a set of data tables to handle its appearance and animation.

```asm
Sprite_PolsVoice_Draw:
{
  %DrawSprite()

  .start_index
    db $00, $01, $02, $03, $04
  .nbr_of_tiles
    db 0, 0, 0, 0, 1
  .x_offsets
    dw 0
    dw 0
    dw 0
    dw 0
    dw 0, 0
  .y_offsets
    dw 0
    dw 0
    dw 0
    dw 0
    dw -4, -20
  .chr
    db $6C
    db $6A
    db $6C
    db $6A
    db $6E, $4E
  .properties
    db $3B
    db $3B
    db $3B
    db $7B
    db $3B, $3B
  .sizes
    db $02
    db $02
    db $02
    db $02
    db $02, $02
}
```

## 3. Key Behaviors and Implementation Details

*   **Fixed Health:** Unlike many other sprites, Pols Voice has a fixed health of `10` and its health is not dynamically scaled based on Link's sword level.
*   **State Management:** Pols Voice uses `SprAction, X` and `%SpriteJumpTable` to manage its `PolsVoice_MoveAround` and `PolsVoice_HopAround` states. Transitions between these states are triggered by timers or random chance.
*   **Movement Patterns:** Pols Voice moves by bouncing towards the player (`Sprite_BounceTowardPlayer`) and also has a hopping movement (`PolsVoice_HopAround`). It reacts to tile collisions by bouncing (`Sprite_BounceFromTileCollision`).
*   **Flute Song Interaction:** A unique and defining characteristic of Pols Voice is its vulnerability to the flute song. When Link plays the flute (`SongFlag` is set), Pols Voice immediately despawns and drops a prize (`ForcePrizeDrop_long`). This is a classic Zelda enemy mechanic.
*   **Damage Reaction:** When damaged by Link, Pols Voice inverts its speed (`Sprite_InvertSpeed_XY`) and transitions to the `PolsVoice_HopAround` state, providing a temporary reprieve or change in behavior.
*   **Custom OAM Drawing:** Pols Voice uses the `%DrawSprite()` macro with OAM data tables to render its appearance and animations.
*   **`SprTimerA` Usage:** This timer controls the duration of the `PolsVoice_HopAround` state before transitioning back to `PolsVoice_MoveAround`.