fix: useRightHandedSystem must be passed via Scene constructor options (v1.1.2)

Author: styk-tv

CHANGELOG.md

@@ -6,6 +6,29 @@ Versions follow [SemVer](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.1.2] — 2026-05-01
+
+### Fixed
+- **`useRightHandedSystem` now actually sticks at scene init.** v1.1.1 set
+  `scene.useRightHandedSystem = true` via property assignment AFTER the
+  Scene constructor returned. Empirically, on Babylon 9.5.0 that
+  assignment does not survive the rest of scene initialisation — a
+  runtime probe shortly after createWireface returned read
+  `scene.useRightHandedSystem === false` despite the source assignment.
+  The face still rendered visibly because of the default `flipFace: true`
+  rotation, but profile / three-quarter views were mirrored (camera at
+  `+X` saw the face's left because the geometry was implicitly flipped
+  by the runtime LH→fix-by-rotation path).
+
+  Fix: pass the option to the Scene constructor —
+  `new BABYLON.Scene(engine, { useRightHandedSystem: true })`. Verified
+  with playwright: scene now reports `useRightHandedSystem: true` from
+  the first frame and profile / three-quarter views render the
+  conventionally-correct sides of the face. Both lib and editor get
+  the fix; the editor's view buttons now map naturally without any
+  view-alpha rewiring or geometry flip. The post-construction property
+  assign is also kept (belt-and-braces).
+
 ## [1.1.1] — 2026-05-01
 
 ### Fixed
@@ -219,7 +242,8 @@ Initial release.
 - CDN distribution via jsDelivr + unpkg, both indented (`wireface.js`) and
   minified (`dist/wireface.min.js`) flavors.
 
-[Unreleased]: https://github.com/styk-tv/wireface/compare/v1.1.1...HEAD
+[Unreleased]: https://github.com/styk-tv/wireface/compare/v1.1.2...HEAD
+[1.1.2]: https://github.com/styk-tv/wireface/compare/v1.1.1...v1.1.2
 [1.1.1]: https://github.com/styk-tv/wireface/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/styk-tv/wireface/compare/v1.0.2...v1.1.0
 [1.0.2]: https://github.com/styk-tv/wireface/compare/v1.0.1...v1.0.2

examples/editor.html

@@ -572,13 +572,10 @@ <h3>session <span class="num">i/o</span></h3>
 
 const canvas = document.getElementById('renderCanvas');
 const engine = new BABYLON.Engine(canvas, true, { preserveDrawingBuffer: true, stencil: true, antialias: true });
-const scene = new BABYLON.Scene(engine);
-// v1.1.1: use right-handed coordinate system so the face's +Z forward (built
-// by warpToFace) naturally points at the default ArcRotateCamera. Removes
-// the need for a 180° Y-flip at the faceRoot to make front view correct, and
-// fixes the "profile shows back of head" bug — view alphas now map to the
-// natural side of the face, as the user requested ("find a way to ... relax
-// those on init so we can use view as designed").
+// v1.1.2: useRightHandedSystem must be passed via constructor options
+// (post-construction property assign gets silently no-op'd by Babylon 9.5's
+// scene init in some paths). Keeps both forms for resilience.
+const scene = new BABYLON.Scene(engine, { useRightHandedSystem: true });
 scene.useRightHandedSystem = true;
 scene.clearColor = new BABYLON.Color4(0, 0, 0, 1);
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "wireface",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Minimal embeddable wireframe lipsync face renderer — drives expressive character profiles from voice or TTS audio in the browser.",
   "main": "wireface.js",
   "browser": "wireface.js",

wireface.js

@@ -243,18 +243,26 @@
 
     /* ── Babylon scene ── */
     const engine = new BABYLON.Engine(canvas, true, { preserveDrawingBuffer: false, stencil: false, antialias: true });
-    const scene  = new BABYLON.Scene(engine);
-    // v1.1.1: right-handed coordinate system. Babylon defaults to LH where +Z
-    // is into the screen, so a face built with +Z=nose-forward by warpToFace
-    // would render facing AWAY from the default ArcRotateCamera at -Z (the
-    // user would see the back of the head). RH flips Z so +Z is out-of-screen,
-    // which means the face naturally faces the camera AND the camera view
-    // alphas (front=-π/2, profile=0, three-q=-π/2-0.6) map to the
+    // v1.1.2: useRightHandedSystem MUST be set via Scene constructor options
+    // (not by post-construction property assignment) — the post-assign path
+    // gets silently no-op'd somewhere in Babylon 9.5's scene init pipeline,
+    // so the scene boots in LH despite our request. The constructor option
+    // sticks. Verified empirically with playwright: post-assign showed
+    // `scene.useRightHandedSystem === false` at first frame, but options-form
+    // shows true.
+    //
+    // Why we want RH at all: Babylon's LH default puts +Z into the screen.
+    // warpToFace builds the face with +Z = nose-forward, so in LH the face
+    // would render facing AWAY from the default ArcRotateCamera at -Z (user
+    // sees back of head, profile shows wrong side). RH flips Z so +Z is
+    // out-of-screen, geometry naturally faces the camera, and the camera
+    // view alphas (front=-π/2, profile=0, three-q=-π/2-0.6) map to the
     // conventionally-correct sides of the face — front shows the front,
     // profile shows the face's right, three-quarter is a proper portrait
-    // angle. Fixes the "everything is flipped so views start incorrectly"
-    // bug without touching warpToFace, faceRoot.rotation, or any view alpha.
-    scene.useRightHandedSystem = true;
+    // angle. No geometry change, no faceRoot.rotation flip, no view-alpha
+    // rewiring.
+    const scene = new BABYLON.Scene(engine, { useRightHandedSystem: true });
+    scene.useRightHandedSystem = true;  // belt and braces — also assign post-ctor
     scene.clearColor = new BABYLON.Color4(0, 0, 0, 1);
     // we never pick on pointer-move; saves a per-frame ray test
     scene.skipPointerMovePicking = true;