-
Notifications
You must be signed in to change notification settings - Fork 3
Home
Welcome! To get you started, please read the How-to page. Otherwise, use the side bar for navigation.
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, whereas >this text< should be in a fixed-width font.
In short, all characters (“glyphs”) in a fixed-width font have the same, well, width.
Here are some comparison visuals.
On the Game Boy, FWFs are hugely common because each glyph can be represented as a single tile. For a better read on this topic, PinoBatch tooted some visuals, and 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, more details below). Using this engine spares you the time and energy necessary to write that functionality yourself, and also lets you benefit from the accumulated feedback and bugfixes that this codebase received :)
gb-vwf boasts many features, some going even a little beyond the VWF functionality itself.
- Easy integration into your game loop: call the two functions once per frame, in whatever context you want!
- Automatic line wrapping, for a neat look without having to spend time worrying about layout. Enjoy quicker prototyping and iterating on your dialogue.
- Support for up to 128 fonts, which can be used concurrently.
- Characters are 8 pixels tall, and can be up to 8 pixels wide.
- Can output to 2 different colours.
- Built-in text speed support. The special speed of 0 is an “as fast as possible” mode.
- “External sync” support lets you check if text reached a certain point; this is useful e.g. for syncing animations to running text.
- Support for “sub-strings”, useful for example to insert the player's custom name in a RPG.
- Support for banked ROMs (“sub-strings” cannot cross ROM banks, though).
- Low ROM footprint: the engine itself requires around 2000 bytes of ROM0, and (2048 + 9 × character) bytes of ROMX.
- Low CPU usage (around 10%), thanks to carefully optimized code.
- Small RAM footprint, below 128 bytes.
- Automatically manages its own tile memory as configured by you, and writes appropriate tilemap entries by itself.
- Debugfile support, to dynamically check that nothing unexpected occurs, without any overhead.
- Fonts are 1bpp, thus no anti-aliasing for you. Dynamic colours would be very expensive with a 2bpp font, though.
- No built-in GBC support: VRAM bank 1 is never written to, and the engine does not switch VRAM banks either.
- If the “textbox” touches the right edge of the tilemap, newlines may skip one row of tiles under rare circumstances.
- Words wider than the textbox will overflow it.
The engine will not forcibly break words; please use the
<ZWS>control character to give it such opportunities.
Automatic hyphenation is not supported, and will never be. It would be way too CPU- and ROM-intensive.
However, you can insert control characters (soft hyphens) to hint at possible hyphenation points. The engine just doesn't attempt to determine those automatically.
A demo exists (check the releases for a pre-built ROM). Looking at its source code is recommended for inspiration on how to “wire up” gb-vwf into your game.