The REXPaint import module

REXPaint logo

The REXPaint import module can initialize an Object from one or many .xp files. REXPaint is a popular text-art editor for Windows, available for free on gridsagegames.com. (Should run fine on Wine)

When enabled, an additional zlib dependency will be added to the project. The download and build will be performed automatically by the Hunter package manager. A pre-existing distribution of zlib will probably not be suitable, as the module requires some custom build parameters.

Tip

If you find the plaintext manual a bit hard to read, I’m maintaining an unofficial markdown edition. Contributions welcome!

The REXPaint+VisualT workflow

REXPaint needs some configuration in order to reach an optimum level of productivity. We’ll set everything up with the help of the Font Atlas Generator webapp, which I wrote for the purpose.

1. Create a new font atlas

  • Choose a reference font to design your Sprites. You could use the default font of your System’s terminal, or a readily available one. The generator uses DejaVu Sans Mono as default, which is the default font of the Ubuntu terminal. The only requirement is that it must be a monospaced font.

  • On the generator app, define the charset (glyph palette) you want to use. Avoid making the character set too large or it’ll become awkward to use. The font atlas must be 16 columns wide. The generator creates square cells by default. While that can be appropriate for bitmap artworks, you’ll notice that everything looks squashed horizontally once exported to actual text (just see what happens to the VTCat in the examples!). That’s because most font’s glyphs are taller than wide. Try to find a compromise between fidelity and usability.

  • Click on the save image and export charset for REXPaint buttons to save the output.

2. Add the font to REXPaint (also explained in the REXPaint manual)

  • Move to REXPaint’s root dir.

  • Move the two downloaded files to data\fonts.

  • Open _config.xt with a text editor, the file contains a two-sided text table: GUI on the left and Art on the right. We’ll operate on the Art side. Add a new row by copy-pasting the CP437 16x16 line, and change the Set Name field as desired. Replace the contents of the File field with your atlas’ file name, and update the Columns and Rows values.

  • If you want, you can also replace the Unicode field with the file name of your charset file. Since REXPaint is a bitmap editor, it does not store any associations between font tiles and their corresponding character, not even in the .xp files. You can provide that data yourself by specifying a charset file. That’s also the reason why VisualT requires a charset file to import .xp files.

CMake specs

conditions

VisualT_XP_IMPORTER

targets

VisualT_xp_importer

components

VisualT_xp_importer

dependencies

VisualT_runtime

See more on Build instructions.

API

enum VTXpLoadMode

This enumerator is meant to be used with vtInitializeXp() .

.xp files are made up of n layers of equal size, which together form an image. This structure is similar to the one used by Objects, where each layer corresponds to a Sprite. The only difference is that Sprites can be of different sizes, while layers cannot. This is why the module can work in two modes:

Values:

enumerator VT_XP_FILES

One Sprite per file: each Sprite is constructed from a different .xp file. This mode allows you to use layers normally in REXPaint, and also to have differently sized Sprites. The downside is that it requires one .xp file per Sprite.

enumerator VT_XP_LAYERS

One Sprite per layer: each Sprite is constructed from a different layer of the same .xp file. This mode allows you to use a single .xp file. The downside is that editing in REXPaint can be less convenient and all Sprites will be the same size.

int vtInitializeXp(VTObj *obj, VTXpLoadMode loadMode, FILE *restrict mapFile, unsigned int filesLength, FILE *restrict const *files)

Initializes *obj from one or more .xp files.

.xp files are created by the REXPaint text-art editor. You may pass one or more files depending on loadMode. You also need to pass a charset file mapFile.

Return

A value < 0 if the operation failed. An attempt is always made to close mapFile and all files, even in case of failure, where *obj is left uninitialized.

Parameters

  • obj: a pointer the Object to initialize

  • loadMode: selects the conversion mode

  • mapFile: a pointer to the charset file that will be used to map tiles indices to their corresponding character

  • filesLength: the length of files. In VT_XP_LAYERS mode must be 1.

  • files: an array of pointers to .xp files