tools reference

Version 1.1.12


These are some tools written in Python that are required to build the example game and can be used in new projects.

This reference should complement both the command line help available in all tools (with -h flag), and the example game itself.

Data conversion tools

This tool converts an image in PNG RGB image into a tileset of up to 256 tiles.

The image is expected to use an approximation to RGB for the colours in the Toshiba palette.

Palette index RGB value Notes
0 255, 0, 255 Transparent
1 0, 0, 0
2 102, 204, 102
3 136, 238, 136
4 68, 68, 221
5 119, 119, 255
6 187, 85, 85
7 119, 221, 221
8 221, 102, 102
9 255, 119, 119
10 204, 204, 85
11 238, 238, 136
12 85, 170, 85
13 187, 85, 187
14 204, 204, 204
15 238, 238, 238

Any other colour will result in an error converting the image.

The tool ensures that the tiles follow the screen 2 mode restrictions: 2 colours per line on each 8x8 tile.

By default the generated file will include a colour map, with ID_colors as identifier (if the default “tiles” is used, the table will use tiles_colors).

The colour table can be omitted using the --no-colors flag.

Example of use: tiles.png > tiles.h

This will result in a C include output. To generate assembler, use --asm flag.

The output can be used with ubox_set_tiles and ubox_set_tiles_colors, and the rest of the tiles functions.

This tool converts a PNG RGB image that is a multiple of 16x16 into a sprite (or sprites), to be used by ubox’s sprite functions.

The result is 1 bit per pixel data without colour information. The colour will be provided as part of the attr field in the sprite_attr struct when calling ubox_set_sprite_attr.

The tool interprets dark grey (RGB: 28, 28, 28) as transparent in the MSX palette, and any other colour will be used as visible monochrome data. If the image has more than one colour, it will be used to identify different sprites.

For example:

Example sprite with 2 colours per frame

Will be translated into 6 sprites: 3 frames (16x16) with 2 sprites per frame, corresponding to the sprite defined by the green colour and the sprite defined by the white colour.

Usage following the example: -i player_sprite player.png > player.h

This is a map importer to use with tiled JSON format.

The map importer supports:

Map requirements

The map file is expected to follow this conventions:

Please check map.json of the example game for a reference.


The map importer requires a configuration file in JSON format that provides information about the valid entities in the map.

For each entity it expects:

This allows the tool to validate the map and ensure that:

Please check data/map_conf.json in the example game for an example.


Tiled doesn’t have support to define rooms in a big map, so this importer will split the map in rooms of a specific size (32x24 tiles by default), translating the information of any entity on that area.

The map size must be multiple of the room size and the result will be a number of rooms to be used independently by the game.

Each of these rooms will have the following structure:

Size Description
2 bytes map data length (0 for empty map, and no more data will be included)
1 byte entities length in bytes, including the terminator byte (0xff)
n bytes map data (n-bit per tile, default 8-bit), may be compressed
m bytes entity data (ends with 0xff)

The output by default is a C include file.

For example: --aplib map.json rooms > rooms.h

Will generate an include file with a rooms array pointing to the generated rooms. In this case, the output is compressed with aPLib.

The include by default will not include the data if LOCAL is undefined. It should be included as follows in one C module:

/* in data.c for example */
#define LOCAL
#include "rooms.h"
#undef LOCAL

Refer to the example game and run_game() in game.c for a full example.


Entities are defined in the Entities layer by using rectangle objects.

The expected properties are:

In “Custom properties” the map importer supports:

The entities are encoded as 3 bytes by default, as follows.

Byte Description
t MSB is set if param is 1, the rest (7 lower bits, from 0 to 127) is the index of the entity in the configuration file
x x position in the room, in pixels
y y position in the room, in pixels

If the entity has the fixed property, an extra byte is added with the width or height (whatever is bigger) in tiles. This can be used for entities that cover an area, for example a moving platform. The example game doesn’t use this property.

The entities are encoded in a stream that ends with the byte 0xff as terminator.

Refer to the example game and init_map_entities() in game.c for a full example.

This is a simple tool to make CAS files to be used in different MSX emulators.

It supports the following block types:

Use -h flag to get command line help, and check the example game for sample on how to build a CAS file with a loading screen.

This tools converts an PNG RGB image into a Screen 2 SCR image.

The image is expected to use an approximation to RGB for the colours in the Toshiba palette (see for the palette values).

The image must be 256x192 pixels.

The SCR file is 768 background tiles (6144 bytes) followed by the background colours for the 3 areas of the screen (6144 bytes), that can be uploaded to the VDP “as is”.

Check the example game for a sample on how to use it.

Build helpers


This tool is used to calculate how much much space in the DATA and CODE sections is used by the game.

It takes three parameters:

For example:

chksize 8000 4000

Has the output:

ROM: CODE  11430 bytes
     INIT  00016 bytes
     Total 11446 bytes
RAM:       01256 bytes

If the CODE + INIT (ROM) or the DATA (RAM) is over the provided limits, the tool will report it with an error.

This is a wrapper around sdcc -MM to automatically generate a Makefile.deps with the dependencies to build a project.

This ensures that only the required files are compiled when there is a change in the project, reducing the compilation time during development.

See game/Makefile for an example.

Copyright © 2020-2022 Juan J. Martinez (jjm at
Licensed CC BY NC SA 4.0.