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.

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');