Dynamic X

English

Português

Español

日本語

Dynamic X is an advanced dynamic load management system whose purpose is to support the transfer of graphics and color palettes to the VRAM and CGRAM respectively. This system would replace Dynamic Z V3.7 which in turn is a replacement for DSX.

Download

• Dynamic X Website

Features

• Load Poses Dynamically: Allows to load poses for Dynamic Sprites from any ASM code.
• Draw Poses: Allows to draw any pose that is registered in the system anywhere on the screen and from any ASM code. The way of drawing is totally optimized for each pose, basically all the poses that have similar characteristics, use the same graphic routine to optimize cycles and to make it as efficient as possible, besides diminishing considerably the amount of ROM used in graphic routines, since, 1 graphic routine can draw hundreds of different poses that belong to different Sprites.
• Load Graphics to VRAM.
• Load Color Palettes to the CGRAM.
• Automatic Palette Assignment: When a Sprite loads a palette, it can ask the system to assign a palette in an automated way, it will look for a free palette and it can be used by the Sprite, in case the palette is already loaded in the loaded CGRAM then it will give the Sprite that palette. The system informs if there are no palettes available, this way, you can avoid that the Sprite tries to work with wrong palettes.
• Color Palette Effects: You can edit the palettes that are loaded to change attributes such as Hue, Saturation and Brightness, you can weight them with a preset color or de-power certain RGB or HSL channels.
• Registration of Graphics and Palettes: The system allows you to insert graphics and palettes in the ROM, when you do so, the position in which they were saved in the ROM are available and you can also know the ID with which it was registered in the system, you can use that ID to dynamically load those graphics. Dynamic X will take care of deleting the graphics and palettes previously saved by the system and insert the new graphics and palettes in a free place in the ROM.

Features that may have compatibility issues

• Custom Player Graphics: Dynamic X allows you to either change the player graphics using an EXGFX similar to GFX32 being limited to use the size and number of poses of the Vanilla game or simply disable completely the dynamic loading of player graphics, yoshi or podoboos to make your own dynamic routine for a custom player without limitations of size or number of poses. This feature allows you to change the graphics at any time, so you could use different players in different levels or in different areas of the same level.
• Player Custom Palettes: Dynamic X allows you to change the player's color palette freely.
• Player DMA optimizations: Dynamic X decreases considerably the cycles used by the NMI handler, since, the player graphics, yoshi and podoboos are only loaded in the VRAM when they are required, not always as it happens in the Vanilla game. This also leaves you some extra tiles in SP1 in levels that don't use yoshi or podoboos, even an extra tile in levels that don't use the layer.

Prerequisites

• .Net 7 x86

Installation

General Steps

Before installing Dynamic X.

1. The ROM must have SA-1 Pack installed.
2. Put all files with ".drawinfo" extension in the "DrawInfo" folder.
3. Put all files with ".dynamicinfo" extension in the "DynamicInfo" folder.
4. Put all files with ".paleffect" extension in the "PaletteEffects" folder.
5. Put all resource files such as GFXs and Color Palettes with ".bin" extension in the "DynamicResources" folder.

Using the Tool Directly

You can install Dynamic X by opening the file "DynamicXTool.exe", it will open a console telling you what to type at any given moment. It will start asking you for the ROM paths, Pixi folder, UberasmTool or GPS (these last 3 are optional) and then it will ask you for the features you want to install, put "y" or "yes" to enable each feature and "n" or "no" to disable that feature. Warning: Features such as Player Features and Status Bar Optimization, may have incompatibilities with other resources, so you should be careful when installing them. Be careful which features you install.

Using the Tool From Console

You must call the command:

DynamicXTool -use-settings

The ROM will install with the default settings if you have never done a previous installation, if you have done a previous installation, then the settings used in that installation will be used.

Settings

In case you want to change the settings manually you must open the settings.json file that will look like this:

{
  "InputROMPath": "",
  "OutputROMPath": "",
  "PixiPath": "",
  "UberasmToolPath": "",
  "GPSPath": "",
  "GraphicChange": true,
  "PaletteChange": true,
  "PaletteEffects": true,
  "DynamicPoses": true,
  "DrawingSystem": true,
  "ControllerOptimization": true,
  "FixedColorOptimization": true,
  "StatusBarOptimization": false,
  "ScrollingOptimization": true,
  "PlayerFeatures": false
}

You must change the parameters according to the settings you want.

Formats

Dynamic Info

Files with extension ".dynamicinfo" are used to insert pose graphics, palettes and other resources into the ROM. They also include the information necessary for the poses to be loaded correctly into the VRAM.

The format of these files is as follows:

PosesGraphics:
	...
Palettes:
	...
Resources:
	...
PosesChunksSizes:
	...

• PosesGraphics: Below this label goes each graphics file used to load dynamic poses. Example:

PosesGraphics: 
	DKCKlaptrap.bin

• Palettes: Below this label goes each color palette file used for dynamic poses. Example:

Palettes:
	DKCKlaptrapPal1.bin
	DKCKlaptrapPal2.bin
	DKCKlaptrapPal3.bin
	DKCKlaptrapPal4.bin
	DKCKlaptrapPal5.bin

• Resources: Below this label goes each extra file that is used as a resource and that you want to insert into the ROM. Example:

Resources:
	Geno.bin
	GenoPal.bin
	FireGenoPal.bin
	GenoPalPlayer2.bin
	FireGenoPalPlayer2.bin

• PosesChunksSizes: Below this label goes 2 lines for each pose, the first line is a label describing the pose and the second line is 2 values, each of these values indicates how many 8x8 tiles are used in each chunk, each dynamic pose has 2 chunks of data generally (except some exceptions that may require only 1 chunk), the top chunk and the bottom chunk. The top chunk is all the 8x8 tiles that are before the last 8 pixels high line, while the bottom chunk is the last line. In the following example you can see 3 images, the left one is how the assembled image should look like, the second one is how it would look like in the VRAM and the third one is how it would be saved in the binary file, it would also show how the poses sizes of that pose are, which in this case would be 8 tiles of the top chunk and 8 tiles of the bottom chunk:

PosesChunksSizes:
Frame0_PoseChunksSizes:
    db $08,$08

Note: For poses whose number of 8x8 tiles is divisible by 16, you can use only the top chunk that has all the tiles and the bottom chunk would be 0. For Example if you have:

PosesChunksSizes:
Frame0_PoseChunksSizes:
    db $10,$10

You can use:

PosesChunksSizes:
Frame0_PoseChunksSizes:
    db $20,$00

This is better because can use less DMA Transfers. Also the second number never can be higher than $0F.

Draw Info

The files with extension ".drawinfo", have the necessary information to draw poses, these poses can be dynamic or static poses. Dynamic X uses these files to generate optimized graphic routines for each pose, the tool detects if one of the tables is necessary or not, eliminates redundant data, pigeonholes each pose in a group that shares similar characteristics and then inserts a graphic routine for each group of poses that share similar characteristics. The file format is as follows:

Dynamic: 
	...
Tiles:
	...
XDisplacements:
	...
YDisplacements:
	...
Sizes:
	...
Properties:
	...

• Dynamic: If true it is dynamic, if false it is static, example:

Dynamic: 
	true

• Tiles: It is a table that indicates which tiles each pose uses, in the case of the dynamic poses it must be considered that the tile of more superior to the left is the tile $00, this table contains 2 lines for each pose, the first line is PoseName_Tiles: and the second line would be each one of the tiles used by the pose This table is optional and in case it is not, it will use the value $00 for the tiles of the pose. This table is optional and in case it is not present, it will use the value $00 for the tiles of the pose. The following example draws 4 tiles forming a 32x32 pose:

Tiles:
Pose32x32_Tiles:
    db $00,$02,$04,$06

• XDisplacements: It is a table that indicates the horizontal displacement of each tile with respect to the pose position and contains 2 lines for each pose, the first line is PoseName_XDisp: and the second line is a value for each tile of the pose indicating how much should move horizontally each tile with respect to the pose position, additionally you can add 2 more lines for each pose for when the pose is flipped horizontally, the format is the same as the previous 2 lines only that the first line is PoseName_XDispFlipX:. This table is optional and if it does not exist, it will use the value $00 for the pose tiles.The following example draws 4 tiles forming a 32x32 pose and allowing horizontal flipping. The following example draws 4 tiles forming a 32x32 pose and allowing horizontal flipping:

XDisplacements:
Pose32x32_XDisp:
    db $00,$10,$00,$10
Pose32x32_XDispFlipX:
    db $10,$00,$10,$00

• YDisplacements: It is a table that indicates the vertical displacement of each tile with respect to the pose position and contains 2 lines for each pose, the first line is PoseName_YDisp: and the second line is a value for each tile of the pose indicating how much should move vertically each tile with respect to the pose position, additionally you can add 2 more lines for each pose for when the pose is flipped vertically, the format is the same as the previous 2 lines only that the first line is PoseName_YDispFlipY:. This table is optional and if it does not exist, it will use the value $00 for the pose tiles.The following example draws 4 tiles forming a 32x32 pose and allowing vertical flipping. The following example draws 4 tiles forming a 32x32 pose and allowing vertical flipping:

YDisplacements:
Pose32x32_YDisp:
    db $00,$00,$10,$10
Pose32x32_YDispFlipY:
    db $10,$10,$00,$00

• Sizes: Is a table indicating the size of each tile used, each value is $00 for 8x8 tiles and $02 for 16x16 tiles. It contains 2 lines for each pose, the first line is PoseName_Sizes: and the second line is a value for each tile of the pose indicating the size of each tile. This table is optional and in case it does not exist, it will use the value $02 for the pose tiles. The following example draws 4 tiles forming a 32x32 pose:

Sizes:
Pose32x32_Sizes:
    db $02,$02,$02,$02

• Properties: Is a table indicating the properties of each tile, the properties follow the format YXCCPPPT, where X is if the tile is flipped horizontally, Y is if the tile is flipped vertically, CC is the priority with respect to layer 1 and layer 2, where 00 is the lowest priority and 11 is the highest, CCC is the color palette used by the tile and T is 1 for using SP3/SP4 and 0 for SP1/SP2. It contains 2 lines for each pose, the first line is PoseName_Sizes: and the second line is a value for each tile of the pose indicating the property of each tile. This table is optional and in case it does not exist, it will use the value given in the !PropParam for the pose tiles. The following example draws 4 tiles forming a 32x32 pose:

Properties:
Pose32x32_Properties:
    db $20,$20,$20,$20

Palette Effect

The files with extension ".paleffect" are json files that are used for multiple color palette effects, both global and normal, these files can be created using the tool "Palette Effect Creator" that is included with Dynamic X. The format of these files is as follows:

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

• Name: This is the name of the color palette effect set. Example:

  "Name": "DecreaseSaturation",

• Effects: It is a list with each of the color palette effects, these have 7 parameters, the first 3 are Channel1, Channel2 and Channel3 which are values between 0 and 31 that indicate the value of each channel, in the case of an RGB effect, Channel1 is R, Channel2 is G and channel3 is B, in the case of an HSL effect, Channel1 is H, Channel2 is S and Channel3 is L, then come 3 more values, the Ratio1, Ratio2 and Ratio3, each of these is a number between 0 and 31 indicating how much each Channel affects the colors of the color palette, where 0 is that it affects 0% and 31 is that it affects 100%, finally Channels is to indicate whether it is an RGB or HSL effect, 0 is RGB and 1 is HSL. The following example shows 2 HSL effects that decrease saturation:

  "Effects": [
    {
      "Channel1": 0,
      "Channel2": 0,
      "Channel3": 0,
      "Ratio1": 0,
      "Ratio2": 30,
      "Ratio3": 0,
      "Channels": 1
    },
    {
      "Channel1": 0,
      "Channel2": 0,
      "Channel3": 0,
      "Ratio1": 0,
      "Ratio2": 31,
      "Ratio3": 0,
      "Channels": 1
    }
  ]

Palette Effect Creator

You can find the tool on the official Dynamic X website:

• Palette Effect Creator