Nova64 Godot Host Contract

Adapter contract version: 1.0.0
Godot adapter version: 0.5.0
Status: Active — Phase 3 in-progress polish

Purpose

This document is the authoritative reference for the Nova64 Godot host bridge. It covers:

• the call_bridge(method, payload) → Dictionary entry point
• every supported command, its payload shape, and its return value
• the capabilities descriptor
• the input poll format
• handle lifecycle rules
• known gaps vs the Three.js and Babylon browsers backends
• cart lifecycle wiring

For the general adapter surface that all backends must satisfy see docs/ADAPTER_CONTRACT.md. For backend structure and ownership rules see docs/BACKEND_RUNTIME.md.

Architecture Overview

JS (QuickJS)   →   engine.call(method, payload)
                         ↓
               nova64-godot/gdextension/src/bridge.cpp
               Nova64Host::call_bridge(method, payload)
                         ↓
               GDScript node tree + Godot rendering APIs

Nova64 JS runs inside QuickJS embedded in a Godot GDExtension node (Nova64Host). All rendering, input, audio, and asset work crosses the bridge via engine.call(method, payload). No direct Godot API calls exist in cart code or the JS shim.

The shim at nova64-godot/godot_project/shim/nova64-compat.js translates cart-facing Nova64 API calls (createCube, setCameraPosition, etc.) into call_bridge method+payload pairs. Cart code never calls engine.call directly.

Bridge Entry Point

Nova64Host::call_bridge(method: String, payload: Dictionary) → Dictionary

• method — dot-separated namespace and command, e.g. "material.create".
• payload — zero or more named parameters.
• return — a Dictionary; always includes { "error": ..., "message": ... } on failure.

Unknown methods return { "error": "unsupported_method" }.

Batched dispatch is available via engine.flush(commands) where commands is an Array of [method, payload] pairs or {m, p} objects. Returns an Array of result Dictionaries in the same order.

Capabilities Descriptor

host.getCapabilities (or engine.init) returns a Dictionary:

{
  "backend": "godot",
  "contractVersion": "1.0.0",
  "adapterVersion": "0.5.0",
  "features": [ ... ]
}

The features array lists every method string that call_bridge will handle without returning unsupported_method. Cart and runtime code should use this array for feature detection rather than hard-coding backend checks.

Handle Lifecycle

• Every *.create command returns { "handle": <integer> }.
• Handles are opaque 32-bit unsigned integers managed by HandleTable.
• Handle kinds: MATERIAL, GEOMETRY, MESH_INSTANCE, CAMERA, LIGHT, TEXTURE, AUDIO, MULTI_MESH, PARTICLES.
• Passing a handle of the wrong kind to a command returns { "error": "invalid_*_handle" }.
• Destroy commands free the backing Godot node and resource. Using a destroyed handle is a no-op (safe but silently ignored).
• transform.set resolves handles of kinds MESH_INSTANCE, CAMERA, LIGHT, MULTI_MESH, and PARTICLES — all node-backed resource types.

Command Reference

System

Material

Colors are passed as { r, g, b, a } floats (0–1) or as a single number encoding 0xRRGGBB.

Geometry

All geometry commands return { handle }. Geometry handles are immutable after creation; rebuild to change shape.

Mesh

Transform

transform.set applies to any node-backed handle (mesh, camera, light, instanced mesh, particles).

If both lookAt and rotation are present, lookAt wins.

Camera

Lights

light.setSun creates or updates a shared DirectionalLight3D used for day/night cycles. It is separate from individually tracked light handles.

Environment

Input Poll

input.poll takes no payload and returns a snapshot of current Godot input state.

{
  "keys": ["KeyA", "Space"],        // web-style key codes currently held
  "left": true,                      // Arrow/WASD convenience bools
  "right": false,
  "up": false,
  "down": false,
  "action": false,
  "buttons": [false, false, ...],    // 14-element gamepad button array
  "axis": { "lx": 0.0, "ly": 0.0, "rx": 0.0, "ry": 0.0, "lt": 0.0, "rt": 0.0 },
  "touches": [{ "id": 0, "x": 100, "y": 280 }]  // active touches, 640x360 logical
}

Touches echo whatever the GDScript host last pushed via set_touches (Nova64Host can't enumerate active touches from the Input singleton, so the host captures InputEventScreenTouch/Drag and pushes the live set each frame). They surface to carts as nova64.input.touches() / touchCount().

Key codes use web KeyboardEvent.code names ("KeyW", "ArrowLeft", "Space", "Enter", "ShiftLeft", etc.). The full mapped set is defined in bridge.cpp at _cmd_input_poll.

Gamepad button array (buttons[0..13]) maps to the Nova64 gamepad layout: 0=ArrowLeft, 1=ArrowRight, 2=ArrowUp, 3=ArrowDown, 4=KeyZ, 5=KeyX, 6=KeyC, 7=KeyV, 8=KeyA, 9=KeyS, 10=KeyQ, 11=KeyW, 12=Enter, 13=Space.

Axes apply a shaped deadzone (0.18) and power curve (exponent 1.35).

Texture

Audio

Instanced Mesh

Particles

Model Loading

Video (proposed — not yet implemented in the host)

This section defines the host-side commands nova64.video will use on Godot once the Godot adapter ships. The JS API is already stable in runtime/api-video.js; it currently falls through to a stub on Godot hosts. When the bridge below is in place, videoApi(gpu)'s backend detector will recognise Godot and route real calls through.

Asset format: Godot's VideoStream core supports .ogv (Theora) out of the box and .webm (VP8/9) via the webm plugin. .mp4 (H.264) is not natively supported in Godot 4 and would require a third-party plugin or transcoding to one of the above. The browser path uses .mp4 freely, so carts that want cross-host compatibility should ship both an .mp4 and a transcoded .ogv / .webm and let the engine pick by backend.

Events: the host MUST emit video.finished with payload { handle, skipped: bool } when a fullscreen video ends or is skipped, so the playFullscreen promise resolves.

Voxel

The compact column record format is documented in docs/GODOT_VOXEL_PLAN.md.

WAD Loading

The WAD bridge exposes the WAD directory and raw lump data to JS for parsing by runtime/wad.js. The C++ side handles file I/O; JS handles all parsing.

wad.load returns a directory array of { name, filepos, size } objects for every lump. Carts call wad.readLump to fetch individual lump byte arrays, which are then decoded by WADLoader in JS.

Overlay (2D HUD)

Overlay commands draw on a CanvasLayer rendered above the 3D scene. Coordinates are in the cart's 640×360 virtual canvas space.

overlay.batch is the preferred path for HUD-heavy carts; it amortises the JS→C++ call overhead to a single round-trip per frame. Image ops use the compact array form ['image', textureHandle, x, y, w, h, color].

Cart Lifecycle

Godot drives the cart lifecycle through Nova64Host node callbacks:

1. load_cart(res_path) — evaluates the cart ES module, caches init, update, draw exports. Returns false if the module has no recognisable lifecycle exports.
2. cart_init() — calls the cart's init() export once.
3. cart_update(delta) — calls update(dt) every _process frame.
4. cart_draw() — calls draw() every frame after cart_update.

The host GDScript (scripts/nova64_host.gd) wires these to Node._process(delta).

Capability Matrix

The table below summarises supported and unsupported features compared to the Three.js browser backend.

Known Divergences from Browser Backends

The cart-facing shim is a hand-maintained second copy of runtime/, so it can also diverge by accident. The semantics that are easy to invert — directional-light orientation, createMaterial(kind) shading models, and WAD collision geometry — and the pnpm test:godot:parity gate that pins them are documented in GODOT_PARITY.md.

The deliberate divergences:

• Pointer lock / mouse look — Godot captures the cursor via Input.mouse_mode = MOUSE_MODE_CAPTURED. The shim translates this but raw mouse delta comes from Godot InputEventMouseMotion, not browser movementX/Y. High-sensitivity mouse carts may need tuning.
• HTMLCanvas API — Not available inside QuickJS. Carts that use document.createElement('canvas') for texture generation must detect Godot mode and use nova64.draw or texture.createFromImage instead.
• DOM events — window.addEventListener, document.addEventListener, fetch, XMLHttpRequest, and similar browser APIs are not available. The shim guards the most common drag-and-drop and file-picker paths.
• WAD sector light / COLORMAP — Godot WAD rendering uses a flat ambient term. COLORMAP-based sector darkening is not yet implemented (tracked in ROADMAP.md Phase 3 WAD sub-roadmap).
• WAD animated flats — Animated floor/ceiling textures are not yet driven by the Godot WAD path.
• Sprite billboard parity — Transparent pixel handling and per-frame rotation tables for WAD sprites need additional parity work.

Error Response Shape

All failed commands return:

{ "error": "<error_code>", "message": "<human_readable>" }

Common error codes:

Source References