Reskit level Tool
❌ level is intended for internal use and no issues or pull requests will be accepted for it. It is only available on the stinkhead7ds branch.
This document details some approaches for implementing the level tool.
What is level?
level is a tool for reskit that converts Tiled Map Editor tilesets and maps to a binary format accessible to C or assembly language engines. It distinguishes itself from other available homebrew tools by offering support for Tiled's native tmx/tsx XML formats, and user-specified object definitions.
Converting a Tiled Map Editor Module with level
To convert a Tiled map and tileset:
reskit level -i map.tmx --console md
Reskit will compile and output multiple level-related artifacts (depending on --console setting) which you can then bundle into your game project.
Graphics Layers
The string property reskit-layer set on a Tile Layer indicates which layer should be applied to which hardware layer in your system of choice.
Valid Options Per Console
--console md
Layers and Tile Size
a/Afor Plane Ab/Bfor Plane B
Tile layers without reskit-layer set are ignored by the level tool. If no tile layer is specified using the reskit-layer property, or you use a setting invalid for the selected system, you will receive an error on the command line. Ensure both your tilemap and tileset are set to 8x8 tiles, or you will get a validation error upon running level.
Tile Order
Use property reskit-tile-order to assign a tile order when loaded into VRAM. Valid options are sprite and tile. These match the sprite and tile orders expected by the MD VDP.
Palette Assignment
Per tile in the tileset, you can use property reskit-palette to assign a palette to each tile. Care should be taken not to exceed 15 colours per tile in total.
Objects
Object layers let you define what objects are in the map. Objects may be players, items, triggers, and are identified by the reskit-object-id attribute, which will correlate with an id provided by you in argument --symbol-ids. Use reskit-field[x] to define the value for a given field, specified by --fields.
Artifact File Formats
.bin Format (Tiles)
This is a system-specific binary format of tiles formatted for your target system. Normally you would take this data and DMA it to the VRAM in your homebrew.
--console md
- Output format is identical to
tilesetminus the palette. One .bin file is output by default, as only one tile set per Tiled Editor tilemap is currently supported. (For background layers with different tiles than foreground tiles, combine foreground and background tiles into the same set.)
.pal Format (Palettes)
These are the palettes accompanying the tiles output above.
--console md
- Output format is PAL0 through PAL4 as generated per the user's
reskit-palettesettings in the tilemap. DMA these directly to CRAM.
.map Format (Tile Map)
While the above format contains the graphics, this contains the nametable settings for each layer i.e. pointers to entries in the above list of tiles for each region of the screen. Normally you would take this data and DMA it to the VRAM in your homebrew, where the pattern map nametable is set.
--console md
- This contains entries in VDP nametable format, in tile layer B followed by tile layer A, sized according to your settings in Tiled Map Editor. DMA this to the nametable location in each respective layer.
.lvc Format (Level Collision Map)
The collision map contains bounding boxes drawn in Tiled editor that your map can check against each iteration of the game loop.
2 bytes: Number of bounding boxes
For (Number of bounding boxes):
2 bytes: X dimension
2 bytes: Y dimension
2 bytes: X2 dimension (x + width)
2 bytes: Y2 dimension (y + height)
.spt Format (Sprite Table)
The Sprite Table contains a mapping of sprites to tile indices, as well as their tile dimensions and number of animation frames.
2 bytes: Number of Sprites
For (Number of Sprites):
2 bytes: Sprite ID
2 bytes: Tile index location (in tiles.bin)
1 byte: Sprite Width (tiles)
1 byte: Sprite Height (tiles)
2 byte: Palette used for tiles
2 byte: Number of animation frames
2 byte: Animation speed (in 1/60 of a second)
.obs file (Objects)
This file contains a large array of object structs as defined by the --fields option.
2 bytes: Number of objects
2 bytes: Size of object struct (number of 16-bit fields)
For (number of objects):
For (number of 16-bit fields):
2 bytes: Field in order defined by --fields option