Home

gb-vwf documentation

Welcome! Use the side bar for navigation.

What this is

This is a variable-width font (VWF) engine for the Game Boy.

Most Game Boy games use a fixed-width font (FWF). If you are reading this in your browser, this text should be in a variable-width font, and this should be in a fixed-width font. In short, all characters in a fixed-width font have the same, well, width.

The Game Boy's gfx hardware uses a tilemap, which is to say that some "tiles" of 8x8 pixels are stored in VRAM, and can then be freely re-used as a grid. This means that implementing a FWF is as simple as writing tiles containing 1 character each, then referencing those on the tilemap. For this reason, fixed-width text is insanely popular on the Game Boy.

For a better read on this topic, Eevee wrote about it as she was trying to write her own text engine.

Variable-width text has some advantages, such as being more compact (and looking cooler 😎), but it is more complex, and has a different VRAM usage (although that can be beneficial). This engine is provided so you don't have to spend the time writing that functionality yourself, and also so you can benefit from the accumulated feedback that this codebase recieved :)

Features

The engine boasts additional features, not all of which are linked to the VWF functionality itself.

• Easy integration in your game loop: call the function once per frame, in whatever context you want!
• CPU usage is below 10%, except when printing multiple characters in a single call (obviously), thanks to carefully optimized code
• Support for automatic line wrapping / textbox scrolling / more!
• Support for banked ROMs; some of the engine has to be stored in bank 0, but the bulk is stored in a separate bank to save bank 0 space
• Reasonable RAM footprint, below 256 bytes. May be possible to customize in the future.
• Support for multiple fonts (up to 16) with multiple variants each (up to 8)
• Characters are 8 pixels tall, and can be up to 256 pixels wide, although only the first 8 can be opaque
• Can print 3 different colors at the same time
• Built-in text speed support; specially, a delay of "0" causes all text to be printed in a single call
• Can be made to automatically write tile IDs to the tilemap
• Automatically wraps the tile being written to as configured
• Most configuration can be changed at run-time
• "Sync" support lets you check if text reached a certain point; you can do whatever you want from that point onwards
• Can be configured to call error handler functions when some invalid conditions occur
• Support for "sub" strings, useful e.g. for the player's name in a RPG

Limitations

• Possibly high ROM bank 0 usage from fonts (to be fixed in the next release)
• Automatic hyphenation is not supported, and will never be. This would be way too CPU-intensive. You can insert control characters (soft hyphens) to hint at possible hyphenation points, but the engine does not attempt to determine those automatically
• No built-in GBC support, VRAM bank 1 is never written to, and the engine does not switch VRAM banks either

Example

An example demo is provided (check the releases for a pre-built ROM); I encourage you to look at its source and take inspiration from it as well.