Patch:Galaxy Sprite Parameters

From KeenWiki
Jump to navigation Jump to search

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.)


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.


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.)


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.


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.


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


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.


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.


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.)