Formats - haven1433/HexManiacAdvance GitHub Wiki

The heart of HexManiacAdvance rests in what data formats it's capable of understanding. These can be as simple as the text in the games, or as complex as compressed tilemaps that depend on tilesets and palettes elsewhere in the ROM. This page intends to list all the available formats, their specifier, and additional information about them.


Pokemon Character Set

Format Specifier: ""
Example: ^""

Most text in the game is formatted this way. The text ends with FF. The format can optionally end with a number when used in a table, which makes the text always use that many bytes. Pokemon Character Set example While most anchors require names, text is an exception: because there are just so many blobs of text in the game, and often a pointer in a table will point to text, it's perfectly fine to have an anchor to text that is missing a name.


Format Specifier: `asc`{length}
Example: ^data.header.romname`asc`32

A little text in the header uses ASCII. The ASCII format is also included since many other types of files use it.

ASCII example


Tables are extremely important, because they can contain related data of mixed length that can all be referred to together as a single element.

Raw-Length Table

Format Specifier [{element content}]{length}
Example ^data.pokemon.names[name""11]412

Raw tables have a fixed length. You can extend them, but their length is just a simple number.

Raw table example

Matched-Length Tables

Format Specifier [{element content}]{name}{+offset}{-offset}
Example ^graphics.pokemon.sprites.front[sprite<`lzs4x8x8`> uncompressedLength: index:]data.pokemon.names+28

Matched-Length tables have a length that depends on another table. This effectively links the tables together, allowing HexManiacAdvance to know that the tables have related data. Note that tables can have a linked-length without the length being the exact same: there can be a + or - factor after the name.

Matched Table example

Stream Tables

Format Specifier [{element content}]!{End Token}
Example ^graphics.overworld.palettes[pal<`ucp4`> id:|h unused:]!0000000000000000

Stream tables continue until the end token is found.

Stream Table example

Image formats

Image formats all follow a common pattern: {compression}{type}{bits}{size}{dependency} This can get a bit confusing, so let's break it down.

  • compression: if the format is for compressed data, it'll start with lz. If it's for uncompressed data, it'll start with uc.
  • type: (p) for palette, (s) for sprite, (t) for tileset, and (m) for tilemap.
  • bits: 4 if it uses 16 colors, 8 if it uses 256 colors. Special images also use 1 when they only use 2 colors (such as footprints) or 2 when they only use 4 colors (such as fonts).
  • size: for sprites and tilemaps, the size is specified as WxH, such as 6x4. The width is measured in tiles, which are 8x8 blocks of pixels. So a typical pokemon front sprite would be 64x64 pixels, which is 8x8 tiles.
  • dependency: sprites and tilesets may optionally include the name of a free palette, palette table, or palette field within the same table. This will cause HexManiacAdvance to always use that palette when displaying the sprite or tileset. Tilemaps may optionally include the name of a free tileset, tileset table, or tileset field within the same table; this will cause HexManiacAdvance to always use that tileset (and it's palette, if it has one) when displaying the tilemap.

That's a lot of details, so examples are shown below.

Compressed Palettes

Format Specifier lzp4
Example ^`lzp4`

Uncompressed Palettes

Format Specifier ucp4{:pages}
Example ^graphics.titlescreen.pokemon.palette`ucp4:D`

The 'pages' part of the format tells HexManiacAdvance both how many pages the palette has (how many sets of 16 colors), as well as a hint for where the game loads that palette in color space. This matters for tilemaps and tilesets that use the palette, since the tilemap has to track which tiles use which palettes. There are 16 pages, 0 through F.

Compressed Sprites

Format Specifier lzs4x{width}x{height}{|palette}
Example ^graphics.bag.male`lzs4x8x8|graphics.bag.palette`

Note that the amount of data in the compressed sprite can actually be any multiple of the width-height chosen: this effectively splits the sprite into 'pages', where each page has the width/height that you specified. In the case of this example, each backpack image is actually 8 tiles wide and 8 tiles tall, but the actual sprite sheet contains 4 different backpack images. HexManiacAdvance will automatically calculate the number of pages in a compressed sprite sheet based on the width/height that you choose.

Uncompressed Sprites

Format Specifier ucs4x{width}x{height}{|palette}
Example ^graphics.items.fossils.sprite1`ucs4x8x8|graphics.items.fossils.palette1`

Compressed sprites are allowed to have multiple pages, but uncompressed sprites are not: the data that you specify will all show up in a single view.

Compressed Tilesets

Uncompressed Tilesets

Compressed Tilemaps

Uncompressed Tilemaps

Special use formats

Level-Up moves

Pokemon Trainer Teams

Overworld Sprite Lists

⚠️ ** Fallback** ⚠️