incanto 0.55.0 → 0.57.0

package/editor/index.html

@@ -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-BfqmvXYD.js"></script>
+    <script type="module" crossorigin src="./assets/index-CV1m-aX5.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/GameServer-C56iOUgF.js">
   </head>
   <body>

package/package.json

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

package/skills/incanto-assets.md

@@ -182,7 +182,11 @@ frame 40. Those frames draw whatever is at the wrong end of the sheet.
 ```
 
 The suggested sizes are the ones that actually divide your image, so the fix is
-usually in the message. `bunx incanto-assets info <name>` prints the real frame
+usually in the message. **All three nodes that cut a grid out of an image check
+it** — `AnimatedSprite2D`, `AnimatedSprite3D` and `TileMap2D` — because they do
+the same floor-division and it fails the same silent way. An
+`AnimatedSprite3D` with a sheet and no `frameWidth`/`frameHeight` also says so
+rather than drawing a mob-shaped hole. `bunx incanto-assets info <name>` prints the real frame
 size for a built-in, and the editor's 📚 picker fills it in from the catalog's
 metadata — or leaves it BLANK when the catalog does not carry it, because an
 invented frame size is exactly this bug.

package/skills/incanto-audio.md

@@ -350,6 +350,11 @@ background loop authored in scene JSON. Wire `crossfadeTo` from gameplay:
 this.engine.music.crossfadeTo('/audio/boss.mp3', 3);
 ```
 
+**A track that will never play says so.** A 404 or an undecodable file lands in
+the engine log (`[incanto] music '/audio/boss.mp3' will not play — could not
+load.`) instead of being indistinguishable from a game with no music. The
+autoplay gate is still just the gate — a track waiting for a tap is not an error.
+
 > Large music files are NOT bundled — reference them by URL (see §4).
 
 **Headless the state machine still runs and `current` still updates** — nothing
@@ -448,7 +453,8 @@ bricking the game.
 ### Quality tiers
 
 ```ts
-import { qualityEnvironment, readDeviceHints, suggestQuality, setEnvironment3D } from 'incanto';
+import { qualityEnvironment, readDeviceHints, suggestQuality } from 'incanto';
+import { setEnvironment3D } from 'incanto/3d'; // it applies a 3D environment
 
 const tier = engine.settings.get('quality') ?? suggestQuality(readDeviceHints());
 setEnvironment3D(engine, qualityEnvironment(tier));

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

@@ -203,11 +203,24 @@ A nameplate, a sign, a damage number:
 - It IS a `Sprite3D`, so `anchor`, `tint`, `opacity`, `alphaTest`, `renderOrder`
   and `orderGroup` all work exactly as they do there.
 
-A **damage number** is this node plus two lines: set `text`, then float it up
-and fade `opacity` to 0 over ~0.6 s and `queueFree()`. Re-rasterising is
-handled — the texture is rebuilt only when the text (or size/colour/font)
-changes, and the old one is disposed, so a number per hit does not leak a
-texture per hit.
+A **damage number** is this node plus the `FloatAway` behavior, and no
+TypeScript of your own:
+
+```json
+{ "name": "Hit", "type": "Label3D",
+  "props": { "text": "12", "height": 0.35, "color": "#ff5a5a" },
+  "script": { "name": "FloatAway", "props": { "rise": 1.2, "seconds": 0.7, "drift": 0.3 } } }
+```
+
+It rises with an ease-out (constant speed reads as a lift, not a hit), holds at
+full opacity for `hold` of its life so the number is readable, fades, and frees
+itself — so a hundred numbers a fight leave nothing in the tree. `drift` keeps
+ten at once from stacking into one. Spawning is `duplicateNode` + set `text` and
+`position`.
+
+Re-rasterising is handled: the texture is rebuilt only when the text (or
+size/colour/font) changes, and the old one is disposed, so a number per hit does
+not leak a texture per hit.
 
 | Prop | Default | Notes |
 |---|---|---|

package/skills/incanto-gameplay-behaviors.md

@@ -20,7 +20,8 @@ with `gameplay: false`, or register a subset yourself:
 import { registerGameplayBehaviors } from 'incanto/gameplay';
 registerGameplayBehaviors();                 // all of them (default in createGame)
 
-import { Health, Pickup, registerBehavior } from 'incanto/gameplay';
+import { registerBehavior } from 'incanto';
+import { Health, Pickup } from 'incanto/gameplay';
 registerBehavior('Health', Health);          // or pick just what you use
 ```
 
@@ -828,6 +829,25 @@ import { CameraShake, Cooldown, hitStop, screenFlash } from 'incanto/gameplay';
   tested. (A stepped frame still HAPPENS while paused: `update` runs with
   `dt = 0`, which is how the pause menu's own key polling keeps working.)
 
+### `FloatAway` — rise, fade, gone
+
+The second half of a damage number, a pickup puff, a `+50`:
+
+```json
+{ "name": "Hit", "type": "Label3D",
+  "props": { "text": "12", "height": 0.35 },
+  "script": { "name": "FloatAway", "props": { "rise": 1.2, "seconds": 0.7, "drift": 0.3 } } }
+```
+
+`rise` (world units, negative sinks) · `seconds` · `hold` (fraction of the life
+at full opacity before the fade) · `drift` (sideways, so ten at once do not
+stack) · `freeOnEnd` (default true).
+
+Works on anything with `position` and `opacity` — a `Label3D`, a `Sprite3D`
+puff, a 2D `Label`. It reads the start position ONCE, so the ease does not
+compound, and it frees the node a frame after it is invisible rather than on the
+frame it gets there (which reads as a flicker).
+
 ## Did the effect fire?
 
 Sound has `engine.audio`; vision has **`engine.effects`**, and the question is

package/skills/incanto-hud.md

@@ -167,6 +167,12 @@ widget use `UiButton`'s `pressed`.
 Setting `.value` from a behavior updates the control and does **NOT** re-emit
 `changed` — restoring a saved setting must not fire the handler that saved it.
 
+**Every prop is live.** `color`, `size`, `width`, `background`, `label` and
+`anchor` are re-read each frame, so flashing the score red, growing a health bar
+or moving a widget to another corner all work from a behavior — and from the
+editor's inspector, which is the same code path. They used to be baked in when
+the widget was built and could never be changed afterwards.
+
 ## Playable on a controller (focus navigation)
 
 A menu you can only click is not playable on a gamepad, and "add controller

package/skills/incanto-performance.md

@@ -92,6 +92,11 @@ that built a mesh), dispose it in the behavior's `onExitTree`.
 | `renderScale` | `0.25`–`2` | image softness only | **yes** |
 | antialiasing | follows the tier | jagged edges at `low` | **no — boot only** |
 
+`maxFps` and `renderScale` apply in **2D as well as 3D** now — they persisted for
+every game and were applied by the 3D boot only, so a 2D options menu saved a
+number and changed nothing. `quality` remains a 3D tier (there are no shadows,
+bloom or clouds to drop in 2D).
+
 ### quality
 
 **Water follows the tier too, and it is the biggest single saving.**

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

@@ -192,6 +192,20 @@ engine.input.pressAction('jump');           // one justPressed frame, held until
 engine.input.releaseAction('jump');         // …released (one justReleased frame)
 engine.input.setActionVector('move', 1, 0); // analog vector2; (0, 0) clears
 ```
+
+**An action name you typed that does not exist says so.** A controller tolerates
+a missing action — a game with no sprint key must not crash — but a value you
+NAMED and never declared is a typo, and it used to be indistinguishable from the
+tolerated case:
+
+```
+[incanto] /Game/Player/Ctl: Unknown input action 'movement'.
+Declared actions: [move, jump]. The character will not move.
+```
+
+Once per node and action, and only when the prop differs from its default —
+leaving `sprintAction` alone in a game with no sprint key is the ordinary case
+and stays silent.
 Injected state combines with key state (vectors clamped to unit length).
 
 ## Patterns

package/skills/incanto-save-slots.md

@@ -146,7 +146,8 @@ The engine does not route scenes — deliberately, because only your game knows
 what a key means. What it does is record the key, so the routing is a lookup:
 
 ```ts
-import { createGame2D, loadScene } from 'incanto';
+import { loadScene } from 'incanto';
+import { createGame2D } from 'incanto/2d';
 import level1 from './level1.scene.json';
 import level2 from './level2.scene.json';
 

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

@@ -399,6 +399,10 @@ shouting the same thing every frame has one problem, not six hundred.
 
 ### `bunx incanto-frame` — what is actually on screen
 
+Works for **2D and 3D** games alike (as does `incanto-logs`, and `game.frame()`).
+Both used to be answered by the 3D boot only, so a 2D preview that was open and
+drawing reported "no page answered".
+
 The rung above framing. `framing` PREDICTS what the camera should see from the
 scene graph; this measures what the GPU drew — the only one that can catch a
 black screen, a material that failed, or a shader drawing where it should not.

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

package/dist/log-report-CPFm4OXf.js

@@ -1,173 +0,0 @@
-//#region src/core/drive-script.ts
-const num = (raw) => {
-	if (raw === void 0) return null;
-	const n = Number(raw);
-	return Number.isFinite(n) ? n : null;
-};
-/**
-* `vector move 0 1; step 2000` → steps, or an error naming the bad command.
-*
-* Semicolons and newlines both separate, so a whole plan fits in one shell
-* argument and a longer one fits in a file. `#` starts a comment.
-*
-* A command it does not know REFUSES THE WHOLE SCRIPT. Skipping it would leave
-* an agent looking at a frame that never moved, believing it had walked
-* somewhere — the failure mode this exists to prevent.
-*/
-function parseDrive(text) {
-	const steps = [];
-	let totalMs = 0;
-	const lines = text.split(/[;\n]/).map((l) => l.replace(/#.*$/, "").trim()).filter(Boolean);
-	for (const line of lines) {
-		const [word, ...rest] = line.split(/\s+/);
-		const bad = (why) => ({
-			steps: [],
-			error: `${why}: "${line}"`,
-			totalMs: 0
-		});
-		switch (word) {
-			case "press":
-			case "release": {
-				const action = rest[0];
-				if (!action) return bad(`${word} needs an action name`);
-				steps.push(word === "press" ? {
-					kind: "press",
-					action
-				} : {
-					kind: "release",
-					action
-				});
-				break;
-			}
-			case "vector": {
-				const action = rest[0];
-				const x = num(rest[1]);
-				const y = num(rest[2]);
-				if (!action || x === null || y === null) return bad("vector needs an action and two numbers");
-				steps.push({
-					kind: "vector",
-					action,
-					x,
-					y
-				});
-				break;
-			}
-			case "key": {
-				const code = rest[0];
-				const dir = rest[1];
-				if (!code || dir !== "down" && dir !== "up") return bad("key needs a code and down|up");
-				steps.push({
-					kind: "key",
-					code,
-					down: dir === "down"
-				});
-				break;
-			}
-			case "pointer": {
-				const dx = num(rest[0]);
-				const dy = num(rest[1]);
-				if (dx === null || dy === null) return bad("pointer needs two numbers");
-				steps.push({
-					kind: "pointer",
-					dx,
-					dy
-				});
-				break;
-			}
-			case "step": {
-				const ms = num(rest[0]);
-				if (ms === null || ms < 0) return bad("step needs a duration in ms");
-				steps.push({
-					kind: "step",
-					ms
-				});
-				totalMs += ms;
-				break;
-			}
-			default: return bad("not a command");
-		}
-	}
-	return {
-		steps,
-		error: null,
-		totalMs
-	};
-}
-//#endregion
-//#region src/core/log-report.ts
-const RANK = {
-	debug: 0,
-	info: 1,
-	warn: 2,
-	error: 3
-};
-/** Under this, with the loop running, is a frame rate somebody can feel. */
-const SLOW_FPS = 50;
-/** How many distinct messages to carry. Beyond this it is a log file, not a report. */
-const MAX_GROUPS = 20;
-/** The engine logs values, not strings — format them the way a console would. */
-function format(parts) {
-	return parts.map((p) => {
-		if (typeof p === "string") return p;
-		if (p instanceof Error) return p.message;
-		try {
-			return JSON.stringify(p);
-		} catch {
-			return String(p);
-		}
-	}).join(" ");
-}
-function logReport(input) {
-	const counts = {
-		debug: 0,
-		info: 0,
-		warn: 0,
-		error: 0
-	};
-	const byMessage = /* @__PURE__ */ new Map();
-	for (const e of input.entries) {
-		counts[e.level] += 1;
-		const message = format(e.parts);
-		const key = `${e.level}\0${message}`;
-		const seen = byMessage.get(key);
-		if (seen) {
-			seen.count += 1;
-			seen.lastMs = Math.max(seen.lastMs, e.timeMs);
-		} else byMessage.set(key, {
-			level: e.level,
-			message,
-			count: 1,
-			lastMs: e.timeMs
-		});
-	}
-	const grouped = [...byMessage.values()].sort((a, b) => RANK[b.level] - RANK[a.level] || b.lastMs - a.lastMs).slice(0, MAX_GROUPS);
-	const hidden = input.hidden === true;
-	const slow = !hidden && input.stats.running && input.stats.fps > 0 && input.stats.fps < SLOW_FPS;
-	return {
-		hidden,
-		ok: counts.error === 0 && input.stats.errors === 0 && input.assetErrors.length === 0,
-		slow,
-		counts,
-		grouped,
-		worst: grouped.find((g) => g.level === "error") ?? grouped[0] ?? null,
-		stats: input.stats,
-		assetErrors: input.assetErrors
-	};
-}
-/** The report as a person or an agent reads it: what is wrong, then the numbers. */
-function logText(r) {
-	const lines = [];
-	if (r.stats.errors > 0) lines.push(`${r.stats.errors} error${r.stats.errors === 1 ? "" : "s"} were swallowed to keep the game alive — it is running, and something in it is broken`);
-	for (const a of r.assetErrors) lines.push(`asset ${a.ref} never loaded: ${a.error} (${a.url})`);
-	for (const g of r.grouped) {
-		if (g.level === "debug") continue;
-		lines.push(`[${g.level}] ${g.message}${g.count > 1 ? ` ×${g.count}` : ""}`);
-	}
-	if (lines.length === 0) lines.push("nothing wrong — no warnings, no errors, no failed assets");
-	if (!r.stats.running) lines.push(`not running — the loop is stopped (${r.stats.nodes} nodes in the scene)`);
-	else if (r.hidden) lines.push(`${r.stats.nodes} nodes · frame rate not measurable — the page is hidden (a window covered by another counts), and the browser throttles it. Bring it to the front`);
-	else lines.push(`${Math.round(r.stats.fps)} fps · ${r.stats.frameMs.toFixed(1)}ms per frame · ${r.stats.nodes} nodes${r.slow ? " — slow enough to feel" : ""}`);
-	return lines.join("\n");
-}
-//#endregion
-export { logText as n, parseDrive as r, logReport as t };