Oskiewar engine: the game/renderer split #

Written 2026-09-26 from four read-only surveys of xbox/live/oskiewar.js (day branch, 21.5k lines) and xbox/native-bios/ (App.cpp, QuickJsEngine.cpp, ScenePrimitives.inc). Numbers are Series X AC_NATIVE_PROFILE hostJsMs unless noted.

The problem in one line #

On the console the game's JavaScript runs interpreted (QuickJS, no JIT) and that JavaScript is the whole frame: ~24 ms in the freeskate park, 60 fps needs <16. Render CPU is 0.7 ms; the GPU is idle. Every frame the JS re-tessellates ~2,100 faces (Bézier limbs, cloth skirts, hair fans, quad meshes, capsule edges) and hands them over one call at a time.

The emitTriangle comment (batching a Float32Array cost 5.7 ms where per-face calls cost 1.8) is right and points the wrong way: in QuickJS a typed-array element write costs ~0.23 µs and a 12-arg C call ~0.85 µs, so the count of numbers crossing is the cost, whichever side writes them. 2,100 faces are 25,000 numbers a frame. A fighter's pose is ~130. Only designs where JS sends O(objects) and C++ produces the faces get under the 1.8 ms floor.

The split #

Game (one JS source; deterministic; 331 tests): input, gameSim/netTick, rollback (netSnapshot/netRestore/netStateHash), replay capture, the world-space pose (buildRunnerWorldGeometry — it is also the hitbox source, so it never leaves JS), the LOD tier decision (figureLod), the camera solve, and the order things are drawn in (gamePaint).

Renderer (C++ on the console; a JS reference everywhere else): everything from "world-space pose + camera" down — projection, clipping, capsule/disc/ ribbon fans, skeleton skinning, outfit, face, terrain strips, quad-mesh lighting, HUD glyph fanning, post effects.

The interface is retained handles plus small per-frame payloads:

// once per map / per look
const mesh  = meshUpload(verticesF32, facesF32, capsulesF32)   // → int
const style = figureStyle(jsonString)                          // → int
// per frame
meshDraw(mesh, cameraF32 /* the persistent 27-float buffer */)
figure(style, pose /* the JS pose object; C++ walks it by atom */, state, tier, depth)
postEffects(focusY, band, feather, tiltPx, motionX, motionY)   // shipped, 1.0.0.48

Rules that keep it one game:

• The renderer returns nothing the game reads.
• paint never writes a sim object. Render-only fields (lodTier, displayFps, interpolation) live in WeakMaps or a frame-state snapshot, not on player (players ride structuredClone into net snapshots).
• Nothing reachable from gameSim reads runtime().monotonicUs, cameraDoll, projectPoint or viewWidth() — a wall clock inside the pose would give two seats different hitboxes.
• Every native call is additive and levelled: native advertises capabilities().sceneApi = N; JS resolves the level once at boot (no typeof on hot paths) and keeps its level-(N−1) path. Level 0 is the JS reference, which is what the web, the Mac shell and the tests run.
• Native changes bump Package.appxmanifest Version every time — the Device Portal keeps the package it has when the version matches.

Where the frame goes (park, five figures) #

Migration, in order of ms per day #

Each step is measured the same way: dev-deploy, read AC_NATIVE_PROFILE median over 20 lines, screenshot with xbox/tools/live.mjs screenshot.

Tests #

• The harness (createFight) stubs triangle3d and never defines capsule3d/disc3d/figure/meshDraw, so all 120 triangle-observing tests keep exercising the JS reference unchanged.
• Add scene-level stubs that record {kind, handle, tier} and assert semantic counts (five figures at tier 1, one mesh) — the countPoseBuilds pattern.
• Golden cross-check: quickjs_engine_smoke.cpp dumps the native triangle stream for one canonical pose/mesh; a Node test replays the reference and diffs. This is the test that would have caught SceneDisc (5 ring tiers) already differing from discRingFor (6 tiers).
• Source-shape gate: REQUIRED_SCENE_API in oskiewar.js ≤ the sceneApi literal in App.cpp, so oskiewar-release.mjs cannot ship a JS that needs a level the console does not advertise.

Rejected #

• GPU instancing as the fix. Building the instance list in JS costs the same as the calls it replaces. It pays only as a cheaper sink under a C++ builder, or for shared props.
• A retained angle skeleton with C++ forward kinematics. The rig is ~450 lines of positional, terrain-probing game logic and the hitbox source; a positional pose is the same wire size as angles.
• Submitting the inset on alternate frames. Nothing is retained on the GPU between frames; it would flicker.