SPX (Sprite XML) Format

External sprite definition file format for the Resource Manager.

Overview

SPX files (.SPX) are XML files that define sprite sheet images and their animations in a single file. They are referenced from resources.xml via the <sprite-xml> tag.

Reference in resources.xml

<sprite-xml path="PLAYER.SPX" />
<sprite-xml path="SPRITES\ENEMIES.SPX" />

No name attribute is needed. The SPX file itself contains named image and sprite resources that become available through the Resource Manager.

Creating SPX Files

Pix8 exports this format directly — it is the quickest way to produce a sprite sheet and its animation definitions together. Pix8 is our own 256-color indexed pixel art editor and runs in the browser or as a Windows desktop app.

1. Draw the animation frames on the frame timeline, grouping them with tags (one tag per animation, e.g. player_idle, player_run)
2. File → Export as... (Ctrl+Shift+E) → SPX
3. The result is a ZIP containing the .SPX file plus the packed .PCX sprite sheet(s). Sheets are bin-packed to stay within the 320×200 VGA limit.
4. Unpack it into your DATA\ directory and reference the .SPX from resources.xml

Still (non-animated) images can be exported as SPX too. SPX files are plain XML, so they can also be written or tweaked by hand — the format is documented below.

File Format

Root element: <sprite-xml>

Image Tag

<image name="player" path="PLAYER.PCX" palette="player" />

Attribute	Required	Description
name	Yes	Resource name for referencing
path	Yes	PCX file path (relative to SPX file)
palette	No	Name for extracted palette resource

Sprite Tag

<sprite name="player_idle" image="player" width="32" height="32" duration="0.8">
  <frame x="0" y="0" />
  <frame x="32" y="0" />
  <frame x="64" y="0" />
</sprite>

Attribute	Required	Description
name	Yes	Sprite resource name
image	Yes	Reference to image resource
duration	Yes	Total animation duration in seconds
width	No	Default frame width (pixels)
height	No	Default frame height (pixels)

Frame Tag

<frame x="0" y="0" />
<frame x="32" y="0" width="48" height="32" offset-x="-8" offset-y="0" duration="0.2" />

Attribute	Required	Description
x	Yes	X position in sprite sheet
y	Yes	Y position in sprite sheet
width	No	Frame width (inherits from sprite)
height	No	Frame height (inherits from sprite)
offset-x	No	Drawing offset X (default 0)
offset-y	No	Drawing offset Y (default 0)
duration	No	Per-frame duration in seconds

Default Width/Height

When width and height are set on the <sprite> tag, all frames inherit these values. Individual frames can override with their own width/height.

If the sprite has no default size, every frame must specify width and height.

Frame Offsets

offset-x and offset-y adjust the drawing position of a frame. This is useful when a frame has a different size than the sprite default:

<sprite name="attack" image="player" width="32" height="32" duration="0.6">
  <frame x="0" y="64" />
  <frame x="32" y="64" width="48" height="32" offset-x="-8" />
  <frame x="80" y="64" width="48" height="32" offset-x="-8" />
  <frame x="128" y="64" />
</sprite>

The attack frames are wider (48px vs 32px default), so offset-x="-8" centers them relative to the normal position. When the sprite is flipped horizontally, offsets are automatically negated.

Per-Frame Duration

By default, all frames share the total duration equally (duration / frame_count). Individual frames can override this:

<sprite name="walk" image="player" width="32" height="32" duration="0.8">
  <frame x="0" y="0" />
  <frame x="32" y="0" duration="0.3" />
  <frame x="64" y="0" />
  <frame x="96" y="0" />
</sprite>

When any frame specifies duration, the engine switches to variable frame timing:

• Frames without explicit duration get sprite.duration / frame_count as default
• The total animation duration becomes the sum of all frame durations

Complete Example

<sprite-xml>
  <image name="player" path="PLAYER.PCX" palette="player" />

  <sprite name="player_idle" image="player" width="32" height="32" duration="0.8">
    <frame x="0" y="0" />
    <frame x="32" y="0" />
    <frame x="64" y="0" />
    <frame x="96" y="0" />
  </sprite>

  <sprite name="player_run" image="player" width="32" height="32" duration="0.5">
    <frame x="0" y="32" />
    <frame x="32" y="32" />
    <frame x="64" y="32" />
    <frame x="96" y="32" />
    <frame x="128" y="32" />
    <frame x="160" y="32" />
  </sprite>

  <sprite name="player_attack" image="player" width="32" height="32" duration="0.6">
    <frame x="0" y="64" />
    <frame x="32" y="64" width="48" height="32" offset-x="-8" duration="0.2" />
    <frame x="80" y="64" width="48" height="32" offset-x="-8" duration="0.2" />
    <frame x="128" y="64" />
  </sprite>
</sprite-xml>

Path Resolution

Image paths in SPX files are relative to the SPX file location, not to resources.xml. For example:

DATA\
  RES.XML              <- contains: <sprite-xml path="SPRITES\PLAYER.SPX" />
  SPRITES\
    PLAYER.SPX         <- contains: <image path="PLAYER.PCX" />
    PLAYER.PCX         <- loaded from DATA\SPRITES\PLAYER.PCX

Usage in Code

SPX-loaded sprites are accessed identically to inline sprites:

ResMan.Init(True);
ResMan.LoadFromXML('DATA\RES.XML');

{ Sprites from SPX files are available by name }
PlayerIdle := ResMan.GetSprite('player_idle');
PlayerRun := ResMan.GetSprite('player_run');