npm - incanto - Versions diffs - 0.67.0 → 0.68.0 - Mend

incanto 0.67.0 → 0.68.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (70) hide show

package/bin/_pick-server.mjs +48 -0
package/bin/incanto-check.mjs +16 -2
package/bin/incanto-frame.mjs +10 -25
package/bin/incanto-logs.mjs +8 -18
package/dist/2d.d.ts +6 -6
package/dist/2d.js +6 -4
package/dist/3d.d.ts +30 -6
package/dist/3d.js +8 -6
package/dist/{audio-player-BNUHo0JF.d.ts → audio-player-DOrq7sP-.d.ts} +62 -4
package/dist/{behavior-ZnfzKDo3.d.ts → behavior-DoFPYrgo.d.ts} +78 -1
package/dist/boot-failure-CKYrEcGF.js +47 -0
package/dist/{create-game-FAXdHta3.js → create-game-DbWtVTxD.js} +21 -25
package/dist/{create-game-DMetd3vR.js → create-game-IZIydDwI.js} +9 -9
package/dist/debug.d.ts +1 -1
package/dist/{duplicate-B8QnX2-r.js → duplicate-IWIqk0HJ.js} +1 -1
package/dist/{editor-switch-DAvWQeld.d.ts → editor-switch-CnIOiyNJ.d.ts} +1 -1
package/dist/editor.js +11 -5
package/dist/env.d.ts +1 -1
package/dist/{environment-presets-C-5g2pMh.js → environment-presets-CybQXNqS.js} +57 -8
package/dist/{gameplay-CGSv-9XR.js → gameplay-DM1eu_cV.js} +20 -2
package/dist/gameplay.d.ts +51 -3
package/dist/gameplay.js +2 -2
package/dist/index.d.ts +6 -6
package/dist/index.js +8 -7
package/dist/{loader-KZESOZmE.js → loader-BC4PNtJX.js} +26 -1
package/dist/{loader-DyT30ArB.d.ts → loader-CcB533FR.d.ts} +2 -2
package/dist/net.d.ts +2 -2
package/dist/net.js +1 -1
package/dist/{physics-2d-_B6zj3zU.js → physics-2d-B7Y6dPZO.js} +2 -2
package/dist/{physics-3d-i1IeAY0F.js → physics-3d-bG3n70Ky.js} +3 -3
package/dist/react.d.ts +2 -2
package/dist/react.js +1 -1
package/dist/{register-Cs53CY7s.js → register-3ta-2Xig.js} +68 -7
package/dist/{register-vIxU3Xbv.js → register-ibCjm-wH.js} +3 -3
package/dist/{replay-BkpDV51O.js → replay-CYvhVHHN.js} +28 -5
package/dist/{replay-D0GcEHYU.d.ts → replay-Dvn8aeBd.d.ts} +38 -4
package/dist/{schema-CFeioQRE.d.ts → schema-B6ugCV1Q.d.ts} +11 -0
package/dist/{split-screen-DS8RaUV_.js → split-screen-CYwDkbLF.js} +2 -2
package/dist/{split-screen-DD5eYIgW.d.ts → split-screen-DhrSzZIB.d.ts} +3 -3
package/dist/{src-BLlsGJW9.js → src-D7RIqXYF.js} +1 -1
package/dist/{teardown-LB9cTnXJ.js → teardown-D2NEmxPB.js} +2 -2
package/dist/{test-81uZ967a.js → test-8hoHeRmo.js} +26 -21
package/dist/test.d.ts +6 -6
package/dist/test.js +3 -3
package/dist/vite.js +2 -2
package/dist/{rendering-options-ByAdi8PF.js → webgl-unavailable-N9nQqesw.js} +45 -1
package/editor/assets/{agent8-C2jtNKbx.js → agent8-BrrHOjMJ.js} +1 -1
package/editor/assets/{debug-DoU3KeqS.js → debug-BBhKuBNV.js} +1 -1
package/editor/assets/{index-CNqHojcC.js → index-eVd0BToA.js} +92 -92
package/editor/index.html +1 -1
package/package.json +1 -1
package/schemas/scene.schema.json +4 -0
package/skills/incanto-3d-character.md +1 -0
package/skills/incanto-audio.md +49 -0
package/skills/incanto-building-2d-games.md +37 -0
package/skills/incanto-building-3d-games.md +37 -0
package/skills/incanto-gameplay-behaviors.md +28 -1
package/skills/incanto-node-reference.md +1 -0
package/skills/incanto-physics-and-input.md +23 -0
package/skills/incanto-scene-json-authoring.md +12 -1
package/templates-app/beacon-isle-3d/package.json +1 -1
package/templates-app/beacon-isle-3d/src/main.ts +8 -1
package/templates-app/platformer-2d/package.json +1 -1
package/templates-app/platformer-2d/src/main.ts +8 -1
package/templates-app/star-survivor/package.json +1 -1
package/templates-app/star-survivor/src/main.ts +8 -1
package/templates-app/tps-3d/package.json +1 -1
package/templates-app/tps-3d/src/main.ts +8 -1
package/templates-app/village-quest-3d/package.json +1 -1
package/templates-app/village-quest-3d/src/main.ts +8 -1

package/editor/index.html CHANGED Viewed

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Incanto Scene Editor</title>
     <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'><rect width='16' height='16' rx='3' fill='%236ee7dc'/><text x='8' y='12' text-anchor='middle' font-size='11' font-family='monospace' fill='%230e1018'>i</text></svg>" />
-    <script type="module" crossorigin src="./assets/index-CNqHojcC.js"></script>
+    <script type="module" crossorigin src="./assets/index-eVd0BToA.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/GameServer-C56iOUgF.js">
   </head>
   <body>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "incanto",
-  "version": "0.67.0",
+  "version": "0.68.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",

package/schemas/scene.schema.json CHANGED Viewed

@@ -2378,6 +2378,10 @@
               "type": "boolean",
               "default": true
             },
+            "platformCarry": {
+              "type": "boolean",
+              "default": true
+            },
             "turnSpeed": {
               "type": "number",
               "default": 100

package/skills/incanto-3d-character.md CHANGED Viewed

@@ -54,6 +54,7 @@ did not until now.
 | `maxJumps` | `1` | `2` = double jump. Extra jumps work in mid-air. |
 | `airControl` | `0.2` | how much ground control you keep airborne (0 = committed, 1 = full). |
 | `fallGravity` | `2.5` | gravity multiplier while falling. Higher = snappier arc. |
+| `platformCarry` | `true` | ride whatever you are standing on. Off = the controller steers in WORLD space, so standing still on a moving floor brakes you off it (measured: 95.9% of a moving deck's travel kept, 0.0% with this off). |
 Every one defaults to OFF (`0` / `1`) or to the previous hard-coded constant, so
 a scene that asks for nothing behaves exactly as before.

package/skills/incanto-audio.md CHANGED Viewed

@@ -396,6 +396,55 @@ changed under it. `engine.music` deliberately survives a scene swap (it belongs
 to the engine, not the scene): call `engine.music.stop(1)` or `crossfadeTo` when
 the music should change.
+## Sounds on a GRID: rhythm games and anything charted to a soundtrack
+A sound fired from `update()` cannot land closer than one frame to where a chart
+wants it — 16.67 ms at 60 Hz, 33.33 ms at 30, and that is the whole difference
+between a rhythm game that feels tight and one that does not. The engine's frame
+clock is exact (3600 steps land on `engine.time` 60.000000000 s and beat error
+never compounds); the last 16 ms is the gap.
+Schedule on the AUDIO clock instead. Queue a short LOOKAHEAD ahead of now, every
+frame, and let Web Audio place the sound:
+```ts
+const LEAD = 0.08;                 // schedule this far ahead of the speaker
+let cursor = 0;                    // next un-queued note
+engine.updated.connect(() => {
+  const horizon = engine.sfx.now + LEAD;
+  while (cursor < chart.length && startedAt + chart[cursor].atSec <= horizon) {
+    hit.play(startedAt + chart[cursor].atSec);   // AudioPlayer.play(at)
+    cursor++;
+  }
+});
+```
+- **`engine.sfx.now`** — seconds on the audio clock, the one the sound is
+  actually placed on. `0` headless and before the first sound.
+- **`AudioPlayer.play(at)`** and **`engine.sfx.play(params, gain, { when })`** —
+  PRESETS only. A `src` clip goes through an `<audio>` element, which has no
+  scheduling clock; `at` is ignored for one rather than approximated.
+- A time already past plays immediately (Web Audio's own rule), so a scheduler
+  that ran late is late, not silent.
+- Everything else still applies: the bus gain, `engine.audio.recent()`, and
+  `muted`. A scheduler hand-rolled on a raw `AudioContext` hits the same
+  accuracy and loses all three.
+Measured: 0 of 64 notes were given a scheduled start on the frame path; the same
+64 queued this way land at **|mean| 0.000000 ms**.
+**Charting against a music FILE** needs the playhead of the thing you can hear,
+not a counter you started next to `music.play()` (a different clock, which keeps
+counting through a gesture-block, a stall or a seek):
+```ts
+const songSeconds = engine.music.playhead;   // null = nothing playing, or no clock
+```
+It is the raw element time, so a looping track wraps to 0 each pass — a loop
+boundary to chart against, not a fault.
 ## Decision guide
 - **Need a quick game sound (coin/jump/hit/explosion/…)** → set `preset`. Done.

package/skills/incanto-building-2d-games.md CHANGED Viewed

@@ -485,3 +485,40 @@ which is why a wall jump was not awkward to write but impossible.
 headless bot sessions and reports what could not be reached, which wires never
 fired, and whether anything in the level can hurt the player. See
 `incanto-playtesting.md`.
+## When the boot FAILS: say so, or the bar sits at 100% forever
+`createGame2D`/`createGame2D` reject like any promise, and the loading overlay
+every starter shows is removed on the line *after* the await. So a boot that
+fails leaves the bar at 100% with no text, and the reason in a console the
+player will never open. Measured with WebGL denied on a pristine scaffold: the
+overlay was still reading `Emberwood 100%` 8.6 seconds later.
+One `.catch` fixes it, and every shipped template now carries it:
+```ts
+import { createGame2D, showBootFailure } from 'incanto/2d';
+const game = await createGame2D({ canvas, scene: sceneJson }).catch((e) => {
+  showBootFailure(e);   // paints the reason into #loading (or its own panel)
+  throw e;
+});
+document.querySelector('#loading')?.remove();
+```
+**No WebGL is the case worth naming** — the 2D renderer is WebGL too. A machine
+with acceleration off, a blocklisted driver, a locked-down or headless browser, or a page that already
+holds too many contexts cannot make one, and three throws
+`Error('Error creating WebGL context.')` with nothing to branch on. The engine
+rethrows it as an `IncantoError` with code **`WEBGL_UNAVAILABLE`** and a message
+naming the likely causes, so you can show a real screen:
+```ts
+import { isWebGLAvailable } from 'incanto/2d';
+if (!isWebGLAvailable()) showMyOwnBrowserTooOldScreen();   // ask BEFORE booting
+```
+`isWebGLAvailable()` probes a throwaway canvas and never touches yours; it
+returns `false` outside a browser.

package/skills/incanto-building-3d-games.md CHANGED Viewed

@@ -648,3 +648,40 @@ It stubs unregistered behaviors (it measures geometry, not logic; a scene with
 any custom behavior used to read as clean — measured 0 floating before
 `registerBehavior`, 26 after) and throws when it cannot measure. A level built
 from mesh floors has no terrain height to read: use a physics raycast instead.
+## When the boot FAILS: say so, or the bar sits at 100% forever
+`createGame2D`/`createGame3D` reject like any promise, and the loading overlay
+every starter shows is removed on the line *after* the await. So a boot that
+fails leaves the bar at 100% with no text, and the reason in a console the
+player will never open. Measured with WebGL denied on a pristine scaffold: the
+overlay was still reading `Emberwood 100%` 8.6 seconds later.
+One `.catch` fixes it, and every shipped template now carries it:
+```ts
+import { createGame3D, showBootFailure } from 'incanto/3d';
+const game = await createGame3D({ canvas, scene: sceneJson }).catch((e) => {
+  showBootFailure(e);   // paints the reason into #loading (or its own panel)
+  throw e;
+});
+document.querySelector('#loading')?.remove();
+```
+**No WebGL is the case worth naming.** A machine with acceleration off, a
+blocklisted driver, a locked-down or headless browser, or a page that already
+holds too many contexts cannot make one, and three throws
+`Error('Error creating WebGL context.')` with nothing to branch on. The engine
+rethrows it as an `IncantoError` with code **`WEBGL_UNAVAILABLE`** and a message
+naming the likely causes, so you can show a real screen:
+```ts
+import { isWebGLAvailable } from 'incanto/3d';
+if (!isWebGLAvailable()) showMyOwnBrowserTooOldScreen();   // ask BEFORE booting
+```
+`isWebGLAvailable()` probes a throwaway canvas and never touches yours; it
+returns `false` outside a browser.

package/skills/incanto-gameplay-behaviors.md CHANGED Viewed

@@ -1211,7 +1211,7 @@ spawners, music, or monster aggression to it. The `hour` field (0-24) is
 writable: jump to a time of day in one assignment. For one-off look changes
 use `setEnvironment3D(engine, patch)` from `incanto/3d` directly.
-## Boot loading overlay## Boot loading overlay
+## Boot loading overlay
 ```ts
 import { preloadSceneAssets } from 'incanto';
@@ -1221,6 +1221,33 @@ await preloadSceneAssets(sceneJson.assets);   // black screen + bar + %, auto-re
 Replaces the ~125-line hand-rolled loading screen; `createLoadingOverlay()`
 gives you the raw overlay when you preload something else.
+## Where a node actually IS (`position` is parent-relative)
+`node.position` is the offset from its PARENT, not the world. A scene nests
+freely — `Terrain/Clouds/Cloud1/Puff1` four deep is what the engine's own
+generator writes — so a distance check reading `position` on a nested node
+measures from the wrong origin and says nothing about it. Measured on a crate
+parented to a rock: `position` is `[0, 3.02, 0]` and the world point is
+`[13, 14.31, 80.18]` — **82 m apart**.
+```ts
+import { localFromWorld, worldPosition } from 'incanto/gameplay';
+const here = worldPosition(crate);              // [13, 14.31, 80.18]
+crate.position = localFromWorld(crate, [0, 20, 0]);   // put it at world [0,20,0]
+```
+Both work headless and in both dimensions — arity comes from the node (2 for a
+2D node, 3 for a 3D one), and an ancestor with no `position` contributes
+nothing. Do NOT reach for `_ensureObject3D().matrixWorld`: it is internal, and
+in a headless verify script there is no renderer to parent the object, so it
+hands back the LOCAL position with no warning.
+**Translation only.** They sum ancestor positions and ignore ancestor rotation
+and scale — the same contract physics already uses (`worldPosition2D` /
+`worldPosition3D`) and that `applyGroundSnap` assumes. A node under a ROTATING
+parent needs the renderer's matrix, not this.
 ## Persistence (high scores, unlocks, settings)
 ```ts

package/skills/incanto-node-reference.md CHANGED Viewed

@@ -297,6 +297,7 @@ Signals: `movementStateChanged(state)`
 | `pitchMin` | `-1.3` | number |
 | `pitchMax` | `1.5` | number |
 | `cameraCollision` | `true` | boolean |
+| `platformCarry` | `true` | boolean |
 | `turnSpeed` | `100` | number |
 | `camLerp` | `25` | number |
 | `moveAction` | `"move"` | string |

package/skills/incanto-physics-and-input.md CHANGED Viewed

@@ -479,6 +479,29 @@ rotating discs. It is what makes a floating-island game work.
 Author it the obvious way: move the platform's `position` (a behavior, a
 `PathFollow`, an `Oscillate`). Nothing else to declare.
+**The 3D PLAYER is a different rig, and it needs one prop.** A
+`CharacterController3D` must sit under a dynamic `RigidBody3D` (hard error
+otherwise), not a `CharacterBody3D` — the character bodies in a 3D game are its
+enemies and NPCs. The controller steers toward a target velocity every fixed
+step, so pressing nothing means "target zero", which in world space is a brake
+aimed at the platform's own motion. `platformCarry` (default **true**) makes
+that target relative to the floor instead. Measured on a 400 m deck moving
+4 m/s, rider pressing nothing: **95.9%** of the travel kept, **0.0%** with
+`platformCarry: false`.
+```json
+{ "name": "Ctl", "type": "CharacterController3D",
+  "props": { "view": "free", "platformCarry": false } }
+```
+Turn it off for a conveyor you want to be scenery. Vertical carry needs no prop
+either way — the hover spring rides whatever surface is under it, which is why
+a 3D elevator always looked right while a conveyor did not.
+The carry comes from the platform's POSITION DELTA, not its `linearVelocity`,
+because writing `position` calls `setTranslation` — a teleport that transfers no
+momentum to anything. Both authoring styles work.
 The carry stops the moment the character is no longer grounded on it, so walking
 off an edge or jumping is not "sticky", and it is vertical as well as horizontal
 — an elevator lifts you.

package/skills/incanto-scene-json-authoring.md CHANGED Viewed

@@ -26,6 +26,7 @@ wiring, and composition are all in the file. TS is for *behavior only* (attached
   "constants": { "UI": 1000, "Background": -100 },
   "input": { "<action>": { "...": "...", "touch": "joystick|button (optional — mobile on-screen controls)" } },
   "multiplayer": { "room": "auto" },
+  "fragment": false,
   "root": { "name": "Level1", "type": "Node", "children": [] },
   "connections": []
 }
@@ -33,6 +34,13 @@ wiring, and composition are all in the file. TS is for *behavior only* (attached
 - `format` MUST be `1`. `type` MUST be `"scene"`. `name` non-empty.
 - `dimension` is optional: `"2d"` or `"3d"` only.
+- `fragment` (optional, default `false`) says this file is a PIECE of another
+  scene — a spawner's prefab, a sub-scene something instances — and is never
+  rendered on its own. It changes nothing at runtime; it tells the checker to
+  stop asking a prefab where its camera and its sun are. Set it on any scene
+  you load from TypeScript and hand to a spawner. (A scene another scene
+  embeds with `instance` needs no key — `incanto-check` walks the project and
+  can see that for itself.)
 - `viewport` (optional) makes scene JSON own responsive layout: author the world
   in fixed `design` pixels (`[width, height]`, positive numbers) and the renderer
   maps them onto any canvas size. `fit`: `"expand"` (design rect always fully
@@ -158,7 +166,10 @@ level 1's layers.
 ## Parents and children
 EVERY node type can hold children — `children` is universal, so any node works
-as a grouping container. The inverse is not true: some types demand a SPECIFIC
+as a grouping container. **A child's `position` is relative to its parent**, so
+nesting is also how you move a group: shift the parent and everything under it
+follows. From code, `worldPosition(node)` (`incanto/gameplay`) is where a nested
+node actually is; `node.position` is the local offset. The inverse is not true: some types demand a SPECIFIC
 parent and are therefore also invalid as the root. Today's rule:
 - `CharacterController2D` must be a direct child of a `CharacterBody2D` —

package/templates-app/beacon-isle-3d/package.json CHANGED Viewed

@@ -14,7 +14,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.67.0",
+    "incanto": "^0.68.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/beacon-isle-3d/src/main.ts CHANGED Viewed

@@ -6,7 +6,7 @@
  * world with `bun run world`, the game logic never changes.
  */
 import { assetUrls, preloadUrls } from 'incanto';
-import { createGame3D } from 'incanto/3d';
+import { createGame3D, showBootFailure } from 'incanto/3d';
 import { BEHAVIORS } from './behaviors';
 import gameJson from './game.scene.json';
@@ -25,6 +25,13 @@ const game = await createGame3D({
   scene: gameJson,
   behaviors: BEHAVIORS,
   pointer: true,
+}).catch((e) => {
+  // Without this the player watches the loading overlay sit at 100% forever:
+  // `#loading` is removed on the line below, so anything that rejects here (no
+  // WebGL context, a scene that will not load) leaves the bar up and the reason
+  // in a console nobody opens.
+  showBootFailure(e);
+  throw e;
 });
 document.querySelector('#loading')?.remove();

package/templates-app/platformer-2d/package.json CHANGED Viewed

@@ -11,7 +11,7 @@
   },
   "dependencies": {
     "@dimforge/rapier2d-compat": "0.19.3",
-    "incanto": "^0.67.0",
+    "incanto": "^0.68.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/platformer-2d/src/main.ts CHANGED Viewed

@@ -14,7 +14,7 @@
  * height/stomp/knockback/checkpoint-respawn/platform-carry), GoblinSkin,
  * FollowCam (follow + screen-shake), ParallaxLayer, HudUpdater.
  */
-import { createGame2D } from 'incanto/2d';
+import { createGame2D, showBootFailure } from 'incanto/2d';
 import goblinUrl from 'incanto/assets/characters/goblin.png';
 // Built-in sprite art ships in the package — import the URLs and inject them into
 // the scene's asset placeholders before boot (the engine clones the scene).
@@ -49,6 +49,13 @@ const game = await createGame2D({
   canvas,
   scene,
   behaviors,
+}).catch((e) => {
+  // Without this the player watches the loading overlay sit at 100% forever:
+  // `#loading` is removed on the line below, so anything that rejects here (no
+  // WebGL context, a scene that will not load) leaves the bar up and the reason
+  // in a console nobody opens.
+  showBootFailure(e);
+  throw e;
 });
 document.querySelector('#loading')?.remove();

package/templates-app/star-survivor/package.json CHANGED Viewed

@@ -11,7 +11,7 @@
   },
   "dependencies": {
     "@dimforge/rapier2d-compat": "0.19.3",
-    "incanto": "^0.67.0",
+    "incanto": "^0.68.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/star-survivor/src/main.ts CHANGED Viewed

@@ -11,7 +11,7 @@
  * leaves open: `Survivor` (move + auto-attack + XP/level-up/upgrades + HUD),
  * `Director` (ring-spawn around the player + escalation), `EnemyDrop`, `EnemyFace`.
  */
-import { createGame2D } from 'incanto/2d';
+import { createGame2D, showBootFailure } from 'incanto/2d';
 import ghostUrl from 'incanto/assets/characters/ghost.png';
 import goblinUrl from 'incanto/assets/characters/goblin.png';
 import knightUrl from 'incanto/assets/characters/medieval-knight.png';
@@ -36,6 +36,13 @@ const game = await createGame2D({
   canvas,
   scene,
   behaviors,
+}).catch((e) => {
+  // Without this the player watches the loading overlay sit at 100% forever:
+  // `#loading` is removed on the line below, so anything that rejects here (no
+  // WebGL context, a scene that will not load) leaves the bar up and the reason
+  // in a console nobody opens.
+  showBootFailure(e);
+  throw e;
 });
 document.querySelector('#loading')?.remove();

package/templates-app/tps-3d/package.json CHANGED Viewed

@@ -13,7 +13,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.67.0",
+    "incanto": "^0.68.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/tps-3d/src/main.ts CHANGED Viewed

@@ -13,7 +13,7 @@
  * win/lose banner).
  */
 import { assetUrls, preloadUrls } from 'incanto';
-import { createGame3D } from 'incanto/3d';
+import { createGame3D, showBootFailure } from 'incanto/3d';
 // A bundled clip looped as low ambience (no large music files ship in the
 // package — see incanto-audio.md). vite resolves + hashes the real file.
 import musicUrl from 'incanto/assets/audio/spells_cast.mp3';
@@ -41,6 +41,13 @@ const game = await createGame3D({
   scene: sceneJson,
   behaviors: { Shoot, HudUpdater },
   pointer: true, // pointer-lock mouse look (lockOnClick) — drives the free-view yaw/pitch
+}).catch((e) => {
+  // Without this the player watches the loading overlay sit at 100% forever:
+  // `#loading` is removed on the line below, so anything that rejects here (no
+  // WebGL context, a scene that will not load) leaves the bar up and the reason
+  // in a console nobody opens.
+  showBootFailure(e);
+  throw e;
 });
 document.querySelector('#loading')?.remove();

package/templates-app/village-quest-3d/package.json CHANGED Viewed

@@ -13,7 +13,7 @@
     "@dimforge/rapier2d-compat": "0.19.3",
     "@dimforge/rapier3d-compat": "0.19.3",
     "@pixiv/three-vrm": "^3.5.3",
-    "incanto": "^0.67.0",
+    "incanto": "^0.68.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/village-quest-3d/src/main.ts CHANGED Viewed

@@ -8,7 +8,7 @@
  * declarative `animations` map — zero animation code.
  */
 import { assetUrls, preloadUrls } from 'incanto';
-import { createGame3D } from 'incanto/3d';
+import { createGame3D, showBootFailure } from 'incanto/3d';
 import { BEHAVIORS } from './behaviors';
 import villageJson from './village.scene.json';
@@ -27,6 +27,13 @@ const game = await createGame3D({
   scene: villageJson,
   behaviors: BEHAVIORS,
   pointer: true, // pointer-lock look (click the canvas)
+}).catch((e) => {
+  // Without this the player watches the loading overlay sit at 100% forever:
+  // `#loading` is removed on the line below, so anything that rejects here (no
+  // WebGL context, a scene that will not load) leaves the bar up and the reason
+  // in a console nobody opens.
+  showBootFailure(e);
+  throw e;
 });
 document.querySelector('#loading')?.remove();