# 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. ## As it runs (2026-10-14) One source, `xbox/live/oskiewar.js`, is the game on every host. `gameSim` advances the state (rollback covers `netSimArrays`); `paint` → `gamePaint` draws it through one camera, `cameraDoll`, and one set of draw names (`triangle3d`, `box`, `write`, …) that the emitter block near the top of the file shadows. What happens next depends on the host: | host | path | retained | per frame in JS | |---|---|---|---| | web (`mac-test.html`) | frame program: ops into a Float32Array, run by `frame-vm.mjs` into `scene3d-webgl` | meshes (ASSET/MESH), figure sketches (SHAPES/LOOK) | everything still *computed* in JS; the program is one handover | | Mac (`main.swift`, JavaScriptCore) | immediate; faces gathered by `batchFaces` into `triangles3d` | sky camera, SDF bubbles, pool decals | every mesh, figure, shadow and terrain strip projected in JS | | Xbox (QuickJS, `QuickJsEngine.cpp`) | immediate, one call per face | `meshUpload`/`meshDraw`, `sceneMesh`, `disc3d`/`capsule3d` fans | figures (shapes), terrain, HUD | | AC Native (`fedac/native/lib/oskiewar-host.mjs`) | immediate, one call per face | `disc3d` (sides picked in the adapter) | everything else | Rebuilt every frame that could be kept: on the Mac every quad mesh (park, dojo roof and floor, decks) is re-projected in JS because the Mac has no `meshUpload`/`meshDraw` (the Xbox's C++ `MeshDraw` is the model to port); terrain strips everywhere; flat figures on every immediate host. **Projection.** There is one camera, `cameraDoll`, and one stage, `viewWidth()` × `viewHeight` from `gameView()` (synced each paint). Every consumer derives from it fresh: `projectPoint`/`worldTriangle` in JS, `prepareObjectView` for objects and figures, the CAMERA op for the web, `mainNativeCamera()` (27 floats, rebuilt on every ask) for meshes, sky, decals and SDF on native hosts. A host maps the stage onto its drawable with its own live logical size, never a constant (`projection.test.mjs` checks 1920×1080 and 2880×800). **World entities.** `worldTypes` lists every kind of world thing: where its instances live, which exist, where one stands, which fields tween, how it draws. gamePaint's prop pass and depth-sorted pass and the render interpolation all walk it. Ids are renderer-side (a WeakMap); nothing is written onto sim objects, so `netSimArrays` keeps its shape. `worldEntities()` lists `{ id, type, x, y, z }`. Map furniture (decks, roof panes, hall cubes, the grid field) is still map state, not entities. Bench: `xbox/live/bench/paint.mjs` (counts and a hash of what the host is handed), `paint-ab.mjs` (same-process A/B of one draw function), `jsc-bridge.swift` (what a JavaScriptCore→Swift call costs). ## 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: ```js // 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) | phase | ms | why | |---|---|---| | figures (`drawRunner` ×5) | 8 | ~514 native calls per pastel skater; skirt cloth, ponytail, face, curved limbs, bow all tessellated in JS | | sim | 7.5 | poses built 9–12×/frame (melee, balls, camera, paint, inset); `updateBall` 2.4, `resolveMelee` 1.2 | | park meshes | 3.4 + 2.1 + 1.5 | meshes are cached but their ~120 edge capsules are re-projected in JS every frame; `sceneMesh` re-validates and heap-allocates per face | | P1 inset | 4.2 | every park mesh re-sent through `sceneMesh` a second time, unculled (the bounds check reads a field only the web path computes) | | HUD text | 1.6 | strings rebuilt per frame, DirectWrite layout per string per frame | ## Migration, in order of ms per day | step | lane | work | saves | |---|---|---|---| | 0 | JS | cache `runtime()`/`capabilities()` per sim and paint; hoist `typeof` to constants; one pose memo per tick shared by melee, balls, camera, paint and inset (keyed on the sim tick, never the wall clock); one combat-box cache per tick; render fields off `player`; `ac()` at 1 Hz; HUD strings at 10 Hz | 3–4 ms | | 1 | native | `meshUpload/meshDraw/meshFree`: validate, AABB, pre-light once at upload; capsules folded in and fanned after projection; stack clipping; the inset draws the same handles with its own camera; hall draws retained even with roof shards | ~2.5 ms | | 2 | native | `figureStyle` + `figure`: tiers 1–3, tier-0 flat body, curved chains, hair cap, outfit minus skirt, trio face, scars, strobe. JS keeps ponytail/skirt/bow/items/shield/glyphs for now. Split `drawRunner` into `figureRecord` → `figureNative` \| `figureJs` | ~1.2–1.4 of 1.6 ms per figure | | 3 | native | `sceneDraw(camera, viewMask)` for both views; `meshDrawAt` for rigid props (a skateboard = 7 calls, not ~110); `figureInstance` with ponytail/skirt Verlets in C++; crowd batch | ~3.5 + ~2 ms | | 4 | native | terrain strips by handle for the outdoor maps; native glyph-run cache; `sceneMesh` per-face allocs gone | ~3 ms outdoor | | 5 | web | ship `scene3d-webgl.mjs` + the reference module so "web = reference" is checked, not hoped; Mac gains `triangles3d`/`figure` via a C shim | 0 console ms | 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.