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

Octorok

Overview

The Octorok sprite (!SPRID = $08) is a complex enemy implementation that supports both land-based and water-based variations. It features dynamic behavior, including transformation between forms, distinct movement patterns, and projectile attacks.

Sprite Properties

• !SPRID: $08 (Vanilla sprite ID for Octorok)
• !NbrTiles: 05
• !Harmless: 00
• !HVelocity: 00
• !Health: 00 (Health is likely set dynamically or is vanilla)
• !Damage: 00 (Damage is likely from projectiles)
• !DeathAnimation: 00
• !ImperviousAll: 00
• !SmallShadow: 00
• !Shadow: 00 (Shadow is drawn conditionally in _Long)
• !Palette: 00
• !Hitbox: 00
• !Persist: 00
• !Statis: 00
• !CollisionLayer: 00
• !CanFall: 00
• !DeflectArrow: 00
• !WaterSprite: 00
• !Blockable: 00
• !Prize: 00
• !Sound: 00
• !Interaction: 00
• !Statue: 00
• !DeflectProjectiles: 00
• !ImperviousArrow: 00
• !ImpervSwordHammer: 00
• !Boss: 00

Main Structure (Sprite_Octorok_Long)

This routine acts as a dispatcher, determining whether to execute Land Octorok or Water Octorok logic based on SprSubtype.

Sprite_Octorok_Long:
{
  PHB : PHK : PLB
  JSR Sprite_Octorok_Draw
  JSL Sprite_CheckActive : BCC .SpriteIsNotActive
    LDA.w SprSubtype, X : BEQ +
      JSL Sprite_DrawWaterRipple
      JSR Sprite_WaterOctorok_Main
      JMP ++
    +
    JSL Sprite_DrawShadow
    JSR Sprite_Octorok_Main
    ++
  .SpriteIsNotActive
  PLB
  RTL
}

Initialization (Sprite_Octorok_Prep)

This routine is currently empty, indicating that initial setup is minimal or handled by vanilla routines.

Land Octorok Main Logic (Sprite_Octorok_Main)

This routine handles the behavior of a land-based Octorok, including movement and potential transformation into a Water Octorok.

• Movement: Calls Sprite_Octorok_Move for general movement.
• Transformation: Checks the tile type the Octorok is on. If it's a water tile, the Octorok transforms into a Water Octorok by setting SprSubtype, X to 01.
• Directional States: Uses a jump table to manage animations for moving in different directions (Down, Up, Left, Right).

Sprite_Octorok_Main:
{
  JSR Sprite_Octorok_Move

  ; TILETYPE 08
  LDA.l $7FF9C2,X : CMP.b #$08 : BEQ .water_tile
    ; TILETYPE 09
    CMP.b #$09 : BNE .not_water_tile
  .water_tile
    LDA.b #$01 : STA.w SprSubtype, X
    STZ.w SprAction, X
    STZ.w SprMiscG, X
    RTS
  .not_water_tile

  LDA.w SprAction, X
  JSL JumpTableLocal

  dw Octorok_MoveDown
  dw Octorok_MoveUp
  dw Octorok_MoveLeft
  dw Octorok_MoveRight

  Octorok_MoveDown:
  {
    %PlayAnimation(0,1,10)
    RTS
  }

  Octorok_MoveUp:
  {
    %StartOnFrame(2)
    %PlayAnimation(2,3,10)
    RTS
  }

  Octorok_MoveLeft:
  {
    %StartOnFrame(4)
    %PlayAnimation(4,5,10)
    RTS
  }

  Octorok_MoveRight:
  {
    %StartOnFrame(6)
    %PlayAnimation(6,7,10)
    RTS
  }
}

Octorok Movement (Sprite_Octorok_Move)

This shared routine handles the Octorok's general movement, damage reactions, and tile collision.

• Damage & Collision: Handles damage flash (Sprite_DamageFlash_Long), movement (Sprite_Move), and checks for damage to/from Link.
• Directional Logic: Sets the sprite's action based on its direction (SprMiscC, X).
• Tile Collision: Detects tile collisions and changes the Octorok's direction accordingly.
• Barrage Logic: Contains logic related to a potential projectile barrage (octorok_used_barrage).

Sprite_Octorok_Move:
{
  JSL Sprite_DamageFlash_Long
  JSL Sprite_Move
  JSL Sprite_CheckDamageFromPlayer
  JSL Sprite_CheckDamageToPlayer

  ; Set the SprAction based on the direction
  LDA.w SprMiscC, X : AND.b #$03 : TAY
  LDA.w .direction, Y : STA.w SprAction, X

  LDA.w SprMiscF, X : AND.b #$01 : BNE .octorok_used_barrage
    LDA.w SprMiscC, X : AND.b #$02 : ASL A : STA.b $00
    INC.w SprDelay, X
    LDA.w SprDelay, X
    LSR A
    LSR A
    LSR A
    AND.b #$03
    ORA.b $00
    STA.w SprGfx, X

    LDA.w SprTimerA, X : BNE .wait
      INC.w SprMiscF,X

      LDY.w SprType,X
      LDA.w .timer-8,Y : STA.w SprTimerA,X

      RTS

  .wait
  LDY.w SprMiscC, X

  LDA.w .speed_x, Y : STA.w SprXSpeed, X
  LDA.w .speed_y, Y : STA.w SprYSpeed, X

  JSL Sprite_CheckTileCollision
  LDA.w $0E70, X : BEQ .no_collision
    LDA.w SprMiscC,X : EOR.b #$01 : STA.w SprMiscC,X
    BRA .exit
  .no_collision
  RTS

  .octorok_used_barrage
  STZ.w SprXSpeed, X : STZ.w SprYSpeed,X
  LDA.w SprTimerA, X : BNE Octorock_ShootEmUp
    INC.w SprMiscF, X
    LDA.w SprMiscC, X
    PHA
    JSL GetRandomInt : AND.b #$3F : ADC.b #$30 : STA.w SprTimerA, X
    AND.b #$03 : STA.w SprMiscC, X
    PLA
    CMP.w SprMiscC, X : BEQ .exit
      EOR.w SprMiscC, X : BNE .exit
        LDA.b #$08 : STA.w SprTimerB,X
  .exit
  RTS

  .direction
    db   3,   2,   0,   1

  .speed_x
    db  24, -24,   0,   0

  .speed_y
    db   0,   0,  24, -24

  .timer
    db  60, 128, 160, 128
}

Octorok Projectile Logic (Octorock_ShootEmUp)

This routine determines the Octorok's shooting behavior, allowing for both single-shot and four-way attacks.

Octorock_ShootEmUp:
{
  ; Use SprMiscD as a flag to shoot 4 ways for awhile before going back to single shot

  LDA.w SprMiscD, X : BEQ .continue
    LDA.w SprTimerD, X : BNE .four_ways
      LDA.b #$01 : STA.w SprMiscD, X
  .continue
  JSL GetRandomInt : AND.b #$1F : BNE .single_shot
  .four_ways
    LDA.b #$01 : STA.w SprMiscD, X
    LDA.b #$20 : STA.w SprTimerD, X
    JSR Octorok_Shoot4Ways
    RTS
  .single_shot
  JSR Octorok_ShootSingle
  RTS
}

Water Octorok Main Logic (Sprite_WaterOctorok_Main)

This routine governs the behavior of a water-based Octorok, including its attack patterns and states.

• Attack: Calls Sprite_WaterOctorok_Attack.
• Facing Directions: Uses a jump table to manage animations for facing different directions (Down, Up, Left, Right) and a hidden state.

Sprite_WaterOctorok_Main:
{
  JSR Sprite_WaterOctorok_Attack

  LDA.w SprAction, X
  JSL JumpTableLocal

  dw WaterOctorok_FaceDown
  dw WaterOctorok_FaceUp
  dw WaterOctorok_FaceLeft
  dw WaterOctorok_FaceRight
  dw WaterOctorok_FaceHidden

  WaterOctorok_FaceDown:
  {
    %PlayAnimation(0,1,10)
    RTS
  }

  WaterOctorok_FaceUp:
  {
    %StartOnFrame(2)
    %PlayAnimation(2,3,10)
    RTS
  }

  WaterOctorok_FaceLeft:
  {
    %StartOnFrame(4)
    %PlayAnimation(4,5,10)
    RTS
  }

  WaterOctorok_FaceRight:
  {
    %StartOnFrame(6)
    %PlayAnimation(6,7,10)
    RTS
  }

  WaterOctorok_FaceHidden:
  {
    %StartOnFrame(8)
    %PlayAnimation(8,8,10)
    RTS
  }
}

Water Octorok Attack Logic (Sprite_WaterOctorok_Attack)

This routine manages the Water Octorok's attack states, including hiding, emerging, attacking, and re-hiding.

• States: Uses SprMiscG, X as a state machine for WaterOctorok_Hidden, WaterOctorok_PoppingUp, WaterOctorok_Attacking, and WaterOctorok_Hiding.
• WaterOctorok_Hidden: Remains hidden until Link is within a certain distance, then transitions to WaterOctorok_PoppingUp.
• WaterOctorok_PoppingUp: Emerges from the water, faces Link, and then transitions to WaterOctorok_Attacking.
• WaterOctorok_Attacking: Shoots a single projectile (Octorok_ShootSingle) after a timer, then transitions to WaterOctorok_Hiding.
• WaterOctorok_Hiding: Hides back in the water and transitions to WaterOctorok_Hidden.

Sprite_WaterOctorok_Attack:
{
  JSL Sprite_DamageFlash_Long
  JSL Sprite_CheckDamageToPlayer

  LDA.w SprMiscG, X
  JSL JumpTableLocal

  dw WaterOctorok_Hidden
  dw WaterOctorok_PoppingUp
  dw WaterOctorok_Attacking
  dw WaterOctorok_Hiding

  WaterOctorok_Hidden:
  {
    LDA.w SprTimerA, X : BEQ +
      RTS
    +

    JSL GetDistance8bit_Long
    CMP.b #$40 : BCC .not_close_enough ; LD < 64
      INC.w SprMiscG, X
      %SetTimerA($10)
    .not_close_enough
    RTS
  }

   WaterOctorok_PoppingUp:
   {
     JSL Sprite_CheckDamageFromPlayer
     LDA.w SprTimerA, X : BNE +
       INC.w SprMiscG, X
       %SetTimerA($20)
       JSL Sprite_DirectionToFacePlayer
       ; LDA.w SprMiscC, X : AND.b #$03 : TAY
       ; LDA.w Sprite_Octorok_Move_direction, Y : STA.w SprAction, X
     +
     RTS
   }

   WaterOctorok_Attacking:
   {
     JSL Sprite_CheckDamageFromPlayer
     LDA.w SprTimerA, X : BNE +
       INC.w SprMiscG, X
       %SetTimerA($10)
       RTS
     +
     JSR Octorok_ShootSingle
     RTS
   }

   WaterOctorok_Hiding:
   {
     LDA.w SprTimerA, X : BNE +
       LDA.b #$04 : STA.w SprAction, X
       STZ.w SprMiscG, X
       %SetTimerA($40)
     +
     RTS
   }
}

Projectile Spawning (Octorok_ShootSingle, Octorok_Shoot4Ways, Octorok_SpawnRock)

These routines handle the spawning and animation of Octorok projectiles.

• Octorok_ShootSingle: Manages the animation and timing for shooting a single rock projectile.
• Octorok_Shoot4Ways: Manages the animation, timing, and direction changes for shooting rock projectiles in four cardinal directions.
• Octorok_SpawnRock: Spawns a rock projectile (sprite ID $0C) with specific initial offsets and speeds based on the Octorok's current direction.

Octorok_ShootSingle:
{
  LDA.w SprTimerA, X : CMP.b #$1C : BNE .bide_time
    PHA
    JSR Octorok_SpawnRock
    PLA
  .bide_time
  LSR #3
  TAY
  LDA.w .mouth_anim_step, Y : STA.w SprMiscB, X
  RTS

  .mouth_anim_step
    db $00, $02, $02, $02
    db $01, $01, $01, $00
    db $00, $00, $00, $00
    db $02, $02, $02, $02
    db $02, $01, $01, $00
}

Octorok_Shoot4Ways:
{
  LDA.w SprTimerA, X
  PHA
  CMP.b #$80 : BCS .animate
    AND.b #$0F : BNE .delay_turn
    PHA
    LDY.w SprMiscC, X
    LDA.w .next_direction, Y : STA.w SprMiscC, X
    PLA
    .delay_turn
    CMP.b #$08 : BNE .animate
      JSR Octorok_SpawnRock
  .animate
  PLA
  LSR #4
  TAY
  LDA.w .mouth_anim_step, Y : STA.w SprMiscB, X
  RTS

  .next_direction
    db $02, $03, $01, $00

  .mouth_anim_step
    db $02, $02, $02, $02
    db $02, $02, $02, $02
    db $01, $00
}

Octorok_SpawnRock:
{
  LDA.b #$07 : JSL SpriteSFX_QueueSFX2WithPan
  LDA.b #$0C : JSL Sprite_SpawnDynamically : BMI .fired_a_blank
    PHX

    LDA.w SprMiscC,X
    TAX

    LDA.b $00 : CLC : ADC.w .offset_x_low,X : STA.w SprX,Y
    LDA.b $01 : ADC.w .offset_x_high,X : STA.w SprXH,Y
    LDA.b $02 : CLC : ADC.w .offset_y_low,X : STA.w SprY,Y
    LDA.b $03 : ADC.w .offset_y_high,X : STA.w SprYH,Y

    LDA.w SprMiscC,Y
    TAX

    LDA.w .rock_speed_x,X : STA.w SprXSpeed,Y
    LDA.w .rock_speed_y,X : STA.w SprYSpeed,Y

    PLX
  .fired_a_blank
  RTS

  .offset_x_low
    db  12, -12,   0,   0

  .offset_x_high
    db   0,  -1,   0,   0

  .offset_y_low
    db   4,   4,  12, -12

  .offset_y_high
    db   0,   0,   0,  -1

  .rock_speed_x
    db  44, -44,   0,   0

  .rock_speed_y
    db   0,   0,  44, -44
}

Drawing (Sprite_Octorok_Draw)

The drawing routine handles OAM allocation, animation, and palette adjustments. It explicitly uses REP #$20 and SEP #$20 for 16-bit coordinate calculations.

Sprite_Octorok_Draw:
{
  JSL Sprite_PrepOamCoord
  JSL Sprite_OAM_AllocateDeferToPlayer

  LDA.w SprFrame, X : TAY ;Animation Frame
  LDA .start_index, Y : STA $06
  LDA.w SprFlash : STA $08

  PHX
  LDX .nbr_of_tiles, Y ;amount of tiles -1
  LDY.b #$00
  .nextTile

  PHX ; Save current Tile Index?
  TXA : CLC : ADC $06 ; Add Animation Index Offset

  PHA ; Keep the value with animation index offset?

  ASL A : TAX

  REP #$20

  LDA $00 : STA ($90), Y
  AND.w #$0100 : STA $0E
  INY
  LDA $02 : STA ($90), Y
  CLC : ADC #$0010 : CMP.w #$0100
  SEP #$20
  BCC .on_screen_y

  LDA.b #$F0 : STA ($90), Y ;Put the sprite out of the way
  STA $0E
  .on_screen_y

  PLX ; Pullback Animation Index Offset
  INY
  LDA .chr, X : STA ($90), Y
  INY
  LDA .properties, X : ORA $08 : STA ($90), Y

  PHY
  TYA : LSR #2 : TAY
  LDA.b #$02 : ORA $0F : STA ($92), Y ; store size in oam buffer
  PLY : INY
  PLX : DEX : BPL .nextTile

  PLX

  RTS


  ; =========================================================

  .start_index
  db $00, $01, $02, $03, $04, $05, $06, $07, $08
  .nbr_of_tiles
  db 0, 0, 0, 0, 0, 0, 0, 0, 0
  .chr
  db $80
  db $80
  db $82
  db $82
  db $A0
  db $A2
  db $A0
  db $A2
  db $AA ; Water Octorok
  .properties
  db $0D
  db $4D
  db $0D
  db $4D
  db $0D
  db $0D
  db $4D
  db $4D
  db $3D ; Water Octorok
}

Design Patterns

• Subtype-based Behavior: The Octorok utilizes SprSubtype to implement distinct behaviors for Land and Water Octoroks, including different main logic routines and conditional drawing (shadow vs. water ripple).
• Dynamic Transformation: A Land Octorok can dynamically transform into a Water Octorok if it moves onto a water tile, showcasing a unique environmental interaction.
• Complex State Machines: Both Land and Water Octoroks employ intricate state machines to manage their movement, attack patterns, and emerging/hiding behaviors, making them engaging enemies.
• Projectile Attacks: The Octorok can perform both single-shot and four-way projectile attacks, adding variety to its offensive capabilities.
• 16-bit OAM Calculations: Demonstrates explicit use of REP #$20 and SEP #$20 for precise 16-bit OAM coordinate calculations, crucial for accurate sprite rendering and positioning.