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

incanto 0.68.0 → 0.69.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 (75) hide show

package/assets/catalog.json +9 -5
package/bin/incanto-assets.mjs +14 -1
package/bin/incanto-check.mjs +53 -3
package/bin/incanto-new.mjs +29 -1
package/bin/incanto-serve.mjs +160 -0
package/bin/incanto-verify.mjs +40 -0
package/bin/incanto.mjs +1 -0
package/dist/2d.d.ts +7 -5
package/dist/2d.js +4 -4
package/dist/3d.d.ts +4 -4
package/dist/3d.js +7 -7
package/dist/{audio-player-DOrq7sP-.d.ts → audio-player-C0j2k-yB.d.ts} +32 -13
package/dist/{behavior-DoFPYrgo.d.ts → behavior-rm8vVzu_.d.ts} +67 -0
package/dist/{create-game-DbWtVTxD.js → create-game-CvJ1wSRP.js} +13 -9
package/dist/{create-game-IZIydDwI.js → create-game-CwxEDlCm.js} +13 -9
package/dist/debug.d.ts +1 -1
package/dist/{duplicate-IWIqk0HJ.js → duplicate-Dj4L-5AA.js} +1 -1
package/dist/editor.js +1 -1
package/dist/{environment-presets-CybQXNqS.js → environment-presets-BO-7XoFV.js} +4 -4
package/dist/{frame-report-DCnHFmto.d.ts → frame-report-DNxDAb1w.d.ts} +8 -0
package/dist/{frame-report-BSMny7oe.js → frame-report-Dlq13Gyj.js} +1 -0
package/dist/{gameplay-DM1eu_cV.js → gameplay-D1KixWK8.js} +157 -151
package/dist/gameplay.d.ts +1 -1
package/dist/gameplay.js +1 -1
package/dist/index.d.ts +4 -4
package/dist/index.js +6 -6
package/dist/{loader-BC4PNtJX.js → loader-DZE7B07H.js} +22 -6
package/dist/{loader-CcB533FR.d.ts → loader-DadV2QCT.d.ts} +1 -1
package/dist/net.d.ts +2 -2
package/dist/net.js +1 -1
package/dist/{physics-2d-B7Y6dPZO.js → physics-2d-CF5yyjbj.js} +2 -2
package/dist/{physics-3d-bG3n70Ky.js → physics-3d-DbYaEcZy.js} +3 -3
package/dist/react.d.ts +1 -1
package/dist/react.js +1 -1
package/dist/{register-ibCjm-wH.js → register-DbVArsns.js} +19 -10
package/dist/{register-3ta-2Xig.js → register-mmfugpaQ.js} +107 -15
package/dist/{replay-CYvhVHHN.js → replay-BEHLDcQV.js} +2 -2
package/dist/{replay-Dvn8aeBd.d.ts → replay-BQfkX4x7.d.ts} +1 -1
package/dist/{sheet-grid-BT6N_Bjs.js → sheet-grid-Cea343VO.js} +6 -2
package/dist/{split-screen-CYwDkbLF.js → split-screen-CauMwu6y.js} +2 -2
package/dist/{split-screen-DhrSzZIB.d.ts → split-screen-Cg76MCV5.d.ts} +2 -2
package/dist/{src-D7RIqXYF.js → src-CYEu-_S9.js} +1 -1
package/dist/{teardown-D2NEmxPB.js → teardown-CMqFVxO9.js} +5 -4
package/dist/{test-8hoHeRmo.js → test-D6ISmuFE.js} +60 -17
package/dist/test.d.ts +15 -4
package/dist/test.js +2 -2
package/dist/vite.d.ts +70 -2
package/dist/vite.js +176 -14
package/dist/{webgl-unavailable-N9nQqesw.js → webgl-unavailable-Z5_g8x9H.js} +12 -1
package/editor/assets/{agent8-BrrHOjMJ.js → agent8-BDvaZMQJ.js} +1 -1
package/editor/assets/{debug-BBhKuBNV.js → debug-CMULinBW.js} +1 -1
package/editor/assets/{index-eVd0BToA.js → index-CZIRr5EL.js} +91 -91
package/editor/index.html +1 -1
package/package.json +4 -3
package/skills/incanto-assets.md +16 -2
package/skills/incanto-audio.md +19 -3
package/skills/incanto-building-2d-games.md +29 -0
package/skills/incanto-building-3d-games.md +60 -2
package/skills/incanto-gameplay-behaviors.md +18 -1
package/skills/incanto-save-slots.md +27 -0
package/skills/incanto-verifying-your-game.md +96 -2
package/skills/incanto-your-first-game.md +2 -1
package/templates-app/beacon-isle-3d/package.json +1 -1
package/templates-app/beacon-isle-3d/src/main.ts +13 -3
package/templates-app/platformer-2d/index.html +0 -23
package/templates-app/platformer-2d/package.json +1 -1
package/templates-app/platformer-2d/src/behaviors.ts +26 -16
package/templates-app/platformer-2d/src/game.scene.json +17 -27
package/templates-app/platformer-2d/src/main.ts +24 -12
package/templates-app/star-survivor/package.json +1 -1
package/templates-app/star-survivor/src/main.ts +17 -6
package/templates-app/tps-3d/package.json +1 -1
package/templates-app/tps-3d/src/main.ts +26 -15
package/templates-app/village-quest-3d/package.json +1 -1
package/templates-app/village-quest-3d/src/main.ts +13 -3

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-eVd0BToA.js"></script>
+    <script type="module" crossorigin src="./assets/index-CZIRr5EL.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.68.0",
+  "version": "0.69.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",
@@ -54,7 +54,7 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.node.json",
     "test": "vitest run --project unit --root ../.."
   },
   "peerDependencies": {
@@ -102,6 +102,7 @@
     "incanto-new": "bin/incanto-new.mjs",
     "incanto-frame": "bin/incanto-frame.mjs",
     "incanto-verify": "./bin/incanto-verify.mjs",
-    "incanto-logs": "./bin/incanto-logs.mjs"
+    "incanto-logs": "./bin/incanto-logs.mjs",
+    "incanto-serve": "./bin/incanto-serve.mjs"
   }
 }

package/skills/incanto-assets.md CHANGED Viewed

@@ -21,13 +21,27 @@ playable character — model, locomotion clips, body, controller, skin and input
 ## 1. Built-in assets (in the package)
 ```bash
-bunx incanto-assets list                  # the full catalog (see categories below)
+bunx incanto-assets list                  # name · kind · GRID · what it is
 bunx incanto-assets info medieval-knight  # description + animation names
 bunx incanto-assets copy medieval-knight --out public/assets
 ```
 `list --json` prints every entry. Each entry carries a **`url`** — the drop-in
-reference you put in scene JSON so the asset LOADS (the contract, see §1b).
+reference you put in scene JSON so the asset LOADS (the contract, see §1b) —
+and, where the art has a grid, the numbers a node needs:
+```
+2dbasic          character  [animated] 111×83           2dbasic sprite sheet image…
+minecraft-tiles  tile                  16×16 (25 tiles) Minecraft-themed tiles…
+```
+`frameWidth`/`frameHeight` are what `AnimatedSprite2D.frameWidth` and
+`TileMap2D.tileSize` want; `columns` and `tiles` tell you the highest index a
+`legend` may name (25 tiles means 0–24, and asking for 99 draws clamp-streaks —
+the engine reports it, but the catalog is where you get the number). **The sizes
+live in these fields and nowhere else** — a frame size in the description was a
+second copy, and it drifted: `2dbasic` said 192×192 for art whose real grid is
+111×83.
 ### Categories — the whole built-in set

package/skills/incanto-audio.md CHANGED Viewed

@@ -414,7 +414,7 @@ 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)
+    hit.playAt(startedAt + chart[cursor].atSec);   // NOT play() — see below
     cursor++;
   }
 });
@@ -422,9 +422,14 @@ engine.updated.connect(() => {
 - **`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 })`** —
+- **`AudioPlayer.playAt(when)`** 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.
+  scheduling clock, so `playAt` on one plays immediately.
+- **`play()` takes no arguments, deliberately.** It is the method scenes wire
+  signals to, and a signal hands its handler whatever it carries — `collected`
+  leads with a number, so `collected → play` would have become `play(10)` and
+  scheduled the pickup sound at absolute audio-clock second 10. Scheduling has
+  its own name.
 - 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
@@ -479,6 +484,17 @@ session.engine.audio.recent();
 its volume comes from. `countOf(name)` is the assertion you usually want;
 `clearLog()` resets between steps.
+**A LOOPING sound is recorded once, and its entry carries `loop: true`.**
+Re-recording every pass would evict the rest of the log within seconds for a
+0.2 s preset, so the count stays 1 — which used to make "the alarm loops"
+indistinguishable from "the alarm fired once and stopped". Assert the flag when
+that is the difference you care about:
+```ts
+const alarm = session.engine.audio.recent().find((e) => e.name === 'alarm');
+expect(alarm?.loop).toBe(true);
+```
 This covers every path: `AudioPlayer.play()` on both the procedural and the
 `src` route, `engine.music.play`/`crossfadeTo`, and `engine.sfx.startVoice`. It
 records the INTENT to play — that the wiring fired — not that a speaker moved;

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

@@ -212,6 +212,35 @@ offsets that survive any canvas size: a `Label` at `[-16, 16]` under a
 `top-right` layer hugs the corner everywhere. Misspelled anchors fail at load
 listing the valid set. With a viewport design, UI coordinates are design px.
+### A `UILayer` still SCALES. On a phone, use `HudLayer`
+`UILayer` ignores the camera; it does not ignore the viewport. Its contents are
+design pixels multiplied by the same scale as the world, and on a portrait phone
+that scale is small:
+```
+1280×800   scale 1.333   a fontSize 15 Label paints at 20 device px
+390×844    scale 0.406   the same Label paints at  6.1 device px
+```
+Six device pixels is an unreadable smear, and it is the flagship 2D template's
+control hint before this was fixed. The vertical framing goes the same way:
+`design: [960, 540]` under `fit: "expand"` shows a portrait phone **2077 world
+px** of height, so the play surface is a band with acres of empty sky.
+**`HudLayer` and the `Ui*` widgets are DOM at their declared CSS pixels** and are
+immune — which is why the engine's own volume sliders and touch controls stayed
+legible in the same capture that reduced the template's HUD to a grey line. Use
+them for anything a player has to READ:
+| | |
+| --- | --- |
+| `Label` under `UILayer` | part of the picture — damage numbers, world-anchored callouts, art |
+| `UiText` under `HudLayer` | part of the interface — score, hearts, hints, menus |
+See `incanto-hud.md`. It costs nothing on desktop and it is the difference
+between a readable and an unusable phone build.
 ## Patterns
 - Group pickups/enemies (`"groups": ["coins"]`) and query `scene.tree.getNodesInGroup('coins')`.

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

@@ -320,8 +320,66 @@ atmosphere recipe below).
 ## Reference example
-A minimal 3D scene — ground plane + 3 orbiting primitives + sun +
-lamp + camera, verified rendering. Copy it as a starting point.
+The smallest 3D scene that renders something you can see. Every line matters:
+without the light it is black, without `current: true` the camera is a guess,
+and without `ambient` the unlit faces are pitch dark.
+```json
+{
+  "format": 1,
+  "type": "scene",
+  "dimension": "3d",
+  "name": "Hello",
+  "environment": {
+    "sky": { "type": "atmosphere", "elevationDeg": 35, "azimuthDeg": 140 },
+    "ambient": { "color": "#ffffff", "intensity": 0.2 },
+    "shadows": true
+  },
+  "root": {
+    "name": "World",
+    "type": "Node3D",
+    "children": [
+      { "name": "Sun", "type": "DirectionalLight3D",
+        "props": { "position": [6, 10, 4], "intensity": 2, "castShadow": true } },
+      { "name": "Camera", "type": "Camera3D",
+        "props": { "position": [7, 6, 9], "rotation": [-26, 36, 0], "current": true } },
+      { "name": "Ground", "type": "MeshInstance3D",
+        "props": { "mesh": "plane", "size": [40, 1, 40], "receiveShadow": true,
+                   "material": { "color": "#6b8f3a", "roughness": 1 } } },
+      { "name": "Pivot", "type": "Node3D", "script": { "name": "Spin" },
+        "children": [
+          { "name": "Cube", "type": "MeshInstance3D",
+            "props": { "mesh": "box", "position": [2, 0.5, 0], "castShadow": true,
+                       "material": { "color": "#e0563f", "roughness": 0.4 } } },
+          { "name": "Ball", "type": "MeshInstance3D",
+            "props": { "mesh": "sphere", "size": [0.6, 0.6, 0.6], "position": [-2, 0.6, 0],
+                       "castShadow": true,
+                       "material": { "color": "#4f8fe0", "metalness": 0.6, "roughness": 0.2 } } },
+          { "name": "Gem", "type": "MeshInstance3D",
+            "props": { "mesh": "gem", "size": [0.5, 0.5, 0.5], "position": [0, 0.8, 2],
+                       "castShadow": true,
+                       "material": { "color": "#ffd166", "flatShading": true, "roughness": 0.1 } } }
+        ] }
+    ]
+  }
+}
+```
+Rotating the PIVOT orbits all three children — no maths in the behaviour:
+```ts
+import { Behavior } from 'incanto';
+export class Spin extends Behavior {
+  override update(dt: number): void {
+    const node = this.node as unknown as { rotation: number[] };
+    node.rotation = [0, (node.rotation[1] ?? 0) + 40 * dt, 0];
+  }
+}
+```
+Check it before you open a browser: `bunx incanto-check` says the scene is legal
+and lit, and `bunx incanto-verify` walks the whole ladder.
 ## Atmosphere (sky, fog, shadows, exposure)

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

@@ -71,7 +71,14 @@ warn: World/Enemy: Chase.target — '%Playerr' matches no node in this scene.
 — which is the one failure that used to be completely silent (a prop path
 resolves with `getNodeOrNull`, so the scene opens and the enemy just never
-chases). `Chase.target` and `FollowCamera.target` are `required`: an EMPTY one
+chases). That is for a behaviour the ENGINE ships: `incanto-check` reads scene
+files and cannot load your TypeScript, so a `nodePath: true` prop on a
+behaviour of YOUR OWN is invisible to it. `auditScene` from `incanto/test`
+gives the identical sentence once your behaviours are registered — which is why
+every scaffolded `verify.ts` calls it before `runScript`, and why a
+hand-written harness that skips it loses this check.
+`Chase.target` and `FollowCamera.target` are `required`: an EMPTY one
 is a load error naming the node, not a surprise in the browser.
 **Never write `/root/<RootName>/...`.** If your root node is named `Game`, the
@@ -1189,6 +1196,16 @@ Multi-scene games: `flow.goToScene(nextSceneJson, { fadeSeconds: 0.4 })`
 fades to black, swaps, fades back (headless = instant). Title → level →
 next level is three JSON files and this one call.
+**A swap builds the physics world the incoming scene needs.** `physics: 'auto'`
+can only look at the scene the game BOOTS with, and a title screen has no
+bodies — so this used to leave the level with no physics at all: it rendered
+perfectly, nothing fell, nothing collided, nothing could be collected or hurt.
+`createGame2D`/`createGame3D` now hand the engine a way to build one, and the
+swap asks. It is asynchronous (Rapier is WASM), so the first frames after a
+swap into a physics scene run unsimulated — imperceptible, and the alternative
+was a game that never simulated. `physics: false` stays off across swaps, and a
+scene with no bodies still pays for nothing.
 ## DayNight (live 24-hour cycle)
 Drives the scene `environment` (needs an atmosphere sky): sun elevation/

package/skills/incanto-save-slots.md CHANGED Viewed

@@ -253,6 +253,33 @@ that DOES serialize, on a node with no uid, is state that goes nowhere.
 (`Health`, `ScoreKeeper`, `Collector`); a scene file cannot be asked whether
 YOUR behavior serializes, so this walks the live tree and names those too.
+## When the browser will not store anything
+A private window, storage disabled, or an exhausted quota: `localStorage`
+throws, and the store falls back to memory. **That fallback is right** —
+refusing to save would be worse — but everything in the session still reads
+healthy, so the player only finds out by reloading and losing the run. Measured
+under Safari-private conditions: `set('highScore', 4200)` then `get(...)`
+returned 4200, with zero warnings and no way to ask.
+```ts
+if (!slots.persistent) {
+  banner.show('This browser will not keep your progress — private window?', { seconds: 6 });
+}
+```
+`SaveSlots.persistent` (and `SaveStore.persistent`) is `false` whenever writes
+live only as long as the tab. The engine also says it once per namespace: on the
+console, and — from `SavePoint` — through `engine.log`, so `incanto-logs` and
+the `says` rung of `incanto-verify` see it too.
+`SavePoint` still emits `saved(slot)` in that state, deliberately: it did save,
+for as long as the page is open, and a Continue button that never lights up
+would be a second bug. Ask `persistent` before promising the player anything.
+Headless — tests, verify scripts, SSR — `persistent` is `false` and nothing is
+logged: in-memory is the design there, not a failure.
 ## Saving from the scene — `SavePoint`
 *When* to save is a design decision (checkpoint, level end, on quit) and only

package/skills/incanto-verifying-your-game.md CHANGED Viewed

@@ -116,6 +116,16 @@ The sections below are the same rungs one at a time, for when you need the detai
 ## 1. After EVERY scene edit: `incanto-check`
+```bash
+bunx incanto-check                                  # structure, assets, semantics
+bunx incanto-check --behaviors src/behaviors.ts --strict-behaviors
+```
+`--strict-behaviors` makes a `script.name` that resolves nowhere a FAILURE
+instead of a stub — and it needs `--behaviors` to know what you registered.
+Without it, on any project with a behaviour of its own, it could only ever fail:
+`Unknown behavior 'Hunter' … Did you forget registerBehavior?`
 ```bash
 bunx incanto-check               # validates every *.scene.json under cwd
 bunx incanto-check --json        # machine-readable (code + details.path/prop)
@@ -637,8 +647,9 @@ the path, then **▶ play ▸ ⤢ run as the game** and the page is the game aga
 running your edit. `game.openEditor()` is the same switch from code.
 It follows `debug` (so a build with the overlay has it) and loads lazily, so a
-game that never opens it never downloads it. `editor: false` opts out;
-`editor: { save }` adds the editor's save button, wired to your own writer:
+game that never opens it never downloads it. `editor: false` opts out at
+RUNTIME — the button is absent — and `editor: { save }` adds the editor's save
+button, wired to your own writer:
 ```ts
 createGame3D({
@@ -660,6 +671,89 @@ overlay is a lazily-imported chunk — it stays out of the main bundle (no size
 cost), but it still ships in the build, so that runtime `debug` flag is the only
 thing gating it: keep it `false` (or dev-gated) in anything you publish.
+## 9. Verify the thing you SHIP, not just the thing you run
+Everything above measures a dev server. The artifact a player gets is
+`bun run build` — a bundled, minified `dist/` with different asset paths and a
+different module graph — and the boot path is the only code a BUILD adds over a
+SCENE. Two of the nastiest defects this engine has had lived exactly there: a
+`main.ts` whose scene swap left the game with no physics, and a boot that threw
+behind a loading overlay that never came down.
+`incanto-frame` and `incanto-logs` ask a dev server, and the dev server asks the
+page over vite's HMR channel. A build has no HMR, so they used to answer:
+```
+? draws — no incanto dev server found.
+? says  — no incanto dev server found.
+```
+**`incanto-serve` closes that.** It serves your build as plain static files —
+no bundler, no transform, byte-for-byte what you deploy — and adds only the
+`/__incanto/*` endpoints the CLIs already speak, plus one inline script injected
+into `index.html` at serve time. Nothing is written to disk, so what you measure
+is what you ship.
+```bash
+bun run build                 # the artifact
+bunx incanto-serve            # ./dist on :4180 (or: incanto-serve build --port 5050)
+# open http://127.0.0.1:4180/ , then:
+bunx incanto-verify           # draws and says now measure the BUILT game
+bunx incanto-logs             # what the built page is complaining about
+bunx incanto-frame --out shipped.png
+```
+**Ship-check list**, in the order things actually break:
+1. **`bun run build` at all.** Dev-only code (`import.meta.env.DEV`, a plugin
+   that is `apply: 'serve'`) can compile and then do nothing.
+2. **Open the built page.** A blank screen with a console error is the common
+   failure; `incanto-logs` reads it without you opening devtools.
+3. **`incanto-verify` against `incanto-serve`.** `draws` catches an asset base
+   path that survived dev and broke under a subdirectory deploy; `says` catches
+   the 404s.
+4. **A phone-sized window.** See `incanto-web-integration.md` — a HUD that is
+   legible at 1280×800 can be 6 px tall at 390×844.
+5. **A second load.** Saves, settings and unlocks come back; a private window
+   answers `slots.persistent === false` (see `incanto-save-slots.md`).
+The one thing `incanto-serve` is not is a production server: it is a local tool
+for looking at a build, on `127.0.0.1` by default.
+### The editor is in your build, even in a 2D game
+`editor: false` is a runtime option and **cannot remove bytes from a bundle**.
+The editor chunk is lazy — a game that never opens it never downloads it — but
+it is in `dist/`, and it imports `incanto/3d`, which imports rapier3d. Measured
+on a pristine `platformer-2d` scaffold:
+```
+2236503  assets/rapier-*.js    rapier3d      ← a 2D game can never execute this
+1692278  assets/rapier-*.js    rapier2d      ← the one it uses
+ 471186  assets/3d-*.js        the 3D adapter
+─────────
+5979588  total
+```
+A build-time decision needs a build-time lever:
+```ts
+import { incantoScenes, incantoTrim } from 'incanto/vite';
+export default defineConfig({
+  plugins: [incantoScenes(), incantoTrim({ editor: false })],
+});
+```
+```
+5979588  →  2769972 bytes     53.7% smaller, same game
+```
+Build only: the dev server keeps the editor, so `☰ debug ▸ ✎ edit this scene`
+works the whole time you are making the game and is simply absent from what you
+ship. Opening it in a trimmed build says so in one sentence rather than failing
+obscurely. Reach for this when deploy size matters — a CDN, a jam upload, an
+agent8 zip — and leave it off otherwise.
 ## 8. Debugging signals
 - `this.log.info(...)` in behaviors — shows up in `runScript().logs` (and the

package/skills/incanto-your-first-game.md CHANGED Viewed

@@ -242,7 +242,8 @@ Things that cost real time, in the order you will meet them.
 | a 3D character that feels right | `incanto-3d-character.md` |
 | terrain, water, trees, sky | `incanto-environment.md` |
 | sound | `incanto-audio.md` |
-| shake, flash, hit-stop, particles | `incanto-game-feel.md` |
+| shake, flash, hit-stop, particles | `incanto-gameplay-behaviors.md` (`CameraShake`, `screenFlash`, `hitStop`, `Particles2D/3D`) |
+| is the feel RIGHT? measure it | `incanto-game-feel.md` |
 | HUD, menus, inventory | `incanto-hud.md` |
 | proving it works | `incanto-verifying-your-game.md` |

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.68.0",
+    "incanto": "^0.69.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

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

@@ -34,7 +34,17 @@ const game = await createGame3D({
   throw e;
 });
-document.querySelector('#loading')?.remove();
-// console-poking handle for playtesting
+// The console handle FIRST, before any wiring of your own can throw.
+// `game.stats()`, `game.assetErrors()`, `game.frame()` and `game.engine.log`
+// are the entire in-page diagnostic surface, and a static build has no other.
+// Assigned after the wiring, one mistake below took all of them with it.
 (window as unknown as { game: typeof game }).game = game;
+// The overlay comes down LAST, after any wiring of your own. There is none in
+// this template — when you add some, put it above this line and wrap it:
+//
+//   try { …your wiring… } catch (e) { showBootFailure(e); throw e; }
+//
+// A throw between the overlay coming down and the handle going up used to leave
+// a level that renders perfectly with no player and no error of any kind.
+document.querySelector('#loading')?.remove();

package/templates-app/platformer-2d/index.html CHANGED Viewed

@@ -49,28 +49,6 @@
           transform: rotate(360deg);
         }
       }
-      .round-btn {
-        position: fixed;
-        bottom: 2rem;
-        right: 2rem;
-        z-index: 1001;
-        width: 88px;
-        height: 88px;
-        border: none;
-        border-radius: 9999px;
-        background: rgba(255, 209, 102, 0.45);
-        color: #1d2a44;
-        font-weight: bold;
-        font-size: 0.9rem;
-        cursor: pointer;
-        user-select: none;
-        -webkit-user-select: none;
-        touch-action: none;
-        transition: transform 0.1s;
-      }
-      .round-btn:active {
-        transform: scale(0.9);
-      }
     </style>
   </head>
   <body>
@@ -79,7 +57,6 @@
       <div class="spinner"></div>
     </div>
     <canvas id="game"></canvas>
-    <button type="button" id="btn-jump" class="round-btn">JUMP</button>
     <script>
       // agent8 embed harness: report the game size to a hosting iframe parent.
       function postGameSize() {

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

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

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

@@ -19,9 +19,9 @@
  *   HudUpdater   — paint ScoreKeeper/hearts/lives into the HUD + win/lose banner.
  */
-import type { Node } from 'incanto';
+import type { Node, UiBanner, UiText } from 'incanto';
 import { Behavior } from 'incanto';
-import type { AnimatedSprite2D, Camera2D, CharacterBody2D, Label, Node2D } from 'incanto/2d';
+import type { AnimatedSprite2D, Camera2D, CharacterBody2D, Node2D } from 'incanto/2d';
 import { Particles2D } from 'incanto/2d';
 // ---- tuning (px, y-down; scene gravity is [0, 1800]) --------------------------
@@ -499,17 +499,27 @@ interface HeartState {
   hearts: number;
 }
 export class HudUpdater extends Behavior {
-  private get coinLabel(): Label {
-    return this.getNode('CoinLabel') as unknown as Label;
-  }
-  private get heartLabel(): Label {
-    return this.getNode('HeartLabel') as unknown as Label;
-  }
-  private get livesLabel(): Label {
-    return this.getNode('LivesLabel') as unknown as Label;
-  }
-  private get banner(): Label {
-    return this.getNode('/root/BannerLayer/Banner') as unknown as Label;
+  /*
+   * `UiText` under a `HudLayer`, not `Label` under a `UILayer`.
+   *
+   * A `Label` lives in the WORLD and scales with `viewport.design`. At
+   * 1280x800 this HUD painted at 20 device px; on a 390x844 phone the same
+   * nodes painted at 6.1 — an unreadable grey smear — because the viewport
+   * scale there is 0.406. The DOM widgets are declared in CSS pixels and are
+   * immune, which is why the engine's own volume sliders and touch controls
+   * stayed legible in the same capture while the flagship's HUD did not.
+   */
+  private get coinLabel(): UiText {
+    return this.getNode('CoinLabel') as unknown as UiText;
+  }
+  private get heartLabel(): UiText {
+    return this.getNode('HeartLabel') as unknown as UiText;
+  }
+  private get livesLabel(): UiText {
+    return this.getNode('LivesLabel') as unknown as UiText;
+  }
+  private get banner(): UiBanner {
+    return this.getNode('/root/BannerLayer/Banner') as unknown as UiBanner;
   }
   private get score(): ScoreLike {
     return this.getNode('/root').behavior as unknown as ScoreLike;
@@ -534,8 +544,8 @@ export class HudUpdater extends Behavior {
     this.livesLabel.text = `x ${Math.max(0, this.score.lives)}`;
   }
   private show(text: string, color: string): void {
-    const b = this.banner;
-    b.text = text;
-    b.color = color;
+    // `UiBanner` owns its own fade and queue; a sticky one stays until the
+    // next `show`, which is what a win/lose screen wants.
+    this.banner.show(text, { color, seconds: 0 });
   }
 }

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

@@ -1848,52 +1848,49 @@
       },
       {
         "name": "HUD",
-        "type": "UILayer",
-        "props": {
-          "anchor": "top-left"
-        },
+        "type": "HudLayer",
         "script": {
           "name": "HudUpdater"
         },
         "children": [
           {
             "name": "CoinLabel",
-            "type": "Label",
+            "type": "UiText",
             "props": {
-              "position": [20, 30],
+              "anchor": "topLeft",
               "text": "◆ 0",
-              "fontSize": 26,
+              "size": 22,
               "color": "#ffd166"
             }
           },
           {
             "name": "HeartLabel",
-            "type": "Label",
+            "type": "UiText",
             "props": {
-              "position": [20, 64],
+              "anchor": "topLeft",
               "text": "♥♥♥",
-              "fontSize": 26,
+              "size": 22,
               "color": "#ff6b81"
             }
           },
           {
             "name": "LivesLabel",
-            "type": "Label",
+            "type": "UiText",
             "props": {
-              "position": [120, 64],
+              "anchor": "topLeft",
               "text": "x 3",
-              "fontSize": 22,
+              "size": 18,
               "color": "#f4f4f4"
             }
           },
           {
             "name": "Hint",
-            "type": "Label",
+            "type": "UiText",
             "props": {
-              "position": [20, 100],
+              "anchor": "bottom",
               "text": "A/D run · Space jump (double-jump!) · stomp goblins · reach the gold flag",
-              "fontSize": 15,
-              "color": "#1d2a44"
+              "size": 14,
+              "color": "#f4f4f4"
             }
           }
         ],
@@ -1901,20 +1898,13 @@
       },
       {
         "name": "BannerLayer",
-        "type": "UILayer",
-        "props": {
-          "anchor": "center"
-        },
+        "type": "HudLayer",
         "children": [
           {
             "name": "Banner",
-            "type": "Label",
+            "type": "UiBanner",
             "props": {
-              "position": [0, 0],
-              "text": "",
-              "fontSize": 64,
-              "color": "#ffffff",
-              "align": "center"
+              "size": 44
             }
           }
         ]