incanto 0.74.0 → 0.75.0

package/templates-app/beacon-isle-3d/src/game.scene.json

@@ -34,7 +34,9 @@
     "jump": { "type": "button", "keys": ["Space"], "touch": "button" },
     "sprint": { "type": "button", "keys": ["ShiftLeft", "ShiftRight"] },
     "interact": { "type": "button", "keys": ["KeyE"], "touch": "button" },
-    "attack": { "type": "button", "keys": ["Mouse0", "KeyF"], "touch": "button" }
+    "attack": { "type": "button", "keys": ["Mouse0", "KeyF"], "touch": "button" },
+    "pause": { "type": "button", "keys": ["Escape"] },
+    "restart": { "type": "button", "keys": ["KeyR"] }
   },
   "assets": {
     "characters/base": {
@@ -2756,6 +2758,110 @@
               "anchor": "bottomRight",
               "shadow": true
             }
+          },
+          {
+            "name": "PauseMenu",
+            "type": "UiPanel",
+            "uid": "n_36ox1wee9cdz2cgj",
+            "props": {
+              "anchor": "center",
+              "layout": "column",
+              "gap": 12,
+              "padding": 22,
+              "visible": false,
+              "background": "rgba(10,14,22,0.92)",
+              "radius": 12
+            },
+            "children": [
+              {
+                "name": "PausedTitle",
+                "type": "UiText",
+                "uid": "n_kdecsevdetjk0q1i",
+                "props": { "text": "PAUSED", "size": 26 }
+              },
+              {
+                "name": "Resume",
+                "type": "UiButton",
+                "uid": "n_vaxmkxrqot30vd7u",
+                "props": { "text": "RESUME", "size": 18 }
+              },
+              {
+                "name": "PauseOptions",
+                "type": "UiButton",
+                "uid": "n_3nt1ztixpsvjtb86",
+                "props": { "text": "OPTIONS", "size": 16 }
+              },
+              {
+                "name": "Save",
+                "type": "UiButton",
+                "uid": "n_enx1clunsomchjx2",
+                "props": { "text": "SAVE", "size": 16 }
+              },
+              {
+                "name": "Continue",
+                "type": "UiButton",
+                "uid": "n_3hpo1n3ho12l7po2",
+                "props": { "text": "CONTINUE", "size": 16 }
+              },
+              {
+                "name": "Restart",
+                "type": "UiButton",
+                "uid": "n_0ytaknljuqmthwpl",
+                "props": { "text": "START OVER", "size": 16 }
+              }
+            ]
+          },
+          {
+            "name": "Options",
+            "type": "UiPanel",
+            "uid": "n_drf0bze03zae5h4l",
+            "props": {
+              "anchor": "center",
+              "layout": "column",
+              "gap": 10,
+              "padding": 22,
+              "visible": false,
+              "background": "rgba(10,14,22,0.92)",
+              "radius": 12
+            },
+            "children": [
+              {
+                "name": "OptionsTitle",
+                "type": "UiText",
+                "uid": "n_wn6vz16vfsnz4guj",
+                "props": { "text": "OPTIONS", "size": 24 }
+              },
+              {
+                "name": "Master",
+                "type": "UiVolumeSlider",
+                "uid": "n_aguq7s3aeapln07y",
+                "props": { "label": "master", "bus": "master", "width": 260 }
+              },
+              {
+                "name": "Sfx",
+                "type": "UiVolumeSlider",
+                "uid": "n_yyaguhkmv9z4u9a8",
+                "props": { "label": "effects", "bus": "sfx", "width": 260 }
+              },
+              {
+                "name": "Mute",
+                "type": "UiMuteToggle",
+                "uid": "n_3yj77bemd2sjm4yi",
+                "props": { "label": "mute everything" }
+              },
+              {
+                "name": "Quality",
+                "type": "UiQualitySelect",
+                "uid": "n_e3ehj0ln9p28ib59",
+                "props": { "label": "quality" }
+              },
+              {
+                "name": "Back",
+                "type": "UiButton",
+                "uid": "n_y95ob0mpwrvvhr78",
+                "props": { "text": "BACK", "size": 16 }
+              }
+            ]
           }
         ],
         "uid": "n_0q1r3a6rijr3hc1w"
@@ -2895,12 +3001,55 @@
             }
           }
         ]
+      },
+      {
+        "name": "Flow",
+        "type": "Node",
+        "uid": "n_ibf6agaxzcxjhcmg",
+        "script": { "name": "GameFlow", "props": { "saveSlots": "beacon-isle" } }
       }
     ],
     "uid": "n_nxftk1ep8wbi1bn9"
   },
   "connections": [
     { "signal": "interacted", "from": "Keeper", "to": "/root", "handler": "onTalk" },
-    { "signal": "died", "from": "Player", "to": "/root", "handler": "onPlayerDown" }
+    { "signal": "died", "from": "Player", "to": "/root", "handler": "onPlayerDown" },
+    {
+      "from": "/root/HUD/PauseMenu/Resume",
+      "signal": "pressed",
+      "to": "/root/Flow",
+      "handler": "resume"
+    },
+    {
+      "from": "/root/HUD/PauseMenu/PauseOptions",
+      "signal": "pressed",
+      "to": "/root/Flow",
+      "handler": "screen",
+      "args": ["/root/HUD/Options"]
+    },
+    {
+      "from": "/root/HUD/PauseMenu/Restart",
+      "signal": "pressed",
+      "to": "/root/Flow",
+      "handler": "restart"
+    },
+    {
+      "from": "/root/HUD/Options/Back",
+      "signal": "pressed",
+      "to": "/root/Flow",
+      "handler": "back"
+    },
+    {
+      "from": "/root/HUD/PauseMenu/Save",
+      "signal": "pressed",
+      "to": "/root/Flow",
+      "handler": "save"
+    },
+    {
+      "from": "/root/HUD/PauseMenu/Continue",
+      "signal": "pressed",
+      "to": "/root/Flow",
+      "handler": "continueFrom"
+    }
   ]
 }

package/templates-app/molehill-2d/PROJECT/Status.md

@@ -25,3 +25,10 @@
   `tags` entry on the node and a branch in `onMoleClicked`.
 - Turn the field into a GRID of clickable cells and you have a match-3, a
   minesweeper or a tower-defense build menu; the input path is identical.
+
+## Pausing
+
+ESC pauses and shows the pause menu; OPTIONS opens the settings over it and
+BACK returns to the menu that asked. All of it is `GameFlow` (`pausePanelPath`,
+`screen(path)`, `back()`) wired with `connections` — there is no TypeScript for
+any screen in this game.

package/templates-app/molehill-2d/package.json

@@ -11,7 +11,7 @@
   },
   "dependencies": {
     "@dimforge/rapier2d-compat": "0.19.3",
-    "incanto": "^0.74.0",
+    "incanto": "^0.75.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/molehill-2d/src/game.scene.json

@@ -1175,8 +1175,106 @@
             "type": "UiButton",
             "uid": "n_u20dbq90sumk4806",
             "props": { "anchor": "bottom", "text": "PLAY AGAIN", "visible": false }
+          },
+          {
+            "name": "PauseMenu",
+            "type": "UiPanel",
+            "uid": "n_z9nyxykbc17ausrw",
+            "props": {
+              "anchor": "center",
+              "layout": "column",
+              "gap": 12,
+              "padding": 22,
+              "visible": false,
+              "background": "rgba(10,14,22,0.92)",
+              "radius": 12
+            },
+            "children": [
+              {
+                "name": "PausedTitle",
+                "type": "UiText",
+                "uid": "n_f7eckdwb24bwqpo8",
+                "props": { "text": "PAUSED", "size": 26 }
+              },
+              {
+                "name": "Resume",
+                "type": "UiButton",
+                "uid": "n_oz53g65a66krulb0",
+                "props": { "text": "RESUME", "size": 18 }
+              },
+              {
+                "name": "PauseOptions",
+                "type": "UiButton",
+                "uid": "n_cn8ix0y56khi3i90",
+                "props": { "text": "OPTIONS", "size": 16 }
+              },
+              {
+                "name": "Restart",
+                "type": "UiButton",
+                "uid": "n_cy1svsikf8hhtz3m",
+                "props": { "text": "START OVER", "size": 16 }
+              }
+            ]
+          },
+          {
+            "name": "Options",
+            "type": "UiPanel",
+            "uid": "n_2t2waf1lsux76rw9",
+            "props": {
+              "anchor": "center",
+              "layout": "column",
+              "gap": 10,
+              "padding": 22,
+              "visible": false,
+              "background": "rgba(10,14,22,0.92)",
+              "radius": 12
+            },
+            "children": [
+              {
+                "name": "OptionsTitle",
+                "type": "UiText",
+                "uid": "n_rp0oo781nder7a6m",
+                "props": { "text": "OPTIONS", "size": 24 }
+              },
+              {
+                "name": "Master",
+                "type": "UiVolumeSlider",
+                "uid": "n_8sufldfevj26zdb2",
+                "props": { "label": "master", "bus": "master", "width": 260 }
+              },
+              {
+                "name": "Sfx",
+                "type": "UiVolumeSlider",
+                "uid": "n_ahyngscv3eatp9mi",
+                "props": { "label": "effects", "bus": "sfx", "width": 260 }
+              },
+              {
+                "name": "Mute",
+                "type": "UiMuteToggle",
+                "uid": "n_478neek47ba9eaa4",
+                "props": { "label": "mute everything" }
+              },
+              {
+                "name": "Quality",
+                "type": "UiQualitySelect",
+                "uid": "n_f35z57tq3jsxrdz1",
+                "props": { "label": "quality" }
+              },
+              {
+                "name": "Back",
+                "type": "UiButton",
+                "uid": "n_m5d8dwpml28xj9jz",
+                "props": { "text": "BACK", "size": 16 }
+              }
+            ]
           }
         ]
+      },
+      {
+        "name": "Flow",
+        "type": "Node",
+        "uid": "n_08m0apva5yx370w6",
+        "script": { "name": "GameFlow" }
       }
     ]
   },
@@ -1200,6 +1298,35 @@
     { "signal": "lost", "from": ".", "to": "Hud", "handler": "onLost" },
     { "signal": "won", "from": ".", "to": "Field", "handler": "stop" },
     { "signal": "lost", "from": ".", "to": "Field", "handler": "stop" },
-    { "signal": "pressed", "from": "Hud/Again", "to": "Hud", "handler": "onAgain" }
-  ]
+    { "signal": "pressed", "from": "Hud/Again", "to": "Hud", "handler": "onAgain" },
+    {
+      "from": "/root/Hud/PauseMenu/Resume",
+      "signal": "pressed",
+      "to": "/root/Flow",
+      "handler": "resume"
+    },
+    {
+      "from": "/root/Hud/PauseMenu/PauseOptions",
+      "signal": "pressed",
+      "to": "/root/Flow",
+      "handler": "screen",
+      "args": ["/root/Hud/Options"]
+    },
+    {
+      "from": "/root/Hud/PauseMenu/Restart",
+      "signal": "pressed",
+      "to": "/root/Flow",
+      "handler": "restart"
+    },
+    {
+      "from": "/root/Hud/Options/Back",
+      "signal": "pressed",
+      "to": "/root/Flow",
+      "handler": "back"
+    }
+  ],
+  "input": {
+    "pause": { "type": "button", "keys": ["Escape"] },
+    "restart": { "type": "button", "keys": ["KeyR"] }
+  }
 }

package/templates-app/platformer-2d/PROJECT/Status.md

@@ -65,3 +65,10 @@ A course past GroundD (x 3000+): `Trampoline` (`restitution 1`) with a dead `Bou
 (`friction 0`) with a `Sled` at 260 px/s, and a `Hound` (`CharacterBody2D` + `Chase`
 `ground: true`) under a `Perch`. `verify.ts` measures the rebound (287 of 300 px), the slide
 (400 px of ice) and that the hound stays on the floor under a perched player.
+
+## Pausing
+
+ESC pauses and shows the pause menu; OPTIONS opens the settings over it and
+BACK returns to the menu that asked. All of it is `GameFlow` (`pausePanelPath`,
+`screen(path)`, `back()`) wired with `connections` — there is no TypeScript for
+any screen in this game.

package/templates-app/platformer-2d/docs/project-2d-rules.md

@@ -17,8 +17,9 @@ YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template
    `createGame2D({ behaviors })` and attached with `"script": { "name": "Name" }`.
    This game's custom behaviors are the platformer GAME FEEL the library leaves
    open: `PlayerController` (coyote-time, jump-buffer, double-jump, variable jump
-   height, stomp, knockback, hearts+lives, checkpoint respawn, moving-platform
-   carry), `GoblinSkin`, `FollowCam` (follow + screen-shake), `ParallaxLayer`,
+   height, stomp, checkpoint respawn, moving-platform carry — hearts, i-frames,
+   the knockback and the control lock are the Player's `Vitals` **Health**, which
+   the controller reads: `staggered`, `kickVelocity`, `takeLift()`), `GoblinSkin`, `FollowCam` (follow + screen-shake), `ParallaxLayer`,
    `HudUpdater`.
 4. 🔑 UIDS ARE GENERATED: omit `uid` and the loader assigns one (via the engine's
    `newUid`). NEVER hand-invent readable uid strings.

package/templates-app/platformer-2d/package.json

@@ -11,7 +11,7 @@
   },
   "dependencies": {
     "@dimforge/rapier2d-compat": "0.19.3",
-    "incanto": "^0.74.0",
+    "incanto": "^0.75.0",
     "three": "^0.184.0"
   },
   "devDependencies": {

package/templates-app/platformer-2d/src/behaviors.ts

@@ -23,6 +23,7 @@ import type { Node, UiBanner, UiText } from 'incanto';
 import { Behavior } from 'incanto';
 import type { AnimatedSprite2D, Camera2D, CharacterBody2D, Node2D } from 'incanto/2d';
 import { Particles2D } from 'incanto/2d';
+import type { Health } from 'incanto/gameplay';
 
 // ---- tuning (px, y-down; scene gravity is [0, 1800]) --------------------------
 const RUN_SPEED = 250;
@@ -35,12 +36,9 @@ const BUFFER = 0.12; // press jump slightly early and it still fires on landing
 const JUMP_CUT = 0.45; // release jump while rising → cut the climb (variable height)
 const MAX_JUMPS = 2; // ground jump + one air (double) jump
 const STOMP_BOUNCE = 560; // upward pop after squashing a goblin
-const KNOCK_X = 300;
-const KNOCK_UP = 360;
-const CONTROL_LOCK = 0.22; // seconds the player can't steer after a knockback
-const INVULN = 1.1; // i-frames after a hit
+// hearts, i-frames, the knockback and the control lock after a hit are the
+// Player's `Vitals` Health (game.scene.json) — this controller reads them
 const RESPAWN_INVULN = 1.4;
-const MAX_HEARTS = 3;
 const PLAYER_HW = 18;
 const PLAYER_HH = 33;
 const ENEMY_HW = 26;
@@ -71,14 +69,15 @@ interface Audio {
 }
 
 export class PlayerController extends Behavior {
-  hearts = MAX_HEARTS;
+  /** Hearts = the Vitals' hit points; the HUD reads this. */
+  get hearts(): number {
+    return this.health.current;
+  }
 
   private gravity = 1800;
   private coyote = 0;
   private buffer = 0;
   private jumps = 0;
-  private invuln = 0;
-  private lock = 0;
   private wasGrounded = true;
   private respawn: [number, number] = [0, 0];
   private platform: Node2D | null = null;
@@ -89,6 +88,9 @@ export class PlayerController extends Behavior {
   private get body(): CharacterBody2D {
     return this.node as unknown as CharacterBody2D;
   }
+  private get health(): Health {
+    return this.getNode('Vitals').behavior as unknown as Health;
+  }
   private get skin(): AnimatedSprite2D {
     return this.getNode('Skin') as unknown as AnimatedSprite2D;
   }
@@ -108,6 +110,9 @@ export class PlayerController extends Behavior {
     this.getNode('/root').on('lost', () => {
       this.over = true;
     });
+    // a death is the Vitals' signal, whoever dealt it — a hit, a pit, or a
+    // probe calling `kill()` — so every route spends a life the same way
+    this.getNode('Vitals').on('died', () => this.die());
     // moving-platform CARRY: a Feet sensor remembers the platform we stand on so we
     // ride its motion (the kinematic controller doesn't inherit platform velocity).
     const feet = this.getNode('Feet');
@@ -137,15 +142,19 @@ export class PlayerController extends Behavior {
 
     this.coyote = Math.max(0, this.coyote - dt);
     this.buffer = Math.max(0, this.buffer - dt);
-    this.invuln = Math.max(0, this.invuln - dt);
-    this.lock = Math.max(0, this.lock - dt);
 
     const grounded = body.isOnFloor();
     const dir = this.input.getVector('move');
     let vx = body.velocity[0] ?? 0;
     let vy = body.velocity[1] ?? 0;
 
-    if (this.lock <= 0) vx = dir.x * RUN_SPEED;
+    // a hit's stagger takes the stick, and its kick IS the velocity while it
+    // lasts: this controller drives the body, so it reads the Health's kick
+    // (`applyKnockback: false` in the scene) instead of Health moving the body
+    const health = this.health;
+    if (!health.staggered) vx = dir.x * RUN_SPEED;
+    const kick = health.kickVelocity;
+    if (kick.length > 0) vx = kick[0] ?? vx;
 
     if (grounded) {
       this.jumps = 0;
@@ -177,6 +186,13 @@ export class PlayerController extends Behavior {
     }
     if (this.input.justReleased('jump') && vy < 0) vy *= JUMP_CUT;
 
+    // the hit's hop: the kick's vertical part comes out ONCE, then gravity owns it
+    const lift = health.takeLift();
+    if (lift !== 0) {
+      vy = lift;
+      this.platform = null;
+    }
+
     body.velocity = [vx, vy];
 
     // ride a moving platform: add its per-frame delta before resolving collisions
@@ -224,12 +240,12 @@ export class PlayerController extends Behavior {
         body.velocity = [body.velocity[0] ?? 0, vy];
         this.jumps = 1; // a stomp refreshes the air jump — chain bounces
         this.shake(8);
-      } else if (this.invuln <= 0) {
-        this.takeHit(px < ex ? -1 : 1);
+      } else if (this.health.invulnerableRemaining <= 0) {
+        this.takeHit([ex, ey]);
       }
     }
 
-    if (this.invuln <= 0) {
+    if (this.health.invulnerableRemaining <= 0) {
       for (const h of tree.getNodesInGroup('hazard')) {
         const hn = h as unknown as Node2D;
         const size = ((hn as unknown as { collider?: { size?: number[] } }).collider?.size ?? [
@@ -247,7 +263,7 @@ export class PlayerController extends Behavior {
             (size[1] ?? 40) / 2,
           )
         ) {
-          this.takeHit(this.facing * -1);
+          this.takeHit([px + this.facing * 10, py]); // a hazard hits from the front
           break;
         }
       }
@@ -270,7 +286,7 @@ export class PlayerController extends Behavior {
           (size[1] ?? 80) / 2,
         )
       ) {
-        this.die();
+        this.health.kill(); // → `died` → `die()`
         return;
       }
     }
@@ -300,23 +316,20 @@ export class PlayerController extends Behavior {
     }
   }
 
-  private takeHit(dirX: number): void {
-    this.hearts -= 1;
-    this.invuln = INVULN;
-    this.lock = CONTROL_LOCK;
-    this.body.velocity = [dirX * KNOCK_X, -KNOCK_UP];
+  /** Hurt from a world point: the Vitals take the heart, the i-frames, the kick and the stagger. */
+  private takeHit(from: [number, number]): void {
+    const health = this.health;
+    health.damage(1, from); // the killing blow reaches `die()` through `died`
     this.sfx('SfxHurt');
     this.shake(10);
-    if (this.hearts <= 0) this.die();
   }
 
   private die(): void {
     const sk = this.scoreKeeper;
     sk.loseLife();
     if (sk.lives > 0) {
-      this.hearts = MAX_HEARTS;
-      this.invuln = RESPAWN_INVULN;
-      this.lock = 0;
+      this.health.revive();
+      this.health.protect(RESPAWN_INVULN);
       this.platform = null;
       this.body.velocity = [0, 0];
       this.body.position = [this.respawn[0], this.respawn[1]];
@@ -381,7 +394,8 @@ export class PlayerController extends Behavior {
     this.playOnce(skin, clip);
 
     // blink while invulnerable
-    skin.opacity = this.invuln > 0 && Math.floor(this.invuln * 14) % 2 === 0 ? 0.35 : 1;
+    const inv = this.health.invulnerableRemaining;
+    skin.opacity = inv > 0 && Math.floor(inv * 14) % 2 === 0 ? 0.35 : 1;
   }
 
   private lastClip = '';