aede7551a3
- Created detailed documentation for the Minecart sprite, outlining its properties, constants, collision setup, main logic, and design patterns. - Added documentation for the Pedestal sprite, including its vanilla overrides, custom logic for item interaction, and event triggering based on area context. - Introduced documentation for the Portal sprite, detailing its two-way warping system, initialization, main logic, and helper routines for seamless transitions. - Documented the Switch Track sprite, explaining its interactive behavior, state-based animation, and integration with external switches for dynamic track manipulation.
233 lines
6.7 KiB
Markdown
233 lines
6.7 KiB
Markdown
# Switch Track
|
|
|
|
## Overview
|
|
The Switch Track sprite (`!SPRID = Sprite_SwitchTrack`) is an interactive object designed to function as a rotating segment of a minecart track. Its visual appearance and implied path change dynamically based on its `SprAction` (which represents its mode of rotation) and the on/off state of a corresponding switch, stored in `SwitchRam`.
|
|
|
|
## Sprite Properties
|
|
* **`!SPRID`**: `Sprite_SwitchTrack` (Custom symbol, likely a remapped vanilla ID)
|
|
* **`!NbrTiles`**: `02`
|
|
* **`!Harmless`**: `00`
|
|
* **`!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`**: `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_RotatingTrack_Long`)
|
|
This routine handles the Switch Track's drawing and dispatches to its main logic if the sprite is active.
|
|
|
|
```asm
|
|
Sprite_RotatingTrack_Long:
|
|
{
|
|
PHB : PHK : PLB
|
|
JSR Sprite_RotatingTrack_Draw
|
|
JSL Sprite_CheckActive : BCC .SpriteIsNotActive
|
|
JSR Sprite_RotatingTrack_Main
|
|
.SpriteIsNotActive
|
|
PLB
|
|
RTL
|
|
}
|
|
```
|
|
|
|
## Initialization (`Sprite_RotatingTrack_Prep`)
|
|
This routine initializes the Switch Track upon spawning. It sets `SprDefl, X` to `$80`. It then calculates the tile attributes of the tile directly above the switch track and sets `SprAction, X` based on the `SPRTILE` value (normalized by subtracting `$D0`). This `SprAction, X` likely determines the initial mode or orientation of the track.
|
|
|
|
```asm
|
|
Sprite_RotatingTrack_Prep:
|
|
{
|
|
PHB : PHK : PLB
|
|
LDA.b #$80 : STA.w SprDefl, X
|
|
|
|
; Setup Minecart position to look for tile IDs
|
|
; We use AND #$F8 to clamp to a 8x8 grid.
|
|
; Subtract 8 from the Y position to get the tile right above instead.
|
|
LDA.w SprY, X : AND #$F8 : SEC : SBC.b #$08 : STA.b $00
|
|
LDA.w SprYH, X : STA.b $01
|
|
|
|
LDA.w SprX, X : AND #$F8 : STA.b $02
|
|
LDA.w SprXH, X : STA.b $03
|
|
|
|
; Fetch tile attributes based on current coordinates
|
|
LDA.b #$00 : JSL Sprite_GetTileAttr
|
|
|
|
LDA.w SPRTILE : SEC : SBC.b #$D0 : STA.w SprAction, X
|
|
|
|
PLB
|
|
RTL
|
|
}
|
|
```
|
|
|
|
## Constants
|
|
* **`SwitchRam = $0230`**: A WRAM address that stores the state (on/off) of each individual switch, indexed by its `SprSubtype`. This allows for multiple independent switch tracks.
|
|
|
|
## Main Logic & State Machine (`Sprite_RotatingTrack_Main`)
|
|
This routine manages the visual state of the Switch Track based on its `SprAction` (mode of rotation) and the corresponding switch state in `SwitchRam`.
|
|
|
|
* **Modes**: The `SprAction, X` determines the mode of rotation, with four defined modes:
|
|
* `0` = TopLeft -> TopRight
|
|
* `1` = BottomLeft -> TopLeft
|
|
* `2` = TopRight -> BottomRight
|
|
* `3` = BottomRight -> BottomLeft
|
|
* **State-Based Animation**: For each mode, the `SprFrame, X` (animation frame) is set based on the on/off state of the switch (`SwitchRam, Y`). This visually changes the track's orientation.
|
|
|
|
```asm
|
|
Sprite_RotatingTrack_Main:
|
|
{
|
|
; Get the subtype of the track so that we can get its on/off state.
|
|
LDA.w SprSubtype, X : TAY
|
|
|
|
LDA.w SprAction, X
|
|
JSL UseImplicitRegIndexedLocalJumpTable
|
|
|
|
dw TopLeftToTopRight
|
|
dw BottomLeftToTopLeft
|
|
dw TopRightToBottomRight
|
|
dw BottomRightToBottomLeft
|
|
|
|
; 00 = TopLeft -> TopRight
|
|
TopLeftToTopRight:
|
|
{
|
|
LDA.w SwitchRam, Y : BNE .part2
|
|
LDA.b #$00 : STA.w SprFrame, X
|
|
RTS
|
|
.part2
|
|
LDA.b #$01 : STA.w SprFrame, X
|
|
RTS
|
|
}
|
|
|
|
; 01 = BottomLeft -> TopLeft
|
|
BottomLeftToTopLeft:
|
|
{
|
|
LDA.w SwitchRam, Y : BNE .part2_c
|
|
LDA.b #$03 : STA.w SprFrame, X
|
|
RTS
|
|
.part2_c
|
|
LDA.b #$00 : STA.w SprFrame, X
|
|
RTS
|
|
}
|
|
|
|
; 02 = TopRight -> BottomRight
|
|
TopRightToBottomRight:
|
|
{
|
|
LDA.w SwitchRam, Y : BNE .part2_a
|
|
LDA.b #$01 : STA.w SprFrame, X
|
|
RTS
|
|
.part2_a
|
|
LDA.b #$02 : STA.w SprFrame, X
|
|
RTS
|
|
}
|
|
|
|
; 03 = BottomRight -> BottomLeft
|
|
BottomRightToBottomLeft:
|
|
{
|
|
LDA.w SwitchRam, Y : BEQ .part2_b
|
|
LDA.b #$03 : STA.w SprFrame, X
|
|
RTS
|
|
.part2_b
|
|
LDA.b #$02 : STA.w SprFrame, X
|
|
RTS
|
|
}
|
|
}
|
|
```
|
|
|
|
## Drawing (`Sprite_RotatingTrack_Draw`)
|
|
This routine handles OAM allocation and animation for the Switch Track. It explicitly uses `REP #$20` and `SEP #$20` for 16-bit coordinate calculations, ensuring accurate sprite rendering.
|
|
|
|
```asm
|
|
Sprite_RotatingTrack_Draw:
|
|
{
|
|
JSL Sprite_PrepOamCoord
|
|
LDA.b #$04 : JSL OAM_AllocateFromRegionB
|
|
|
|
LDA $0DC0, X : CLC : ADC $0D90, X : TAY;Animation Frame
|
|
LDA .start_index, Y : STA $06
|
|
|
|
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 (without the *2 not 16bit anymore)
|
|
INY
|
|
LDA .chr, X : STA ($90), Y
|
|
INY
|
|
LDA .properties, X : 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
|
|
.nbr_of_tiles
|
|
db 0, 0, 0, 0
|
|
.chr
|
|
db $44
|
|
db $44
|
|
db $44
|
|
db $44
|
|
.properties
|
|
db $3D
|
|
db $7D
|
|
db $FD
|
|
db $BD
|
|
}
|
|
```
|
|
|
|
## Design Patterns
|
|
* **Interactive Puzzle Element**: The Switch Track is a key puzzle element that changes its orientation based on an external switch (likely the `mineswitch` sprite), directly influencing the path of minecarts.
|
|
* **State-Based Animation**: The track's animation frame (`SprFrame, X`) is directly controlled by the on/off state of a corresponding switch in `SwitchRam`, providing clear visual feedback to the player about its current configuration.
|
|
* **Subtype-Driven State**: The `SprSubtype` is used to index into `SwitchRam`, allowing each individual Switch Track to maintain its own independent state. This enables complex puzzle designs with multiple, distinct switch tracks.
|
|
* **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.
|