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.

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:

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 running an animation. New animations won't be queued, and idle loop 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.
FileIndex	+$08	Offset from the base files for stationary and moving animations. The file index appears to be restricted to the following common indices; BugVM instructions that directly set FileIndex will wrap any further values to zero. Common indices Direction FileIndex Right / East 0 Left / West 1 Up / North 2 Down / South 3
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.
IdleTime	+$0D	How many idle frames to continue executing the current IdleInstr.
IdleInstr	+$0E	The current IdleInstr being executed. See "Idle Loop Instructions".
IdlePC	+$0F	Pointer to the next idle loop instruction to execute.
IdleScript	+$11	Pointer to the start point of the current idle loop.
	+$13 to +$1F	Presumed empty

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

Animation Script Context Fields

Field	Offset
	+$00	Purpose unknown. Zeroed upon initialization.
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.
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.

Idle Loop Instructions

Idle Loops are small lists of instructions that dictate how a non-player-controlled sprite, such as an NPC, will move across the screen.

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.

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.