Sprites, also referred to individually as "Sprite Frames", are the graphic elements used for displaying Players, Objects, and non-text Status Script Objects.
They are loaded by Character Defs, Object Defs, and Status Scripts as "Sprite Sets", which group them for separation between each Player/Object, and order them for use in their Animations.
Sprite Files
The graphics and property values that make up Sprites are stored in "Sprite Files" (".spr" files), a file format specifically designed to allow flexibility within HCGE's Sprite Editor.
These files are created by calling to "load" the nonexistent file from within a Character Def, or from within an Object Def, which will create a single blank Sprite Frame, and then using the Sprite Editor's "Save" option. A Sprite File for a Character Def contains only one Sprite Set, which acts as the full set of Sprite Frames for the Player Character defined by that Character Def, while a Sprite File for an Object Def contains multiple Sprite Sets that can be loaded as "Game", "Zone", or "Act" Object Sprite Sets, depending on where the Object Def that references it is loaded.
The Sprite Editor is used to expand and manipulate Sprite Set lists and each Sprite Frame itself, including using the "Import" feature to obtain Frame graphics from external image files, which can also be written back to standard image files using the "Export" feature.
Multiple Sprites and the "Primary Sprite"
Each Player/Object may display more than one Sprite at the same time by running more than one Animation.
These Sprites will be drawn to the screen in the order in which the Animations were started, placing the first one at the back, and the last one at the front.
The Sprite referenced at any given time by the "Primary Animation" (the first Animation that was run) is considered to be the "Primary Sprite".
During Collision tests against "Attack" and "Hurt" boxes, the Sprites referenced by every active Animation are tested.
When testing "MainBounds" Boxes or Hotspots, only the settings for the "Primary Sprite" are used.
Sprite Properties
Aside from the actual image, Sprites contain a few property settings that are involved in Drawing, Collision, and miscellaneous Script-driven behavior.
These values are offsets based on Object Position or Player Position, meaning that the X and Y settings represent points surrounding that position (given in the figure below as "0") in this manner:
-X-Y | +X-Y
-----0-----
-X+Y | +X+Y
These properties are entered as text in the appropriate "Def Files", but can be manipulated graphically from within the Sprite Editor.
Display Offsets
"Display Offsets" specify where the Sprite should be drawn in relation to the current position of the Object/Player.
This is based on the upper-left corner of the image, so, according to the above figure, settings of 0,0 will cause the image to begin at 0, and fall entirely into the +X+Y quadrant.
Objects/Players are generally managed such that their position variables represent their center.
To accomplish this, its "Primary Sprites" should be made to center around its position.
Numerically, this involves setting the X and Y values to half of the image's width and height, respectively, and negating them (for example, a sprite of size 36,48 would use settings of -18,-24).
Within the Sprite Editor, this is easily accomplished by manipulating the image so that it is centered on the crosshair.
This property also contains a "Backward" X setting, and an "Upside-Down" Y setting, which are used when the image is drawn mirrored or flipped, respectively.
These values can be set independently of the "Normal" X and Y values so that the image centers on a point other than the Object/Player position, but they are generally set so that the image mirrors/flips perfectly around that position.
The Sprite Editor can be set to automatically adjust these values, or to allow them to be manipulated separately. Mirrored/Flipped positions for Collision Boxes and Hotspots are automatically generated based on these settings.
Collision Boxes
A "Collision Box" is any one of three types of areas defined within the Sprite for use in various types of Collision testing.
Script Commands that perform Player/Object and Object/Object Collision tests will allow for tests between any combination of these types.
These properties consist of two X offsets and two Y offsets, which define the four corners of the Box in relation to the Object/Player position.
MainBounds
Each Sprite has one "MainBounds" Box, which is primarily used for Collision with the Level, and for Collision between Players/Solid Objects and Players/Path Objects.
Generally, each Sprite within a set should use the same settings for this Box, because otherwise, an Object/Player that is testing for these collisions will behave improperly when the Box's size changes during Animation.
If, however, the Box must change size, the position of the Object/Player must be updated manually so that it stays in contact with the Path, or any other solid entity. (For example, assume a Player is following the floor beneath him. If his "Primary Animation" is currently using Sprites that have a lower MainBound Y value of 5, and he switches to an Animation whose Sprites have a lower MainBound value of 3, his Y position must also be altered by +2 at the same time so that he maintains collision with the floor.)
This Box may also be tested for any other purpose by using certain Script Commands.
In addition to the Commands that test for overlapping Collision Boxes, there exist commands to obtain the world position of any of the four sides of this box in relation to the active Player/Object it belongs to.
"MainBounds" is only tested for the "Primary Sprite"; no other Sprite that may be visible for this Object/Player will be included in any test.
This Box is represented in the Sprite Editor by the area outlined in blue.
Attack Boxes
A Sprite may contain any number of "Attack Boxes", including none at all.
There is no built-in purpose for them, but they are generally used by Scripted Collision Tests to cause one Player/Object to "damage" another when it overlaps with one of its "Hurt Boxes".
Every "Attack Box" belonging to the Sprite Frames currently referenced by every active Animation for the Player/Object is tested by any Collision Box overlap test.
These Boxes are represented in the Sprite Editor by areas outlined in green.
Hurt Boxes
A Sprite may contain any number of "Hurt Boxes", including none at all.
There is no built-in purpose for them, but they are generally used by Scripted Collision Tests to cause one Player/Object to accept "damage" from another when it overlaps with one of its "Attack Boxes".
Every "Hurt Box" belonging to the Sprite Frames currently referenced by every active Animation for the Player/Object is tested by any Collision Box overlap test.
These Boxes are represented in the Sprite Editor by areas outlined in red.
Hotspots
A Sprite may contain any number of "Hotspots", including none at all.
There is no built-in purpose for them, but they are generally used by Script Functions to position spawned Objects or obtain Level Tile Properties from a position relative to the current Sprite Frame.
This is accomplished by using the Script Commands to obtain the world position of the Hotspot in relation to the active Player/Object it belongs to.
Hotspots are used individually, so any Hotspot within any Sprite Frame may be used for any purpose, regardless of how others in the same Frame are used.
Their reference ID is based on the order in which they were added to the Sprite Frame.
This should be taken into consideration when creating them so that Hotspot tests for a specific purpose can be performed using the same ID regardless of the Sprite Frame that is currently in use by the Player/Object.
In the case of Tile Properties, the Hotspot should generally use the same settings for each Sprite Frame within an Animation, unless the desired effect actually requires a more complex test based on the Sprite Frame Image.
In the case of Object positioning, the Hotspot can use different settings for each Sprite Frame so that the spawned Object appears to be coming from the same visible portion of the Player/Object regardless of the image it is currently displaying (such as a projectile fired from a bobbing weapon).
Hotspots are only used from within the "Primary Sprite"; they are not accessible from any other Sprite that may be visible for this Object/Player.
These Spots are represented in the Sprite Editor by flashing pixels.
Sprites and Status Script Objects
Sprites intended solely for use with Status Script Objects are loaded as Sets by Status Script Files.
None of the above properties are taken for these Sprites, and they are always drawn such that their "position" corresponds with the upper-left corner of their image.
Status Script Objects can be made to display Sprites from Sets loaded by their own Script or any other Status Script that is currently loaded.
Status Script Objects may also be made to display Sprites that were loaded for Players or Game Objects, but the only properties that will have any effect or use are the Drawing Offsets.
Because a standard Status Script Sprite doesn't contain Drawing Offset settings, Script Commands for relative positioning do not take those settings into account.
Using "Left" and "Top" alignment will act on what would be considered the Player/Object position, meaning that, if the Sprite's image is centered, "Left"/"Top" alignment will act on the Sprite's center.
Sprites and Players
Sprites for use with any one Player Character are loaded as a single Set by its Character Def File.
These are the only Sprites that can be used by that Player Character.
Sprites and Game Objects
Sprites for use with Game Objects are loaded as Sets by Object Def Files.
Game Objects can be made to display Sprites from any Set made available by any currently-loaded Object Def.
They may also be made to display Sprites associated with any currently-loaded Player Character.