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

Collectible Sprites (Pineapple, Seashell, Sword/Shield, Rock Sirloin)

Overview

The Collectible sprite (!SPRID = $52) is a versatile implementation designed to represent various collectible items within the game, including Pineapples, Seashells, the starting Sword/Shield, and Rock Sirloin. Its specific appearance and behavior are dynamically determined by the SprAction, X state and the current AreaIndex, allowing for context-sensitive item placement and interaction.

Sprite Properties

• !SPRID: $52 (Vanilla sprite ID, likely for a generic collectible)
• !NbrTiles: 03
• !Harmless: 01
• !HVelocity: 00
• !Health: 00
• !Damage: 00
• !DeathAnimation: 00
• !ImperviousAll: 00
• !SmallShadow: 00
• !Shadow: 00
• !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_Collectible_Long)

This routine acts as a dispatcher for drawing, selecting the appropriate drawing routine based on the AreaIndex:

• If AreaIndex is $58 (Intro Sword area), it calls Sprite_SwordShield_Draw.
• If AreaIndex is $4B (Lupo Mountain area), it calls Sprite_RockSirloin_Draw.
• Otherwise, it calls Sprite_Pineapple_Draw.
• It also handles shadow drawing and dispatches to the main logic if the sprite is active.

Sprite_Collectible_Long:
{
  PHB : PHK : PLB

  LDA.b $8A : CMP.b #$58 : BNE .not_intro_sword
    JSR Sprite_SwordShield_Draw
    BRA +
  .not_intro_sword
  LDA.b $8A : CMP.b #$4B : BNE .not_lupo_mountain
    JSR Sprite_RockSirloin_Draw
    BRA +
  .not_lupo_mountain
  JSR Sprite_Pineapple_Draw
  +
  JSL Sprite_DrawShadow
  JSL Sprite_CheckActive
  BCC .SpriteIsNotActive

  JSR Sprite_Collectible_Main

  .SpriteIsNotActive
  PLB
  RTL
}

Initialization (Sprite_Collectible_Prep)

This routine initializes the collectible sprite upon spawning, with conditional logic based on the AreaIndex:

• Intro Sword: If AreaIndex is $58, it checks Link's Sword flag ($7EF359). If Link already has the Sword, the sprite despawns. It also sets SprAction, X to $02 (SwordShield).
• Rock Sirloin: If AreaIndex is $4B, it sets SprAction, X to $03 (RockSirloin).

Sprite_Collectible_Prep:
{
  PHB : PHK : PLB

  ; Don't spawn the sword if we have it.
  LDA.b $8A : CMP.b #$58 : BNE .not_intro_sword
    LDA.l $7EF359 : BEQ +
      STZ.w SprState, X
    +
    LDA.b #$02 : STA.w SprAction, X
  .not_intro_sword
  LDA.b $8A : CMP.b #$4B : BNE .not_lupo_mountain
    LDA.b #$03 : STA.w SprAction, X
  .not_lupo_mountain

  PLB
  RTL
}

Main Logic & State Machine (Sprite_Collectible_Main)

This routine manages the behavior of various collectible items through a jump table based on SprAction, X:

• Pineapple: Moves the sprite (JSL Sprite_Move). If Link touches it (JSL Sprite_CheckDamageToPlayer), it increments the Pineapples custom item count and despawns the sprite.
• Seashell: Similar to Pineapple, but increments the Seashells custom item count.
• SwordShield: Plays an animation, moves the sprite. If Link touches it, it grants Link the Sword (LDY.b #$00, JSL Link_ReceiveItem) and despawns the sprite.
• RockSirloin: Moves the sprite. It checks Link's Glove flag ($7EF354). If Link has the Glove, it checks for player contact. If touched, it handles interaction with thrown sprites (JSL ThrownSprite_TileAndSpriteInteraction_long), increments the RockMeat custom item count, and despawns the sprite.

Sprite_Collectible_Main:
{
  LDA.w SprAction, X
  JSL   JumpTableLocal

  dw Pineapple
  dw Seashell
  dw SwordShield
  dw RockSirloin

  Pineapple:
  {
    JSL Sprite_Move
    JSL Sprite_CheckDamageToPlayer : BCC +
      LDA.l Pineapples : INC A : STA.l Pineapples
      STZ.w SprState, X
    +
    RTS
  }

  Seashell:
  {
    JSL Sprite_Move
    JSL Sprite_CheckDamageToPlayer : BCC +
      LDA.l Seashells : INC A : STA.l Seashells
      STZ.w SprState, X
    +
    RTS
  }

  SwordShield:
  {
    %PlayAnimation(0,0,1)
    JSL Sprite_Move
    JSL Sprite_CheckDamageToPlayer : BCC +
      LDY.b #$00 : STZ $02E9
      JSL Link_ReceiveItem
      STZ.w SprState, X
    +
    RTS
  }

  RockSirloin:
  {
    JSL Sprite_Move
    LDA.l $7EF354 : BEQ .do_you_even_lift_bro
      JSL Sprite_CheckDamageToPlayer : BCC +
        JSL ThrownSprite_TileAndSpriteInteraction_long
        LDA.l RockMeat : INC A : STA.l RockMeat
        STZ.w SprState, X
    +
    .do_you_even_lift_bro
    RTS
  }

}

Drawing (Sprite_Pineapple_Draw, Sprite_SwordShield_Draw, Sprite_RockSirloin_Draw)

Each collectible type has its own dedicated drawing routine. These routines handle OAM allocation and animation, and explicitly use REP #$20 and SEP #$20 for 16-bit coordinate calculations. Each routine contains its own specific OAM data for rendering the respective item.

Design Patterns

• Multi-Item Collectible: A single sprite definition (!SPRID = $52) is used to represent multiple distinct collectible items, with their specific appearance and behavior determined by SprAction, X and AreaIndex. This allows for efficient reuse of sprite slots for various in-game items.
• Context-Sensitive Spawning/Drawing: The sprite's initial appearance and drawing routine are dynamically selected based on the AreaIndex, enabling specific items to appear in designated locations within the game world.
• Item Granting: Collectibles grant items to Link upon contact, directly influencing his inventory and progression.
• Quest Progression Integration: The Sword/Shield collectible despawns if Link already possesses the Sword, and the Rock Sirloin requires Link to have the Glove to interact with it, integrating these items into the game's quest and progression systems.
• 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.