oracle-of-secrets/Docs/Sprites/Objects/MineSwitch.md

Mine Switch

Overview

The Mine Switch sprite (!SPRID = Sprite_Mineswitch) is an interactive puzzle element, typically found in the Goron Mines. It functions as a lever-style switch that Link can activate by attacking it, altering the state of minecart tracks or other game elements. This sprite supports both a regular on/off switch and a speed-controlling switch, with its behavior and appearance changing based on its current state.

Sprite Properties

• !SPRID: Sprite_Mineswitch (Custom symbol, likely a remapped vanilla ID)
• !NbrTiles: 02
• !Harmless: 01
• !HVelocity: 00
• !Health: 01
• !Damage: 00
• !DeathAnimation: 00
• !ImperviousAll: 00
• !SmallShadow: 00
• !Shadow: 00
• !Palette: 00
• !Hitbox: 00
• !Persist: 01 (Continues to live off-screen)
• !Statis: 00
• !CollisionLayer: 00
• !CanFall: 01
• !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_LeverSwitch_Long)

This routine handles the Mine Switch's drawing and dispatches to its main logic if the sprite is active.

Sprite_LeverSwitch_Long:
{
  PHB : PHK : PLB
  JSR Sprite_LeverSwitch_Draw
  JSL Sprite_CheckActive : BCC .SpriteIsNotActive
    JSR Sprite_LeverSwitch_Main
  .SpriteIsNotActive
  PLB
  RTL
}

Initialization (Sprite_LeverSwitch_Prep)

This routine initializes the Mine Switch upon spawning. It sets SprDefl, X to 0. It retrieves the switch's on/off state from SwitchRam, indexed by SprSubtype, X, and sets SprAction, X and SprFrame, X accordingly. It also sets SprTileDie, X to 0 and SprBulletproof, X to 0.

Sprite_LeverSwitch_Prep:
{
  PHB : PHK : PLB

  LDA.b #$00 : STA.w SprDefl, X

  ; Get the subtype of the switch so that we can get its on/off state.
  LDA.w SprSubtype, X : TAY

  LDA.w SwitchRam, Y : STA.w SprAction, X : STA.w SprFrame, X
  LDA.b #$00 : STA.w SprTileDie, X
  STZ.w SprBulletproof, X

  PLB
  RTL
}

Constants

• SwitchRam = $0230: A WRAM address that stores the state (on/off) of each individual switch, indexed by its SprSubtype.

Main Logic & State Machine (Sprite_LeverSwitch_Main)

This routine manages the Mine Switch's behavior through a jump table, supporting different types of switches:

• Player Collision: Prevents Link from passing through the switch (JSL Sprite_PlayerCantPassThrough).
• SwitchOff: Plays an animation. If Link attacks it (JSL Sprite_CheckDamageFromPlayer) and a timer (SprTimerA, X) allows, it plays a sound ($25), turns the switch on (STA.w SwitchRam, Y to 01), sets a timer, and transitions to SwitchOn.
• SwitchOn: Plays an animation. If Link attacks it and a timer allows, it plays a sound ($25), turns the switch off (STA.w SwitchRam, Y to 00), sets a timer, and transitions to SwitchOff.
• SpeedSwitchOff: Plays an animation. If Link attacks it, it plays a sound ($25), sets $36 to 01 (likely a global speed flag for minecarts), and transitions to SpeedSwitchOn.
• SpeedSwitchOn: Plays an animation. If Link attacks it, it plays a sound ($25), clears $36, and transitions to SpeedSwitchOff.

Sprite_LeverSwitch_Main:
{
  JSL Sprite_PlayerCantPassThrough

  LDA.w SprAction, X
  JSL UseImplicitRegIndexedLocalJumpTable

  dw SwitchOff
  dw SwitchOn
  dw SpeedSwitchOff
  dw SpeedSwitchOn

  SwitchOff:
  {
    %PlayAnimation(0,0,4)
    LDA.w SprTimerA, X : BNE .NoDamage
      JSL Sprite_CheckDamageFromPlayer : BCC .NoDamage
        LDA #$25 : STA $012F

        ; Get the subtype of the switch so that we can get its on/off state.
        LDA.w SprSubtype, X : TAY

        ; Turn the switch on.
        LDA #$01 : STA.w SwitchRam, Y
        LDA #$10 : STA.w SprTimerA, X
        %GotoAction(1)
    .NoDamage
    RTS
  }

  SwitchOn:
  {
    %PlayAnimation(1,1,4)
    LDA.w SprTimerA, X : BNE .NoDamage
      JSL Sprite_CheckDamageFromPlayer : BCC .NoDamage
        LDA #$25 : STA $012F

        ; Get the subtype of the switch so that we can get its on/off state.
        LDA.w SprSubtype, X : TAY
        
        ; Turn the switch off.
        LDA #$00 : STA.w SwitchRam, Y
        LDA #$10 : STA.w SprTimerA, X
        %GotoAction(0)
    .NoDamage
    RTS
  }

  SpeedSwitchOff:
  {
    %PlayAnimation(0,0,4)
    JSL Sprite_CheckDamageFromPlayer : BCC .NoDamage
      LDA.b #$25 : STA $012F
      LDA.b #$01 : STA $36
      %GotoAction(3)
    .NoDamage
    RTS
  }

  SpeedSwitchOn:
  {
    %PlayAnimation(1,1,4)
    JSL Sprite_CheckDamageFromPlayer : BCC .NoDamage
      LDA #$25 : STA $012F
      STZ.w $36
      %GotoAction(2)
    .NoDamage
    RTS
  }
}

Drawing (Sprite_LeverSwitch_Draw)

This routine handles OAM allocation and animation for the Mine Switch. It explicitly uses REP #$20 and SEP #$20 for 16-bit coordinate calculations, ensuring accurate sprite rendering.

Design Patterns

• Interactive Puzzle Element: The Mine Switch is a key interactive puzzle element that Link can activate by attacking it, triggering changes in the game environment.
• State-Based Behavior: The switch has distinct "on" and "off" states, with different animations and effects, providing clear visual feedback to the player.
• Subtype-Driven State: The SprSubtype is used to index into SwitchRam, allowing each individual switch to maintain its own independent state, enabling complex puzzle designs with multiple switches.
• Speed Control: The "Speed Switch" variant directly controls a global speed flag ($36), likely affecting the speed of minecarts or other moving objects, adding another layer of interaction to the minecart system.
• 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.