Sprite Definition

Sprite Definition

Sprite Definitions determine the basic kinds of moving elements that can exist in a game, and defines in detail how they behave under various circumstances throughout the entire game.

Sprite Definition

This window can be invoked to edit a new sprite definition by right-clicking on the Sprite Definitions folder and selecting "New", or by left-clicking on the folder and choosing "New Object" from the File menu. To edit an existing sprite definition, double-click the sprite definition beneath the Sprite Definitions folder, or select it and then choose "Properties" from the View menu, or "Edit" from the context (right-mouse) menu.

At the top of this window are some basic pieces of information about the sprite definition visible no matter which tab is selected below. The Name of the sprite definition is used to refer to the sprite definition and must be unique throughout the project. The Folder is a backslash-delimited name that can be used to specify a parent folder name into which the sprite definition will be nested for organizational purposes only in the project tree. The Base Class was a relatively advanced feature, and would be left at the default value of SpriteBase in most cases until version 2.3.0. Now another option LightSpriteBase is available. That should be selected to create a sprite definition that includes all the extra properties and behaviors of a dynamic light source. Of course the previous purpose is also still valid: if you want to create Source Code objects to define sprites with specialized sets of rule functions you can specify your SpriteBase-derived base class here. LightSpriteBase is now just one pre-packaged example of that.

Because sprite definitions consist of different components that have a significant deal of detail to explain, the description of sprite definitions is split up into 3 parts corresponding with the 3 tabs. This page will explain sprite states. For more information about sprite parameters or sprite rules, see one of these pages:

Introduction to Sprite States

Sprite states define the various appearances and behaviors the sprite can have. For example, if you have a sprite that can move left and right (and face in the appropriate direction while moving), it would make sense to have at least two states, one for moving left and one for moving right. Each state could have its own animation. Jumping left and jumping right could be a good use for two additional states. The states are not inherently linked to distinct behaviors, but the rules can refer to the sprite's current state to determine how it will behave.

Sprite Definition Menu

The Sprite Definition menu contains a number of commands that specifically apply to sprite states.

Add State

Creates a new state within the current sprite definition, and assigns it a default name with a uniquely identifying number.

Delete State

Delete the state currently selected in the state list. Note: Any sprite instances that are using the state being deleted will also be deleted!

Move State Up

Move the state upward in the list. This decreases the number assigned to the state, which may affect some rules that rely on the sequence of sprite states (especially those involving rotating sprites, which assume the states are all in order rotating counter-clockwise).

Move State Down

Move the state downward in the list. This increases the number assigned to the state, which may affect some rules that rely on the sequence of sprite states (especially those involving rotating sprites, which assume the states are all in order rotating counter-clockwise).

Add Frame to State

Append an animation frame to the end of the currently selected state. A frame must be selected in the "Available Frames" pane. The selected frame is added to the end of the state using the currently displayed Repeat Count and Mask Alpha Level. If the repeat count of the previous frame is 0, then the frame is not technically added as an animation frame but becomes part of the existing frame as a new "sub-frame" (see Repeat Count below for details).

Remove Frame from State

Remove the selected frames in the "Frames in Current State" pane from the currently selected state.

Preview State Animation

Display a small preview window that estimates how the sprite will appear and animate at runtime. It is recommended that you keep the number of running preview windows to a minimum.

Export to template...

If you are creating a sprite definition that you want to re-use in other projects or submit to a public SGDK2 sprite library, you can use this command to automaticlly pick out all the pieces related to this sprite definition and export them to a separate SGDK2 file. This will prompt for text as it exports. This text is displayed in the Import Sprite wizard as the file description when the sprite template file is selected. The credits that are inserted into the template file are taken from the current project's credits, so make sure thay are applicable to the sprite template being exported.

Rotating Sprite State Wizard

Rotating sprites can require many states, one for each angle which the sprite may aim. Manually creating these states and the associated frames would be tedious. This wizard walks through collecting some parameters and then automatically creates the frames and states for a rotating sprite, adding them to the current sprite. The wizard can also be used to append frames to existing states in cases where the rotating states should have multiple frames.

Toolbar

A toolbar at the top of the box listing all the sprite states provides shortcuts to relavent operations for sprite states. In order, the buttons correspond to the following menu items that are relevant to sprite states:

Add State
Delete State
Move State Up
Move State Down
Preview State Animation

State List

The list on the left of the States tab displays all the states belonging to this sprite definition. Selecting a state will display its properties and frames for editing.

State Properties

The properties that apply to the state as a whole are displayed at the top of State tab to the right of the state list.

State Name

The name of a sprite state must be unique within the sprite definition. Other sprite definitions may re-use the same state names. Names must begin with a letter and contain only letters, digits and spaces.

Frameset

Each sprite state can refer to its own frameset. Only one frameset may be used per sprite state. The frames from the frameset selected here are displayed in the "Available Frames" panel at the bottom. If a state contains frames when changing the frameset, you will be prompted to delete the frames because the frame numbers referred to by the state likely do not apply for a different frameset. You may choose not to delete the frames if you believe the new framesets frames are similar enough to be applicable to the existing frame index references.

Width, Height

This size in no way affects the appearance of the sprite state, but rather affects how it behaves. The width and height determine how much of this sprite state is treated as "solid". These properties are used to define a rectangle that extends rightward and downward from the current frame's origin. The origin is the coordinate where the axes meet in the Frame Editor tab of the frameset editor, usually the top left corner of the image. Each state can have its own size. For example, a crouching state might be shorter than a standing state. In cases where sprite states are different sizes, the rule functions that are provided for switching between states will disallow switching to a state if it's new size would cause it to penetrate a solid tile.

Frames

Below the state properties is a list of the individual frames contained in the current state. These frames are generally used to provide an animation sequence for the state, but can also be used to form "composite frames" in which multiple frames overlap. The frame that is displayed is determined by a property if the sprite called "frame" which determines the index of the currently active frame. So it doesn't necessarily need to be used to constantly animate the sprite state either. To add frames to the state, drag them from the "Available Frames" panel at the bottom, or select a frame in that panel and choose "Add Frame To State" (or press Ctrl+I) to append the selected frame(s) to the state. You can also add frames by duplicating existing frames in the state. To duplicate a frame, hold the Ctrl key while dragging a frame to the position in the sequence where a duplicate should be added. Dragging a frame to a new location without holding Ctrl will change the sequence of the frames (removing the frame from its old position and inserting it into the new position).

Below the frame list are two properties that apply specifically to each frame:

Repeat Count

When animating a sprite state, it's likely that you won't want to flip through the frames at top speed. Use the repeat count setting to determine how long the selected frame(s) are displayed (how many times they are implicitly repeated before moving to the next frame in the animation sequence). If the repeat count is 0, the frame is merged with the next frame. A series of frames that have a repeat count of 0 will draw the first frame in the back, and draw each subsequent frame in front of the previous until a frame with a non-zero repeat count is reached. Assigning a repeat count of 0 to the last frame is invalid, and will be implicitly assumed to be 1.

Mask Alpha Level

This setting determines the shape of the frame for use in detecting collisions with other sprites. The "shape" of a frame is based on its opaque pixels. Because the frames can have up to 255 levels of transparency, you can use this setting to determine at which level pixels are considered opaque versus transparent. A value of 1, for example, will consider any pixel that is the slightest bit opaque to be solid. A value of 255 will cause the sprite to be entirely empty as far as collisions are concerned. A value of 0 will cause the sprite to assume a rectangular shape that matches its "solid size" defined by the width and height above.

A mask level of 0 is recommended for sprites that don't really need fine-tuned collision detection based on pixels. There are two reasons for this: 1) creating collision masks can take a significant amount of time during the map's loading sequence (if there are many large sprites with lots of frames that need masks) but no collision mask is needed for sprites that use a Mask Alpha Level of 0; 2) Detecting collisions between two sprites that have a Mask Alpha Level of 0 is very simple and may improve performance if there are many large collision tests required.

Rather than directly entering the value into the field, you must use the button to display the editor to set the value. The editor for this field will show the sprite and show distinctions between the solid pixels and the empty pixels based on the current setting as it is changed. There are a number of options for how to display the solidity as this value is adjusted:

Solid Black on Image	Pixels from the sprite that are considered solid for the purposes of collision detection with other sprites are drawn as black. The remainder of the non-solid pixels are drawn unaltered against a diagonal mesh background. Use this setting to clearly see the areas of a light sprite that are visible, but not solid.
Solid White on Image	Pixels from the sprite that are considered solid are drawn as white. The remainder of the non-solid pixels are drawn unaltered against a diagonal mesh background. Use this setting to clearly see the areas of a dark sprite that are visible, but not solid.
Solid Image on Black	Pixels from the sprite that are considered solid are drawn as they originally appear in the sprite (against a diagonal mesh background, which may be visible if some solid pixels are partially transparent). The non-solid areas are covered in black. Use this setting to clearly see the part of a light sprite that will collide with other sprites.
Solid Image on White	Pixels from the sprite that are considered solid are drawn as they originally appear in the sprite. The non-solid areas are covered in white. Use this setting to clearly see the part of a dark sprite that will collide with other sprites.
Solid Black on White	Pixels from the sprite that are considered solid are drawn in black. Non-solid pixels are drawn in white. Use this setting to clearly contrast the solid areas of the sprite from the non-solid areas regardless of the colors used in the sprite.
Solid White on Black	Pixels from the sprite that are considered solid are drawn in white. Non-solid pixels are drawn in black. Use this setting to clearly contrast the solid areas of the sprite from the non-solid areas regardless of the colors used in the sprite.

Note that if you set the alpha mask level to 0, the collision rectangle can actually be smaller than the visible area of the sprite (smaller than it would be if the mask level were 1) because the solidity rectangle can be smaller than the visible area of the sprite. This is reflected in the solidity preview when the level is 0.