incanto 0.34.0 → 0.35.0

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

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

@@ -3,6 +3,19 @@
   "type": "scene",
   "dimension": "3d",
   "name": "EmberwoodVillage",
+  "strings": {
+    "en": {
+      "quest.talkElder": "Talk to the Elder [E]",
+      "ui.playAgain": "Play again",
+      "ui.hint": "WASD move · Shift sprint · E talk · click/F strike",
+      "settings.language": "Language"
+    },
+    "ko": {
+      "quest.talkElder": "촌장에게 말을 걸어보세요 [E]",
+      "ui.playAgain": "다시 하기",
+      "settings.language": "언어"
+    }
+  },
   "environment": {
     "sky": {
       "type": "atmosphere",
@@ -3435,7 +3448,7 @@
             "type": "UiText",
             "uid": "n_vq_quest",
             "props": {
-              "text": "Talk to the Elder [E]",
+              "text": "@t:quest.talkElder",
               "size": 16,
               "anchor": "topLeft",
               "shadow": true
@@ -3463,7 +3476,7 @@
             "type": "UiButton",
             "uid": "n_vq_restart",
             "props": {
-              "text": "Play again",
+              "text": "@t:ui.playAgain",
               "anchor": "bottom",
               "visible": false
             }
@@ -3473,12 +3486,21 @@
             "type": "UiText",
             "uid": "n_vq_hint",
             "props": {
-              "text": "WASD move · Shift sprint · E talk · click/F strike",
+              "text": "@t:ui.hint",
               "size": 12,
               "color": "#cccccc",
               "anchor": "bottomRight",
               "shadow": true
             }
+          },
+          {
+            "name": "Language",
+            "type": "UiLanguageSelect",
+            "uid": "n_4m6tsfl0og3ekii3",
+            "props": {
+              "label": "@t:settings.language",
+              "anchor": "topRight"
+            }
           }
         ]
       }