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

incanto 0.65.0 → 0.67.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 (88) hide show

package/bin/_behaviors-loader.mjs +87 -0
package/bin/incanto-editor.mjs +39 -2
package/bin/incanto-feel.mjs +4 -1
package/bin/incanto-frame.mjs +52 -3
package/bin/incanto-logs.mjs +33 -3
package/bin/incanto-multiplay.mjs +50 -1
package/bin/incanto-play.mjs +3 -1
package/bin/incanto-playtest.mjs +3 -25
package/bin/incanto-verify.mjs +15 -2
package/dist/2d.d.ts +76 -4
package/dist/2d.js +3 -3
package/dist/3d.d.ts +213 -14
package/dist/3d.js +6 -6
package/dist/{audio-player-BrEHwbK1.d.ts → audio-player-BNUHo0JF.d.ts} +1 -1
package/dist/{behavior-CmMuQ6CL.d.ts → behavior-ZnfzKDo3.d.ts} +58 -1
package/dist/{create-game-DIyh5Zy9.js → create-game-DMetd3vR.js} +14 -8
package/dist/{create-game-W2xzTJhs.js → create-game-FAXdHta3.js} +138 -11
package/dist/debug.d.ts +1 -1
package/dist/debug.js +3 -2
package/dist/{duplicate-CqSAtdrh.js → duplicate-B8QnX2-r.js} +1 -1
package/dist/editor.js +7 -2
package/dist/{environment-presets-BvHs6HEk.js → environment-presets-C-5g2pMh.js} +113 -9
package/dist/{gameplay-D-H986A4.js → gameplay-CGSv-9XR.js} +295 -12
package/dist/gameplay.d.ts +102 -6
package/dist/gameplay.js +2 -2
package/dist/index.d.ts +50 -6
package/dist/index.js +7 -6
package/dist/{loader-CTB441z4.d.ts → loader-DyT30ArB.d.ts} +1 -1
package/dist/{loader-lQDCwNag.js → loader-KZESOZmE.js} +148 -1
package/dist/net.d.ts +2 -2
package/dist/net.js +1 -1
package/dist/{physics-2d-CmnunaR2.js → physics-2d-_B6zj3zU.js} +57 -4
package/dist/{physics-3d-DULB1lD1.js → physics-3d-i1IeAY0F.js} +74 -5
package/dist/{quiet-rapier-BAJ4K94N.js → quiet-rapier-C6fW4zcW.js} +14 -1
package/dist/react.d.ts +1 -1
package/dist/react.js +1 -1
package/dist/{register-CgeR4ckF.js → register-Cs53CY7s.js} +110 -16
package/dist/{register-DO5_Qp0Q.js → register-vIxU3Xbv.js} +38 -4
package/dist/rendering-options-ByAdi8PF.js +184 -0
package/dist/{replay-CEw2xAhG.js → replay-BkpDV51O.js} +4 -3
package/dist/{replay-CThvwkcQ.d.ts → replay-D0GcEHYU.d.ts} +1 -1
package/dist/{split-screen-DxZzC1nm.d.ts → split-screen-DD5eYIgW.d.ts} +2 -2
package/dist/{split-screen-gb0c3xdb.js → split-screen-DS8RaUV_.js} +2 -2
package/dist/{src-DYffzHbd.js → src-BLlsGJW9.js} +1 -1
package/dist/{teardown-BordHL9o.js → teardown-LB9cTnXJ.js} +2 -2
package/dist/{test-CXZuXs8k.js → test-81uZ967a.js} +127 -24
package/dist/test.d.ts +7 -5
package/dist/test.js +2 -2
package/dist/{touch-DESwnpOc.js → touch-DEAmqGdf.js} +30 -186
package/dist/vite.d.ts +0 -7
package/dist/vite.js +13 -3
package/editor/assets/{agent8-DO5qzIOD.js → agent8-C2jtNKbx.js} +1 -1
package/editor/assets/debug-DoU3KeqS.js +3 -0
package/editor/assets/{index-CqEUVaPN.js → index-CNqHojcC.js} +92 -92
package/editor/index.html +1 -1
package/package.json +1 -1
package/schemas/scene.schema.json +20 -1
package/skills/incanto-building-3d-games.md +19 -0
package/skills/incanto-editor.md +5 -1
package/skills/incanto-environment.md +2 -2
package/skills/incanto-gameplay-behaviors.md +86 -7
package/skills/incanto-hud.md +14 -1
package/skills/incanto-multiplayer.md +14 -0
package/skills/incanto-node-reference.md +60 -2
package/skills/incanto-performance.md +35 -0
package/skills/incanto-physics-and-input.md +69 -0
package/skills/incanto-playtesting.md +15 -1
package/skills/incanto-save-slots.md +21 -1
package/skills/incanto-verifying-your-game.md +19 -0
package/skills/incanto-web-integration.md +24 -3
package/skills/incanto-your-first-game.md +4 -4
package/templates-app/beacon-isle-3d/package.json +1 -1
package/templates-app/beacon-isle-3d/src/game.scene.json +38 -19
package/templates-app/platformer-2d/package.json +1 -1
package/templates-app/platformer-2d/src/game.scene.json +99 -53
package/templates-app/star-survivor/package.json +1 -1
package/templates-app/star-survivor/src/game.scene.json +31 -17
package/templates-app/tps-3d/package.json +1 -1
package/templates-app/tps-3d/src/game.scene.json +14 -8
package/templates-app/village-quest-3d/package.json +1 -1
package/templates-app/village-quest-3d/src/grove.scene.json +20 -11
package/templates-app/village-quest-3d/src/village.scene.json +10 -7
package/editor/assets/debug-DntG9CVD.js +0 -3
package/templates-app/beacon-isle-3d/coverage.json +0 -9
package/templates-app/platformer-2d/coverage.json +0 -5
package/templates-app/star-survivor/coverage.json +0 -5
package/templates-app/tps-3d/coverage.json +0 -5
package/templates-app/village-quest-3d/coverage.json +0 -9

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-CqEUVaPN.js"></script>
+    <script type="module" crossorigin src="./assets/index-CNqHojcC.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.65.0",
+  "version": "0.67.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

@@ -2350,6 +2350,10 @@
               "type": "number",
               "default": 0.01
             },
+            "stepHeight": {
+              "type": "number",
+              "default": 0.35
+            },
             "mouseLook": {
               "type": "boolean",
               "default": true
@@ -3423,6 +3427,9 @@
             "damping": {
               "type": "number",
               "default": 5
+            },
+            "collide": {
+              "default": null
             }
           },
           "additionalProperties": false
@@ -3577,6 +3584,9 @@
             "damping": {
               "type": "number",
               "default": 5
+            },
+            "collide": {
+              "default": null
             }
           },
           "additionalProperties": false
@@ -5670,6 +5680,15 @@
               "minItems": 3,
               "maxItems": 3,
               "default": [0, 0, 0]
+            },
+            "angularVelocity": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 3,
+              "maxItems": 3,
+              "default": [0, 0, 0]
             }
           },
           "additionalProperties": false
@@ -7661,7 +7680,7 @@
             },
             "focusable": {
               "type": "boolean",
-              "default": false
+              "default": true
             },
             "draggable": {
               "type": "boolean",

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

@@ -41,8 +41,14 @@ const game = await createGame3D({
   scene: sceneJson,          // cloned internally — no cast, no structuredClone
   pointer: true,             // pointer-look + lock-on-click (FPS pattern); default off
   // behaviors: { ... },     // registered for you (hot-replace tolerant)
+  // settings: { namespace: 'my-game' },  // ← if anything else Incanto is
+  //   served from this domain. Volume, language and the quality tier persist
+  //   under `incanto:<namespace>:`, and the default is shared by everyone: a
+  //   neighbouring game's player can boot yours at quarter resolution, muted.
 });
 // game.engine / game.scene / game.renderer / game.physics
+// `game.scene` is the LIVE scene, not the one you booted with — it follows every
+// swap, including `flow.restart()`. `game.sourceJson` is the authored JSON.
 // game.dispose() — ONE call tears everything down (SPA unmount)
 ```
@@ -629,3 +635,16 @@ or empty, and nothing throws.
 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`.
+### `findFloatingProps` throws rather than reporting a clean scene it never read
+It answers "which props hover above the terrain", and it needs the scene to LOAD
+and a `Terrain3D` to measure against. It used to return `[]` for both failures —
+so a scene that would not load, a scene with no terrain and a genuinely clean
+scene all printed the same green.
+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.

package/skills/incanto-editor.md CHANGED Viewed

@@ -44,7 +44,11 @@ The `scenes` button opens the project as a tree, not a list of paths:
   panel — so `⏎` loads something without arrowing first.
 - Each row carries **when it was last written and how big it is**, which is usually
   how you recognise the file you were just in.
-- **create** makes a new scene at the path in the box — left empty it uses the
+- **create** makes a new scene at the path in the box — **matching the project**:
+a 3D game gets `dimension: "3d"` with a `Node3D` root, a 2D game gets 2D, read
+from the scenes already on disk. It used to hardcode 2D for everyone, and node
+types are immutable by design, so a 3D author's new scene could only be deleted
+and re-made by hand — left empty it uses the
   placeholder, which tracks the folder you are standing in, so a scene lands beside
   its siblings rather than at the project root. Parent dirs are created.
 - Loading another scene while you have unsaved EDITS asks first, and the answer

package/skills/incanto-environment.md CHANGED Viewed

@@ -799,7 +799,7 @@ hue reads grey.
 | `sunDirection` | `[0.5, 0.8, 0.3]` | TOWARD the sun, for the specular glint — match the scene's key light (non-zero, load-time check) |
 | `sunColor` | `"#fff5d6"` | glint/sheen tint |
 | `sunIntensity` | `1` | glint/sheen strength (≥ 0; 0 = off) |
-| `detailStrength` | `0.3` | animated detail-normal strength (≥ 0; 0 = vertex normals only) |
+| `detailStrength` | `0.26` | animated detail-normal strength (≥ 0; 0 = vertex normals only) |
 | `absorption` | `0.15` | Beer's-law constant per meter of water depth (≥ 0; lower = clearer/wider turquoise band; red absorbs ~3× faster than blue under the hood) |
 | `refraction` | `true` | screen-space refraction of the submerged scene |
 | `preset` | `"custom"` | **THE one-choice water type** (0.16.0): `ocean` \| `pool` \| `lake` \| `pond` bundles every wave/color/clarity/caustics knob into a hand-tuned sea state. A preset value applies ONLY where a prop still sits at its schema default — pick the type, then override any detail prop and your value wins. ocean = traveling swell + whitecaps + wide turquoise→deep absorption · pool = near-flat crystal water + strong above-water caustics · lake = calm high-reflectivity mirror, green-teal murk · pond = still, mossy, opaque quickly. `custom` (default) changes nothing |
@@ -1074,7 +1074,7 @@ underneath decides everything else.
 | `opacity` | `0.85` | upper bound on the body's opacity |
 | `foam` | `1` | whitewater dial — 0 = a glassy canal, 2 = raging |
 | `ripples` | `1` | surface-detail dial (ripple relief + glitter) |
-| `terrain` | `''` | drape target path; empty = auto-find the first Terrain3D (a wrong path fails at load) |
+| `terrain` | `""` | drape target path; empty = auto-find the first Terrain3D (a wrong path fails at load) |
 | `carve` | `true` | cut the bed. The river trenches its own channel into the terrain it drapes on — see below |
 | `flowForce` | `1` | how hard the current sweeps bodies downstream (0 = visual only) |
 | `spray` | `1` | mist at the foot of every drop the course turns out to contain — the node finds them and hangs a Particles3D plume on each (0 = off) |

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

@@ -111,7 +111,7 @@ what breaks one that forgets the other half:
 ```json
 { "signal": "died",     "from": "Player", "to": "Score",  "handler": "loseLife" },
-{ "signal": "lifeLost", "from": "Score",  "to": "Player", "handler": "revive" }
+{ "signal": "lifeLost", "from": "Score",  "to": "Player", "handler": "reviveFull" }
 ```
 Without the second wire the player is a walking corpse after the first death —
@@ -516,6 +516,59 @@ is a far worse failure than one running when it was meant to sleep.
 From TypeScript it is the same switch: `this.getNode('../Hunt').behavior.enable()`.
+## FaceTarget
+Turn toward the nearest thing in a group and say when you are pointed at it —
+turrets, sentry guns, security cameras, an NPC that watches you walk past.
+`Chase` finds the nearest target and turns toward it, and then MOVES, which is
+the one thing a turret must not do; `Patrol`/`Chase`'s `facePath` only turns as
+a side effect of locomotion, so a stationary node could not use it. A tower
+defense built before this hand-wrote acquisition and the aim gate.
+| Prop | Default | Meaning |
+|---|---|---|
+| `targetGroup` | `""` | group to acquire from — nearest live member wins (required) |
+| `range` | `0` | only acquire within this distance (0 = anywhere) |
+| `facePath` | `""` | node to TURN (usually a skin); empty turns its own node |
+| `turnSpeed` | `6` | turn rate rad/s; 100 is an instant snap |
+| `aimTolerance` | `6` | degrees of slop that still counts as pointed at it |
+Signals: `acquired(node)` · `lostTarget` · **`aimed`** · `lostAim`
+```jsonc
+{ "name": "Turret", "type": "Node3D",
+  "script": { "name": "FaceTarget",
+    "props": { "targetGroup": "enemy", "range": 12, "facePath": "../Barrel" } } }
+```
+**`aimed` is the useful one.** "Only fire while actually pointed at it" becomes a
+wire instead of an angle comparison every caller repeats and one caller forgets.
+`onTarget` and `target` are readable from TypeScript for the rest.
+## Currency
+Money you can spend. `ScoreKeeper` is a SCORE — it counts up, it has no spend,
+no affordability question, and its counter already drives the win condition, so
+every shop, build mode, upgrade tree and economy game wrote its own wallet.
+| Prop | Default | Meaning |
+|---|---|---|
+| `amount` | `0` | what you start with |
+| `max` | `0` | ceiling (0 = none) |
+Signals: `changed(amount)` · `earned(gain)` · `spent(cost)` · **`refused(cost)`**
+Methods: `spend(cost) -> boolean` · `earn(gain)` · `canAfford(cost)` · `setAmount(n)`
+```ts
+if (!wallet.spend(TOWER_COST)) return;   // `refused` already fired for the HUD
+placeTower(pad);
+```
+`spend` returns whether it went through and emits `refused` when it did not, so
+"you cannot afford that" is one wire to a banner. It saves through `serialize()`
+like `Health` and `ScoreKeeper`.
 ## Wander
 Seeded random roaming inside a circle around the spawn point — idle critters,
@@ -768,8 +821,35 @@ Signals: `waveStarted(index)` · `waveCleared(index)` · `allCleared`
 ## Projectile
 Straight-line, constant-velocity motion — bullets, arrows, thrown rocks. Pure
-MOVEMENT by design: **compose** it with `DamageOnContact` (deal damage), `Lifetime`
-(auto-despawn) and an Area collider on the SAME node — don't conflate them.
+MOVEMENT by design: **compose** it with `DamageOnContact` (deal damage) and
+`Lifetime` (auto-despawn) — don't conflate them. A node carries ONE script, so
+those go on CHILD nodes and each one sets **`freeParent: true`** so it frees the
+BULLET rather than itself. Copy this:
+```jsonc
+{ "name": "Bullet", "type": "Node3D",
+  "script": { "name": "Projectile", "props": { "speed": 30 } },
+  "children": [
+    { "name": "Hit", "type": "Area3D",
+      "props": { "collider": { "shape": "sphere", "radius": 0.2 } },
+      "script": { "name": "DamageOnContact",
+        "props": { "amount": 10, "targetGroup": "enemy",
+                   "destroySelf": true, "freeParent": true } } },
+    { "name": "Life", "type": "Node3D",
+      "script": { "name": "Lifetime", "props": { "seconds": 2, "freeParent": true } } }
+] }
+```
+**Without `freeParent` the bullet never dies.** Both behaviors used to free only
+their own node, so the hitbox and the timer removed THEMSELVES and the bullet
+flew on forever — one leaked node per shot, damaging exactly once, with no error.
+Measured on a tower defense built from the published package:
+```
+t=0.58 bullet z=2.92  | Dmg child: alive | Life child: gone  | foe hp: 100
+t=1.18 bullet z=5.92  | Dmg child: gone  | Life child: gone  | foe hp: 90
+t=2.88 bullet z=14.42 | (both gone)      | foe hp: 90   <- still flying
+```
 `direction` is a vector OR `'forward'` (from the node `rotation`); it's a
 union-typed prop so its default is `null` (= `'forward'`).
@@ -792,10 +872,9 @@ as a gun that simply never hits anything.) In 2D `rotation` is a scalar and
 { "name": "Bullet", "type": "Area2D", "props": { "rotation": 0 },
   "script": { "name": "Projectile", "props": { "speed": 600, "direction": "forward" } } }
 ```
-> Compose: add `DamageOnContact` and `Lifetime` to make it actually hurt and
-> despawn. One node carries one script, so attach `Projectile` here and wire the
-> others onto sibling/child Area nodes (or use a Spawner that clones a fully-built
-> bullet template).
+> Compose: add `DamageOnContact` and `Lifetime` on CHILD nodes, both with
+> `freeParent: true`, as shown above — or use a Spawner that clones a
+> fully-built bullet template.
 ---

package/skills/incanto-hud.md CHANGED Viewed

@@ -183,7 +183,20 @@ support" was not something a JSON scene could express at all.
 ```
 Arrow keys / d-pad move the focus between the **focusable** widgets under that
-layer, `Enter` / `A` activates, and the focused one wears a ring.
+layer — and only the ones the player can actually SEE: a hidden widget hides
+everything under it, and a hidden layer has no ring at all. (Until 0.67 the walk
+recursed into closed panels, so Enter on a title screen could press a button in
+the shop and spend the gold.) `hud.focusables()` returns the ring, so a game can
+ask what it is stuck with.
+A **`UiDialogue` takes focus while it is up**: Enter/A picks the highlighted
+choice, left/right move between them, and a line with no choices advances. Its
+choices are DOM buttons inside the widget rather than nodes, so this is the
+widget's own key handling — before 0.67 a choice could only be answered with a
+mouse, and `charsPerSecond: 0` rendered no buttons at all, which was an
+unanswerable soft-lock.
+ `Enter` / `A` activates, and the focused one wears a ring.
 `UiButton`/`UiSlider`/`UiToggle`/`UiSelect` are focusable by default;
 `UiText`/`UiBar`/`UiImage`/`UiPanel` are not, so arrowing never lands on a label.

package/skills/incanto-multiplayer.md CHANGED Viewed

@@ -378,3 +378,17 @@ Kernel constraints (agent8 platform facts — don't fight them):
   client transport swap (for a normal single-client game, just omit `{transport}`;
   a split-screen demo like arena-preview also drops its local-only scaffolding) PLUS
   deploying `server/` (the "Going live on agent8" section above) — not literally one line.
+## The `agrees` rung runs YOUR server
+`incanto-multiplay` loads `server/src/server.ts` (or `--server FILE`) and runs
+the match against it. It did not until 0.67: every match ran on a bare loopback
+kernel with no remote functions, so `roomState` came back `{}` instead of
+`{"matchMs": 5983.3}`, a `manager.call('claimRelic')` threw
+`Loopback kernel has no remote function 'claimRelic'`, and the report still said
+`ok=true errors=0 problems=[]`. Moving `server/src/server.ts` out of the tree
+changed nothing — a ✓ that could not have been a ✗.
+If your server cannot be loaded the run REFUSES rather than quietly measuring a
+game without its own rules.

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

@@ -290,6 +290,7 @@ Signals: `movementStateChanged(state)`
 | `airControl` | `0.2` | number |
 | `fallGravity` | `2.5` | number |
 | `floatHeight` | `0.01` | number |
+| `stepHeight` | `0.35` | number |
 | `mouseLook` | `true` | boolean |
 | `zoomMin` | `0` | number |
 | `zoomMax` | `0` | number |
@@ -446,6 +447,7 @@ Signals: `movementStateChanged(state)`
 | `length` | `0` | number |
 | `stiffness` | `50` | number |
 | `damping` | `5` | number |
+| `collide` | `null` | null |
 ## `Joint3D` — `incanto/3d`
@@ -466,6 +468,7 @@ Signals: `movementStateChanged(state)`
 | `length` | `0` | number |
 | `stiffness` | `50` | number |
 | `damping` | `5` | number |
+| `collide` | `null` | null |
 ## `Label` — `incanto/2d`
@@ -760,6 +763,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `friction` | `0.5` | number |
 | `restitution` | `0` | number |
 | `linearVelocity` | `[0,0,0]` | array |
+| `angularVelocity` | `[0,0,0]` | array |
 Signals: `triggerEnter(other)` · `triggerExit(other)`
@@ -1035,7 +1039,7 @@ Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `presse
 |---|---|---|
 | `anchor` | `"bottom"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
 | `visible` | `true` | boolean |
-| `focusable` | `false` | boolean |
+| `focusable` | `true` | boolean |
 | `draggable` | `false` | boolean |
 | `dropTarget` | `false` | boolean |
 | `charsPerSecond` | `40` | number |
@@ -1327,6 +1331,7 @@ wire their signals through scene `connections`. Full guide: `incanto-gameplay-be
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `water` | `""` | node path |
 | `draft` | `0.35` | number |
 | `stiffness` | `3` | number |
@@ -1342,17 +1347,21 @@ Signals: `submerged` · `surfaced`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `falloff` | `0.28` | number |
 ### `Chase`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `target` | `""` | node path |
 | `speed` | `60` | number |
 | `stopRange` | `0` | number |
 | `loseRange` | `0` | number |
 | `moveParent` | `false` | boolean |
+| `facePath` | `""` | node path |
+| `turnSpeed` | `100` | number |
 Signals: `reachedTarget` · `lostTarget`
@@ -1360,9 +1369,9 @@ Signals: `reachedTarget` · `lostTarget`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `button` | `0` | number |
 | `maxDistance` | `0` | number |
-| `enabled` | `true` | boolean |
 Signals: `clicked` · `hovered` · `unhovered`
@@ -1370,19 +1379,32 @@ Signals: `clicked` · `hovered` · `unhovered`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `group` | `"player"` | string |
 Signals: `totalChanged(total)`
+### `Currency`
+| Prop | Default | Kind |
+|---|---|---|
+| `enabled` | `true` | boolean |
+| `amount` | `0` | number |
+| `max` | `0` | number |
+Signals: `changed` · `earned` · `spent` · `refused`
 ### `DamageOnContact`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `amount` | `10` | number |
 | `targetGroup` | `""` | string |
 | `oncePerTarget` | `true` | boolean |
 | `repeatEvery` | `0` | number |
 | `destroySelf` | `false` | boolean |
+| `freeParent` | `false` | boolean |
 Signals: `dealtDamage(amount, target)`
@@ -1390,6 +1412,7 @@ Signals: `dealtDamage(amount, target)`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `daySeconds` | `240` | number |
 | `startHour` | `10` | number |
 | `maxSunElevationDeg` | `55` | number |
@@ -1398,10 +1421,24 @@ Signals: `dealtDamage(amount, target)`
 Signals: `dayPhaseChanged`
+### `FaceTarget`
+| Prop | Default | Kind |
+|---|---|---|
+| `enabled` | `true` | boolean |
+| `targetGroup` | `""` | string |
+| `range` | `0` | number |
+| `facePath` | `""` | node path |
+| `turnSpeed` | `6` | number |
+| `aimTolerance` | `6` | number |
+Signals: `acquired` · `lostTarget` · `aimed` · `lostAim`
 ### `FloatAway`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `rise` | `1` | number |
 | `seconds` | `0.7` | number |
 | `hold` | `0.3` | number |
@@ -1412,6 +1449,7 @@ Signals: `dayPhaseChanged`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `target` | `""` | node path |
 | `offset` | `[]` | array |
 | `smoothing` | `0` | number |
@@ -1421,6 +1459,7 @@ Signals: `dayPhaseChanged`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `restartAction` | `"restart"` | string |
 | `pauseAction` | `"pause"` | string |
 | `freezeOnEnd` | `true` | boolean |
@@ -1433,6 +1472,7 @@ Signals: `flowChanged`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `max` | `100` | number |
 | `regenPerSec` | `0` | number |
 | `invulnerableFor` | `0` | number |
@@ -1444,6 +1484,7 @@ Signals: `damaged(amount, current)` · `healed(amount, current)` · `died` · `r
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `action` | `"interact"` | string |
 | `range` | `2` | number |
 | `actorGroup` | `"player"` | string |
@@ -1454,8 +1495,10 @@ Signals: `interacted(actor)`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `seconds` | `1` | number |
 | `startOnSignal` | `false` | boolean |
+| `freeParent` | `false` | boolean |
 Signals: `expired`
@@ -1463,6 +1506,7 @@ Signals: `expired`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `to` | `[]` | array |
 | `duration` | `1` | number |
 | `ease` | `"easeInOut"` | one of: `linear` `easeIn` `easeOut` `easeInOut` |
@@ -1474,6 +1518,7 @@ Signals: `arrived`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `axis` | `"y"` | one of: `x` `y` `z` |
 | `amplitude` | `1` | number |
 | `frequency` | `1` | number |
@@ -1483,6 +1528,7 @@ Signals: `arrived`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `speed` | `120` | number |
 | `loop` | `false` | boolean |
@@ -1492,11 +1538,15 @@ Signals: `waypointReached` · `arrived`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `points` | `[]` | array |
 | `speed` | `60` | number |
 | `loop` | `true` | boolean |
 | `mode` | `"loop"` | one of: `loop` `pingpong` |
 | `pauseAt` | `0` | number |
+| `moveParent` | `false` | boolean |
+| `facePath` | `""` | node path |
+| `turnSpeed` | `100` | number |
 Signals: `reachedPoint(index)`
@@ -1504,6 +1554,7 @@ Signals: `reachedPoint(index)`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `value` | `1` | number |
 | `kind` | `"coin"` | string |
 | `collectorGroup` | `"player"` | string |
@@ -1514,6 +1565,7 @@ Signals: `collected(value, other)`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `speed` | `300` | number |
 | `direction` | `null` | null |
 | `gravity` | `0` | number |
@@ -1522,6 +1574,7 @@ Signals: `collected(value, other)`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `game` | `"game"` | string |
 | `slot` | `"1"` | string |
 | `label` | `""` | string |
@@ -1535,6 +1588,7 @@ Signals: `saved` · `restored` · `noSave` · `hasSave`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `score` | `0` | number |
 | `lives` | `0` | number |
 | `scoreToWin` | `0` | number |
@@ -1545,6 +1599,7 @@ Signals: `scoreChanged(score)` · `won` · `lost` · `lifeLost(lives)`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `prefab` | `""` | node path |
 | `interval` | `1` | number |
 | `max` | `0` | number |
@@ -1558,6 +1613,7 @@ Signals: `spawned(node)` · `finished`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `speed` | `40` | number |
 | `radius` | `50` | number |
 | `changeEvery` | `2` | number |
@@ -1566,6 +1622,7 @@ Signals: `spawned(node)` · `finished`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `waves` | `[]` | array |
 | `autoStart` | `true` | boolean |
@@ -1575,6 +1632,7 @@ Signals: `waveStarted(index)` · `waveCleared(index)` · `allCleared`
 | Prop | Default | Kind |
 |---|---|---|
+| `enabled` | `true` | boolean |
 | `aggroTarget` | `""` | node path |
 | `aggroRange` | `12` | number |
 | `deAggroRange` | `0` | number |

package/skills/incanto-performance.md CHANGED Viewed

@@ -289,3 +289,38 @@ Set `maxFps` to 30 and confirm `fps` settles near 30 — if it settles near 20,
 is slower than the cap and the cap is not what is limiting it.
 See `incanto-verifying-your-game.md` for the full loop.
+## Identical meshes share their GPU objects
+`MeshInstance3D` used to make a private geometry AND material per node, even
+when byte-identical. Measured at 3,200 units — all runs at the same 3,209 draw
+calls, 1,741,932 triangles and an identical screenshot:
+```
+per-node geometry + material   31.0 ms wall  (renderMs 27.3)
+share one geometry             27.0 ms
++ share two materials          15.4 ms       <- 2x the headroom
+```
+13.1 ms of that cliff was GPU state churn from per-node objects. Nodes now share
+one geometry per (mesh, size) and one material per distinct `material` dict, and
+a node whose look changes gets its own again. **Nothing to do — it is the
+default.** The consequence to know: mutate node PROPS, never the three.js
+material you fished out of a node, because it may not be only yours.
+This does not replace `InstancedMesh3D`. A field of identical props is still one
+node and one draw call there (12,800 units, 11 draw calls, 2.30 ms); sharing
+helps the one-node-per-thing path, which is what a hand-authored level is.
+## The quality tier only ever takes away
+`high` no longer mentions `bloom` or `post` at all, because mentioning them
+CREATED them: on a scene that declared neither, `high` and `medium` both
+rendered a five-pass frame at 3.3 ms where `low` rendered one pass at 1.24 ms —
+62% of the frame on a chain the game never asked for, and
+`engine.scene.environment.bloom` read back `{strength: 0.8, threshold: 1}`.
+A tier is also REVERSIBLE now: it is applied against the scene FILE rather than
+against whatever the last tier left behind, so `low` → `high` restores exactly
+what you authored instead of leaving it stripped.