incanto 0.36.2 → 0.38.0

package/skills/incanto-performance.md

@@ -0,0 +1,212 @@
+---
+name: incanto-performance
+description: Graphics settings the engine provides so a game does not have to invent them — quality tier (shadows/bloom/post/clouds), frame cap, resolution scale, and the one lever (antialiasing) that can only change at boot. They persist, they apply themselves, and the ones that can change live do. Use when supporting low-end devices or building a settings menu.
+---
+
+# incanto — performance settings (quality tier, frame cap, resolution)
+
+The settings a player expects to find in a graphics menu, provided by the engine so
+your game does not have to invent them: **quality tier**, **frame cap**, **resolution
+scale**. They persist, they apply themselves, and the ones that can change live do.
+
+You do not implement any of this. You decide whether to expose it.
+
+---
+
+## The short version
+
+```ts
+const game = await createGame3D({ canvas, scene });
+
+// createGame3D has ALREADY done all of this:
+//   - picked a starting tier from the device, on a first visit only
+//   - read the saved tier at boot for antialiasing (see "boot vs live" below)
+//   - bound the tier, the frame cap and the resolution scale to the live game
+
+game.engine.settings.set('quality', 'low');   // shadows/bloom/post drop THIS FRAME
+game.engine.settings.set('maxFps', 30);       // the loop slows down, and stays cool
+game.engine.settings.set('renderScale', 0.7); // fewer pixels, same world
+```
+
+Every one of those is written to the save store and comes back on the next launch.
+
+---
+
+## The four levers, and what each actually costs
+
+| setting | values | costs | changes live |
+| --- | --- | --- | --- |
+| `quality` | `'low'` `'medium'` `'high'` | shadows, bloom, post, clouds | **yes** |
+| `maxFps` | `0` (uncapped) or fps | nothing visual — battery and heat | **yes** |
+| `renderScale` | `0.25`–`2` | image softness only | **yes** |
+| antialiasing | follows the tier | jagged edges at `low` | **no — boot only** |
+
+### quality
+
+`low` turns off shadows, bloom, post and clouds. `medium` keeps shadows but makes them
+**static** (they render once instead of every frame — the measured 42% of a shadow's
+cost is re-rendering it) and drops post. `high` is everything.
+
+The tier is applied as an environment patch, so a scene that never had bloom does not
+gain any at `high` — the tier can only take things away or restore what the scene asked
+for.
+
+### maxFps
+
+Gates the **whole frame**, not just the render: an uncapped loop on a 144 Hz phone runs
+game logic 144 times a second that nobody will ever see. `0` means "as fast as the
+display goes" and is the default — a cap nobody asked for is a downgrade.
+
+`dt` still comes from the clock, so a capped game is not a slow game. Physics is fixed-
+step and unaffected.
+
+### renderScale
+
+The cheapest lever on a weak GPU. At `0.66` the fragment shaders run over **44%** of the
+pixels; the image goes soft and nothing else changes. Compare that with dropping a
+quality tier, which costs the shadows outright. On a phone that cannot hold 60, try
+`renderScale` before `quality`.
+
+It multiplies with the engine's automatic resolution governor rather than fighting it,
+so a player who already scaled down does not get scaled down twice.
+
+---
+
+## Boot vs live — the one thing that cannot change while running
+
+`antialias` is a **WebGL context attribute**. three fixes it when the context is
+created, and there is no API anywhere that changes it afterwards. So:
+
+- the tier's antialiasing is read **at boot** from the saved setting
+- changing `quality` mid-game changes shadows/bloom/post immediately, and the
+  antialiasing on the **next launch**
+
+If your settings menu wants to be honest about that, say "applies on restart" next to
+antialiasing only. Everything else is immediate.
+
+A scene's own `environment.rendering` and an explicit `pixelRatio` option both still win
+over the tier — an author who pinned a value meant it.
+
+---
+
+## Detection runs once, and a choice is permanent
+
+```ts
+engine.settings.autoQuality();          // first visit only — picks from the device
+engine.settings.chooseQuality('high');  // a HUMAN chose; never auto-detect again
+```
+
+`createGame3D` calls `autoQuality()` for you. Call `chooseQuality(tier)` — not
+`set('quality', tier)` — from a settings menu, so re-detection on the next launch does
+not silently undo it. (A separate `qualityChosen` flag is needed because a chosen tier
+that happens to equal the detected one is otherwise indistinguishable from no choice.)
+
+Device hints used: `hardwareConcurrency`, `deviceMemory`, and whether the pointer is
+coarse. They are hints; a player's own choice always wins.
+
+---
+
+## The menu itself is three nodes
+
+You do not build a graphics menu. You place it.
+
+```json
+{ "name": "Graphics", "type": "UiPanel", "props": { "anchor": "center" },
+  "children": [
+    { "name": "Quality",    "type": "UiQualitySelect" },
+    { "name": "FrameCap",   "type": "UiFrameCapSelect" },
+    { "name": "Resolution", "type": "UiRenderScaleSelect" }
+  ] }
+```
+
+No script, no signal connections, no `Settings` knowledge. Each node reads the
+setting it owns, writes it when the player picks, and follows a change made
+anywhere else — so two menus (a title screen and a pause screen) can never
+disagree.
+
+| node | writes | reads as |
+| --- | --- | --- |
+| `UiQualitySelect` | `chooseQuality()` | Low / Medium / High |
+| `UiFrameCapSelect` | `maxFps` + `engine.maxFps` | 30 / 60 / 120 / Unlimited |
+| `UiRenderScaleSelect` | `renderScale` | 50% / 75% / 100% |
+
+`UiQualitySelect` goes through **`chooseQuality`**, not `set('quality')`, so the
+next launch's device detection cannot undo what a person picked.
+
+Restrict or extend the choices with `options` — `"60,120,0"` on a game that is
+unplayable at 30, `"0.5,0.75,1,1.5"` for supersampling on a strong GPU:
+
+```json
+{ "name": "FrameCap", "type": "UiFrameCapSelect", "props": { "options": "60,120,0" } }
+```
+
+### Localizing the labels
+
+The option text is English unless the scene declares a string for it — a menu
+reading `settings.quality.high` is worse than one reading `High`, so an
+undeclared key falls back to English rather than showing the key:
+
+```json
+"strings": {
+  "ko": {
+    "settings.quality.low": "낮음",
+    "settings.quality.medium": "보통",
+    "settings.quality.high": "높음",
+    "settings.frameCap.unlimited": "제한 없음"
+  }
+}
+```
+
+The `label` prop takes `@t:` like every other widget:
+`{ "label": "@t:settings.quality" }`.
+
+---
+
+## Wiring your own menu
+
+Each setting has a `bind*` that applies the saved value immediately and again on every
+change, and returns an unsubscribe:
+
+```ts
+const off = engine.settings.bindFrameCap((fps) => { engine.maxFps = fps; });
+engine.settings.bindRenderScale((s) => renderer.setRenderScale(s));
+engine.settings.bindQuality((patch) => setEnvironment3D(engine, patch));
+```
+
+`createGame3D` already installs all three. You only reach for these when you build your
+own game loop.
+
+To read the current values for your UI:
+
+```ts
+engine.settings.get('quality');     // 'low' | 'medium' | 'high'
+engine.settings.get('maxFps');      // 0 = uncapped
+engine.settings.get('renderScale'); // 1 = native
+```
+
+---
+
+## What NOT to do
+
+- **Do not build your own frame limiter** with `setTimeout` around your update. The
+  engine's cap is deadline-based; a naive `if (now - last < interval) return` snaps a
+  45 fps request to 30 on a 60 Hz display, which is worse than not capping.
+- **Do not lower the quality tier to fix a slow scene you can fix properly.** The tier
+  is the player's lever. If your game is slow at `high` on a normal machine, run
+  `bunx incanto-check` and look at the triangle and draw-call counts first.
+- **Do not offer antialiasing as a live toggle.** It cannot be one. See above.
+- **Do not read `devicePixelRatio` yourself.** The renderer already clamps it to 2 and
+  scales it by the tier and the governor.
+
+---
+
+## Verifying
+
+```ts
+const { fps, triangles, drawCalls } = game.stats();
+```
+
+Set `maxFps` to 30 and confirm `fps` settles near 30 — if it settles near 20, the game
+is slower than the cap and the cap is not what is limiting it.
+
+See `incanto-verifying-your-game.md` for the full loop.

package/skills/incanto-playtesting.md

@@ -0,0 +1,143 @@
+---
+name: incanto-playtesting
+description: The engine plays your game and reports whether it works — bunx incanto-playtest runs seeded headless bot sessions and reports win rate, unreachable destinations, wires that never fire, falls out of the world, and whether anything can hurt the player. Failing runs come back as replays. Use after a level or game loop is in place, before handing the game back.
+---
+
+# Playtesting — is it a game?
+
+`incanto-check` answers *will it load*. This answers *is it a game*.
+
+```bash
+bunx incanto-playtest src/game.scene.json --runs 20 --seconds 60
+```
+
+```
+20 runs × up to 60s
+
+  ✓ reached "won" in 17/20   median 38s
+  ✗ fell in 3/20 (last at y=-52.0)
+
+  never reached (1 of 6):
+    /Game/Vault/Chest
+
+  never fired (2 of 9):
+    /Game/Boss.died
+    /Game/QuestLog.completed
+
+  danger: the player took damage 0 times in 20 runs — nothing here can hurt you
+
+  replays: .incanto/playtest/fell-seed7.json
+```
+
+Exits **1** when no run reached a win, so it gates CI.
+
+## What it does
+
+A bot plays your game, headlessly, with real physics and a seeded RNG. It reads
+the scene's own `input{}` block for its controls, so it can play a game it has
+never seen. It holds a heading for a while rather than flipping a coin per
+frame, and steers toward the part of the world it has visited least — enough to
+find a door, not enough to solve a puzzle.
+
+No renderer is involved, so twenty minutes of simulated play takes a second or
+two.
+
+## What it reports, and where each answer comes from
+
+| line | source |
+|---|---|
+| `reached "won"` | `GameFlow` state `'won'`, or a `won` signal (e.g. `ScoreKeeper`) |
+| `lost` | `GameFlow` `'gameover'`, a `lost` signal, or the player's `Health.died` |
+| `fell` | the player's world Y dropped below `--fall-below` (default: 50 under the spawn) |
+| `error` | `stats().errors` went above zero — a behavior threw |
+| `stuck` | none of the above before the clock ran out |
+| `never reached` | destinations the bot never came within 2 units of |
+| `never fired` | signals a `connections[]` entry listens to that never happened |
+| `danger` | how many times the player's `Health` emitted `damaged` |
+
+**Nothing here is a guess about your design.** The scene already declares what
+winning is; this only listens.
+
+## Destinations are what YOU marked
+
+A node counts as somewhere to go when it **runs a behavior**, **carries a
+group**, or **is a trigger volume** (`Area2D`/`Area3D`). Decoration is silent —
+keying off the tree alone reported 150 unreached nodes on one village scene and
+138 of them were roof beams.
+
+So: if you want the playtester to care about something, give it a group.
+
+```json
+{ "name": "Chest", "type": "MeshInstance3D", "groups": ["loot"] }
+```
+
+## Reading the failures
+
+**`never reached`** is the reachability question, and research on game QA puts
+it as the single largest bug class: a place the level says you can go and the
+geometry says you cannot. Check the jump height, the gap, the collider.
+
+**`never fired`** means you drew a wire that does nothing. Either the signal is
+unreachable or the connection is wrong.
+
+**`nothing here can hurt you`** is a design report, not an error. Sometimes it
+is exactly right (a walking simulator). Usually it means the hazards are not
+wired up.
+
+**`stuck` in every run** with no `won` at all usually means the scene declares
+no win condition — add a `GameFlow` or a `ScoreKeeper` and the report becomes
+far more useful.
+
+## Replays
+
+A run that did not win is written out. Because the engine is deterministic
+(seeded RNG, injected clock), a replay reproduces that run **bit-identically**:
+
+```bash
+bunx incanto-play src/game.scene.json --seed 7   # then replay the recording
+```
+
+One file per *kind* of failure — twenty identical "stuck" replays teach nothing
+the first one does not.
+
+## Your behaviors
+
+Without `--behaviors`, unregistered scripts are stubbed: the structure plays and
+your game logic does not, which is fine for a reachability pass. To test the
+real thing:
+
+```bash
+bunx incanto-playtest src/game.scene.json --behaviors src/behaviors.ts
+```
+
+## From TypeScript
+
+```ts
+import { playtest, playtestText, failingReplays } from 'incanto/test';
+
+const report = await playtest(sceneJson, { runs: 20, seconds: 60 });
+console.log(playtestText(report));
+```
+
+`report.runs` carries per-run outcome, timing, reached paths, fired signals,
+damage and the replay.
+
+## Pairs with the feel report
+
+`incanto-playtest` answers *can it be finished*. `bunx incanto-feel` answers
+*how does it move* — jump apex, turnaround, and the coyote/jump-buffer windows
+measured rather than read. A level whose apex is 0.26 u and whose gaps are 2 u
+apart shows up here as `never reached` and there as the reason why. See
+`incanto-game-feel.md`.
+
+## What it is NOT
+
+It does not know whether your game is fun. It reports reachability,
+completability, coverage and danger. Taste is still yours.
+
+## Before you hand a game back
+
+```bash
+bunx incanto-check src/*.scene.json      # will it load
+bunx incanto-playtest src/game.scene.json --runs 10 --seconds 45   # is it a game
+```

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

@@ -402,3 +402,44 @@ expect(player.position).toEqual(expected); // exact, not approximate
 Rules that make it hold (the engine's own rules anyway): use `engine.rng`
 never Math.random, dt/`engine.time` never Date.now. Gamepads replay through
 the ACTIONS they were bound to, not raw pad state.
+
+
+## The fifth question: is it a GAME?
+
+The four signals above answer *will it load*, *did something throw*, *did the art
+arrive* and *can the camera see it*. None of them answers whether the thing can
+be played.
+
+```bash
+bunx incanto-playtest src/game.scene.json --runs 20 --seconds 60
+```
+
+A seeded bot plays it headlessly — reading the scene's own `input{}` for its
+controls — and reports the win rate, destinations it could never reach, wires
+that never fired, falls out of the world, and whether anything can hurt the
+player at all. Failing runs come back as replays. Exits 1 when nothing ever won.
+
+Read `incanto-playtesting.md` before shipping a level.
+
+
+## Do not teleport the player in a verify script
+
+`player.position = [...]` between beats proves the quest LOGIC and quietly
+assumes the thing most likely to be broken: that the player can get there. That
+assumption is the largest single bug class in level design, and a verify script
+that makes it is testing everything except the level.
+
+Walk instead. In a camera-relative rig (`view: "free"`), CALIBRATE rather than
+guess the heading — push one direction, measure the world displacement it
+produced, and rotate every later aim by the difference:
+
+```ts
+const before = at();
+ctx.engine.input.setActionVector('move', 1, 0);
+for (let i = 0; i < 20; i++) ctx.engine.step();
+const inputToWorld = Math.atan2(at()[1] - before[1], at()[0] - before[0]);
+// then aim: setActionVector('move', cos(want - inputToWorld), sin(want - inputToWorld))
+```
+
+`examples/village-quest-3d/verify.ts` does exactly this and fails with
+"the player cannot reach it on foot" when it cannot.

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

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

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

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

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

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

package/templates-app/village-quest-3d/src/village.scene.json

@@ -3334,7 +3334,9 @@
                 "run": "$anims/run",
                 "fastRun": "$anims/runFast",
                 "airborne": "$anims/jump"
-              }
+              },
+              "coyoteSeconds": 0.12,
+              "jumpBufferSeconds": 0.15
             },
             "script": {
               "name": "SwordStrike"

package/templates-app/village-quest-3d/verify.ts

@@ -26,6 +26,58 @@ interface Vec {
   position: number[];
 }
 
+/**
+ * WALK there — do not teleport.
+ *
+ * This file used to set `player.position` at every quest beat, which proved the
+ * quest LOGIC and quietly assumed the thing most likely to be broken: that the
+ * player can actually get there. `incanto-playtest` exists because that
+ * assumption is the largest bug class in level design, and a verify script that
+ * makes it is demonstrating the wrong habit in the repo's own showcase.
+ *
+ * `move` is camera-relative in the `free` rig, so the heading is CALIBRATED
+ * rather than assumed: push one direction, measure the world displacement it
+ * produced, and rotate every later aim by the difference. That works whatever
+ * the camera is doing and needs no knowledge of the rig.
+ */
+function walkTo(
+  ctx: { engine: Engine; getNode(path: string): unknown },
+  target: readonly [number, number],
+  opts: { within?: number; timeoutMs?: number; label?: string } = {},
+): void {
+  const within = opts.within ?? 1.2;
+  const budget = Math.round((opts.timeoutMs ?? 20000) / (1000 / 60));
+  const player = ctx.getNode('/root/Player') as unknown as Vec;
+  const at = (): [number, number] => [player.position[0] ?? 0, player.position[2] ?? 0];
+  const dist = (): number => Math.hypot(target[0] - at()[0], target[1] - at()[1]);
+
+  // calibrate: push +x in INPUT space and see where the world went
+  const before = at();
+  ctx.engine.input.setActionVector('move', 1, 0);
+  for (let i = 0; i < 20; i++) ctx.engine.step();
+  const after = at();
+  ctx.engine.input.setActionVector('move', 0, 0);
+  const moved = Math.hypot(after[0] - before[0], after[1] - before[1]);
+  if (moved < 0.05) throw new Error(`walkTo(${opts.label ?? ''}): the player cannot move at all`);
+  const inputToWorld = Math.atan2(after[1] - before[1], after[0] - before[0]);
+
+  for (let f = 0; f < budget && dist() > within; f++) {
+    const here = at();
+    const want = Math.atan2(target[1] - here[1], target[0] - here[0]);
+    const aim = want - inputToWorld;
+    ctx.engine.input.setActionVector('move', Math.cos(aim), Math.sin(aim));
+    ctx.engine.step();
+  }
+  ctx.engine.input.setActionVector('move', 0, 0);
+  for (let i = 0; i < 10; i++) ctx.engine.step();
+  if (dist() > within) {
+    throw new Error(
+      `walkTo(${opts.label ?? `${target[0]},${target[1]}`}): still ${dist().toFixed(1)} away ` +
+        `after ${opts.timeoutMs ?? 20000}ms — the player cannot reach it on foot`,
+    );
+  }
+}
+
 const ok = (label: string, cond: boolean): void => {
   if (!cond) {
     console.error(`FAIL: ${label}`);
@@ -64,9 +116,8 @@ const ok = (label: string, cond: boolean): void => {
         label: 'talk to the Elder and accept the quest',
         do: (ctx) => {
           sceneName = () => ctx.engine.scene?.source?.name as string;
-          const player = ctx.getNode('/root/Player') as unknown as Vec;
-          player.position = [3, 1.4, 0.2]; // step up to the Elder
-          for (let i = 0; i < 5; i++) ctx.engine.step();
+          // the Elder is at [3, 0, -2] with Interactable range 2.8
+          walkTo(ctx, [3, -2], { within: 2, label: 'the Elder' });
           ctx.engine.input.pressAction('interact');
           ctx.engine.step();
           ctx.engine.input.releaseAction('interact');
@@ -85,8 +136,7 @@ const ok = (label: string, cond: boolean): void => {
         atMs: 6000,
         label: 'north gate swaps to the grove (goToScene)',
         do: (ctx) => {
-          const player = ctx.getNode('/root/Player') as unknown as Vec;
-          player.position = [0, 1.5, -26.4]; // into the gate trigger
+          walkTo(ctx, [0, -26.4], { label: 'the north gate', timeoutMs: 30000 });
           for (let i = 0; i < 30 && sceneName() !== 'WolfGrove'; i++) ctx.engine.step();
           if (sceneName() !== 'WolfGrove') throw new Error(`still in ${sceneName()}`);
         },

package/dist/errors-DGRtWlSx.d.ts

@@ -1,39 +0,0 @@
-import { s as JsonObject } from "./schema-CFeioQRE.js";
-
-//#region src/core/audit.d.ts
-/** Human-readable warnings (empty = clean). Pure JSON walk, no registry. */
-declare function auditScene(scene: JsonObject): string[];
-//#endregion
-//#region src/core/errors.d.ts
-/**
-* Stable error codes for every hard failure in the engine.
-*
-* Incanto fails loudly with machine-readable codes and messages that list valid
-* alternatives — AI agents self-correct on hard failures, not warnings.
-*/
-type IncantoErrorCode = "BAD_FORMAT" | "BAD_NODE_PATH" | "DANGLING_CONNECTION" | "DUPLICATE_BEHAVIOR" | "DUPLICATE_NODE_TYPE" | "DUPLICATE_UNIQUE_NAME" | "DUPLICATE_UID" | "NODE_NOT_FOUND" | "PROP_TYPE_MISMATCH" | "TREE_VIOLATION" | "UNKNOWN_ANIMATION" | "UNKNOWN_ASSET" | "UNKNOWN_CONSTANT" | "UNKNOWN_BEHAVIOR" | "UNKNOWN_HANDLER" | "UNKNOWN_NODE_TYPE" | "UNKNOWN_PROP" | "UNKNOWN_SIGNAL" | "UNRESOLVED_INSTANCE";
-/**
-* Structured context mirrored from the prose message — tools and agents parse
-* THESE instead of regexing the message (which is for humans and may reword).
-*/
-interface IncantoErrorDetails {
-  /** Absolute path of the offending node in the scene being loaded ('/Root/Child'). */
-  readonly path?: string;
-  /** The offending node's uid, when the scene JSON declared one. */
-  readonly uid?: string;
-  /** The offending node's type name. */
-  readonly nodeType?: string;
-  /** The offending prop key. */
-  readonly prop?: string;
-  /** The offending signal name. */
-  readonly signal?: string;
-  /** The valid alternatives the message also lists — for programmatic self-correction. */
-  readonly validOptions?: readonly string[];
-}
-declare class IncantoError extends Error {
-  readonly code: IncantoErrorCode;
-  readonly details: IncantoErrorDetails;
-  constructor(code: IncantoErrorCode, message: string, details?: IncantoErrorDetails);
-}
-//#endregion
-export { auditScene as i, IncantoErrorCode as n, IncantoErrorDetails as r, IncantoError as t };