PocketJS AOT is a separate product line for GBA-class cartridge games. It uses TypeScript and JSX as an authoring DSL, but the final program ships no JavaScript engine. The compiler executes static declarations at build time, lowers supported residual scripts to bytecode, and links compact game data into a fixed native C runtime — producing a realDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/pocket-stack/pocketjs/llms.txt
Use this file to discover all available pages before exploring further.
.gba ROM that plays on hardware or in mGBA with no JS on the cartridge.
The main PocketJS framework docs describe the PSP-oriented UI runtime powered by QuickJS, Solid, Vue Vapor, and PocketJS host components. AOT is intentionally different: it targets tile maps, sprites, palettes, dialogue, flags, choices, and warps — not reactive UIs. There is no shared runtime between the two product lines.
What AOT targets
AOT is built around the constraints and strengths of GBA-class hardware: a 240×160 pixel display, Mode 0 tiled backgrounds, 8×8 pixel BG tiles, 16×16 OBJ sprites, hardware palette banks, and no operating system. Everything the compiler produces maps directly to those hardware resources. The current vertical slice covers:- Typed ASCII tile layers —
defineTilesetpreserves literal tile names so TypeScript rejects legends that reference tiles not in the selected tileset before the compiler builds a ROM. - Build-time JSX prefabs — JSX components such as
<Npc>,<Sign>,<Warp>, and<PlayerSpawn>run during the build, expand into static scene nodes, and never ship to the cartridge. - 4bpp graphics and BGR555 palettes — the compiler bakes tilesets and sprites into GBA-native 4bpp tile data with 15-bit BGR555 color palettes.
- Packed glyph data — Inter Bold is rasterized at compile time with horizontally biased supersampling and quantized into five subpixel coverage palette levels for the tile-based textbox renderer.
- Script bytecode — supported generator scripts (
say,choose,hasFlag,setFlag,battle,giveItem, and more) are lowered from their ASTs to compact bytecode for a small stack VM in the C runtime. - Web demo — compiled cartridge states can be previewed in the independent web demo, a static canvas viewer separate from the framework playground.
aot/demo/game.tsx) compiles to a .gba ROM that passes a headless mGBA E2E suite covering boot, grid movement, collision, NPC dialogue, a choice menu, a battle→flag→item reward sequence, and warping between maps.
How AOT differs from the main PocketJS runtime
| PocketJS Framework | PocketJS AOT | |
|---|---|---|
| Target hardware | PSP-class (Allwinner H) | GBA-class (ARM7TDMI) |
| Runtime engine | QuickJS embedded JS engine | Fixed C runtime, no JS engine |
| UI model | Solid / Vue Vapor reactive components | Tile maps, OBJ sprites, textbox |
| TypeScript/JSX role | Compiled and executed at runtime | Build-time authoring DSL only |
| Output | JavaScript bundle + host bindings | GBA .gba ROM + PJGB blob |
| Scripting | Full JavaScript | Bytecode VM (residualized subset) |
Key concepts
The authoring DSL (aot/dsl/) provides the TypeScript and JSX surface: defineTileset, defineSprite, defineMap, defineGame, host elements (<Npc>, <Warp>, <Sign>, etc.), the script() wrapper, and op functions (say, choose, hasFlag, setFlag, battle, giveItem, and others). The DSL is executed at build time; only the compiled output reaches the cartridge.
The compiler pipeline (aot/compiler/) runs in six stages: evaluate static declarations, bake graphics assets, residualize script generators to bytecode, build the game model, lower everything to PJGB chunks, and pack the cartridge blob. A final stage links the blob into the fixed C runtime using arm-none-eabi-gcc.
The native runtime (aot/runtime/) is a compact, no-allocation C engine: a crt0.s startup, GBA linker script (gba.ld), Mode 0 BG rendering, hardware OAM sprites, grid movement with collision, a suspendable stack VM (script_vm.c), and a subpixel-covered tile textbox and choice menu renderer.
The cartridge format (aot/spec/pjgb.ts) is the PJGB binary container — the single source of truth for chunk layouts, the script VM ISA, and the debug block. A code generator (spec/gen-c.ts) produces runtime/pjgb_gen.h so the C runtime can never drift from the TypeScript compiler definitions.
Pages in this section
Getting Started
Set up AOT, author your first tile map scene, and compile it to a GBA ROM.
Authoring
The full DSL: tile maps, entities, dialogue, choices, flags, warps, and scripts.
Compiler
The compiler pipeline: evaluation, baking, residualization, packing, and linking.
Runtime
The native GBA C engine: video, input, actors, script VM, textbox.
Cartridge Format
The PJGB binary format: chunks, section layout, and how the runtime reads each section.