Dynamic Xtreme files and formats

English	Português	Español	日本語

Dynamic Xtreme uses its own well-structured file system, allowing users to have precise and flexible control over the resources, effects, and data used during the game's execution.

This page documents the different types of files handled by the tool, how they work, their purpose, and the specific formats they use (both current and legacy). Understanding this structure is essential to fully take advantage of Dynamic Xtreme's capabilities.

Many of the legacy formats present in Dynamic Xtreme originally come from Dynamic X, the older version from which the project evolved. These formats remain fully compatible in order to preserve support for a large amount of already existing resources developed for Dynamic X.

The following sections detail the main file types and their formats:

File Types

Dynamic Xtreme uses several specialized file types. The main ones are described below:

Dynamic Resources: Resources stored uncompressed inside the ROM. They are commonly used for dynamic sprites, graphics replacement, tilemap replacement, or palette replacement.
Palette Effects (*.paleffect): Files used to register color palette effects.
Dynamic Info (*.dynamicinfo): Files used to include dynamic resources into the ROM and also generate the relevant data for dynamic sprites.
Draw Info (*.drawinfo): Files used to generate sprite poses (animation frames) and later draw them on screen.

Dynamic Resources

Dynamic Resources are one of the core systems of Dynamic Xtreme. These resources are stored uncompressed inside the ROM, allowing them to be loaded and used quickly during gameplay.

How does the system work?

Dynamic Xtreme collects all dynamic resources, organizes them into packages of up to 1 bank (32 or 64 KB), and automatically inserts them into the ROM. If the ROM has available hi-banks, the tool prioritizes those banks for insertion, improving space organization.

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

Main uses

Dynamic resources are commonly used for:

Graphics: Dynamic sprite graphics or real-time graphics replacement.
Tilemaps: Replacing tiles from different level layers.
Color palettes: Replacing full palettes or assigning specific palettes to dynamic sprites.
Others: Any type of information that needs to be stored in the ROM, such as .brr audio samples, data tables, etc.

This makes the system extremely flexible, allowing not only graphical uses but also any other type of data the user may need to access quickly from the ROM.

Color Palette Files

Currently, the best way to store color palette files is by using binary files (*.bin) where each color occupies 2 bytes following the color format used by the SNES. There are tools that simplify this process, such as Pal2Bin.

To understand this, it is important to consider that the SNES color format is BGR555. This means that each color is stored using 5 bits for blue, 5 bits for green, and 5 bits for red.

Conceptually, the bits are organized like this:

-BBBBB GGGGG RRRRR

However, due to the endian format used by the SNES, the bytes must be stored reversed in memory, so internally they end up organized like this:

GGG RRRRR -BBBBB GG

Because this format can be confusing for users unfamiliar with SNES hardware, improved support for *.pal files is planned for the future, since they are much more common and widely used in modern graphics tools.

In the case of palettes used by dynamic sprites, they must contain a maximum of 15 colors. This means that only colors 1 through 15 of the corresponding palette should be included, since color 0 is used as transparency.

Graphics for Dynamic Sprites

Graphics used by dynamic sprites in Dynamic Xtreme must follow certain organization rules depending on the format used by the resource.

Currently, there are two formats supported by the system:

Current format
Legacy format

The modern format was designed to simplify the creation and maintenance of dynamic resources, allowing the use of layouts that are much easier to understand and organize.

On the other hand, the legacy format corresponds to the original system based on PosesChunksSizes, which offers more advanced and flexible control over the internal organization of graphics in VRAM, but also requires a deeper understanding of how the dynamic system works internally.

Current Format

The modern format is simply based on organizing graphics as continuous 16x16 tiles in VRAM. This format was designed to greatly simplify the process of creating dynamic sprites.

Example:

The example image shows a 32x32 sprite (which uses 4 16x16 tiles) being organized inside the graphics file.

With this system, the user only needs to worry about visually organizing the tiles in the correct order for each pose.

Internally, Dynamic Xtreme reads these graphics and automatically converts them into the legacy format, which is easier for SNES hardware to handle. Additionally, the system automatically removes empty spaces generated by partial tiles declared through modifiers such as q, th, bh, lh, or q3.

Legacy Format

The legacy format uses a graphics organization system optimized to simplify the internal handling of dynamic graphics on SNES hardware.

Unlike the modern format, in this case the user must manually organize the graphics following the layout required by the system.

When a pose uses 7 or fewer 16x16 tiles, the tiles are first organized into a continuous horizontal row. Then, each 16x16 tile must be divided into two 16x8 halves:

top half.
bottom half.

After this:

all top halves are placed continuously first.
then all bottom halves are placed immediately after.

Example:

Given a pose made of 4 16x16 tiles, the following tiles are used:

t1 t2 t3 t4

They must be organized as follows:

t1th t2th t3th t4th t1bh t2bh t3bh t4bh

Where:

tx corresponds to a 16x16 tile.
txth corresponds to the top half of a 16x16 tile.
txbh corresponds to the bottom half of a 16x16 tile.

When a pose uses 8 or more 16x16 tiles, all complete rows of 8 tiles must first be separated. These complete rows can be stored directly without additional reorganization.

Then, any remaining tiles that do not complete a full row of 8 tiles must be organized using the same system previously explained for poses with 7 tiles or fewer.

Considerations About Tile Overlap

In static sprites, it is common to use tile overlap to save graphic space. For example, in a 24x24 sprite it is common to use 3 16x16 tiles and 1 8x8 tile, taking advantage of overlap between the 16x16 tiles.

However, this type of organization is not valid for dynamic sprites.

Because dynamic graphics can be loaded into VRAM in unpredictable ways, tiles cannot visually depend on each other through overlap. Each tile must contain only the graphics corresponding to its own area.

For example, for a 24x24 sprite, instead of using overlap between 16x16 tiles, it is recommended to use:

2 diagonal 16x16 tiles with a shared 8x8 area between them.
2 8x8 tiles organized inside a space equivalent to 1 16x16 tile.

Tile overlap is not allowed in dynamic sprites, although redundancy between 2 different tiles is still possible and those tiles can be strategically organized to save OAM tiles. Additionally, it is still possible to save space through the strategic use of 8x8 tiles.

Palette Effects

Palette Effect files are stored inside the PaletteEffects folder and use the "*.paleffect" extension.

Palette effects allow real-time color modifications over the palettes used by the game. These effects can be used by Dynamic Xtreme's global palette effect system.

Internally, these systems work by modifying the RGB or HSL channels of palette colors in order to produce different visual effects.

Some common uses include:

Day-to-night transitions.
Red flashes to indicate danger.
Blinking cyan effects for objects about to explode.
Hue changes for disco-like effects.
Smooth transitions between visual states.
Lighting or ambient effects.

The system allows a huge variety of combinations and visual effects.

Effect Types

Currently, the following effects exist:

MixRGB (ID 0): Interpolates the RGB channels with a base color.
MixHSL (ID 1): Interpolates the HSL channels with a base color.
MixRG (ID 2): Interpolates only R and G.
MixGB (ID 3): Interpolates only G and B.
MixRB (ID 4): Interpolates only R and B.
MixHS (ID 5): Interpolates only H and S.
MixSL (ID 6): Interpolates only S and L.
MixHL (ID 7): Interpolates only H and L.
MixR (ID 8): Interpolates only the R channel.
MixG (ID 9): Interpolates only the G channel.
MixB (ID 10): Interpolates only the B channel.
MixH (ID 11): Interpolates only the H channel.
MixS (ID 12): Interpolates only the S channel.
MixL (ID 13): Interpolates only the L channel.
PalTransitionRGB (ID 14): Interpolates an entire palette into another using RGB channels.
PalTransitionHSL (ID 15): Interpolates an entire palette into another using HSL channels.
PalFunctionRGB (ID 16): Applies a linear transformation over 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 corresponds to the red channel
- G corresponds to the green channel
- B corresponds to the blue channel
Note: This effect is not implemented yet.
PalFunctionHSL (ID 17): Applies a linear transformation over 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 corresponds to hue.
- S corresponds to saturation.
- L corresponds to lightness.
Note: This effect is not implemented yet.

File Format

Palette effects use a JSON-based format:

{
  "Name": "BowserCharge",
  "Effects": []
}

Where:

Name: Corresponds to the effect name.
Effects: Contains the list of effects used and may use either of the 2 effect formats, simple or generator.

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, Channel3 correspond to the main channel values.
- For RGB effects:
  - 1 = R
  - 2 = G
  - 3 = B
- For HSL effects:
  - 1 = H
  - 2 = S
  - 3 = L
The Ratio values represent the interpolation ratios used by their respective channels.
EffectType corresponds to the effect ID being used.

Generator Format

There is also a format used to automatically generate multiple interpolated effects:

{
  "StartC1": 31,
  "StartC2": 0,
  "StartC3": 0,
  "StartR1": 64,
  "StartR2": 64,
  "StartR3": 64,

  "EndC1": 0,
  "EndC2": 0,
  "EndC3": 0,
  "EndR1": 64,
  "EndR2": 64,
  "EndR3": 64,

  "Steps": 5,
  "EffectType": 0
}

This format allows defining:

An initial state.
A final state.
The number of intermediate steps.

Dynamic Xtreme automatically generates all effects required to perform the transition between both states.

Value Ranges

Channel values (Channel) use ranges between 0 and 31.
Ratio values (Ratio) use ranges between 0 and 127.

DynamicInfo

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

These files have 2 main purposes:

Include dynamic resources into the ROM.
Define which graphics correspond to dynamic sprites and how each pose should be loaded.

The basic structure of a `DynamicInfo` file is the following:

PosesGraphics:
    MyGraphics.bin
    AnotherGraphics.bin

Palettes:
    MyPal.bin
    AnotherPal.bin

Resources:
    MyResource.bin
    AnotherResource.bin

These sections work as lists of dynamic resources that will be included by Dynamic Xtreme.

PosesGraphics contains graphics files for dynamic sprites. These must use the *.bin format.
Palettes contains color palette files. Currently they use the *.bin format, although support for *.pal files is planned for the future.
Resources allows including arbitrary dynamic resources and has no specific format restrictions.

In the case of PosesGraphics, when multiple graphics files are used, all of them are internally combined into a single large graphics block following the order in which they were declared.

Later, each pose is cropped from that combined data and stored inside the ROM in the most convenient way possible for the dynamic system.

Because of this, there is no important practical difference between:

Using a single large graphics file.
Using multiple smaller graphics files.

Both approaches will produce the same internal result inside Dynamic Xtreme.

In addition to these resource lists, DynamicInfo files also contain the definition of the dynamic poses used by the sprite.

The way these poses are defined depends on the format used by the resource:

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

Current Format

The modern format was designed to simplify the creation and maintenance of dynamic sprites.

In this format, the user only needs to specify how many 16x16 tiles each pose uses. Dynamic Xtreme automatically processes the graphics and internally converts them into the optimized format used by the dynamic system.

Example:

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

In this example:

Pose0 uses 5 16x16 tiles.
Pose1 uses 7 16x16 tiles and additionally one top half (16x8).
Pose2 through Pose6 use 4 16x16 tiles.

The format also allows the use of modifiers to represent partial tiles:

q: Top-left 8x8 tile.
h: Top half (16x8).
q3: Top half + bottom-left tile (16x8 + 8x8).

This makes it possible to include a 16x16 tile containing partial graphics. These partial tiles do not support every possible combination, since many of them are not practical for the system. Only the most common and useful configurations are considered.

Internally, Dynamic Xtreme automatically transforms this format into the legacy format, since that format is optimized for performing DMA transfers to VRAM more efficiently.

Legacy Format

The legacy format uses a table called PosesChunksSizes, which manually defines how dynamic graphics should be internally organized.

Example:

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

Each pose contains a subtable composed of 2 values.

The idea behind these values is to represent how many DMA routines would be required to transfer the pose graphics into VRAM under ideal conditions, meaning assuming the sprite is aligned at the beginning of the VRAM sprite section. In practice, ideal conditions usually require 1 or 2 DMA routines.

Most of the time, the first DMA routine transfers a larger amount of data than the second one.

Each of the 2 values represents the amount of 8x8 tiles transferred by each DMA routine.

For example:

db $02,$02

Means:

the first DMA routine transfers 2 8x8 tiles
the second DMA routine transfers another 2 8x8 tiles

In special cases where the sprite uses an amount of 16x16 tiles that perfectly fills rows inside VRAM (for example multiples of 8 16x16 tiles), it is possible to perform the entire transfer using a single DMA routine. In those cases, the second value is defined as $00.

This format was replaced by the current format because it was complex and unintuitive for most users. Currently, using NumberOf16x16TilesPerPose is recommended, although the legacy format remains fully supported and still provides more flexibility for advanced use cases.

DrawInfo

DrawInfo files are stored inside the DrawInfos folder and use the "*.dynamicinfo" extension and contain all the information required to draw poses on screen.

Internally, Dynamic Xtreme collects this information and automatically generates optimized graphic routines. Each graphic routine groups multiple poses that share similar characteristics and is specifically optimized for that type of pose. This allows not only a global pose rendering system, but also a highly efficient system in a large number of cases.

To understand how DrawInfo files work, it is necessary to understand at a high level how SNES OAM works.

OAM is a special memory used to store sprite information. In the case of SMW, it works using 8x8 and 16x16 tiles.

Each tile contains the following attributes:

TileCode: sometimes simply called Tile, corresponds to an internal ID used by the console to indicate which specific VRAM graphic should be used.
Note: When working with dynamic sprites, TileCodes must be defined assuming the sprite was loaded at the beginning of the sprite section in VRAM.
Dynamic Xtreme automatically adjusts these values internally depending on the actual position where the pose was loaded into VRAM during runtime.
Properties: corresponds to a byte containing special tile properties. This byte uses the following format:
- YXCCPPPT
Where:
- Y: indicates whether the tile is vertically flipped.
- X: indicates whether the tile is horizontally flipped.
- CC: tile priority relative to layers (higher value = higher priority).
- PPP: sprite palette used (000 => palette 8, 001 => palette 9, ..., 111 => palette F).
- T: indicates which graphics page to use (0 => SP12, 1 => SP34).
Note: It is possible to define global Properties for all tiles of a pose or sprite. Because of this, the most important properties inside DrawInfo files are usually Y, X, and T, while CC and PPP are generally configured from the code that calls the system.
In the specific case of dynamic sprites, the T property usually does not need to be manually configured, since Dynamic Xtreme automatically detects which graphics page the pose belongs to and configures this bit automatically.
Size: defines the tile size:
- $00: small tile (8x8).
- $02: large tile (16x16).

Additionally, each tile contains:

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

These values allow the tile to be moved relative to the sprite's base position.

Currently, Dynamic Xtreme supports 2 DrawInfo formats: the current format and the legacy format.

Current Format

The current DrawInfo format was designed to significantly improve readability and ease of maintenance for drawing files.

Unlike the legacy format, this system allows:

Grouping multiple poses.
Grouping tile ranges.
Using per-tile 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: Defines shared information for poses 0 through 4 using the name "MyPose".
.NumberOfTiles: Defines that each pose uses 5 tiles.
.TileCode2: Modifies the TileCode only for tile 2.
.TileCode3..4: Modifies the TileCode for tiles 3 and 4.
.Properties: Defines an individual Properties list for each tile.
.XOffsets: Defines an individual XOffset for each tile.
.YOffset2..4: Modifies the YOffset only for tiles 2 through 4.
.Size0..4: Defines the size of tiles 0 through 4.

Directives used in singular form allow modifying a specific tile or a specific range of tiles.

Examples:

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

In these cases:

.TileCode2:: Modifies only tile 2
.TileCode3..4: Modifies only tiles 3 and 4
.YOffset1..3: Modifies the YOffset of tiles 1 through 3

On the other hand, plural directives allow explicitly defining a complete list of values for all tiles in the pose.

Examples:

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

In these cases:

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

This allows combining simple general configurations with specific modifications only where needed.

When a value is not explicitly defined, Dynamic Xtreme automatically uses default values:

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

Unlike the legacy format, these default values work individually per tile, allowing only the necessary information to be omitted without affecting the rest of the pose.

The XPivot and YPivot values are used as rotation axes for performing horizontal or vertical flips on a pose. These values allow tile positions to be automatically recalculated when using the X or Y properties.

If XPivot is not defined, the pose will not be considered compatible with horizontal flipping. Likewise, if YPivot is not defined, the pose will not be considered compatible with vertical flipping.

This allows Dynamic Xtreme to generate more optimized graphic routines when these features are not needed, while also slightly reducing ROM space usage.

It is also possible to use:

.IsStatic

This indicates that the defined poses should be treated as static poses instead of dynamic ones. By default, all poses are treated as dynamic.

The legacy DrawInfo format remains fully supported. The modern format mainly exists to simplify the writing, reading, and maintenance of DrawInfo files while still maintaining a high level of flexibility.

Legacy Format

The legacy DrawInfo format uses multiple separate tables to define each attribute of the tiles used by a pose.

This format was designed following a structure similar to the one normally used when writing manual graphic routines for SNES sprites. The original idea was that people already familiar with developing sprites this way could work with DrawInfo using an organization that felt familiar and relatively intuitive for that traditional workflow.

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 uses an independent section.
Each pose requires a separate subtable.
All values must be manually written.
Tile ranges and pose grouping do not exist.

The main tables correspond to:

Tiles: TileCodes
Properties: OAM Properties
XDisplacements: Horizontal displacements
YDisplacements: Vertical displacements
Sizes: Tile sizes (8x8 or 16x16)

In the case of XDisplacements and YDisplacements, it is also possible to define flipped versions:

XDispFlip
YDispFlip

These tables allow manually specifying the offsets used when a pose is drawn using horizontal or vertical flip.

The directive:

Dynamic: true

Indicates that the poses should be treated as dynamic poses. If defined as false, the poses will be considered static.

Just like in the modern format, automatic default values also exist. If a table does not exist, Dynamic Xtreme will automatically assume the following values:

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

This format remains fully compatible with Dynamic Xtreme, although the modern format is currently recommended since it is considerably more readable, maintainable, and easier to edit.