feat(api)!: consistency sweep — colors 0-255 everywhere, degrees everywhere, Texture.handle

Three silent inconsistencies that forced users to read engine source
(audit Tier-3), fixed as one coordinated breaking pass with all
engine examples migrated and docs/migration-0.5.md as the guide:

- setSceneNodeColor / setOutlineColor / setSceneNodeWaterMaterial took
  0-1 floats — the only color params in the API that did; passing a
  Colors preset silently rendered white. Now 0-255 like every draw*
  call (wrappers divide before the FFI; native stays 0-1). Light
  colors deliberately stay 0-1 float + intensity (radiometric, like
  Unity/Unreal) and are documented as such. World-format tints stay
  0-1 (versioned serialized data); the loader converts.
- drawModelRotated took radians while Camera2D.rotation was degrees;
  now degrees everywhere user-facing (raylib convention).
- Texture.id -> Texture.handle (was the lone outlier among resource
  types).

Plus documentation that existed nowhere user-facing: coordinate system
+ SI units at the top of the physics and scene modules, immediate-vs-
retained-mode guidance, loadTexture failure semantics, light-color
convention, @internal markers on the *Raw compiler-workaround variants.

All examples + src/index.ts pass perry check.

Author: proggeramlug

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.

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);
 }
 

src/audio/index.ts

@@ -69,6 +69,13 @@ export function playMusic(music: Music): void {
   bloom_play_music(music.handle);
 }
 
+/**
+ * @internal Compiler workaround — not part of the public API.
+ * Identical to the non-Raw version but takes primitives instead of
+ * reading object fields (aarch64 Android Perry miscompilation where
+ * obj.field reads feeding f64 FFI args arrive as NaN). Use the
+ * non-Raw version; these disappear when the Perry fix ships.
+ */
 export function playMusicRaw(handle: number): void {
   bloom_play_music(handle);
 }
@@ -77,6 +84,13 @@ export function stopMusic(music: Music): void {
   bloom_stop_music(music.handle);
 }
 
+/**
+ * @internal Compiler workaround — not part of the public API.
+ * Identical to the non-Raw version but takes primitives instead of
+ * reading object fields (aarch64 Android Perry miscompilation where
+ * obj.field reads feeding f64 FFI args arrive as NaN). Use the
+ * non-Raw version; these disappear when the Perry fix ships.
+ */
 export function stopMusicRaw(handle: number): void {
   bloom_stop_music(handle);
 }
@@ -85,6 +99,13 @@ export function updateMusicStream(music: Music): void {
   bloom_update_music_stream(music.handle);
 }
 
+/**
+ * @internal Compiler workaround — not part of the public API.
+ * Identical to the non-Raw version but takes primitives instead of
+ * reading object fields (aarch64 Android Perry miscompilation where
+ * obj.field reads feeding f64 FFI args arrive as NaN). Use the
+ * non-Raw version; these disappear when the Perry fix ships.
+ */
 export function updateMusicStreamRaw(handle: number): void {
   bloom_update_music_stream(handle);
 }
@@ -96,6 +117,13 @@ export function setMusicVolume(music: Music, volume: number): void {
   bloom_set_music_volume(music.handle, volume);
 }
 
+/**
+ * @internal Compiler workaround — not part of the public API.
+ * Identical to the non-Raw version but takes primitives instead of
+ * reading object fields (aarch64 Android Perry miscompilation where
+ * obj.field reads feeding f64 FFI args arrive as NaN). Use the
+ * non-Raw version; these disappear when the Perry fix ships.
+ */
 export function setMusicVolumeRaw(handle: number, volume: number): void {
   bloom_set_music_volume(handle, volume);
 }
@@ -104,6 +132,13 @@ export function isMusicPlaying(music: Music): boolean {
   return bloom_is_music_playing(music.handle) !== 0;
 }
 
+/**
+ * @internal Compiler workaround — not part of the public API.
+ * Identical to the non-Raw version but takes primitives instead of
+ * reading object fields (aarch64 Android Perry miscompilation where
+ * obj.field reads feeding f64 FFI args arrive as NaN). Use the
+ * non-Raw version; these disappear when the Perry fix ships.
+ */
 export function isMusicPlayingRaw(handle: number): boolean {
   return bloom_is_music_playing(handle) !== 0;
 }

src/core/types.ts

@@ -46,7 +46,9 @@ export interface Camera3D {
 }
 
 export interface Texture {
-  id: number;
+  /** Engine handle — same field name as Sound/Music/Font/Model. (Was
+   *  `id` before v0.5, the lone outlier among resource types.) */
+  handle: number;
   width: number;
   height: number;
 }

src/models/index.ts

@@ -158,6 +158,11 @@ export function drawModel(model: Model, position: Vec3, scale: number, tint: Col
 /// Draw a model with a Y-axis rotation (radians). RGBA is packed into
 /// a single f64 (ARGB byte order) to keep the FFI to 7 args, dodging
 /// the Perry-ARM64 9th-arg quirk.
+/**
+ * Draw a model with a Y-axis rotation in DEGREES (engine-wide angle
+ * convention, matching Camera2D.rotation and raylib; was radians before
+ * v0.5). Tint components are 0-255.
+ */
 export function drawModelRotated(
   model: Model, position: Vec3, scale: number, rotY: number, tint: Color,
 ): void {
@@ -168,7 +173,7 @@ export function drawModelRotated(
   const b =  tint.b & 0xff;
   // Use unsigned-shift-zero to keep the value positive when stored as f64.
   const packed = (a | r | g | b) >>> 0;
-  bloom_draw_model_rotated(model.handle, position.x, position.y, position.z, scale, rotY, packed);
+  bloom_draw_model_rotated(model.handle, position.x, position.y, position.z, scale, rotY * Math.PI / 180, packed);
 }
 
 export function unloadModel(model: Model): void {