UI & Text

Variable-Width Font (VWF) System

GB Studio uses a software-rendered variable-width font system, not hardware tile-based text. Characters are drawn into tile buffers at arbitrary pixel offsets, producing proportionally-spaced text on the Game Boy’s 8×8 tile grid.

Font Structure

Each font resource is stored as a banked data block with the following header:

typedef struct font_desc_t {
    UBYTE char_start;      // First character code (usually 32 = space)
    UBYTE char_count;      // Number of characters
    UBYTE char_width;      // Max character width in pixels
    UBYTE char_height;     // Character height in pixels
    UBYTE name_length;     // Length of font name string
    // followed by: name, width table, glyph data
} font_desc_t;

• Banked resources: Fonts are loaded via far_ptr_t (bank + address)
• Width table: One byte per character, giving pixel width for proportional spacing
• Glyph data: 1bpp bitmap for each character

VWF Rendering Pipeline

1. Characters are drawn into a temporary tile buffer
2. Each character’s width advances the cursor by a variable amount
3. When the cursor crosses a tile boundary, the completed tile is written to VRAM
4. Rendering happens during ui_update() in the main loop

Text Control Codes

Control codes are embedded within dialogue text strings to modify rendering behavior. They are processed inline as the VWF engine encounters them.

Text Palette

The text_palette global variable (UINT8, range 0–7) controls which of the 8 BG palettes is used for rendering text tiles.

• Default: 7 (last BG palette)
• In-text control: Can be changed via control code 0x07 within text strings
• Use cases: Colored text, ensuring contrast on dark backgrounds, stylistic variation

Overlay Window

The Game Boy hardware window layer is used for dialogue boxes, menus, and HUD elements. It is positioned independently of the background scroll and always renders on top of the BG and sprite layers.

Window Registers

• win_pos_x, win_pos_y — current window position (engine variables)
• WX_REG, WY_REG — hardware registers (set by VBL_isr)
• MENU_CLOSED_Y = MAXWNDPOSY + 1 (from ui.h) — window off-screen = inactive
• Window uses its own 32×32 tile map, separate from the background
• Text is rendered into the window tile map by the VWF system

Window Management

• ui_update() handles window animation (sliding up/down)
• overlay_cut_scanline — splits the screen between BG and window at a specific scanline

extern UBYTE overlay_cut_scanline;

Dialogue System

The dialogue system combines the overlay window with VWF text rendering to display character dialogue, narration, and informational text.

Dialogue Flow

1. Overlay window slides up from the bottom of the screen
2. Text renders character-by-character using the VWF engine
3. Player presses a button to advance to the next text block
4. Window slides back down when dialogue is complete

GBVM Commands

Menu System

Menus are rendered in the overlay window using a combination of text and a cursor sprite to indicate the selected item.

• VM_CHOICE — display a multiple-choice menu
• Menu items are rendered as text in the overlay window
• A cursor sprite indicates the currently selected item
• Returns the selected index to a variable

Text Drawing Commands (GBVM)

The full set of GBVM commands related to text and overlay rendering:

Common Patterns

Setting Text Color for Dark Backgrounds

When dialogue appears over a dark scene, the default text palette (palette 7) may render text invisible. Prepend a palette change control code before the text, or set text_palette globally:

// Use control code 0x07 to change text palette inline
// In event script: prepend palette change before text

// Or set globally before displaying text
text_palette = 3;  // Use BG palette 3 for text

Custom HUD with Overlay

Keep the overlay window visible during gameplay to display persistent HUD information:

// 1. Show overlay at specific position (non-modal so gameplay continues)
VM_OVERLAY_SHOW 0, 0, .UI_COLOR, .UI_NONMODAL

// 2. Write tiles to overlay
VM_OVERLAY_SET_MAP 0, 0, 20, 2, _ui_hud_tilemap

// 3. Overlay remains visible during gameplay
//    Update individual tiles as values change