Building & exporting .gtr ROMs
A .gtr is a burnable native GameTank ROM — an exact 2 MB flash image that boots in the GameTankEmulator and can be flashed to a real cartridge. It's assembled from the same cart-Forth source and assets as your browser cart; only GameTank carts (see The GameTank machine) can produce one.
From the studio
Signed-in authors editing a GameTank cart see the studio toolbar's Export .gtr button (GameTank carts, signed in) — visible from every tab (hidden on M8; disabled with a "Sign in to export ROMs" hint for anonymous visitors). Clicking it compiles your cart's current bytes server-side — no local toolchain needed — and downloads the resulting ROM. The console reports two things once the build finishes:
- The ROM's byte size (and whether it was served from cache — repeat exports of identical cart bytes skip rebuilding).
- The full placement report — which bank every word landed in, and every cross-bank call edge, with steady-state (per-frame hot-path) edges flagged separately from one-time edges.
The placement report is the fastest way to confirm a @hot / @same-bank / @steady-root pragma edit had the effect you expected — see Cart-Forth subset — Placement pragmas for the full directive reference.
From the command line
The cart-build CLI can drive the same emitter locally, given a checkout of the cc65 toolchain and (optionally) the GameTankEmulator:
cart-build cart.fs cart.sprite "My Cart" \
--machine gametank \
--sheet 0=sheet0.bin \
--smpl sfx.pcm@0 \
--sond cart.sond.json \
--target-medium flash-2m \
--emit gtr --gt-toolchain /path/to/vendor [--emulate]
| Flag | Meaning |
|---|---|
--machine gametank | Required — --emit gtr only applies to GameTank carts. |
--sheet <n>=<file> | Load sprite sheet n (0–7) from a raw byte blob. Repeatable. |
--smpl <file>[@<rate_code>] | Load a raw 8-bit PCM sample, optionally tagged with its rate_code (0–3; see Samples tutorial). Repeatable. |
--sond <json> | Load hand-authored tracker data (instruments + patterns) from a JSON sidecar. |
--target-medium flash-2m | GameTank's default anyway; sets the 2 MB in-cap total explicitly. |
--emit gtr | Also assemble + link a native .gtr ROM, not just the .sprite cart. |
--gt-toolchain <dir> | Directory containing cc65/ (ca65/ld65) and, optionally, GameTankEmulator/. Falls back to the GT_TOOLCHAIN env var. |
--emulate | After a successful build, launch the GameTankEmulator on the freshly-built ROM. |
Music and SFX play natively
A .gtr ROM isn't silent. Every export embeds a 5-voice audio-coprocessor (ACP) mixer firmware plus a main-CPU tracker sequencer that replays the cart's SOND patterns — play-music, play-sfx, loop-sfx, stop-sfx, and set-bpm all work natively, driving the same sample-instrument and synth-instrument audio described in Samples & sample instruments and Sounds editor — Music and SFX buses. Tempo stays locked to 60 Hz wall-time even on frames that run over the GameTank cycle budget, so music doesn't drift out of sync with a throttled framerate.