Dynamic Xtreme files and formats

English	Português	Español	日本語

Dynamic Xtreme uses a set of dedicated file formats to give you control over the resources, effects, and data used during gameplay.

This page documents the file types handled by the tool, their purpose, how they work, and their specific formats, including both current and legacy formats. Understanding this structure helps you make full use of Dynamic Xtreme.

Many of Dynamic Xtreme's legacy formats originated in Dynamic X, the earlier version from which the project evolved. They remain fully compatible to support the many existing resources developed for Dynamic X.

The main file types and their formats are described below.

File types

Dynamic Xtreme uses several specialized file types:

Dynamic resources: resources stored uncompressed in the ROM. Commonly used for dynamic sprites, graphics changes, tilemap changes, or palette changes.
Palette Effects (*.paleffect): files used to register palette effects.
Dynamic Info (*.dynamicinfo): files used to insert dynamic resources into the ROM and generate the data required by dynamic sprites.
Draw Info (*.drawinfo): files used to generate sprite poses (animation frames) so they can be drawn on screen.

Including files from PIXI and UberASMTool

PIXI and UberASMTool resources can declare the files they use through special comments in their main ASM file:

;#incdyn  "ruta/al/recurso.dynamicinfo"
;#incdri  "ruta/al/recurso.drawinfo"
;#incpale "ruta/al/recurso.paleffect"

Each directive registers a different file type:

;#incdyn includes a *.dynamicinfo file.
;#incdri includes a *.drawinfo file.
;#incpale includes a *.paleffect file.

Paths are relative to the main ASM containing the directive. Included files can be in the same folder or any of its subfolders.

Dynamic Xtreme searches for these directives only in the main ASM files registered in PIXI's and UberASMTool's lists. It does not follow files loaded through incsrc.

Resources referenced inside a *.dynamicinfo or *.paleffect included this way use the definition file's folder as their base directory.

Dynamic resources

Dynamic resources are one of Dynamic Xtreme's core systems. They are stored uncompressed in the ROM so they can be loaded and used quickly during gameplay.

How does the system work?

Dynamic Xtreme gathers all dynamic resources, organizes them into packages of at most one bank (32 or 64 KB), and automatically inserts them into the ROM. If high banks are available, the tool prioritizes them for insertion to improve space organization.

There is no strict restriction on the type of data that can be inserted, although most files are *.bin files.

Common uses

Dynamic resources are commonly used for:

Graphics: dynamic sprite graphics or real-time graphics replacement.
Tilemaps: replacing tiles in the level's different layers.
Palettes: replacing complete palettes or assigning specific palettes to dynamic sprites.
Other data: anything you want to store in the ROM, such as .brr audio samples, data tables, and so on.

This makes the system flexible enough for graphics and any other data that needs to be readily available in the ROM.

Palette files

Currently, the recommended way to save palettes is as binary files (*.bin), with each color taking 2 bytes in the SNES color format. Tools such as Pal2Bin can help with this.

The SNES uses the BGR555 color format: each color uses 5 bits for blue, 5 for green, and 5 for red.

Conceptually, the bits are arranged as follows:

-BBBBB GGGGG RRRRR

However, because of the SNES byte order, the bytes are stored in reverse order in memory, producing this arrangement:

GGG RRRRR -BBBBB GG

Because this format can be confusing for users unfamiliar with SNES hardware, improved support for *.pal files is planned. This format is more familiar and widely used in modern graphics tools.

Palettes used by dynamic sprites must contain no more than 15 colors. Include only colors 1 through 15 of the corresponding palette, since color 0 is transparent.

Dynamic sprite graphics

A dynamic sprite's graphics are divided into poses. Each pose contains the tiles that must be loaded into VRAM to display one animation frame.

Dynamic Xtreme supports two ways to organize these graphics:

The current format, recommended for new resources.
The legacy format, retained for compatibility with

resources made for Dynamic X.

Both formats produce the same result in the game. The only difference is how the graphics must be organized in the file.

Current format

In the current format, graphics are organized into 16×16-pixel spaces.

Each pose's tiles are placed consecutively. The next pose's graphics begin immediately after the previous pose's.

The author chooses the tile order within each pose in the graphics file. DynamicInfo specifies how many tiles belong to each pose, and DrawInfo specifies where each tile is drawn. Both must match the graphics layout.

For example, a 32×32-pixel pose normally uses four 16×16 tiles:

The number of tiles used by each pose is declared in the *.dynamicinfo file through NumberOf16x16TilesPerPose.

Dynamic Xtreme automatically rearranges these graphics into the internal format used for DMA transfers. The resource author therefore does not need to prepare the VRAM layout manually.

This is the recommended format for new resources.

If the final 16×16 tile is only partially used, specify which parts to keep with q, h, or q3. Prepare the graphics in a complete 16×16 space; Dynamic Xtreme keeps the indicated parts and discards the rest when processing the resource.

Each cell in the following tables represents an 8×8 tile. The entire table represents the pose's final 16×16 tile. Green marks used parts and gray marks discarded parts.

q

	Left half	Right half
Top half	Top-left 8×8 tile: used	Top-right 8×8 tile: unused
Bottom half	Bottom-left 8×8 tile: unused	Bottom-right 8×8 tile: unused

h

	Left half	Right half
Top half	Top-left 8×8 tile: used	Top-right 8×8 tile: used
Bottom half	Bottom-left 8×8 tile: unused	Bottom-right 8×8 tile: unused

q3

	Left half	Right half
Top half	Top-left 8×8 tile: used	Top-right 8×8 tile: used
Bottom half	Bottom-left 8×8 tile: used	Bottom-right 8×8 tile: unused

Legacy format

The legacy format requires the graphics to already be organized into the blocks that DMA will transfer.

For a pose using seven or fewer 16×16 tiles, split each tile into two 16×8 halves. Store all top halves first, followed by all bottom halves.

For example, a pose made of four tiles:

t1 t2 t3 t4

must be stored like this:

t1th t2th t3th t4th t1bh t2bh t3bh t4bh

Where:

th means the tile's top half.
bh means the tile's bottom half.

When a pose contains eight or more 16×16 tiles, each full row of eight tiles can be stored directly. Arrange the remaining tiles using the half-tile system described above.

Each pose's layout is declared through PosesChunksSizes in the *.dynamicinfo.

This format provides direct control over the internal layout but is harder to prepare and maintain. It is mainly recommended for older resources or advanced use cases.

Palette effects

Palette effect files are stored in the PaletteEffects folder and use the *.paleffect extension.

Palette effects modify the colors used by the game in real time. Dynamic Xtreme's global palette effect system can use these effects.

The global effect affects every color in each palette enabled to receive it. Likewise, an effect applied to a whole sprite affects its entire palette. These systems do not select individual colors within a palette.

To apply an effect only to specific colors, do it manually using the macros and routines described in the Dynamic Xtreme ASM API.

Internally, these systems modify the palette colors' RGB or HSL channels to produce different visual effects.

Common uses include:

Day-to-night transitions.
Red flashes to signal danger.
Blinking cyan effects for objects about to explode.
Shifting tints for disco-style effects.
Smooth transitions between visual states.
Lighting or atmosphere effects.

The system supports many combinations and effects.

Effect types

The following effects are available:

MixRGB (ID 0): interpolates the RGB channels toward a base color.
MixHSL (ID 1): interpolates the HSL channels toward a base color.
MixRG (ID 2): interpolates only R and G.
MixHS (ID 3): interpolates only H and S.
MixRB (ID 4): interpolates only R and B.
MixHL (ID 5): interpolates only H and L.
MixGB (ID 6): interpolates only G and B.
MixSL (ID 7): interpolates only S and L.
MixR (ID 8): interpolates only the R channel.
MixH (ID 9): interpolates only the H channel.
MixG (ID 10): interpolates only the G channel.
MixS (ID 11): interpolates only the S channel.
MixB (ID 12): interpolates only the B channel.
MixL (ID 13): interpolates only the L channel.
PalTransitionRGB (ID 14): interpolates an entire palette toward another using RGB channels.
PalTransitionHSL (ID 15): interpolates an entire palette toward another using HSL channels.
PalFunctionRGB (ID 16): applies a linear transformation to the RGB channels:
- R = R11*R + R12*G + R13*B
- G = R21*R + R22*G + R23*B
- B = R31*R + R32*G + R33*B
Where:
- RXY are ratios.
- R is the red channel.
- G is the green channel.
- B is the blue channel.
Note: this effect is not implemented yet.
PalFunctionHSL (ID 17): applies a linear transformation to the HSL channels:
- H = R11*H + R12*S + R13*L
- S = R21*H + R22*S + R23*L
- L = R31*H + R32*S + R33*L
Where:
- RXY are ratios.
- H is hue.
- S is saturation.
- L is lightness.
Note: this effect is not implemented yet.

File format

Palette effects use a JSON-based format:

{
  "Effects": []
}

Where:

Effects: the list of effects used.

Simple format

The simple format defines a single effect:

{
  "Channel1": 31,
  "Channel2": 0,
  "Channel3": 0,
  "Ratio1": 64,
  "Ratio2": 64,
  "Ratio3": 64,
  "EffectType": 0
}

Where:

Channel1, Channel2, and Channel3 contain the main channel values
- For RGB effects:
  - 1 = R
  - 2 = G
  - 3 = B
- For HSL effects:
  - 1 = H
  - 2 = S
  - 3 = L
Ratio1, Ratio2, and Ratio3 are interpolation factors used to calculate how strongly the effect influences each channel. Values range from 0 (minimum influence) to 127 (maximum influence).
EffectType is the ID of the effect used.

For example, the MixRGB above blends the original colors toward red: Channel1 = 31, Channel2 = 0, and Channel3 = 0. With all three ratios set to 64, the result is approximately halfway between each original color and that red. A black color therefore becomes a medium-intensity red. Increasing the ratios brings the result closer to the specified red.

Palette transitions

The PalTransitionRGB and PalTransitionHSL effects interpolate colors from one palette toward another.

Unlike regular blending effects, these use the Palette field to specify the target palette:

{
  "Palette": "Palettes/NightPalette.bin",
  "Ratio1": 64,
  "Ratio2": 64,
  "Ratio3": 64,
  "EffectType": 14
}

This example uses PalTransitionRGB, whose ID is 14. For an HSL transition, use PalTransitionHSL, whose ID is 15.

The file specified in Palette must contain 2-byte BGR555 colors. Dynamic Xtreme automatically converts the palette into the internal format required by the RGB or HSL effect.

Ratio1, Ratio2, and Ratio3 control interpolation for their respective channels and must range from 0 to 127.

When the *.paleffect is in the traditional PaletteEffects folder, the Palette path is resolved relative to DynamicResources.

When the effect is included from PIXI or UberASMTool through ;#incpale, its path is resolved relative to the folder containing the *.paleffect file.

Value ranges

Channel values (Channel) range from 0 to 31.
Ratio values (Ratio) range from 0 to 127.

DynamicInfo

DynamicInfo files are stored in the DynamicInfos folder and use the *.dynamicinfo extension.

These files have two main purposes:

Insert dynamic resources into the ROM.
Specify which graphics belong to dynamic sprites and how each pose must be loaded.

The basic structure of a DynamicInfo file is:

PosesGraphics:
    MyGraphics.bin
    AnotherGraphics.bin

Palettes:
    MyPal.bin
    AnotherPal.bin

Resources:
    MyResource.bin
    AnotherResource.bin

These sections are lists of dynamic resources to be included by Dynamic Xtreme.

The base directory for paths depends on how the DynamicInfo file is registered:

Method	Base directory for PosesGraphics, Palettes, and Resources files
Traditional folders: DynamicInfo inside `DynamicInfos`	Paths are relative to `DynamicResources`, next to the Dynamic Xtreme executable.
Included through `;#incdyn`	Paths are relative to the folder containing the included `*.dynamicinfo` file.

For example, with the traditional method, Graficos/MyGraphics.bin is found at DynamicResources/Graficos/MyGraphics.bin, not beside the DynamicInfo.

PosesGraphics contains dynamic sprite graphics files. These must use the *.bin format.
Palettes contains palette files. These currently use the *.bin format, with *.pal support planned for the future.
Resources includes arbitrary dynamic resources without a specific format restriction.

When multiple files are listed under PosesGraphics, they are combined internally into one large graphics block in declaration order.

Each pose is then cut from that combined data and stored in the ROM in the arrangement best suited to the dynamic system.

As a result, there is no significant practical difference between:

Using one large graphics file.
Using several separate smaller files.

Both approaches produce the same internal result in Dynamic Xtreme.

In addition to these resource lists, DynamicInfo files define the dynamic poses used by the sprite.

How those poses are defined depends on the resource's format:

Current format (NumberOf16x16TilesPerPose).
Legacy format (PosesChunksSizes).

Current format

The current format was designed to simplify creating and maintaining dynamic sprites.

You only need to specify how many 16×16 tiles each pose uses. Dynamic Xtreme processes the graphics and converts them to the optimized format used internally by the dynamic system.

Example:

NumberOf16x16TilesPerPose:
.Pose0 5
.Pose1 7h
.Pose2..6 4

In this example:

Pose0 uses five 16×16 tiles.
Pose1 uses seven 16×16 tiles plus a top half (16×8).
Pose2 through Pose6 use four 16×16 tiles each.

Modifiers can represent partial tiles:

q: top-left 8×8 tile.
h: top half (16×8).
q3: top half plus bottom-left tile (16×8 + 8×8).

This allows a 16×16 tile to contain only part of its graphics. Partial tiles do not support every possible combination, because many would be impractical for the system. Only the most common, useful arrangements are supported.

Internally, Dynamic Xtreme automatically converts this format to the legacy format, which is optimized for more efficient DMA transfers to VRAM.

Legacy format

The legacy format uses a table named PosesChunksSizes to specify the internal dynamic graphics layout manually.

Example:

PosesChunksSizes:
Pose0_PoseChunksSizes:
    db $02,$02
Pose1_PoseChunksSizes:
    db $02,$02

Each pose has a subtable containing two values.

These values represent how many DMA operations would be needed to transfer the pose's graphics into VRAM under ideal conditions: assuming the sprite is aligned to the start of the sprite VRAM area. Under those conditions, one or two DMA operations are needed.

Usually, the first DMA operation transfers more data than the second.

Each value specifies the number of 8×8 tiles transferred by that DMA operation.

For example:

db $02,$02

means:

The first DMA operation transfers two 8×8 tiles.
The second transfers another two 8×8 tiles.

In special cases where the sprite uses enough 16×16 tiles to fill exact VRAM rows, such as multiples of eight 16×16 tiles, the entire transfer can use a single DMA operation. In those cases, set the second value to $00.

The current format replaced this format because most users found it complex and unintuitive. NumberOf16x16TilesPerPose is now recommended, although the legacy format remains fully compatible and offers more flexibility for advanced cases.

DrawInfo

DrawInfo files are stored in DrawInfos with the *.drawinfo extension. They contain the information needed to draw poses on screen.

Dynamic Xtreme collects this information and automatically generates optimized graphics routines. Each routine groups poses with similar characteristics and is optimized specifically for that kind of pose. This provides a shared pose drawing system that is efficient in a wide range of situations.

Understanding DrawInfo files requires a basic understanding of SNES OAM.

OAM is memory used to store sprite information. SMW uses 8×8 and 16×16 tiles.

Each tile has the following attributes:

TileCode: sometimes simply called Tile, this is the internal ID the console uses to select a particular graphic in VRAM.
Note: for dynamic sprites, define TileCodes as if the sprite were loaded at the start of the sprite VRAM area.
Dynamic Xtreme automatically adjusts these values based on where the pose is actually loaded in VRAM during gameplay.
Properties: a byte containing the tile's properties, using this format:
- YXCCPPPT
Where:
- Y: whether the tile is vertically flipped.
- X: whether the tile is horizontally flipped.
- CC: tile priority relative to layers (higher value = higher priority).
- PPP: sprite palette (000 => palette 8, 001 => palette 9, ..., 111 => palette F).
- T: graphics page (0 => SP12, 1 => SP34).
Note: common Properties can be set for all tiles in a pose or sprite. The most important DrawInfo properties are therefore usually Y, X, and T, while CC and PPP are commonly set by the calling code.
For dynamic sprites, T normally does not need to be set manually: Dynamic Xtreme detects the pose's graphics page and sets this bit automatically.
Size: tile size:
- $00: small tile (8×8).
- $02: large tile (16×16).

Each tile also has:

X displacement (X Offset)
Y displacement (Y Offset)

These values move the tile relative to the sprite's base position.

Dynamic Xtreme supports two DrawInfo formats: current and legacy.

Current format

The current DrawInfo format was designed to make drawing files much easier to read and maintain.

Unlike the legacy format, it supports:

Grouping multiple poses.
Grouping tile ranges.
Using individual default values.
Omitting unnecessary subtables.
Defining individual values or complete value lists.

Example:

MyPose_Pose0..4:
.NumberOfTiles: 5
.TileCode2: $02
.TileCode3..4: $04
.Properties: $00,$40,$00,$00,$40
.XOffsets: $00,$10,$F8,$08,$18
.XPivot: $08
.YOffset2..4: $10
.YPivot: $10
.Size0..4: $02

In this example:

MyPose_Pose0..4: shared information for poses 0 through 4 with the name "MyPose".
.NumberOfTiles: each pose uses five tiles.
.TileCode2: changes only tile 2's TileCode.
.TileCode3..4: changes the TileCode for tiles 3 and 4.
.Properties: an individual Properties value for every tile.
.XOffsets: an individual XOffset for every tile.
.YOffset2..4: changes YOffset only for tiles 2 through 4.
.Size0..4: sets the size of tiles 0 through 4.

Tiles are numbered from 0. For example, .NumberOfTiles: 5 provides tiles 0 through 4.

Singular directives change one tile or a specified range of tiles.

Examples:

.TileCode2: $02
.TileCode3..4: $04
.YOffset1..3: $10

In these cases:

.TileCode2:: changes only tile 2.
.TileCode3..4: changes only tiles 3 and 4.
.YOffset1..3: changes YOffset for tiles 1 through 3.

Plural directives explicitly define a complete value list for every tile in the pose.

Examples:

.Properties: $00,$40,$00,$00,$40
.XOffsets: $00,$10,$F8,$08,$18

In these cases:

.Properties: a complete Properties list.
.XOffsets: a complete XOffsets list.

This allows simple general settings to be combined with specific changes only where needed.

Declarations are applied in the order they appear. If several change the same tile attribute, the last value wins. For example, after .Properties: $00,$40,$00,$00,$40, write .Property2: $80 to change only tile 2's property to $80. If you write the complete list afterward, that list replaces the previous values for all tiles.

When a value is not explicitly defined, Dynamic Xtreme uses these defaults:

TileCode: $00
Property: $00
XOffset: $00
YOffset: $00
Size: $02

Unlike the legacy format, these defaults work individually per tile, letting you omit only the unnecessary information without affecting the rest of the pose.

Offsets specify each tile's position relative to the sprite, in pixels. Without flipping, XOffset is added to the sprite's X position and YOffset to its Y position. For example, an XOffset of $10 puts the tile 16 pixels to the right; $F8 represents −8 and puts it 8 pixels to the left.

XPivot and YPivot calculate where tiles should be placed when the whole pose is flipped horizontally or vertically. They reflect the layout rather than rotating the pose.

For horizontal flipping, the calculation follows these steps:

Start with the sprite's X position.
Add XPivot.
Subtract the tile's original XOffset to reverse its displacement.
For a 16×16 tile, subtract another 8 pixels to adjust for its size. An 8×8 tile needs no such adjustment.

The flipped tile's X position is therefore:

8×8 tile: sprite X + XPivot − XOffset.
16×16 tile: sprite X + XPivot − XOffset − 8.

For example, a pose has two 16×16 tiles with XOffset values of 0 and 16. Setting .XPivot: $18 (24 decimal) swaps their positions when the pose is flipped:

Tile	Unflipped	Horizontally flipped
First: XOffset = 0	Sprite X + 0	Sprite X + 24 − 0 − 8 = Sprite X + 16
Second: XOffset = 16	Sprite X + 16	Sprite X + 24 − 16 − 8 = Sprite X + 0

Vertical flipping uses the same calculation with the sprite's Y position, YPivot, and YOffset.

These flipped offsets are calculated during installation. During gameplay, the drawing routine uses the offsets for the requested flip.

If XPivot is omitted, the pose does not support horizontal flipping. Likewise, omitting YPivot disables vertical flipping for that pose.

This lets Dynamic Xtreme generate more optimized graphics routines when those features are unnecessary, while slightly reducing ROM usage.

You can also use:

.IsStatic

This marks the defined poses as static rather than dynamic. All poses are dynamic by default.

The legacy DrawInfo format remains fully compatible. The current format primarily makes DrawInfo files easier to write, read, and maintain while retaining flexibility.

Legacy format

Legacy DrawInfo uses separate tables to define each pose tile attribute.

This format follows the structure commonly used in hand-written SNES graphics routines. It was intended to give sprite authors familiar with that approach a recognizable, intuitive layout for DrawInfo.

Example:

Dynamic: 
true

Tiles:
MyPose0_Tiles:
    db $00
MyPose1_Tiles:
    db $00

Properties:
MyPose0_Properties:
    db $00
MyPose1_Properties:
    db $00

XDisplacements:
MyPose0_XDisp:
    db $00
MyPose1_XDisp:
    db $00
MyPose0_XDispFlip:
    db $00
MyPose1_XDispFlip:
    db $00

YDisplacements:
MyPose0_YDisp:
    db $01
MyPose1_YDisp:
    db $01
MyPose0_YDispFlip:
    db $FF
MyPose1_YDispFlip:
    db $FF

Sizes:
MyPose0_Sizes:
    db $02
MyPose1_Sizes:
    db $02

In this format:

Each attribute has its own section.
Each pose requires a separate subtable.
Every value must be written manually.
There are no tile ranges or pose groups.

The main tables are:

Tiles: TileCodes.
Properties: OAM properties.
XDisplacements: horizontal offsets.
YDisplacements: vertical offsets.
Sizes: tile sizes (8×8 or 16×16).

XDisplacements and YDisplacements can also have flipped versions:

XDispFlip
YDispFlip

These tables let you specify the offsets used for horizontal or vertical flipping manually.

The directive:

Dynamic: true

marks the poses as dynamic. Set it to false to mark them as static.

As in the current format, default values are automatic. When a table is absent, Dynamic Xtreme uses:

TileCode: $00
Property: $00
XOffset: $00
YOffset: $00
Size: $02

This format remains fully compatible with Dynamic Xtreme, although the current format is recommended because it is considerably easier to read, maintain, and edit.