Patch:Galaxy Sprite Parameters
Galaxy Sprite Parameters describe the various parameters all sprites in Keen Galaxy (And Dreams) have. These range from clipping and speed to what image to use. A number of diverse parameters with various effects are summarized here. Note that these differ from Galaxy Action Parameters; a sprite's action will set and control some of its parameters (As well as the code it uses.) while the sprite parameters are more fundamental, more flexible and more often referenced in sprite code. A related topic is Patch:Vorticons Sprite Parameters.
This page also deals with the Keen Dreams sprite parameters which are very similar to those of Galaxy.
Sprite Structure
This is how the variables are stored, the structure of the sprite. Each variable is a two byte (word) value. Several of these values are not at present well known and information on them likely to be wrong.
Int Function $00 Object type $02 Sprite active type $04 Draw sprite? $06 Clipping $08 Action timer $0A X-position in level $0C Y-position in level $0E X direction $10 Y direction $12 X change in position per frame $14 Y change in position per frame $16 X velocity $18 Y velocity $1A Unknown $1C Current action $1E Current graphic $20 Foreground $22-28 Sprite hitbox in map units $2A Sprite hitbox x midpoint in map units $2C-32 Sprite hitbox in tiles $34-3A Sprite-tile collision with top, right, bottom and left tile flags $3C-3E Holds temporary variables $40 Sprite draw $42 Mask $44-46 Next and previous object in object list
Dreams sprite structure
Variables in Keen Dreams are slightly different to those in Galaxy. The Dreams structure can be considered a 'beta' of the Galaxy structure. Notably there is one extra variable that shifts those after it. Also notable is that the 'foreground' variable exists, but is not implemented in the game. Instead a special tile interaction is used by sprites that appear in the foreground, drastically limiting things.
Int Function $00 Object type $02 Sprite active type $04 Draw sprite? $06 Clipping $08 Action timer $0A X-position in level $0C Y-position in level $0E X direction $10 Y direction $12 X change in position per frame $14 Y change in position per frame $16 X velocity $18 Y velocity $1A Unknown $1C Unknown $1E Current action $20 Current graphic $22 Foreground (NOT IMPLEMENTED) $24-2A Sprite hitbox in map units $2C Sprite hitbox x midpoint in map units $2E-34 Sprite hitbox in tiles $36-3A Sprite-tile collision with top, right, bottom and left tile flags $3E-40 Holds temporary variables $42 Sprite draw $44 Mask $46-48 Next and previous object in object list
Variable functions
These are the functions of each variable in the game, as currently understood.
Object type
This is the sprite type which is used predominantly in sprite collisions to tell an object what kind of object (Keen, Keen's shot...) it is colliding with. In general each different kind of enemy will have its own object type, though few of them are strictly needed. This results in about 15 object types per game.
Sprite activity
This variable controls whether a sprite continues to function when Keen can't see it and when it is destroyed. (This is vital to not overload the sprite array.) The following values are valid:
0: Vanish immediately 1: 'Normal': stop when offscreen 2: 'Moving platform': always active, even offscreen 3: Vanish when offscreen
Draw sprite
This value is either 0 or 1 and determines whether or not the sprite's graphic will be shown. Usually this value is one and a sprite will always show some graphic, but in some circumstances this is not desirable. (See below.)
Clipping
This is the basic clipping, unrelated to tile collision. Keen has a robust tile clipping system used by all sprites that makes it virtually impossible for clipping errors to occur. The value can be 0, 1 or 2 as follows:
0: Ignore all tiles 1: Be stopped by solid sides, bottoms and tops, can move on slopes 2: Be stopped by solid and sloped tiles
Most sprites use clipping of 1, allowing them (Under some circumstances) to move up and down slopes while not falling through flats. Many flying sprites sue 2, as slopes can cause them problems when landing.
Action timer
In a broad sense this is the animation speed; it is how long the sprite will spend on its current action before proceeding to the next action.
X/Y position
This is the current location of the sprite in the level, in map units (1/256th of a tile.) As such no sprite can be more than 255 tiles in a level. This value is affected by many other variables. Changes to it are responsible for all sprite movement.
Direction
This is the horizontal and vertical direction the sprite is facing. Sprites can face left\down, neither or up\right, with values of -1, 0 and +1 respectively. This value controls what direction the sprite moves in, as well as what graphic it uses. (See below.)
Change in position
These variables are how much the sprite's position will change every frame. This is used when sprite moves in 'jerks', usually as it animates. How they change the position depends on the sprite's direction and current action (See below.)
Velocity
These variables also change the sprite position, but do not depend on animation. Such movement is smooth and is used for example for falling things The main difference is that these values are applied every tic of game time, instead of every sprite frame. It too depends on direction.
Current action
This is the sprite action being used. This is important as the sprite action affects so many other variables. (See next section below.) If this is set to 0, the sprite will be removed.
Graphic
This is the graphic drawn to represent the sprite. It is what the player sees. Usually when it is changed the sprite's hitbox is also altered to the one used by the graphic, but this is not strictly necessary. This always has a value, but the graphic may not always be drawn.
Foreground
This is the 'z layer' value, or what layer in the level the sprite graphic is drawn into. The value may be anything from 0-3. A sprite will appear behind any sprite with a larger z value, or, if the z value is the same, that was created after it. Most sprites have a z value of 1, appearing in front of foreground tiles, but not those that have the special 'front' tile property. The following is a rough guide:
0: Appear behind all sprites and fore tiles 1: Appear behind fore tiles and sprites of z>1 2: Appear behind 'front' fore tiles and sprites of z=3 3: Appear in front of everything
Hitbox
The sprite's hitbox; the area that responds to sprite and tile collisions is kept track of in both map units and tiles, as well as the horizontal middle of the hitbox. These are best not interfered with.
Temporary variables
These two parameters (Misc1 and Misc2) store 'temporary' variables, or more accurately variables that are likely to often change and not have a set value. This may include the sprite's health or something that stops it moving. (For example don't move if Misc2 = 1, if shot Misc2 = 0, after attacking.)
Sprite draw
This variable is currently not known.
Mask
This variable is currently not known. It may relate to sprites flashing white when they are shot. It has values between 0-16; 16 'draws normal' 0-15 'draws color' (A colored flash?)
Previous\Next object
These values keep track of what objects are before and after this object in the object list.
Sprite parameters and actions
Sprite actions are 30-byte strings of 2 and 4 byte values that alter a number of sprite parameters. The following is how each part of a sprite action affects sprite parameters.
Sprite animation
Actions contain two animations, one for sprites moving left\down, one for sprites moving up\right (Or neither) Every time the sprite's direction changes the action will notice this and pass the change in animation along to the sprite graphic parameter.
If this value is -1 the existing sprite will be removed and nothing drawn. (Sprite draw is set to 0.) If it is 0 then the current graphic will not be changed.
Action type
This has no direct effect on sprite parameters, but it affects how the action modifies other properties. Notably it controls how often behavior code is run, whether the sprite uses the action's animation delay and how the action's movement affects the sprite position.
Deprotect animation
This variable if set to 1 will stop the sprite animation being drawn. (It sets draw sprite variable to 0.)
Stick to ground
This does not affect any sprite variables directly, but relates to clipping. If it is zero then sprites with clipping 1 cannot move down slopes.
Delay
This variable is usually passed directly to the action timer when the action is first started. However several action types set this to 0, meaning that nothing will happen until some external force changes the actions.
Animation motion
These two variables can be affect the map position and change in position variables in several ways depending on the action type. Some action types mean the sprite moves in bursts, the animation motion value is added to the map position as the action is changed. Other action types divide this value by the animation speed, adding this bit-by-bit to the map position (Smoother motion.) every frame.
Behavior, sprite and tile checks
These do not directly affect any variables. However they set the code used by the sprite which almost certainly contains instructions to change various variables.
Next action
This value is passed to the current action variable when the current action ends.
Default values
Several variables have 'default values' used by sprites if a different value is not set. The following variables are 1 by default, sprite activity, clipping and foreground. Mask is 16. All other values are zero. Map position is set when the sprite is created and is close to where it is placed in the map. (The vertical position is often adjusted a few pixels.)
Changing values of variables in game
Variables are changed in game using a 5 byte string, $C7 $47 $xx $yyyyW, where $xx is the value to change and $yyyyW is the value to change it to. So for example to change a sprite's clipping (Int 6) to 0 the string $C7 $47 $06 $0000W is used. The only exception is object type, which uses the string $C7 $07 $yyyyW (Since it is int 0.)
When a variable is changed it affects only the one object running that code. (For example only one Poison Slug tends to slime (Change its action.) at a time. There are ways to make many objects do the same thing simultaneously, and some rare cases where an entire level is scanned and affected. (For example when the Inchworms combine to make a Foot, the level is scanned and all inchworms removed from the level.)