incanto 0.37.0 → 0.38.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-C833FBzB.js"></script>
+    <script type="module" crossorigin src="./assets/index-BS01WWgM.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/GameServer-C56iOUgF.js">
   </head>
   <body>

package/package.json

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

package/schemas/scene.schema.json

@@ -343,6 +343,9 @@
         {
           "$ref": "#/$defs/UiDialogue"
         },
+        {
+          "$ref": "#/$defs/UiFrameCapSelect"
+        },
         {
           "$ref": "#/$defs/UiImage"
         },
@@ -352,6 +355,12 @@
         {
           "$ref": "#/$defs/UiPanel"
         },
+        {
+          "$ref": "#/$defs/UiQualitySelect"
+        },
+        {
+          "$ref": "#/$defs/UiRenderScaleSelect"
+        },
         {
           "$ref": "#/$defs/UiSelect"
         },
@@ -6560,6 +6569,101 @@
       },
       "required": ["name", "type"]
     },
+    "UiFrameCapSelect": {
+      "type": "object",
+      "x-signals": ["dragStarted", "dragCancelled", "droppedOn", "dropped", "changed"],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "uid": {
+          "type": "string"
+        },
+        "type": {
+          "const": "UiFrameCapSelect"
+        },
+        "groups": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "tags": {
+          "type": "object"
+        },
+        "props": {
+          "type": "object",
+          "properties": {
+            "anchor": {
+              "type": "string",
+              "enum": [
+                "topLeft",
+                "top",
+                "topRight",
+                "left",
+                "center",
+                "right",
+                "bottomLeft",
+                "bottom",
+                "bottomRight"
+              ],
+              "default": "topLeft"
+            },
+            "visible": {
+              "type": "boolean",
+              "default": true
+            },
+            "focusable": {
+              "type": "boolean",
+              "default": true
+            },
+            "draggable": {
+              "type": "boolean",
+              "default": false
+            },
+            "dropTarget": {
+              "type": "boolean",
+              "default": false
+            },
+            "label": {
+              "type": "string",
+              "default": "Frame rate"
+            },
+            "options": {
+              "type": "string",
+              "default": "30,60,120,0"
+            },
+            "value": {
+              "type": "string",
+              "default": ""
+            }
+          },
+          "additionalProperties": false
+        },
+        "script": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "props": {
+              "type": "object"
+            }
+          },
+          "required": ["name"]
+        },
+        "network": {
+          "type": "object"
+        },
+        "children": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/node"
+          }
+        }
+      },
+      "required": ["name", "type"]
+    },
     "UiImage": {
       "type": "object",
       "x-signals": ["dragStarted", "dragCancelled", "droppedOn", "dropped"],
@@ -6883,6 +6987,196 @@
       },
       "required": ["name", "type"]
     },
+    "UiQualitySelect": {
+      "type": "object",
+      "x-signals": ["dragStarted", "dragCancelled", "droppedOn", "dropped", "changed"],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "uid": {
+          "type": "string"
+        },
+        "type": {
+          "const": "UiQualitySelect"
+        },
+        "groups": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "tags": {
+          "type": "object"
+        },
+        "props": {
+          "type": "object",
+          "properties": {
+            "anchor": {
+              "type": "string",
+              "enum": [
+                "topLeft",
+                "top",
+                "topRight",
+                "left",
+                "center",
+                "right",
+                "bottomLeft",
+                "bottom",
+                "bottomRight"
+              ],
+              "default": "topLeft"
+            },
+            "visible": {
+              "type": "boolean",
+              "default": true
+            },
+            "focusable": {
+              "type": "boolean",
+              "default": true
+            },
+            "draggable": {
+              "type": "boolean",
+              "default": false
+            },
+            "dropTarget": {
+              "type": "boolean",
+              "default": false
+            },
+            "label": {
+              "type": "string",
+              "default": "Quality"
+            },
+            "options": {
+              "type": "string",
+              "default": "low,medium,high"
+            },
+            "value": {
+              "type": "string",
+              "default": ""
+            }
+          },
+          "additionalProperties": false
+        },
+        "script": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "props": {
+              "type": "object"
+            }
+          },
+          "required": ["name"]
+        },
+        "network": {
+          "type": "object"
+        },
+        "children": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/node"
+          }
+        }
+      },
+      "required": ["name", "type"]
+    },
+    "UiRenderScaleSelect": {
+      "type": "object",
+      "x-signals": ["dragStarted", "dragCancelled", "droppedOn", "dropped", "changed"],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "uid": {
+          "type": "string"
+        },
+        "type": {
+          "const": "UiRenderScaleSelect"
+        },
+        "groups": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "tags": {
+          "type": "object"
+        },
+        "props": {
+          "type": "object",
+          "properties": {
+            "anchor": {
+              "type": "string",
+              "enum": [
+                "topLeft",
+                "top",
+                "topRight",
+                "left",
+                "center",
+                "right",
+                "bottomLeft",
+                "bottom",
+                "bottomRight"
+              ],
+              "default": "topLeft"
+            },
+            "visible": {
+              "type": "boolean",
+              "default": true
+            },
+            "focusable": {
+              "type": "boolean",
+              "default": true
+            },
+            "draggable": {
+              "type": "boolean",
+              "default": false
+            },
+            "dropTarget": {
+              "type": "boolean",
+              "default": false
+            },
+            "label": {
+              "type": "string",
+              "default": "Resolution"
+            },
+            "options": {
+              "type": "string",
+              "default": "0.5,0.75,1"
+            },
+            "value": {
+              "type": "string",
+              "default": ""
+            }
+          },
+          "additionalProperties": false
+        },
+        "script": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "props": {
+              "type": "object"
+            }
+          },
+          "required": ["name"]
+        },
+        "network": {
+          "type": "object"
+        },
+        "children": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/node"
+          }
+        }
+      },
+      "required": ["name", "type"]
+    },
     "UiSelect": {
       "type": "object",
       "x-signals": ["dragStarted", "dragCancelled", "droppedOn", "dropped", "changed"],

package/skills/incanto-node-reference.md

@@ -990,6 +990,21 @@ Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `presse
 
 Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `lineShown` · `choiceMade` · `dialogueFinished`
 
+## `UiFrameCapSelect` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `focusable` | `true` | boolean |
+| `draggable` | `false` | boolean |
+| `dropTarget` | `false` | boolean |
+| `label` | `"Frame rate"` | string |
+| `options` | `"30,60,120,0"` | string |
+| `value` | `""` | string |
+
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `changed`
+
 ## `UiImage` — `incanto`
 
 | Prop | Default | Kind |
@@ -1044,6 +1059,36 @@ Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `change
 
 Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped`
 
+## `UiQualitySelect` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `focusable` | `true` | boolean |
+| `draggable` | `false` | boolean |
+| `dropTarget` | `false` | boolean |
+| `label` | `"Quality"` | string |
+| `options` | `"low,medium,high"` | string |
+| `value` | `""` | string |
+
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `changed`
+
+## `UiRenderScaleSelect` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
+| `visible` | `true` | boolean |
+| `focusable` | `true` | boolean |
+| `draggable` | `false` | boolean |
+| `dropTarget` | `false` | boolean |
+| `label` | `"Resolution"` | string |
+| `options` | `"0.5,0.75,1"` | string |
+| `value` | `""` | string |
+
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `changed`
+
 ## `UiSelect` — `incanto`
 
 | Prop | Default | Kind |

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