Editing Wikifang:Network Translation Patchsite/SpriteManager

Bugsite's metasprite system is a scriptable SpriteManager which manages the movement of objects on a playfield. These objects need to be managed as a collection of hardware sprites (on systems which support them). In GB retroprogramming parlance these collections of sprites are called metasprites. SpriteManager is Bugsite's implementation of a metasprite system.

== Directions ==

Sprites can be said to be ''facing'' a certain direction; and these directions themselves are referred to either by enumerants or input bits. Here's which is which:

{| class="wikitable"
|+ Direction Key
|-
! Direction !! Enumerant !! Input bit
|-
| Right / East || 0 || Bit 4
|-
| Left / West || 1 || Bit 5
|-
| Up / North || 2 || Bit 6
|-
| Down / South || 3 || Bit 7
|}

== Metasprite Data Structure ==

Each metasprite consists of a '''metasprite struct''' and, if animated, an optional '''scripting context'''. Both data structures exist as an array of 8 slots at $C700 and $C800, respectively. The offsets of each structure are as follows:

{| class="wikitable"
|+ Metasprite Struct Fields
|-
! Field !! Offset !! 
|-
| State || +$00 || A bitmask of various sprite properties.

Bit 0: Metasprite slot is initialized and valid. If this bit is clear, the slot can be treated as unused and overwritten with a new metasprite.

Bit 1: Metasprite is active, meaning the user is expected to be able to see it. Sprites are usually activated and deactivated by a per-frame clip test; however, sprites can also manually deactivate themselves. Deactivated sprites are processed normally, but they do not create visible hardware sprites on screen.

Bit 2: Metasprite is in motion. New animations won't be queued, and choreography scripts won't run, until the animation completes. Stationary animations do not set this flag and are always interruptible animations.

Bit 3: Metasprite has been locked to it's stationary animation.

Bit 4: Metasprite has been locked to it's stationary animation. For some reason, there are two bits with the same effect. It is unknown if one bit has different semantics from the other.
|-
| SpriteY || +$01 || Y coordinate of sprite (16bit)
|-
| SpriteX || +$03 || X coordinate of sprite (16bit)
|-
| MovePerms || +$05 || Pointer into the move permissions array which references the sprite's current location.
|-
| AnimAllowed || +$07 || Must be non-zero for animations to run on this sprite.
|-
| Direction || +$08 || Which direction the sprite is facing.

Acts as an offset from the base files for stationary and moving animations. Is not allowed to exceed 3; further values would be meaningless.

''See "[[#Directions|Directions]]".''
|-
| FileAnimStationary || +$09 || BugFS file ID containing an animation script to be used for the stationary animation.
|-
| FileAnimMoving || +$0B || BugFS file ID containing an animation script to be used for walk cycles and other sprite-moving animations.
|-
| ChoreoRepeat || +$0D || How many times to continue executing the current ChoreoInstr.
|-
| ChoreoInstr || +$0E || The current choreography instruction being executed.

''See "[[#Choreography_Instructions|Choreography Instructions]]".''
|-
| ChoreoPC || +$0F || Pointer to the next choreography instruction to execute.
|-
| ChoreoScript || +$11 || Pointer to the start of the current choreography script.
|-
| || +$13 to +$1F || Presumed empty
|}

If a sprite is animated, the corresponding slot in the scripting context array will also run.

{| class="wikitable"
|+ Animation Script Context Fields
|-
! Field !! Offset !! 
|-
| Playing || +$00 || Set non-zero when an animation is ready to play.
|-
| Delay || +$01 || Amount of frames to wait until next frame of animation.
|-
| FileBank || +$02 || ROM bank of the start of the script's BugFS file.
|-
| FilePtr || +$03 || ROM pointer of the start of the script's BugFS file.
|-
| AnimScript || +$05 || Pointer to start of the current animation script.
|-
| AnimPC || +$07 || Pointer to the next animation instruction to execute.

''See "[[#Animation_Script_Instructions|Animation Script Instructions]]".''
|-
| SpriteIndex || +$09 || Index of the metasprite slot that this animation serves.

''In all known instances, the script context slot index matches the metasprite it serves, even though it's not strictly necessary.''
|-
| SpritePtr || +$0A || Pointer to the metasprite slot that this animation serves.

''This appears to be strictly a convenience feature; the sprite pointer can be generated from the index using four instructions.''
|-
| || +$0C to +$0F || Presumed empty
|}

== Sprite Script Engines ==
Yes, Bugsite has ''two of them''.

=== Choreography Instructions ===
Choreography scripts are small lists of instructions that dictate how a non-player-controlled sprite, such as an NPC, will move across the screen. Each instruction is preceded by a repeat count; each instruction will execute that many times before moving to the next instruction. A maximum of one choreography instruction will execute per frame, and choreography instructions wait for their triggered animations to finish before proceeding. Choreography opcodes do not have operands, and only one flow control instruction.

Setting a repeat value of 0 causes the loop to stop executing instructions. The current instruction will still execute; however, the next time the sprite is processed, the stationary animation for it's current direction will play.

{| class='wikitable'
|-
! Opcode !! Encoding(s) !! Native Impl. !! Description
|-
| ENOP $nn || $00-$4F || N/A || Treated as effective NOP by the script interpreter.
|-
| CNOP $50 || $50 || $33F7 || NOP
|-
| CNOP $51 || $51 || $33FA || NOP
|-
| CNOP $52 || $52 || $33FD || NOP
|-
| CDOWN || $53 || $341F || Run the sprite's move-down animation.
|-
| CUP || $54 || $3436 || Run the sprite's move-up animation.
|-
| CLEFT || $55 || $344D || Run the sprite's move-left animation.
|-
| CRIGHT || $56 || $3464 || Run the sprite's move-right animation.
|-
| CNOP $57 || $57 || $347B || NOP
|-
| CWAIT || $58 || $3400 || Run the stationary animation for the sprite's current direction a random number of times, from $0 to $20.

The repeat value of this instruction is ignored.
|-
| CSTOP || $59 || $341C || Run the stationary animation for the sprite's current direction.
|-
| EFGAME $nn || $60-$EF || N/A || Invalid opcodes, will likely crash game.
|-
| CHALT || $F0 || $33C0 || Reset the choreography script back to ChoreoScript.

The repeat value of this instruction is always treated as 0 (e.g. halt).
|-
| CRESET || $F1 || $33E2 || Reset the choreography script back to ChoreoScript.
|-
| EFGAME $nn || $F2-$FF || N/A || Invalid opcodes, will likely crash game.
|}

''Please keep in mind that directional commands such as IDOWN, IUP, ILEFT, and IRIGHT do not actually move the sprite.'' Instead, they queue the animation script associated with that direction. The animation script itself moves the sprite; it's only by convention that, e.g. IDOWN always executes a script that moves the sprite down two tiles. Furthermore, script execution is predicated upon the target tiles being free; if they are occupied, then the choreography script will halt until that slot becomes free. This has the following consequences:

* The movement path specified by the choreography script will be followed exactly.
* Sprites can get 'stuck' on stationary walls, or even each other.
* NPCs will 'box in' players, never moving until the player moves out of their way, as the player is just another sprite.

=== Animation Script Instructions ===
This scripting engine does the actual job of specifying how a sprite will animate from frame to frame when moving across the screen, as well as moving the sprite's origin, reserving space in the movement array, and generating hardware sprites to display. Animation scripts are executed continuously whenever the sprite has been marked as animated (See State field). 

{| class='wikitable'
|-
! Opcode !! Encoding(s) !! Native Impl. !! Description
|-
| EFGAME $nn || $00-$2F || N/A || Invalid opcodes, will likely crash game.
|-
| SCRNDOWN || $32 || $2A29 || Scroll the screen (e.g. background layer) down one pixel.
|-
| SCRNLEFT || $34 || $2993 || Scroll the screen (e.g. background layer) left one pixel.
|-
| SCRNRIGHT || $36 || $2948 || Scroll the screen (e.g. background layer) right one pixel.
|-
| SCRNUP || $38 || $29DE || Scroll the screen (e.g. background layer) up one pixel.
|-
| RESRVDOWN || $44 || $2AC4 || Mark tile downward as occupied by this sprite.
|-
| RESRVLEFT || $4C || $2BD8 || Mark tile leftward as occupied by this sprite.
|-
| FRAME || $4F || $2C73 || Draw a frame of animation.

This instruction takes one operand; a 16b offset from the start of the containing BugFS file with frame data for this instruction.
|-
| RESRVRIGHT || $52 || $2B7C || Mark tile rightward as occupied by this sprite.
|-
| CLRESET || $53 || $2AA5 || Deactivate the sprite and jump back to the start of the animation script.
|-
| RESRVUP || $55 || $2B20 || Mark tile upward as occupied by this sprite.
|-
| WAIT || $57 || $2A77 || Halt animation processing for a certain number of frames.

This instruction takes one operand; the number of frames to halt for. It is encoded bias $30 (e.g. the operand minus $30 is what is ultimately stored in Delay).
|-
| MOVDOWN || $64 || $2AD5 || Move the sprite down by 16 pixels, and release prior movement reservations.
|-
| MOVLEFT || $6C || $2BE9 || Move the sprite left by 16 pixels, and release prior movement reservations.
|-
| MOVRIGHT || $72 || $2B8D || Move the sprite right by 16 pixels, and release prior movement reservations.
|-
| RESET || $73 || $2AAD || Jump back to the start of the animation script.
|-
| MOVUP || $75 || $2B31 || Move the sprite up by 16 pixels, and release prior movement reservations.
|}

== Move Permissions ==
Bugsite handles collision detection with an array covering the whole of WRAM6; with a backup copy at WRAM7 for restoring old data in the array.

The array appears to exclusively bit 7 zero for unoccupied tiles and bit 7 one for occupied tiles. This is a rather inefficient use of working memory, even with the GBC's copious amounts of it; though it's unknown if the lower 7 bits of each tile byte stores flags or data other than the occupation state of the tile.