npm - incanto - Versions diffs - 0.62.0 → 0.63.1 - Mend

incanto 0.62.0 → 0.63.1

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 (53) hide show

package/bin/incanto-playtest.mjs +14 -5
package/bin/incanto-verify.mjs +9 -4
package/dist/2d.js +3 -3
package/dist/3d.d.ts +22 -0
package/dist/3d.js +5 -5
package/dist/{create-game-BpunnGPX.js → create-game-BsqKOAFN.js} +6 -6
package/dist/{create-game-Caut3bqN.js → create-game-CSnlQDkz.js} +6 -6
package/dist/{duplicate-E4FUs5Bn.js → duplicate-BOOKmkQ7.js} +1 -1
package/dist/{environment-presets-BAWeOeqf.js → environment-presets-BKRo-HXg.js} +3 -3
package/dist/{gameplay-CaHqDiQD.js → gameplay-Dqm4LyKR.js} +30 -4
package/dist/gameplay.js +1 -1
package/dist/index.js +5 -5
package/dist/{loader-DEe272nY.js → loader-zDynoew_.js} +57 -2
package/dist/net.js +1 -1
package/dist/{physics-2d-BXmu2i7W.js → physics-2d-BUD-MADM.js} +5 -5
package/dist/{physics-3d-ClxP6Uv7.js → physics-3d-BsutZCtX.js} +5 -3
package/dist/react.js +1 -1
package/dist/{register-CNh4FlbD.js → register-BSA93acW.js} +3 -3
package/dist/{register-D3yx8D4r.js → register-Btm7_Emq.js} +1 -1
package/dist/{replay-DlgHItNv.js → replay-DKRmiVjk.js} +42 -2
package/dist/{split-screen-CBM9wcMX.js → split-screen-Dx0LvzqS.js} +2 -2
package/dist/{src-CH00_JsR.js → src-DQzZD_gx.js} +1 -1
package/dist/{teardown-C7qP-dcC.js → teardown-BwhkcNt8.js} +1 -1
package/dist/{test-BMkg8zMV.js → test-wPUuuJpP.js} +50 -18
package/dist/test.d.ts +4 -0
package/dist/test.js +2 -2
package/dist/vite.js +2 -2
package/editor/assets/{agent8-m5mtAO_A.js → agent8-CfacwdPM.js} +1 -1
package/editor/assets/{debug-CPhzCT8f.js → debug-D0kX3cGf.js} +1 -1
package/editor/assets/{index-D422P4kW.js → index-BrG3srCa.js} +92 -92
package/editor/index.html +1 -1
package/package.json +1 -1
package/schemas/scene.schema.json +4 -0
package/skills/README.md +4 -0
package/skills/incanto-game-feel.md +3 -2
package/skills/incanto-gameplay-behaviors.md +37 -6
package/skills/incanto-node-reference.md +1 -0
package/skills/incanto-physics-and-input.md +69 -7
package/skills/incanto-scene-json-authoring.md +15 -1
package/skills/incanto-your-first-game.md +242 -0
package/templates-app/beacon-isle-3d/package.json +1 -1
package/templates-app/platformer-2d/package.json +1 -1
package/templates-app/star-survivor/package.json +1 -1
package/templates-app/star-survivor/src/game.scene.json +4 -2
package/templates-app/tps-3d/PROJECT/Requirements.md +3 -1
package/templates-app/tps-3d/index.html +3 -1
package/templates-app/tps-3d/package.json +1 -1
package/templates-app/tps-3d/src/behaviors.ts +4 -2
package/templates-app/tps-3d/src/game.scene.json +3 -2
package/templates-app/tps-3d/verify.ts +38 -0
package/templates-app/village-quest-3d/package.json +1 -1
package/templates-app/village-quest-3d/src/grove.scene.json +6 -2
package/templates-app/village-quest-3d/src/village.scene.json +8 -4

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-D422P4kW.js"></script>
+    <script type="module" crossorigin src="./assets/index-BrG3srCa.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.62.0",
+  "version": "0.63.1",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",

package/schemas/scene.schema.json CHANGED Viewed

@@ -2043,6 +2043,10 @@
             "slopeLimitDeg": {
               "type": "number",
               "default": 45
+            },
+            "stepHeight": {
+              "type": "number",
+              "default": 0.35
             }
           },
           "additionalProperties": false

package/skills/README.md CHANGED Viewed

@@ -1,6 +1,10 @@
 # incanto skills (shipped)
 Full agent skills for building games with this **installed version** of Incanto.
+**New here? `incanto-your-first-game.md` is the walkthrough** — scaffold to a game
+with a real win and lose, the shape of the loop, and the traps that cost a first
+author an hour. Then come back to this list.
 An AI agent should start with `incanto-scene-json-authoring.md`, then the domain skill
 for the task at hand, and **finish every task with `incanto-verifying-your-game.md`**
 — you cannot see the game, and that skill is how you find out whether it works.

package/skills/incanto-game-feel.md CHANGED Viewed

@@ -20,7 +20,8 @@ feel of /Game/Player
   turnaround       367 ms
   input → motion   1 frame(s)
-  jump apex        0.262 u
+  jump apex        0.262 u   (tapped)
+  held apex        0.981 u   ← size your level against THIS
   time to apex     133 ms
   airtime          267 ms
   coyote window    100 ms
@@ -47,7 +48,7 @@ reports **0 ms**. That was a real bug in this engine's own 3D controller until
 | `to a stop` | how much you slide. A platformer that overshoots ledges has a long one. |
 | `turnaround` | the cost of changing your mind. The number players feel most and name least. |
 | `input → motion` | 1 frame is immediate. More than 2 and something is buffering. |
-| `jump apex` / `airtime` | compare against the gaps and platform heights in your level. |
+| `jump apex` / `airtime` | compare against the gaps and platform heights in your level. **Use the HELD apex** — the plain one is a one-frame TAP, and with `jumpCutMultiplier` (the variable-height jump the 3D character skill recommends at `0.45`) that is a fraction of the real jump: measured 0.478 u tapped against 1.831 u held on the same scene. The held line only appears when the two differ. |
 | `coyote window` | **0 reads to players as "the controls are broken"**, not as a missing feature. |
 | `jump buffer` | 0 throws away a press made a few frames before landing. |

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

@@ -222,18 +222,47 @@ Signals: `totalChanged(total)` — Methods: `collect(value)` — state: `total`
 Deals damage to whatever it touches — projectiles, spikes, lava, enemy hitboxes.
 **Goes on an Area.** On `triggerEnter`, finds the contacted entity's `Health` and
 calls `damage(amount)`, then emits `dealtDamage(amount, healthOwnerNode)`.
-`oncePerTarget` (default) prevents re-hitting a resting body every frame;
-`destroySelf` frees the hazard after a hit (single-use projectiles).
 | Prop | Default | Meaning |
 |---|---|---|
 | `amount` | `10` | HP removed per contact |
-| `targetGroup` | `""` | only damage targets whose Health-owner is in this group (`""` = any) |
-| `oncePerTarget` | `true` | damage each target at most once |
+| `targetGroup` | `""` | only damage targets in this group — the tag may sit on the BODY or on the node carrying its `Health` (`""` = any) |
+| `oncePerTarget` | `true` | damage each target at most **once, ever** |
+| `repeatEvery` | `0` | seconds between re-hits while still overlapping (`0` = entry only) |
 | `destroySelf` | `false` | `queueFree()` after the first hit |
 Signals: `dealtDamage(amount, target)`
+### `repeatEvery` is the "and it keeps hurting" knob
+**Contact events fire on ENTRY and EXIT, not per frame.** So `oncePerTarget:
+false` does not mean "hurt every frame" — it means "hurt again on RE-entry". An
+enemy that closes on you and stops moving has entered once, and deals one hit
+and then nothing. Measured, 6 seconds of unbroken overlap at `amount: 10`:
+```
+oncePerTarget=false  repeatEvery=0     → hp 90   ← one hit, then nothing
+oncePerTarget=false  repeatEvery=0.5   → hp 0
+oncePerTarget=true   repeatEvery=0.5   → hp 0
+oncePerTarget=true   repeatEvery=0     → hp 90
+```
+`repeatEvery` is the only prop that makes a resting overlap keep hurting, and it
+overrides `oncePerTarget` — lava pools, poison clouds, an enemy standing on you.
+Set it on **every enemy contact hitbox**; without it a game plays as though the
+enemies are harmless the moment one of them corners you, and every check comes
+back green.
+Pair it with `Health.invulnerableFor`, which is the real "don't drain me every
+frame" guard: with `invulnerableFor: 0.6`, a `repeatEvery` under 0.6 s just
+lands on i-frames, so 0.5–1 s is the useful range.
+The tag may sit on either end of the entity, because they are commonly
+different nodes: a body holds one behavior, so a player with its own script
+keeps its `Health` on a child, and the group stays on the body. `incanto check`
+reports a `targetGroup` that nothing in the scene can satisfy — a hazard that is
+wired, validated and disarmed is otherwise invisible.
 **`targetGroup` — stop enemies killing each other.** With no collision layers in
 v0 (everything overlaps everything), an enemy's contact hitbox would damage any
 `Health` it touches, including other enemies clustered at the spawn point. Gate
@@ -693,7 +722,8 @@ interaction is a `connection`.
         "script": { "name": "Pickup", "props": { "value": 1 } } },
       { "name": "Spike", "type": "Area2D", "props": { "position": [120, 80],
         "collider": { "shape": "rect", "size": [24, 24] } },
-        "script": { "name": "DamageOnContact", "props": { "amount": 40, "oncePerTarget": false } } }
+        "script": { "name": "DamageOnContact",
+          "props": { "amount": 40, "oncePerTarget": false, "repeatEvery": 0.5 } } }
     ]
   },
   "connections": [
@@ -778,7 +808,8 @@ glue an early sim had to hand-write):
               { "name": "Hit", "type": "Area2D",
                 "props": { "collider": { "shape": "circle", "radius": 12 } },
                 "script": { "name": "DamageOnContact",
-                  "props": { "amount": 10, "targetGroup": "player", "oncePerTarget": false } } }
+                  "props": { "amount": 10, "targetGroup": "player",
+                    "oncePerTarget": false, "repeatEvery": 0.5 } } }
             ] }
         ] }
     ]

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

@@ -239,6 +239,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `velocity` | `[0,0,0]` | array |
 | `stickToGround` | `true` | boolean |
 | `slopeLimitDeg` | `45` | number |
+| `stepHeight` | `0.35` | number |
 Signals: `triggerEnter(other)` · `triggerExit(other)`

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

@@ -357,6 +357,36 @@ the tree says, without your scene falling over while you look at it. Use it for
 any "show me the collision geometry" tool. Do NOT use it to freeze a running
 game — that is `engine.timeScale = 0`, which keeps the world coherent.
+## A walking body climbs a step (`stepHeight`, 3D)
+`CharacterBody3D.stepHeight` (default `0.35` m, `0` = off) is how high a ledge
+the body walks UP without jumping. It is Rapier's autostep, and **Rapier does not
+autostep unless it is asked** — before 0.63 nothing asked, so any walking body
+was stopped dead by a curb.
+You will not see this on the player: `CharacterController3D` rides a hover spring
+rather than the character controller, so it floats over small ledges already.
+It is the ENEMIES that walk, and a chaser walks a straight line — it cannot go
+around. Measured on the shipped `tps-3d` template, whose arena has a 0.6 m ramp
+between the spawn and the player, standing still for 45 seconds:
+```
+before   hits=0  hp=100  closest an enemy ever got = 33.91m
+after    hits=9  hp=..   closest = 1.80m   (exactly Chase.stopRange)
+```
+They chased at full speed the whole time and piled up against the near face of a
+knee-high box. Raise `stepHeight` for a world with real stairs; set it to `0` for
+something that genuinely should be blocked by a curb.
+**It loses to a large downward velocity.** Autostep happens inside the movement
+solve, so a body driven with a big constant gravity term every frame never
+climbs. Same 0.3 m ledge, same `stepHeight: 0.35`, only the `velocity[1]`
+differs: `0` → cleared, `−0.1` → cleared, `−2` → stopped at the face. If you are
+integrating your own gravity, apply it as a falling SPEED that resets on the
+ground, not as a constant push. (`moveBody`, which `Chase` and `Patrol` use,
+derives velocity from a position delta and carries no such term.)
 ## Moving platforms carry their riders (2D **and** 3D)
 A `CharacterBody2D`/`CharacterBody3D` standing on a body that moves is dragged
@@ -398,14 +428,46 @@ From scene JSON, the **`Clickable`** behavior needs no code at all:
 | `maxDistance` | `0` | ignore clicks further than this (0 = any) |
 | `enabled` | `true` | stop responding without detaching |
-Signals: **`clicked`**, **`hovered`**, **`unhovered`** — wire them in
-`connections` like any other. `clicked` fires on RELEASE over the same node the
-press started on (a drag that ends elsewhere is not a click, the way every
-button on every platform behaves), and a hit on a CHILD counts as a hit on the
-node — the raycast lands on the visual mesh, which is usually a child.
+Signals: **`clicked(node)`**, **`hovered(node)`**, **`unhovered(node)`** — wire
+them in `connections` like any other. **Each one carries the node it happened
+on**, so one handler can serve a whole board of tiles:
+```jsonc
+{ "signal": "clicked", "from": "/Board/Tile3", "to": "/Board", "handler": "onTileClicked" }
+```
+```ts
+onTileClicked(tile: Node) { this.flip(tile); }   // which tile, without a wire each
+```
+`clicked` fires on RELEASE over the same node the press started on (a drag that
+ends elsewhere is not a click, the way every button on every platform behaves),
+and a hit on a CHILD counts as a hit on the node — the raycast lands on the
+visual mesh, which is usually a child.
+### Testing a mouse-driven game headlessly
+There is no renderer and therefore no raycast, so `engine.picker` is null and
+`Clickable` is inert. That is not a dead end: give the engine a picker of your
+own and drive the cursor.
+```ts
+// A picker that answers from the tree instead of a GPU raycast.
+engine.picker = (x, y) => hitTestYourBoard(x, y);       // return a Node or null
+engine.input.setPointerPosition(150, 0);                // where the cursor IS
+engine.input.handleMouseButton(0, true);                // press …
+engine.step();
+engine.input.handleMouseButton(0, false);               // … and release
+engine.step();                                          // `clicked` fires here
+```
+Note the BUTTON, not an action: `Clickable` reads `mouseJustPressed` directly,
+so `pressAction('click')` drives nothing. Moving the cursor between the press
+and the release correctly produces no click.
-Headless there is no renderer and therefore no raycast: `Clickable` is inert
-rather than wrong, and `engine.picker` is null.
+Without this a mouse game's entire input surface is load-validated and never
+once executed — the scene is legal, every wire resolves, and nothing has ever
+been clicked.
 ## Placement rules

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

@@ -299,7 +299,21 @@ that do exist at the failing spot).
 - `signal` must be DECLARED on the from node (the class's or its behavior's
   `static signals`) — validated at load → `UNKNOWN_SIGNAL` otherwise.
 - `handler` must be a method on the target node OR its behavior (script) — both are
-  validated hard at load. Otherwise → `UNKNOWN_HANDLER`. On **both**, it is
+  validated hard at load. Otherwise → `UNKNOWN_HANDLER`.
+- **The ARGUMENTS are checked when the wire fires**, not at load — nothing declares
+  how many a signal carries, so the pair can only be compared at the moment both
+  are known. A handler given fewer than it needs is reported once, by name:
+  ```
+  [incanto] 'died' from 'Enemy' carries 0 argument(s) and 'Keeper.addScore' needs 1.
+            The missing one(s) arrive as undefined — a number handler gets NaN and
+            never recovers.
+  ```
+  `died → ScoreKeeper.addScore` is the natural way to score a kill and it sets the
+  score to `NaN` on the first one, with the win condition then permanently out of
+  reach. A handler that DEFAULTS what it is not given is correct and stays silent:
+  `won → GameFlow.win` works, because `win(text = 'YOU WIN')` needs nothing. On **both**, it is
   `AMBIGUOUS_HANDLER`: the node's method wins, so the script's would never run
   and nothing would say so. A core node answers to 62 public methods before any
   adapter adds more (`stop` `play` `show` `clear` `say` `start` `free` …), which

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

@@ -0,0 +1,242 @@
+---
+name: incanto-your-first-game
+description: The walkthrough — scaffold, author, verify, hand back. A complete game with a real win and lose in one sitting, the shape of the loop, and the handful of traps that cost every first-time author an hour. Read this FIRST if you have not shipped an Incanto game before.
+---
+# Your first Incanto game
+> Shipped inside the `incanto` npm package — this document always matches the
+> installed engine version. Sibling skills live in `node_modules/incanto/skills/`.
+This is the shortest honest path from nothing to a game with a win and a lose in
+it. Everything below has been built and measured; the timings are real, and so
+are the traps.
+**You cannot see this game.** No browser, no GPU, no screenshot. That sounds like
+the hard part and it is not — the engine ships the instruments, and §5 is how you
+use them. What actually costs first-time authors an hour is §4, so read it even
+if you skim.
+---
+## 1. Three minutes to a running game
+```bash
+bunx incanto@latest new --list                    # what the starters are
+bunx incanto@latest new my-game --template tps-3d # or platformer-2d, star-survivor, …
+cd my-game && bun install
+bun run check && bun run typecheck && bun run verify
+```
+`@latest` matters: `bunx` caches the CLI, and a cached one scaffolds a project
+pinned to ITS version, so you can quietly get an engine a release behind the
+docs you are reading. Check with `grep incanto package.json` if anything below
+does not match what you see.
+The starter is a **complete game**, green on arrival, and it is meant to be
+reshaped rather than read. Four agents building four different games all started
+here; the two who hand-authored a scene from scratch still scaffolded first, for
+the vite config and the verify harness.
+Pick by shape, not by subject: `tps-3d` (third-person combat), `platformer-2d`,
+`star-survivor` (top-down survivor), `village-quest-3d` (quest/NPC),
+`beacon-isle-3d` (open world).
+---
+## 2. What you edit
+```
+src/game.scene.json   ← the game. Nodes, props, connections. This is most of it.
+src/behaviors.ts      ← the parts JSON cannot express. Usually very little.
+src/main.ts           ← boot. You rarely touch it.
+verify.ts             ← the harness that proves it works. You WILL touch it.
+```
+The claim that "all structure is JSON" is not marketing: one of the four builds
+shipped a whole 3D world with **zero** gameplay TypeScript, and another needed
+90 lines for one melee swing. Reach for a built-in behavior before you write a
+class — `incanto-gameplay-behaviors.md` is the list, and it is long.
+Read `incanto-scene-json-authoring.md` before you write JSON. It is the format,
+the node paths, and the connection grammar, and everything else assumes it.
+---
+## 3. The spine: a game that can be WON and LOST
+This is the part worth copying verbatim. It is four nodes and four connections,
+and it is entirely JSON.
+```jsonc
+{ "name": "Score", "type": "Node3D",
+  "script": { "name": "ScoreKeeper", "props": { "scoreToWin": 10, "lives": 3 } } },
+{ "name": "Flow", "type": "Node3D", "script": { "name": "GameFlow" } },
+{ "name": "HUD", "type": "HudLayer", "children": [
+  { "name": "Banner", "type": "UiBanner" },
+  { "name": "Hp", "type": "UiBar", "props": { "anchor": "topLeft", "label": "HP" } }
+] }
+```
+```jsonc
+"connections": [
+  { "signal": "died",  "from": "Player",  "to": "Score", "handler": "loseLife" },
+  { "signal": "won",   "from": "Score",   "to": "Flow",  "handler": "win" },
+  { "signal": "lost",  "from": "Score",   "to": "Flow",  "handler": "gameOver" }
+]
+```
+`GameFlow` freezes `engine.timeScale`, shows a sticky banner, and waits for the
+`restart` action. **Give the Flow its own node** — a node holds one behavior and
+your root probably already has the game's director script.
+A pause menu is the same trick and also zero TypeScript: declare a `pause`
+action, add a `UiPanel` named `PauseMenu` under the HUD, and Escape opens it.
+### The trap that eats an hour here
+`died` carries **no arguments**. `ScoreKeeper.addScore(n)` needs one. So the
+obvious way to score a kill —
+```jsonc
+// WRONG — this is the mistake, not the fix
+{ "signal": "died", "from": "Enemy", "to": "Score", "handler": "addScore" }
+```
+— sets the score to `NaN` on the first kill, and the win condition is
+unreachable forever. The engine reports this the moment the wire fires; do not
+ignore that line. Wire `dealtDamage` from the KILLER instead (it carries the
+amount and the target), which is also clone-safe — a connection on a spawned
+enemy never clones.
+`won → GameFlow.win` is fine, by contrast, because `win(text = 'YOU WIN')`
+defaults what it is not given. That is the difference, and it is the only one.
+---
+## 4. Making things hurt (read this one)
+An enemy that touches you should drain you. Two props decide whether it does,
+and both defaults are the harmless answer.
+**Contact fires on ENTRY and EXIT, never per frame.** So `oncePerTarget: false`
+means "hurt again on RE-entry" — an enemy that closes and stops deals one hit and
+then nothing at all. `repeatEvery` is the knob that makes a resting overlap keep
+hurting. Six seconds of unbroken contact at `amount: 10`:
+```
+oncePerTarget=false  repeatEvery=0     → hp 90   ← one hit, then nothing
+oncePerTarget=false  repeatEvery=0.5   → hp 0
+```
+```jsonc
+{ "name": "Hit", "type": "Area3D",
+  "props": { "collider": { "shape": "sphere", "radius": 1.5 } },
+  "script": { "name": "DamageOnContact",
+    "props": { "amount": 12, "targetGroup": "player",
+               "oncePerTarget": false, "repeatEvery": 0.5 } } }
+```
+Pair it with `Health.invulnerableFor` (the real per-frame guard) and keep
+`repeatEvery` at or above it — under 0.6 s it just lands on i-frames.
+**And they have to be able to REACH you.** A `CharacterBody3D` walks; a chaser
+walks a straight line and cannot go around. `stepHeight` (default 0.35 m) is how
+high a ledge it climbs — raise it for a world with stairs. You will not notice
+this on the player, because `CharacterController3D` rides a hover spring and
+floats over small ledges already.
+The tell for both is one line of `incanto-playtest` output:
+```
+danger: the player took damage 0 times in 4 runs — nothing here can hurt you
+```
+Read it. It is the truth.
+---
+## 5. Handing it back
+Never hand a game back on reasoning. Run the ladder:
+```bash
+bunx incanto verify          # loads · plays · feels · agrees · draws · says
+```
+- **`loads`** — the scene is legal and its assets resolve. Warnings print under
+  it with `!`; a scene that "renders black" says so here.
+- **`plays`** — 8 seeded runs. `error`, `fell` and `stuck` are DEFECTS and fail
+  the rung; `won`, `lost` and `unfinished` are gameplay. A random bot cannot
+  finish a quest, and that is reported as unmeasured, not failed.
+- **`feels`** — the sounds and effects the scene declares, against what actually
+  fired. A game whose feedback is wired and never triggered plays perfectly and
+  feels dead.
+- **`draws` / `says`** — need a dev server with the page open. Unmeasured is not
+  failed.
+Then the two that answer questions the ladder cannot:
+```bash
+bunx incanto-playtest src/game.scene.json --behaviors src/behaviors.ts
+bunx incanto-feel     src/game.scene.json --behaviors src/behaviors.ts
+```
+`playtest` gives you a difficulty read (`won 4/20, lost 9/20, 9.7 hits per run`)
+that no amount of staring at JSON will. `feel` measures your controls by probing
+them — and prints the **held** jump apex next to the tapped one, because with
+`jumpCutMultiplier` those differ by 4× and the held number is the one your level
+geometry has to match.
+Full detail: `incanto-verifying-your-game.md`, `incanto-playtesting.md`,
+`incanto-game-feel.md`.
+### Write the harness, not just the checks
+`verify.ts` in the starter drives the game with `runScript` and asserts what
+happened. Extend it as you build; it is the only thing that will catch a
+regression you cannot see.
+**Assert the game's own physics, not your test's.** A harness that emits
+`triggerEnter` by hand proves the handler answers an event and nothing about
+whether the game produces one — that exact mistake hid a starter whose enemies
+could not reach the player. Let the AI chase, and read the health.
+---
+## 6. The sticky note
+Things that cost real time, in the order you will meet them.
+| when | the trap |
+| --- | --- |
+| wiring a score | `died` carries nothing; `addScore(n)` wants one → `NaN`. Wire `dealtDamage` from the killer. |
+| enemies feel harmless | `repeatEvery` on the contact hitbox, or one hit is all you get. |
+| enemies never arrive | a chaser cannot climb — `stepHeight`, and it loses to a large downward velocity you apply yourself. |
+| sizing a level | use the **held** jump apex, not the tapped one. |
+| a melee weapon | a body with `Health` on the root and a `Hit` child presents TWO colliders; one swing can deal damage twice. Give the weapon a `targetGroup`. |
+| a HUD you cannot see | `UiText.setText()` fills a slot; the `text` prop keeps the authored line. Use `describeCapture` to read what a widget PAINTS. |
+| framing a scene | `describeFraming(scene)` returns the report object; `framingText(report)` renders it. |
+| spawned enemies | connections on a template do NOT clone. Put the wire on something that is not cloned, or emit from a behavior. |
+| a scene that swaps scenes | `incanto-playtest` drives one scene; a mid-run swap is out of its reach. Script it in `verify.ts` instead. |
+---
+## 7. Where to go next
+| you want | read |
+| --- | --- |
+| the JSON format itself | `incanto-scene-json-authoring.md` |
+| nodes, props, defaults | `incanto-node-reference.md` (generated — always current) |
+| ready-made game logic | `incanto-gameplay-behaviors.md` |
+| 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` |
+| HUD, menus, inventory | `incanto-hud.md` |
+| proving it works | `incanto-verifying-your-game.md` |
+And when a game "works" but feels wrong, the answer is almost always in
+`incanto-feel` output you have not run yet.

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

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

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

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

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

package/templates-app/star-survivor/src/game.scene.json CHANGED Viewed

@@ -220,7 +220,8 @@
                   "props": {
                     "amount": 8,
                     "targetGroup": "player",
-                    "oncePerTarget": false
+                    "oncePerTarget": false,
+                    "repeatEvery": 0.5
                   }
                 }
               },
@@ -332,7 +333,8 @@
                   "props": {
                     "amount": 12,
                     "targetGroup": "player",
-                    "oncePerTarget": false
+                    "oncePerTarget": false,
+                    "repeatEvery": 0.5
                   }
                 }
               },

package/templates-app/tps-3d/PROJECT/Requirements.md CHANGED Viewed

@@ -31,7 +31,9 @@
   strafe-aim rig (always face the camera) would be a custom controller tweak.
 - Mouse look needs POINTER LOCK (click the canvas). A free cursor never spins the
   camera (deltas only accumulate while locked or a button is held).
-- HUD is DOM, not nodes: 3D scenes have no 2D `UILayer`/`Label`. The crosshair,
+- HUD is DOM here by CHOICE, not by necessity: `HudLayer` + `UiText`/`UiBar`
+  work in 3D too and are the ones a headless check can read (incanto-hud.md),
+  and this scene keeps a `HudLayer` for its banner. The crosshair,
   HUD and banner live in `index.html`; `HudUpdater` fills them (guarded for
   headless). The crosshair marks the camera aim point, not the gun barrel.
 - Zero-asset: arena, soldier and enemies are primitives; SFX are procedural

package/templates-app/tps-3d/index.html CHANGED Viewed

@@ -110,7 +110,9 @@
         width: 56px;
         height: 56px;
       }
-      /* HUD overlay (3D scenes have no 2D UI nodes — the HUD is plain DOM) */
+      /* This game's HUD is plain DOM. `HudLayer` + `UiText`/`UiBar` work in 3D
+         too (see incanto-hud.md) and are readable headlessly — the scene has one
+         for the banner. Either is fine; DOM here is a choice, not a limit. */
       #hud {
         position: fixed;
         top: 14px;

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

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

@@ -11,7 +11,7 @@
  *   snaps the visible character to FACE the aim on each shot so the soldier turns
  *   to shoot where you're looking.
  * - `HudUpdater` — pure presentation glue. The gameplay library owns the numbers,
- *   not how they're drawn, and 3D scenes have no 2D UI nodes, so this reads
+ *   not how they're drawn, and this game draws its HUD in plain DOM, so it reads
  *   ScoreKeeper.score / Health.current / the wave index / the ammo count each
  *   frame into the HTML HUD overlay (index.html) and flips the win/lose banner.
  */
@@ -315,7 +315,9 @@ export class Shoot extends Behavior {
 // ---------------------------------------------------------------------------
 // HudUpdater — writes the live numbers into the HTML HUD overlay (index.html).
-// 3D scenes have no 2D UILayer/Label nodes, so the HUD is plain DOM. All DOM
+// This HUD is plain DOM by choice. `HudLayer` + `UiText`/`UiBar` also work in
+// 3D and are the readable-headlessly option (incanto-hud.md); the scene keeps a
+// HudLayer for its banner. All DOM
 // access is guarded: headless runs (verify, runScript) have no `document`, so
 // every write is a no-op and the gameplay logic is unaffected.
 // ---------------------------------------------------------------------------

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

@@ -629,7 +629,8 @@
                   "props": {
                     "amount": 12,
                     "targetGroup": "player",
-                    "oncePerTarget": false
+                    "oncePerTarget": false,
+                    "repeatEvery": 0.5
                   }
                 }
               },
@@ -698,7 +699,7 @@
                 "name": "ResumeHint",
                 "type": "UiText",
                 "props": {
-                  "text": "Esc to resume · R to restart",
+                  "text": "Esc to resume \u00b7 R to restart",
                   "size": 13,
                   "color": "#c9d2dd"
                 }