incanto 0.33.0 → 0.35.0

package/skills/incanto-localization.md

@@ -0,0 +1,132 @@
+---
+name: incanto-localization
+description: Ship a game in more than one language: a scene-header `strings` table, `"@t:key"` text props, `engine.t()`, and a ready-made UiLanguageSelect that switches live and persists. English is the base — a key a locale omits falls back to it silently, on purpose. Use whenever a game needs a language other than English, or a language setting.
+---
+
+# Localization — English base, other languages on top
+
+Ship a game in more than one language without a second build, a second scene, or
+a page reload.
+
+**English is the base and the default.** Every other locale is a partial overlay:
+anything it does not translate falls back to English, silently.
+
+## The rule that matters most
+
+> When a translation is ambiguous, when the English term is the more precise one,
+> or when the translation runs so much longer than the English that it breaks the
+> layout — **ship the English.**
+
+Leaving a key untranslated is a **decision**, not a gap to fill. `COMBO`,
+`BOSS`, `LV.`, `HP`, `x1.5` are usually clearer in English to players in every
+language, and a "Continue to the next chapter" that becomes three lines in a
+button will break your menu. Omit the key and the English appears. Nothing warns,
+nothing marks it, nothing logs.
+
+The only mistake worth reporting is a key **nothing** declares — a typo, which
+renders raw on screen. `bunx incanto-check` tells you at author time.
+
+## Declaring strings
+
+One `strings` block in the scene header, locale first:
+
+```json
+{
+  "format": 1, "type": "scene", "name": "Menu",
+  "strings": {
+    "en": {
+      "menu.start": "Start Game",
+      "menu.options": "Options",
+      "settings.language": "Language",
+      "hud.wave": "Wave {n}",
+      "hud.combo": "COMBO"
+    },
+    "ko": {
+      "menu.start": "게임 시작",
+      "menu.options": "설정",
+      "settings.language": "언어",
+      "hud.wave": "{n} 웨이브"
+    }
+  },
+  "root": { "...": "..." }
+}
+```
+
+`hud.combo` has no Korean entry on purpose — "COMBO" is the term players already
+read. It shows as `COMBO` in both languages, and that is correct.
+
+Tables **merge** across scenes: put your shared UI strings in the scene the game
+boots from, and a level that adds three lines of its own keeps them.
+
+## Using them
+
+A text prop becomes translatable by naming a key with `@t:` — the same shape as
+the `"$assetKey"` references you already write:
+
+```json
+{ "name": "Start", "type": "UiButton", "props": { "text": "@t:menu.start" } }
+{ "name": "Wave",  "type": "UiText",   "props": { "text": "@t:hud.wave" } }
+```
+
+Works on every text-bearing widget: `UiText.text`, `UiButton.text`,
+`UiBar.label`, `UiSelect.label`, `UiBanner.show()`, and `UiDialogue` lines,
+speakers and choices.
+
+From a behavior, `engine.t(key, params)`:
+
+```ts
+banner.show(this.engine.t('hud.wave', { n: this.wave }));
+```
+
+`{n}` slots are filled from `params`; a slot with no matching param is left
+alone rather than blanked.
+
+## The language picker
+
+One node. Do not build your own.
+
+```json
+{ "name": "Language", "type": "UiLanguageSelect",
+  "props": { "label": "@t:settings.language" } }
+```
+
+Its options are the locales your scene declares — a game shipping only English
+shows only English — each labeled with its own endonym (`한국어`, not `Korean`),
+because a player who cannot read the language on screen still has to find theirs.
+Picking one switches the game **live** and persists the choice through
+`engine.settings`, so the next visit opens in it.
+
+## What NOT to localize
+
+- **Values, not labels.** `UiSelect.options` are values the game compares
+  against (`"low,medium,high"`); translating them breaks the comparison.
+- **Node names, group names, asset keys, signal names, action names.** These are
+  identifiers.
+- **Anything a behavior parses.** If code does `if (value === 'start')`, that
+  string is an identifier wearing a label's clothes.
+
+## Verifying
+
+```bash
+bunx incanto-check src/scenes/menu.scene.json
+```
+
+Reports any `@t:` key that no locale declares. It says nothing about a key one
+locale omits — that is the design, not a warning.
+
+To check a language actually renders, set it and read the frame:
+
+```ts
+game.engine.locale.locale = 'ko';
+```
+
+Switching takes effect on the **next frame** — nothing to reload, nothing to
+invalidate. Widgets re-read their text every frame, which is what makes this
+work.
+
+## Fonts
+
+The engine's HUD uses the platform font stack. On a machine with no CJK face
+installed, Korean renders as boxes — that is the operating system, not the
+engine. If you ship Korean to an audience you do not control, add a webfont in
+your own page CSS and set it on the HUD layer.

package/skills/incanto-node-reference.md

@@ -145,7 +145,7 @@ Signals: `finished`
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `snapToGround` | `null` | null |
-| `target` | `""` | string |
+| `target` | `""` | node path |
 | `bone` | `""` | string |
 
 ## `BoneLookAt3D` — `incanto/3d`
@@ -160,9 +160,9 @@ Signals: `finished`
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `snapToGround` | `null` | null |
-| `target` | `""` | string |
+| `target` | `""` | node path |
 | `bone` | `"Head"` | string |
-| `lookAt` | `""` | string |
+| `lookAt` | `""` | node path |
 | `maxAngleDeg` | `75` | number |
 | `weight` | `0.85` | number |
 | `forwardAxis` | `"+z"` | one of: `+x` `-x` `+y` `-y` `+z` `-z` |
@@ -178,7 +178,7 @@ Signals: `finished`
 | `renderOrder` | `0` | number |
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `visible` | `true` | boolean |
-| `follow` | `""` | string |
+| `follow` | `""` | node path |
 | `smoothing` | `0` | number |
 | `zoom` | `1` | number |
 | `limits` | `[]` | array |
@@ -289,7 +289,7 @@ Signals: `movementStateChanged(state)`
 | `moveAction` | `"move"` | string |
 | `jumpAction` | `"jump"` | string |
 | `sprintAction` | `"sprint"` | string |
-| `skinPath` | `"../Skin"` | string |
+| `skinPath` | `"../Skin"` | node path |
 | `skinYawOffset` | `0` | number |
 | `animations` | `{}` | object |
 
@@ -352,7 +352,7 @@ Signals: `movementStateChanged(state)`
 | `sway` | `0.5` | number |
 | `drape` | `null` | null |
 | `avoidWater` | `true` | boolean |
-| `terrain` | `""` | string |
+| `terrain` | `""` | node path |
 
 ## `Foliage3D` — `incanto/3d`
 
@@ -386,7 +386,7 @@ Signals: `movementStateChanged(state)`
 | `seed` | `1` | number |
 | `drape` | `null` | null |
 | `avoidWater` | `true` | boolean |
-| `terrain` | `""` | string |
+| `terrain` | `""` | node path |
 
 ## `HudLayer` — `incanto`
 
@@ -394,6 +394,7 @@ Signals: `movementStateChanged(state)`
 |---|---|---|
 | `zIndex` | `100` | number |
 | `visible` | `true` | boolean |
+| `focusNavigation` | `false` | boolean |
 
 ## `InstancedMesh3D` — `incanto/3d`
 
@@ -427,7 +428,7 @@ Signals: `movementStateChanged(state)`
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `visible` | `true` | boolean |
 | `type` | `"revolute"` | one of: `fixed` `revolute` `rope` `spring` |
-| `target` | `""` | string |
+| `target` | `""` | node path |
 | `anchor` | `[0,0]` | array |
 | `targetAnchor` | `[0,0]` | array |
 | `length` | `0` | number |
@@ -447,7 +448,7 @@ Signals: `movementStateChanged(state)`
 | `orderGroup` | `"default"` | one of: `background` `terrain` `default` `characters` `effects` `overlay` |
 | `snapToGround` | `null` | null |
 | `type` | `"spherical"` | one of: `fixed` `spherical` `rope` `spring` |
-| `target` | `""` | string |
+| `target` | `""` | node path |
 | `anchor` | `[0,0,0]` | array |
 | `targetAnchor` | `[0,0,0]` | array |
 | `length` | `0` | number |
@@ -730,7 +731,7 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `sunDirection` | `[0.5,0.8,0.3]` | array |
 | `sunColor` | `"#fff6e0"` | string |
 | `sunIntensity` | `1` | number |
-| `terrain` | `""` | string |
+| `terrain` | `""` | node path |
 | `carve` | `true` | boolean |
 | `flowForce` | `1` | number |
 | `spray` | `1` | number |
@@ -909,7 +910,7 @@ Signals: `timeout`
 | `leafFadeEnd` | `0` | number |
 | `leafShadows` | `true` | boolean |
 | `drape` | `null` | null |
-| `terrain` | `""` | string |
+| `terrain` | `""` | node path |
 
 ## `UILayer` — `incanto/2d`
 
@@ -923,10 +924,13 @@ Signals: `timeout`
 |---|---|---|
 | `anchor` | `"center"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
 | `visible` | `true` | boolean |
+| `focusable` | `false` | boolean |
+| `draggable` | `false` | boolean |
+| `dropTarget` | `false` | boolean |
 | `size` | `42` | number |
 | `seconds` | `2` | number |
 
-Signals: `bannerShown`
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `bannerShown`
 
 ## `UiBar` — `incanto`
 
@@ -934,6 +938,9 @@ Signals: `bannerShown`
 |---|---|---|
 | `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
 | `visible` | `true` | boolean |
+| `focusable` | `false` | boolean |
+| `draggable` | `false` | boolean |
+| `dropTarget` | `false` | boolean |
 | `value` | `100` | number |
 | `max` | `100` | number |
 | `width` | `180` | number |
@@ -944,19 +951,24 @@ Signals: `bannerShown`
 | `background` | `"rgba(0,0,0,0.5)"` | string |
 | `label` | `""` | string |
 
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped`
+
 ## `UiButton` — `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 |
 | `text` | `"OK"` | string |
 | `size` | `16` | number |
 | `color` | `"#ffffff"` | string |
 | `background` | `"rgba(255,255,255,0.14)"` | string |
 | `disabled` | `false` | boolean |
 
-Signals: `pressed`
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `pressed`
 
 ## `UiDialogue` — `incanto`
 
@@ -964,10 +976,13 @@ Signals: `pressed`
 |---|---|---|
 | `anchor` | `"bottom"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
 | `visible` | `true` | boolean |
+| `focusable` | `false` | boolean |
+| `draggable` | `false` | boolean |
+| `dropTarget` | `false` | boolean |
 | `charsPerSecond` | `40` | number |
 | `width` | `520` | number |
 
-Signals: `lineShown` · `choiceMade` · `dialogueFinished`
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `lineShown` · `choiceMade` · `dialogueFinished`
 
 ## `UiImage` — `incanto`
 
@@ -975,6 +990,9 @@ Signals: `lineShown` · `choiceMade` · `dialogueFinished`
 |---|---|---|
 | `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
 | `visible` | `true` | boolean |
+| `focusable` | `false` | boolean |
+| `draggable` | `false` | boolean |
+| `dropTarget` | `false` | boolean |
 | `src` | `""` | string |
 | `width` | `48` | number |
 | `height` | `48` | number |
@@ -982,12 +1000,32 @@ Signals: `lineShown` · `choiceMade` · `dialogueFinished`
 | `tint` | `""` | string |
 | `opacity` | `1` | number |
 
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped`
+
+## `UiLanguageSelect` — `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` | `"Language"` | string |
+| `options` | `""` | string |
+| `value` | `""` | string |
+
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `changed`
+
 ## `UiPanel` — `incanto`
 
 | Prop | Default | Kind |
 |---|---|---|
 | `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
 | `visible` | `true` | boolean |
+| `focusable` | `false` | boolean |
+| `draggable` | `false` | boolean |
+| `dropTarget` | `false` | boolean |
 | `layout` | `"column"` | one of: `column` `row` `grid` |
 | `columns` | `4` | number |
 | `gap` | `8` | number |
@@ -998,17 +1036,22 @@ Signals: `lineShown` · `choiceMade` · `dialogueFinished`
 | `height` | `0` | number |
 | `border` | `""` | string |
 
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped`
+
 ## `UiSelect` — `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` | `""` | string |
 | `options` | `""` | string |
 | `value` | `""` | string |
 
-Signals: `changed`
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `changed`
 
 ## `UiSlider` — `incanto`
 
@@ -1016,6 +1059,9 @@ Signals: `changed`
 |---|---|---|
 | `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` | `""` | string |
 | `value` | `0.5` | number |
 | `min` | `0` | number |
@@ -1024,7 +1070,7 @@ Signals: `changed`
 | `width` | `180` | number |
 | `color` | `"#6ee7dc"` | string |
 
-Signals: `changed`
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `changed`
 
 ## `UiText` — `incanto`
 
@@ -1032,21 +1078,29 @@ Signals: `changed`
 |---|---|---|
 | `anchor` | `"topLeft"` | one of: `topLeft` `top` `topRight` `left` `center` `right` `bottomLeft` `bottom` `bottomRight` |
 | `visible` | `true` | boolean |
+| `focusable` | `false` | boolean |
+| `draggable` | `false` | boolean |
+| `dropTarget` | `false` | boolean |
 | `text` | `""` | string |
 | `size` | `16` | number |
 | `color` | `"#ffffff"` | string |
 | `shadow` | `true` | boolean |
 
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped`
+
 ## `UiToggle` — `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` | `""` | string |
 | `value` | `false` | boolean |
 
-Signals: `changed`
+Signals: `dragStarted` · `dragCancelled` · `droppedOn` · `dropped` · `changed`
 
 ## `VoxelGrid3D` — `incanto/3d`
 
@@ -1134,7 +1188,7 @@ wire their signals through scene `connections`. Full guide: `incanto-gameplay-be
 
 | Prop | Default | Kind |
 |---|---|---|
-| `water` | `""` | string |
+| `water` | `""` | node path |
 | `draft` | `0.35` | number |
 | `stiffness` | `3` | number |
 | `damping` | `3.5` | number |
@@ -1155,7 +1209,7 @@ Signals: `submerged` · `surfaced`
 
 | Prop | Default | Kind |
 |---|---|---|
-| `target` | `""` | string |
+| `target` | `""` | node path |
 | `speed` | `60` | number |
 | `stopRange` | `0` | number |
 | `loseRange` | `0` | number |
@@ -1209,7 +1263,7 @@ Signals: `dayPhaseChanged`
 
 | Prop | Default | Kind |
 |---|---|---|
-| `target` | `""` | string |
+| `target` | `""` | node path |
 | `offset` | `[]` | array |
 | `smoothing` | `0` | number |
 | `deadzone` | `0` | number |
@@ -1220,7 +1274,7 @@ Signals: `dayPhaseChanged`
 |---|---|---|
 | `restartAction` | `"restart"` | string |
 | `freezeOnEnd` | `true` | boolean |
-| `bannerPath` | `"%Banner"` | string |
+| `bannerPath` | `"%Banner"` | node path |
 
 Signals: `flowChanged`
 
@@ -1327,7 +1381,7 @@ Signals: `scoreChanged(score)` · `won` · `lost` · `lifeLost(lives)`
 
 | Prop | Default | Kind |
 |---|---|---|
-| `prefab` | `""` | string |
+| `prefab` | `""` | node path |
 | `interval` | `1` | number |
 | `max` | `0` | number |
 | `at` | `[]` | array |
@@ -1357,14 +1411,14 @@ Signals: `waveStarted(index)` · `waveCleared(index)` · `allCleared`
 
 | Prop | Default | Kind |
 |---|---|---|
-| `aggroTarget` | `""` | string |
+| `aggroTarget` | `""` | node path |
 | `aggroRange` | `12` | number |
 | `deAggroRange` | `0` | number |
 | `chaseSpeed` | `4` | number |
 | `wanderSpeed` | `1.4` | number |
 | `wanderRadius` | `8` | number |
 | `wanderChangeEvery` | `3` | number |
-| `goalTarget` | `""` | string |
+| `goalTarget` | `""` | node path |
 | `stopRange` | `1.2` | number |
 | `moveParent` | `false` | boolean |
 

package/skills/incanto-save-slots.md

@@ -0,0 +1,152 @@
+---
+name: incanto-save-slots
+description: Continue where you left off — Behavior serialize()/deserialize(), engine.captureState()/restoreState(), and a SaveSlots layer over the save store. A save carries behavior state keyed by node uid and reloads the scene from source; it does not snapshot the tree. Use for any game with progress worth keeping.
+---
+
+# Save slots
+
+Let a player close the tab and come back to their run.
+
+## What a save IS
+
+**Which scene, plus every behavior's state, keyed by node uid.**
+
+```json
+{
+  "scene": "village",
+  "state": { "n_player7x": { "current": 62 }, "n_score2k": { "score": 1400 } },
+  "label": "Chapter 2 · Emberwood",
+  "savedAt": 1754160000000,
+  "playtime": 812,
+  "data": { "difficulty": "hard" }
+}
+```
+
+Loading = **load the scene from its file**, then hand each behavior its state
+back by uid.
+
+## What a save is NOT, and why
+
+It is not a snapshot of the live tree. That is deliberate, and it is about this
+engine specifically:
+
+- `Spawner.onReady` **detaches** its prefab template from the tree. A captured
+  tree and a freshly booted one legitimately disagree about which nodes exist,
+  on every scene with a spawner.
+- A spawned enemy that carries its own spawner has already lost *its* template,
+  so re-adding that subtree runs `onReady` against a node that is gone and
+  throws — killing the whole load.
+- Prop deltas cannot be applied without resetting every other prop to default.
+
+Reloading from source sidesteps all three. The structure comes from the file
+(authoritative, already validated); the save carries only what the file cannot
+know.
+
+**The cost, stated plainly: spawned enemies and mid-level positions are not
+restored.** You resume at the scene's start with stats, inventory, unlocks and
+quest flags intact — a checkpoint save. If your game needs a position, save it:
+`serialize()` returns anything.
+
+## Making a behavior saveable
+
+Two optional hooks, exactly like the other five:
+
+```ts
+class QuestLog extends Behavior {
+  accepted = false;
+  wolvesKilled = 0;
+
+  override serialize() {
+    return { accepted: this.accepted, wolvesKilled: this.wolvesKilled };
+  }
+
+  override deserialize(data: JsonValue) {
+    const d = data as { accepted?: unknown; wolvesKilled?: unknown };
+    if (typeof d.accepted === 'boolean') this.accepted = d.accepted;
+    if (typeof d.wolvesKilled === 'number') this.wolvesKilled = d.wolvesKilled;
+  }
+}
+```
+
+**Save only what a fresh `onReady` could not recreate.** `current` health yes;
+`maxHealth` no — that comes back from the scene JSON, and duplicating it makes
+old saves fight your balance patches.
+
+`deserialize` is defensive on purpose: that data may come from a build of your
+game that shipped six weeks ago. Check what you read.
+
+Built-ins that already save: `Health` (current, dead), `ScoreKeeper` (score,
+lives, won/lost), `Collector` (total).
+
+## Every node you save needs a uid
+
+The uid is the join key, because it is the one identifier that survives a rename
+or a reparent. The editor assigns one to every node it touches. A hand-written
+scene may not have them — `engine.captureState()` logs any node that has state to
+save and no uid to key it under.
+
+Never hand-craft a uid. Use `newUid()`.
+
+## Saving and loading
+
+```ts
+import { SaveSlots } from 'incanto';
+
+const slots = new SaveSlots('emberwood');
+
+// save
+slots.write('1', {
+  scene: currentSceneKey,
+  state: game.engine.captureState(),
+  label: 'Chapter 2',
+  savedAt: Date.now(),
+  playtime: elapsed,
+});
+
+// load
+const slot = slots.read('1');
+if (slot) {
+  await loadSceneByKey(slot.scene);        // your routing — the engine does not route
+  const report = game.engine.restoreState(slot.state);
+  if (report.missing.length) console.warn('save is older than this build:', report.missing);
+}
+```
+
+`restoreState` runs AFTER the scene has loaded and `onReady` has fired —
+`onReady` is where a behavior sets its starting values, so restoring first would
+be overwritten.
+
+It never throws. A save naming a uid this build deleted reports it in
+`report.missing` and restores everything else; refusing to load would mean a
+patch that moves one node deletes everyone's progress.
+
+## A load menu
+
+```ts
+for (const slot of slots.all()) {         // newest first
+  render(slot.id, slot.label, new Date(slot.savedAt), slot.playtime);
+}
+slots.remove('2');
+slots.clear();                            // "delete all data"
+```
+
+## Checking your coverage
+
+```ts
+import { behaviorsWithoutSave } from 'incanto';
+console.log(behaviorsWithoutSave(game.engine.scene.root));
+```
+
+Names every behavior in the tree that has props and no `serialize`. Not all of
+them are wrong — a behavior that derives everything from time has nothing to
+save — but it is the list to read before shipping.
+
+## Autosave
+
+There is no autosave node, on purpose: *when* to save is a design decision
+(checkpoint, level end, every 60s, on quit) and only your game knows. Wire it to
+whatever signal marks the moment:
+
+```json
+{ "from": "Level/Exit", "signal": "triggerEnter", "to": "Game", "handler": "onCheckpoint" }
+```

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

package/templates-app/village-quest-3d/PROJECT/Context.md

@@ -37,3 +37,19 @@ again button.
 - Custom code is three behaviors: VillageDirector, GroveDirector, SwordStrike.
   Movement, camera, animation, NPC proximity, patrol walking, dialogue, HUD —
   all engine built-ins wired in scene JSON.
+
+
+## Localization (added with the 0.35 localization feature)
+
+The village HUD ships **English and Korean**, declared in one `strings` block in
+`village.scene.json` and picked with a `UiLanguageSelect` in the top-right
+corner. Switching is live — no reload, no second scene.
+
+One string is deliberately **not** translated: `ui.hint`
+(`WASD move · Shift sprint · E talk · click/F strike`). WASD, Shift, E and F are
+the letters printed on the keyboard, and a Korean gloss of them is both longer
+and less clear. It falls back to English in the Korean build, silently, which is
+the documented and intended behaviour — see `incanto-localization.md`.
+
+That is the example doing double duty: it shows the feature working AND shows
+the judgement call the feature exists to support.

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