feat(playset): scene3d surface + GameBlocks port + native wgpu core — rally renders

[doodlewind]

What

Playset — Three.js mini-games (GameBlocks-class) running on Pocket, end to end: framework, native rendering on desktop wgpu AND PSP GE, and the first four games.

Same bundle on the PSP host under PPSSPP: RMSE 5.4% vs the desktop frame. Wave-1 ports: runner · dogfight · snake

Layers

1. scene3d surface (playset/scene3d/) — closed write-only 3D presentation vocabulary (the 3D sibling of ui): batched writePoses, primitives/heightfield/mesh, vertex-lit fixed-function-honest materials, sun/hemisphere/fog/sky, sprite & beam pools, bindViewport per the <Video> precedent. TS client + <Viewport3D> + renderless sim host for goldens.
2. playset/modules/ — all 74 GameBlocks modules (MIT, attributed) + 3 natives (deterministic CollisionWorld replacing Rapier, blob-shadow, color-utils). Copy-into-project source per SKILL.md (with the Three.js → playset mapping table).
3. Native cores — PROP.scene3d + DRAW_OP.sceneQuad through spec/core (all four DrawList consumers; graceful absence, zero golden drift). Desktop: pocket3d/crates/pocket-scene3d (retained store + rquickjs s3 mount + wgpu vertex-lit renderer), composited in uihost. PSP: the store goes no_std behind a feature gate (one semantics, two hosts — the pocket3d-bsp pattern) with native/src/{scene3d,ge3d}.rs: QuickJS C-API mount, GE hardware sun + hemisphere-average ambient, sceGuFog, depth-only clear, additive pools, 2D-clean exit. Always-on perf probe (avg_js_us per 300 frames) answers the 333 MHz QuickJS question on hardware: bun run hw rally -r.
4. Games — demos/rally (original composition) + wave-1 ports demos/runner, demos/dogfight (17 modules as-is; FlightHud + radar in action), demos/snake (A*/flood-fill AI rival). Each: fixed-step deterministic sim, two-boot byte-identical goldens, exact 30↔60 Hz subsampling, no-s3 degradation, uihost screenshots in-repo.

Validation

• 365 bun tests / 5,879 assertions green (bun run test builds all five game bundles); tsc --noEmit clean; 12 pocket-scene3d cargo tests; no_std build clean; clippy clean
• PSP: all 23 ui e2e goldens byte-exact under PPSSPP, tape:check 180 frames, rally renders at RMSE 5.4%/5.3% vs desktop refs
• Desktop hero-main screenshot: pixel-identical (2D path inert)

Follow-ups

• Wave-2 ports (shooters/defense ×6), wave-3 (vehicles/water/marble/arm), voxel-survival last (needs a voxel-world module)
• Playset gap backlog from wave-1: instanced-geometry verb, pooled-entity helper, edge-triggered input in GameInput, flight-pursuit behavior module, per-target hit radii on projectiles, default font slot for unclassed Text (systemic), point-light verb, frameBounds camera solver, BoardEnvironment rim option, exp fog
• Rust hot-path blocks behind the batch seams; mid-DrawList compositing (v1: scene under all ui); ramp wedge collision; textured materials; pocket port funnel skill
• Hardware perf spike: bun run hw rally -r on the real PSP (PSPLINK console prints the probe)

🤖 Generated with Claude Code

[doodlewind]

Hardware perf spike — answered on a real PSP (2026-07-20)

The standing question ("is QuickJS per-frame 3D sim fast enough at 333 MHz?") now has a measured answer: no, by ~20×, and it's interpreter physics, not a fixable bug.

Two root fixes found on the way

• The host never set the clock — PSPLINK boots at 222/111 MHz. run() now pins 333/333/166 (cpu_mhz= readback in the perf line).
• QuickJS was compiled -O0 since 2021 — libquickjs-sys/build.rs carried .opt_level(0) from the original bring-up experiment. Fixed to -O2 (quickjs-rs branch perf/interpreter-o2).

Calibrated interpreter cost (on device, 333 MHz, -O2)

microbench	unit cost
float mul+add loop iteration	8.3µs (~1.7µs/op ≈ 550 cycles — soft-float f64)
property read	~2.5µs/op
Vector3.copy().multiplyScalar().add()	110µs/chain

Frame budget 16,667µs ≈ ~8k interpreter ops. Rally's step runs ~250k.

rally, per frame (steady state, 300-frame windows)

segment	before	after	fix
step	490ms	268ms	CollisionWorld broadphase grid (insertion-order-exact)
flush	128ms	46ms	Scene3D.markStatic() scenery skip
HUD	69ms	12ms	10 Hz refresh on the virtual 0.1s grid
total JS	689ms	328ms

GE wait: 29µs — the scene3d GE compositor is never the bottleneck. Rust tick+draw+enqueue ≈ 18ms. snake (unoptimized): 54ms steady. hero (ui-only) was always 60 fps.

Consequence for wave 2+

60 fps sims on PSP need the native hot-path blocks already on the backlog (Rust behind the same batch-resolver seams) or sims sized under ~8k ops/frame. Vita/desktop are unaffected (hard-float). All 365 tests + PPSSPP e2e stay byte-exact.

🤖 Generated with Claude Code

[doodlewind]

rally on a real PSP: 689 ms → 13.1 ms per frame

Follow-up to the perf spike. The native sim cores landed, and then chased everything they exposed. Commit 0e70e61.

Per frame, measured on hardware (333 MHz, release)

	before	after
sim step	268 ms	1.7 ms
scene.flush()	128 ms	0.6 ms
HUD	69 ms	2.0 ms
ge::render	17.6 ms	4.3 ms
frame total	689 ms	13.1 ms avg

91.5% of frames land inside the 16.67 ms budget.

What did it

• pocket-playset — the hot GameBlocks blocks as native f32 Rust, one crate for both hosts. The sim owns scene3d node handles and writes poses straight into the shared store, so the per-frame pose batch never becomes JS; the guest's whole turn is one step and one 15-float readHud. The port alone took the step from 268 ms to 1.7 ms — after that, everything costing time was outside the sim.
• Frustum culling in ge3d — 707 draws → ~65, 23,585 → ~6,400 triangles. rally was vertex-bound: 23.6k tris ≈ 28 ms of GE at the ~2.5M lit-verts/s the hardware sustains, which matched the ~30 ms list time I'd measured. Fill was never the constraint.
• Terrain tiling — one heightfield was 4,608 triangles that no cull can reject. 6×6 overlapping patches; the overlap is load-bearing (normals are averaged per mesh, so touching tiles give boundary vertices a half-neighbourhood and a visible seam).
• HUD — one signal per field. A single object signal re-ran every consumer because a fresh object is never ===.

The TS path is untouched

The playset modules remain the reference implementation; a host without ps runs them exactly as before, and every byte-exact golden still pins that path. f32 vs f64 makes the two trajectory-equivalent, not bit-equivalent, so parity is a bounded-divergence test instead: over 600 frames the native car stays within 0.05 u of the reference racing line, and the bounds are mutation-tested (a steer-sign flip misses by 300×).

Two findings worth stealing

• Physics has to sample the terrain that is actually drawn. The procedural samplers hash through fract(sin(...)), which is a genuinely different function in f32 than f64 — 1.94 vs 2.59 at the same point. A native core re-deriving heights puts the car on a surface that is not on screen. The mesh now hands its tessellated grid to the sim.
• avg_work_us excludes the GE wait. The real critical path is (js+tick+draw) + gu_wait + render, and the display is vblank-quantised, so one frame over budget costs a whole 16.7 ms. The probe now counts over-budget frames per 300 — that's the honest 60fps metric, not the mean.

Known remainder

The last 8.5% of over-budget frames are all minimap marker refreshes: rebuilding and diffing a twelve-key style object per marker costs 27 ms on this interpreter, far more than its op count explains. It is not GC — raising the collector threshold changed nothing, measured and reverted. Markers are gated to 5 Hz to halve the hitch rate; making the update itself cheap is the follow-up.

365 TS tests + 77 Rust tests + PPSSPP e2e all green.

🤖 Generated with Claude Code

[doodlewind]

Merged main (39 commits) — conflicts resolved, plus one thing that needs a decision

Branch is MERGEABLE / CLEAN again. Five conflicts, all resolved as unions or in favour of main's newer semantics:

file	resolution
native/src/lib.rs	union — scene3d + playset alongside main's stats/svc/vid
native/src/main.rs	union of the pocketjs_psp::{...} import
package.json	main's test chain is a superset of the shared base; kept it and appended the playset segment (parity --check + the four demo builds + playset/test/)
pocket3d/.../render.rs	took main's DPI-scaled xy/wh closures; the module-level decode_xy/decode_wh stay unscaled because scene_quads reports logical ui px and its caller owns the scaling
tsconfig.json	dropped the retired @pocketjs/aot/* paths (main removed aot/), kept @pocketjs/playset/* and added @pocketjs/playset/sim

Also had to rebuild host-web/pocketjs.wasm — main added core ops (ui_set_active) and the checked-in binary was stale, which failed the sim suites until regenerated.

Verification after the merge: 654 TS tests across the full merged chain, 77 Rust tests (incl. the rally trajectory-parity fixture, still up to date), cargo check --workspace clean, and the PSP EBOOT builds against main's new pins.

⚠️ The QuickJS -O2 fix is no longer in the build

main repinned the PSP toolchain from local paths to git revs:

libquickjs-sys = { git = "https://github.com/pocket-stack/quickjs-rs.git", rev = "0fc946fb..." }

I read that rev's build.rs — it still has .opt_level(0). So the interpreter is back to the unoptimized build the perf spike found had been shipping since a 2021 bring-up experiment. That was worth roughly a 2x on JS time, which is a large share of how rally got to 13.1 ms/frame.

Nothing in this PR can fix that on its own. It needs, in order:

1. perf(libquickjs-sys): compile QuickJS at -O2 (was -O0 since 2021 bring-up) quickjs-rs#6 (-O2 + the GC bindings) merged — it is still a draft I opened;
2. native/Cargo.toml repinned to the resulting rev.

I did not repin to my unmerged branch's sha: it happens to be fetchable through the fork network, but pinning a shipped build to an unmerged branch is a landmine, and merging a PR in another repo is not mine to decide.

I could not re-measure on hardware — the PSPLINK link wedged partway through (pspsh stopped responding; it needs a physical reset). The regression above is established from the pinned source, not inferred from a measurement.

🤖 Generated with Claude Code

[doodlewind]

Repinned to the -O2 quickjs-rs — and found that -O2 was never reaching the compiler

quickjs-rs#6 is merged (ba5bdd0), and native/Cargo.toml, cli/psp-toolchain.json, native-vita and both lockfiles now point at it. test/psp-toolchain.test.ts caught that I had moved only one of those — good guard.

But the repin alone changed nothing, and I have to correct something I said earlier.

libquickjs.a came out byte-identical in size across the -O0 rev and the -O2 rev. scripts/psp.ts sets CRATE_CC_NO_DEFAULTS=1, and cc-rs guards its entire default-flag block on exactly that (cc-1.2.65 src/lib.rs):

let no_defaults = self.no_default_flags || self.get_env_boolean("CRATE_CC_NO_DEFAULTS");
if !no_defaults { self.add_default_flags(&mut cmd, &target, &opt_level)?; }

add_default_flags is the only place cc emits -O. So a build script's .opt_level(2) has never reached this target, and TARGET_CFLAGS carried no -O either — clang compiled every C dependency at its -O0 default. My earlier claim that the -O2 fix "was worth roughly a 2x on JS time" was an inference from a build where the flag never reached the compiler. It should not have been stated as measured.

The fix is -O2 in TARGET_CFLAGS (scripts/psp.ts and scripts/gu-demo.ts, both of which set the no-defaults flag). Evidence it took effect this time: libquickjs.a 1,779,170 → 1,478,486 bytes, where flipping the build script's opt_level had left it identical.

Measured on hardware, rally

	pinned -O2 (inert)	-O2 in TARGET_CFLAGS
guest turn	7,119 µs	3,972 µs (−44%)
frame work	13,058 µs	9,900 µs
critical path	14.8 ms	13.2 ms
over-budget frames	25 / 300	25 / 300

The frame is now GE-bound: the display list runs ~8.8 ms and the CPU reaches the sync well before it finishes, so avg_gu_wait_us rose (1.8 → 3.3 ms) even though total work fell. The over-budget count is unchanged because those frames are still the minimap marker refreshes, which are JS-side spikes rather than steady-state cost.

Correctness with the genuinely optimized interpreter: PPSSPP e2e byte-exact, full suite green.

native-vita is unaffected by the -O0 bug — it does not set CRATE_CC_NO_DEFAULTS, so cc emits the profile's optimization level there. It moves to the same rev only to satisfy the one-revision rule.

🤖 Generated with Claude Code