Merge pull request #65 from Bloom-Engine/audit/architecture-fixes

Architecture overhaul: FFI unification, thread safety, fixed-timestep physics, golden tests, LOD, 256 lights

Author: proggeramlug

.github/workflows/test.yml

@@ -71,6 +71,23 @@ jobs:
         working-directory: native/shared
         run: cargo test --release
 
+  # ---------------------------------------------------------------------------
+  # FFI parity: every function in package.json's perry.nativeLibrary manifest
+  # must be exported with matching arity by every platform crate (hand-written
+  # or via define_core_ffi!/define_physics_ffi!). This is the check whose
+  # absence let Android ship 60 functions behind (#59) and Windows ship the
+  # whole scene-graph surface as silent no-op stubs. Cheap (pure text parse),
+  # runs everywhere, gates merges.
+  # ---------------------------------------------------------------------------
+  ffi-parity:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - name: validate-ffi
+        run: node tools/validate-ffi.js
+      - name: file line limit (2000, ratcheting baseline)
+        run: node tools/check-file-lines.js
+
   # ---------------------------------------------------------------------------
   # Lint: rustfmt + clippy. Advisory while the codebase is still in flux.
   # Flip `continue-on-error: false` once the lint baseline is clean.

.gitignore

@@ -71,3 +71,6 @@ tools/unreal_reference/
 tools/dump_dds/target/
 tools/dump_dds/Cargo.lock
 examples/intel-sponza/assets/outdoor.hdr
+
+# Golden-test failure artifacts (written next to the golden on mismatch)
+*.actual.png

docs/migration-0.5.md

@@ -0,0 +1,66 @@
+# Migrating to Bloom 0.5
+
+0.5 makes the API consistent in three places where conventions silently
+diverged. Each change is breaking on purpose — the old inconsistencies
+caused invisible bugs (colors that rendered white, rotations that were
+60× too fast). All engine examples are already migrated and serve as
+references.
+
+## Surface colors are 0–255 everywhere
+
+`setSceneNodeColor`, `setOutlineColor`, and the color part of
+`setSceneNodeWaterMaterial` previously took 0–1 floats — the only places
+in the API that did. They now take 0–255 like every `draw*` call and the
+`Colors` presets.
+
+```ts
+// before                                    // after
+setSceneNodeColor(node, 0.75, 0.75, 0.7);    setSceneNodeColor(node, 191, 191, 179);
+setSceneNodeColor(node, c.r/255, c.g/255, …) setSceneNodeColor(node, c.r, c.g, c.b, c.a);  // Colors presets now just work
+```
+
+Symptom of unmigrated code: scene nodes render almost black (values
+divided twice).
+
+**Unchanged:** light colors (`addDirectionalLight`, `addPointLight`)
+stay 0–1 floats with a separate intensity — that's the radiometric
+convention (Unity and Unreal do the same), and light color × intensity
+can meaningfully exceed 1.0. The `*.world.json` format also keeps 0–1
+tints (serialized data is versioned separately); the loader converts.
+
+## Angles are degrees everywhere
+
+`drawModelRotated`'s `rotY` was radians; `Camera2D.rotation` was degrees.
+Everything user-facing is now degrees (the raylib convention).
+
+```ts
+// before                                    // after
+drawModelRotated(m, p, 1.0, Math.PI / 2, t); drawModelRotated(m, p, 1.0, 90, t);
+```
+
+Symptom of unmigrated code: models spin ~57× faster than intended.
+
+**Unchanged:** physics angular velocity stays radians/sec (SI, matches
+Jolt), and quaternions are quaternions.
+
+## `Texture.handle` (was `Texture.id`)
+
+`Texture` was the only resource type whose handle field was named `id`;
+`Sound`, `Music`, `Font`, and `Model` all use `handle`.
+
+```ts
+// before            // after
+myAtlas.id           myAtlas.handle
+```
+
+## Also in 0.5 (non-breaking)
+
+- `physics.step(world, dt)` is now fixed-timestep with an accumulator
+  and returns the interpolation alpha; `physics.stepVariable` is the
+  old exact-dt behavior. See docs/physics.md "Stepping".
+- Stale handles (use-after-free/destroy) now fail lookups instead of
+  aliasing whatever object reused the slot.
+- `*Raw` function variants are documented `@internal` — they exist only
+  as a compiler workaround and will be removed.
+- Coordinate system is now documented at the top of the physics and
+  scene modules: right-handed, Y-up, meters, SI units.

docs/physics.md

@@ -107,12 +107,50 @@ const ball = physics.createBody(world, ballShape, {
 // 4. Call optimizeBroadphase once after initial body setup.
 physics.optimizeBroadphase(world);
 
-// 5. In your game loop:
-physics.step(world, 1 / 60);
+// 5. In your game loop — pass the real frame delta; step() runs the
+// simulation at a fixed rate internally (see "Stepping" below):
+physics.step(world, deltaTime);
 const pos = physics.getBodyPosition(ball);
 // ... read positions and render sprites / meshes at those transforms
 ```
 
+## Stepping
+
+`physics.step(world, deltaTime)` is **fixed-timestep**: it accumulates the
+wall-clock delta and advances the solver in whole steps of 1/60 s
+(configurable via `setFixedTimestep(world, hz, maxSteps?)`). Variable-size
+solver steps feed frame hitches straight into the constraint solver —
+tunneling and joint explosions on any slow frame — so the accumulator is
+the default, with two protections baked in:
+
+- A single frame's contribution is clamped to 0.25 s (debugger pauses and
+  OS hitches produce one slowed-down frame, not minutes of catch-up).
+- At most `maxSteps` (default 4) fixed steps run per frame; surplus
+  backlog is dropped. The simulation slows down instead of spiraling.
+
+`step` returns the **interpolation alpha**: how far the carried remainder
+sits between the last two physics states. Two ways to use it:
+
+```typescript
+// Easiest: let the engine blend body transforms for rendering.
+physics.setInterpolation(world, true);
+runGame((dt) => {
+  physics.step(world, dt);
+  const p = physics.getBodyPosition(ball); // already smoothed
+});
+
+// Manual: interpolate game-side state with the same alpha.
+const alpha = physics.step(world, dt);     // or physics.getStepAlpha(world)
+```
+
+With interpolation on, `getBodyPosition`/`getBodyRotation` return the
+blended state; physics queries (raycasts, overlaps, contacts) always see
+the raw simulation state.
+
+Exact-dt stepping is still available as `physics.stepVariable(world, dt)`
+for code that drives its own accumulator — it trades stability for
+control.
+
 ## Character controllers (Tier 2)
 
 For player movement, use `CharacterVirtual` — Jolt's kinematic controller with

examples/pbr-spheres/main.ts

@@ -195,7 +195,7 @@ for (let row = 0; row < GRID_N; row = row + 1) {
 
     const node = createSceneNode();
     attachModelToNode(node, sphereHandle, 0);
-    setSceneNodeColor(node, BASE_R, BASE_G, BASE_B);
+    setSceneNodeColor(node, BASE_R * 255, BASE_G * 255, BASE_B * 255);
     setSceneNodePbr(node, roughness, metallic);
     setSceneNodeCastShadow(node, false);
     setSceneNodeReceiveShadow(node, false);

examples/renderer-test/main.ts

@@ -231,7 +231,7 @@ function placeSphere(
   roughness: number, metalness: number,
 ): number {
   const node = placeNode(sphereHandle, 0, px, py, pz, scale, scale, scale);
-  setSceneNodeColor(node, cr, cg, cb);
+  setSceneNodeColor(node, cr * 255, cg * 255, cb * 255);
   setSceneNodePbr(node, roughness, metalness);
   return node;
 }
@@ -243,7 +243,7 @@ function placeCube(
   roughness: number, metalness: number,
 ): number {
   const node = placeNode(cubeHandle, 0, px, py, pz, sx, sy, sz);
-  setSceneNodeColor(node, cr, cg, cb);
+  setSceneNodeColor(node, cr * 255, cg * 255, cb * 255);
   setSceneNodePbr(node, roughness, metalness);
   // Thin horizontal slabs (floors) should receive but not cast
   // shadows — otherwise they fill the shadow map with their own
@@ -374,7 +374,7 @@ function setupWater(): void {
   updateSceneNodeGeometry(waterNode, wv, wi);
   const wm = mat4Translate(mat4Identity(), { x: 0, y: 0.2, z: cz });
   setSceneNodeTransform(waterNode, wm);
-  setSceneNodeWaterMaterial(waterNode, 0.15, 1.5, 0.1, 0.3, 0.5, 0.6);
+  setSceneNodeWaterMaterial(waterNode, 0.15, 1.5, 26, 77, 128, 153);
   setSceneNodeReceiveShadow(waterNode, true);
 
   // Rocks / objects sticking out of water
@@ -457,7 +457,7 @@ function setupThinGeometry(): void {
     const x = cx - 5.5 + i * 1.0;
     const node = createSceneNode();
     attachModelToNode(node, cubeHandle, 0);
-    setSceneNodeColor(node, 0.6, 0.6, 0.62);
+    setSceneNodeColor(node, 153, 153, 158);
     setSceneNodePbr(node, 0.3, 1.0);
     setSceneNodeCastShadow(node, true);
     setSceneNodeReceiveShadow(node, true);

examples/scene-graph/interactive.ts

@@ -52,7 +52,7 @@ let selectedWallId: string | null = null;
 const floorHandle = createSceneNode();
 const floorPolygon = [-10, -10, 10, -10, 10, 10, -10, 10];
 extrudePolygon(floorHandle, floorPolygon, 0.02);
-setSceneNodeColor(floorHandle, 0.85, 0.85, 0.82, 1.0);
+setSceneNodeColor(floorHandle, 217, 217, 209, 255);
 setSceneNodePbr(floorHandle, 0.7, 0.0);
 
 // Handle → wall ID lookup (for picking)
@@ -112,9 +112,9 @@ function wallSystem(dt: number): void {
 
     // Color based on selection
     if (wall.id === selectedWallId) {
-      setSceneNodeColor(wall.handle, 0.3, 0.6, 1.0, 1.0);
+      setSceneNodeColor(wall.handle, 77, 153, 255, 255);
     } else {
-      setSceneNodeColor(wall.handle, 0.95, 0.95, 0.92, 1.0);
+      setSceneNodeColor(wall.handle, 242, 242, 235, 255);
     }
     setSceneNodePbr(wall.handle, 0.8, 0.0);
 

examples/scene-graph/main.ts

@@ -149,10 +149,10 @@ const floorIdx: number[] = [0, 1, 2, 0, 2, 3];
 updateSceneNodeGeometry(floor, floorVerts, floorIdx);
 
 // Set materials
-setSceneNodeColor(wall1, 0.95, 0.95, 0.92, 1.0);
-setSceneNodeColor(wall2, 0.92, 0.92, 0.88, 1.0);
-setSceneNodeColor(wall3, 0.90, 0.90, 0.86, 1.0);
-setSceneNodeColor(floor, 0.7, 0.7, 0.65, 1.0);
+setSceneNodeColor(wall1, 242, 242, 235, 255);
+setSceneNodeColor(wall2, 235, 235, 224, 255);
+setSceneNodeColor(wall3, 230, 230, 219, 255);
+setSceneNodeColor(floor, 179, 179, 166, 255);
 
 // Set PBR properties
 setSceneNodePbr(wall1, 0.8, 0.0);

examples/scene-graph/room.ts

@@ -151,7 +151,7 @@ function slabSystem(dt: number): void {
     extrudePolygon(handle, flat, slab.elevation);
 
     // Gray floor material
-    setSceneNodeColor(handle, 0.75, 0.75, 0.70, 1.0);
+    setSceneNodeColor(handle, 191, 191, 179, 255);
     setSceneNodePbr(handle, 0.6, 0.0);
 
     clearDirty(id);
@@ -203,7 +203,7 @@ function wallSystem(dt: number): void {
     }
 
     // White wall material
-    setSceneNodeColor(handle, 0.95, 0.95, 0.92, 1.0);
+    setSceneNodeColor(handle, 242, 242, 235, 255);
     setSceneNodePbr(handle, 0.8, 0.0);
 
     clearDirty(id);

examples/scene-graph/shadows.ts

@@ -51,7 +51,7 @@ setDirectionalLight(0.5, 1.0, 0.3, 255, 240, 220, 0.7);
 const floor = createSceneNode();
 const floorPoly = [-5, -5, 5, -5, 5, 5, -5, 5];
 extrudePolygon(floor, floorPoly, 0.05);
-setSceneNodeColor(floor, 0.8, 0.78, 0.72, 1.0);
+setSceneNodeColor(floor, 204, 199, 184, 255);
 setSceneNodePbr(floor, 0.7, 0.0);
 
 // Walls
@@ -69,7 +69,7 @@ function makeWall(sx: number, sz: number, ex: number, ez: number): void {
     sx - nx, sz - nz,
   ];
   extrudePolygon(node, poly, 3.0);
-  setSceneNodeColor(node, 0.95, 0.93, 0.88, 1.0);
+  setSceneNodeColor(node, 242, 237, 224, 255);
   setSceneNodePbr(node, 0.85, 0.0);
 }
 
@@ -88,7 +88,7 @@ function makeBox(cx: number, cy: number, cz: number, w: number, h: number, d: nu
   // Offset Y via transform
   const t = mat4Translate(mat4Identity(), 0, cy, 0);
   setSceneNodeTransform(node, t);
-  setSceneNodeColor(node, r, g, b, 1.0);
+  setSceneNodeColor(node, r * 255, g * 255, b * 255, 255);
   setSceneNodePbr(node, 0.6, 0.0);
 }