GB Studio 4.2

Gameboy Development Reference

GB Studio is a great way to start making your own Gameboy Game. However, documentation on in depth functionality is sparse, so I have created this engine reference, GBVM instruction set, and plugin API documentation for fellow developers.

Also make sure to check out the GB Studio Homepage and GB Studio Central for more resources.

Hardware & Timing

Clock architecture, CPU timing, interrupt sources, VBlank vs timer frequency, and memory map.

Engine Core

Coordinate system, main loop order, scene loading sequence, and game time.

Actors

Actor data structure, flags, animation system, streaming activation, and linked lists.

Graphics & Sprites

VRAM layout, spritesheets, backgrounds, tiles, metasprites, and shadow OAM.

Scroll & Camera

Scroll system, parallax layers, camera modes, and incremental tile loading.

UI & Text

Variable-width fonts, text rendering, control codes, overlay window, and menus.

Palettes & Color

CGB palette system, color loading, fade interpolation, and palette manipulation.

Input & Timers

Joypad input, edge detection macros, timer system, triggers, and projectiles.

Sound & Music

hUGE music driver, sound effects, channel control, and mute masks.

Variables & Memory

Variable system, memory layout, GBVM heap, constants, and math utilities.

GBVM Instructions

Complete instruction set reference with all ~90 opcodes and parameters.

Scene Type Plugins

Creating custom scene types, engine.json, engine fields, and plugin architecture.

Event Plugins

Event plugin API, field types, compile helpers, RPN calculator, and actor opcodes.

Event JSON Reference

All event commands for .gbsres files — variables, actors, text, camera, sound.

Common Pitfalls

Known gotchas, timing issues, and proven solutions for GB Studio development.

Plugin Downloads

Free GB Studio plugins: SmoothFade, ToneBeep, NoiseDrone, and SetTextPalette.

About

This reference documents the internal engine architecture, C API, GBVM instruction set, and plugin system of GB Studio 4.2.2. It is intended for developers creating custom scene type plugins, event plugins, and editing scene event scripts directly in .gbsres JSON files. The information is derived from the GB Studio engine source code (engine version 4.2.2-e1) and verified through real-world plugin development on the Afterburn project.