Config file

This page describes what the configuration file can and/or must contain.

Tip

It may be useful to follow the demo project's config file as a reference, too.

Unless otherwise specified, all of these can be defined in any order.

“Environment” definition

gb-vwf tries to avoid being opinionated; thus, it expects you to provide some “basics”, in whatever way you prefer:

• hardware.inc: What project doesn't use this? You should INCLUDE "hardware.inc" somewhere in the config file (or at least provide equivalent definitions).

  If you forget this, you will get “Unknown symbol” errors.

• A SECTION directive: gb-vwf does not define its own SECTION itself, so that you can define it however you want. It will simply use the section that is active after the config file.

  If you forget this, you will get “Cannot output data outside of a SECTION” errors.

Character set

The chars macro is used to define the character set (which is common to all fonts!). It can be called with as many arguments as desired, and as many times as desired; arguments are processed in order, as if they had all been passed in a single call to chars.

Each argument must be a string, which will be defined as an entry into a new charmap called vwf; the first argument (of the first call) will have ID 0, the next one ID 1, and so on. Empty arguments do not create a charmap entry; but they still increment the ID for the next argument.

Important

"\n" will be forcefully aliased to "NEWLINE" after the config file is processed; this is important to the engine.

Please note that multi-line strings emit \n characters, so you can safely use those, too.

Control characters

Most characters in gb-vwf are simply printed; but some have special behaviour, such as starting a new line, scrolling the textbox, changing the current colour, and so on.

It is possible to define your own control characters using the control_char macro, which takes the following arguments:

• The name of the control character (e.g. SET_FONT).

  It will be used to define both a charmap entry ("<SET_FONT>" in this case) and an exported constant (VWF_SET_FONT).

• A pointer to the function responsible for handling that character.

  Its calling convention is simple: a pointer to the input stream is passed in de (pointing to right after the control character itself), and must be increased for each argument byte consumed. (In particular, if the control character takes no arguments, then this means that de should be preserved.)

• All remaining arguments are taken as .tbl file descriptions for each argument byte.

  Please see section 2.5.1 of the .tbl file spec for a description of their formatting.

Caution

Even if you are not planning to use .tbl files, you must specify those extra arguments (even if with dummy values), as the number of arguments is relied upon by the auto-linewrapper.

This also means that gb-vwf does not support control characters with a dynamic number of arguments. Please consider, for example, using a pointer to the argument list.

Lastly, an extra argument consisting exactly of a bang (!) can be prepended; its presence indicates to the auto-linewrapper that the control character terminates lines.

Aliases

You can define some aliases using the vwf_alias macro. They create both a charmap entry, and register it in the charmap file; the usage is just like RGBASM's charmap directive.

gb-vwf defines some built-in aliases:

• "<COLOR3>" is an alias for VWF_SET_COLOR, 0, which makes the VWF engine print to colour #3; "<COLOR1>" is similarly an alias for VWF_SET_COLOR, 1.
• For each font (see further below), an alias with its name is created; for example, font BASE_SEVEN, ... creates "<FONT_BASE_SEVEN>" as an alias for VWF_SET_FONT, BASE_SEVEN.

Fonts

Each call to the font macro defines one font; the first argument is the font's name, and the second one is an unquoted path to its compiled font file (subject to the usual -I rules).

In particular, a constant is defined and exported with the first argument as its name, and whose value is the font's ID.

Variant bits

For convenience, gb-vwf not only supports setting the font directly, but it also supports only modifying some of the active font's bits.

How many bits are changed by SET_VARIANT is configured by the NB_VARIANT_BITS symbol; if omitted, it defaults to 2 (which is suitable for bold + italic).

Tuning knobs

You can optionally configure some aspects of the VWF engine, by defining some symbols. Note that they don't have to be defined by the config file itself, they can also be defined on the command line (with -D, or with a preinclude).

The knobs are all optional, and default values will be used for them if they are not defined.

Text stack capacity

STACK_CAPACITY must be a constant value, setting how many source pointers the VWF engine can remember. This must be at least 1 (for the active entry), and no more than 127.

Note

Please note that exceeding this capacity will trip a runtime assertion (if using debugfiles), and result in memory corruption and possibly a crash.

Higher values enable deeper nesting of CALL control characters, but consume slightly more memory.

Default value: 8.

Integration “sockets”

The engine needs to have some information about how it's going to be used, in order to properly function within your game (and, preferably, without having to patch vwf.asm!) These take the form of macros and values that must be provided to the engine.

Switching ROM banks

The switch_rom_bank macro is used to switch ROM banks; since that's done differently by different projects, this macro must be provided.

It must expand to some instructions that switch to the ROM bank whose ID is currently held in the a register. (Since it is not given any arguments, using an EQUS instead is fine too.) Those instructions must preserve the bc, de, and hl registers. It can, however, trash the a register and the flags.

Please note that it is called somewhat frequently by the auto-linewrapper, so you should preferably keep it fast.

Clearing the textbox

The VWF_EMPTY_TILE_ID symbol defines what value PrintVWFChars will write to the tilemap when scrolling in a new row.

Notably, this does not have to be a value, let alone constant! This can be any valid source for a ld a, VWF_EMPTY_TILE_ID instruction; in particular, def VWF_EMPTY_TILE_ID equs "[wEmptyTileId]" is perfectly fine.

Waiting for VRAM

The wait_vram macro is used to wait for a suitable time to access VRAM; a default implementation is provided, using the standard ldh a, [rSTAT] :: and STATF_BUSY loop.

It must expand to some instructions that busy-wait until it is safe to access VRAM for at least 12 cycles. (Since it is not given any arguments, using an EQUS instead is fine too.) Those instructions must preserve the bc, de, and hl registers, and they must return a equal to 0.

Please note that it is called frequently by PrintVWFChars, so you should preferably keep it fast. (You can also do something like def wait_vram EQUS "xor a" if you are planning to only ever call PrintVWFChars during VBlank.)