incanto 0.57.0 → 0.59.0

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

@@ -0,0 +1,60 @@
+# Status — platformer-2d (Incanto)
+
+## Implemented
+
+- Full-window single-canvas page with loading overlay, an on-screen JUMP button,
+  and the iframe GAME_SIZE harness.
+- `game.scene.json` — **Castle Run**: viewport (`design [960,540]`, `fit:
+  expand`), `physics.gravity [0,1800]`, `move` (A/D + arrows) / `jump`
+  (Space/W/Up) input, `knight`/`goblin` sheets + `coin`/`gem` textures, and the
+  level —
+  - `Game` root: `ScoreKeeper` (`scoreToWin 100000`, `lives 3`).
+  - Parallax castle backdrop (sky, sun, clouds, far castle band + towers, near
+    castle band + battlements) via `ParallaxLayer`.
+  - `GroundA–D` stone with green moss caps and gaps; `Plat1–4` floating
+    platforms; `MovePlat` (`Patrol` horizontal) + `Lift` (`Oscillate` vertical),
+    both group `platform` (rideable).
+  - `Spikes1/2` (`hazard`), `DeathPlane` (`pit`), `Checkpoint`, `Goal`.
+  - `Gob1–3` goblins (`Patrol` + `GoblinSkin`, group `enemy`).
+  - 12 coins + 2 gems (`Pickup` + bobbing `Oscillate` sprite).
+  - `Player` (`CharacterBody2D` + `PlayerController`) with `Skin` (knight) +
+    `Feet` sensor; `Camera` (`FollowCam`); SFX players; HUD + banner UILayers.
+- Custom code in `src/behaviors.ts`: `PlayerController` (coyote/buffer/double-
+  jump/variable height/stomp/knockback/hearts+lives/checkpoint respawn/platform
+  carry/anim), `GoblinSkin`, `FollowCam` (follow + shake), `ParallaxLayer`,
+  `HudUpdater`. Particle puffs on double-jump/stomp/land/checkpoint via
+  `Particles2D`.
+- `connections`: each coin/gem `collected → addScore` (+ SFX); root `won/lost →
+  SfxWin/SfxLose`.
+- `main.ts`: inject the four asset urls, `createGame2D`, optional music, JUMP
+  button, remove loader, expose `window.game`. Node uids omitted (loader-
+  generated).
+
+## Works (verified)
+
+- `bun run check` → 1/1 scene valid. `bun run typecheck` → clean. `bun run lint`
+  → clean.
+- `bun run verify` (headless `runScript`): 13/13 assertions pass — run right,
+  jump off the ground and settle, a coin raises the score (Pickup → addScore), a
+  STOMP removes a goblin and scores, a side hit costs a heart, dying respawns the
+  knight at the checkpoint, the goal emits `won` once, and a pit fall with the
+  last life emits `lost`.
+- Played in a real browser (`bun run dev`, Playwright-driven): the knight + the
+  goblins render as their real animated sheets; coins/gems render as sprites;
+  ground has moss caps; the parallax castle bands scroll; HUD shows ◆ coins,
+  ♥♥♥ hearts and lives. A tap jump is a short hop (~41px), a held jump is full
+  (~156px), and a mid-air press double-jumps — variable height + double-jump
+  confirmed. FollowCam tracks + clamps to the level bounds. ZERO console errors.
+
+## Not Included (on purpose — and the next polish passes)
+
+- Background castle is styled `ColorRect2D` (no tilemap node in v0): two parallax
+  layers (`CastleFarLayer` 0.82 / `CastleNearLayer` 0.6), each a Node2D with ONE
+  `ParallaxLayer` whose children (wall band + towers + crenellation merlons + warm
+  glowing windows + a gate + a pennant) inherit the scroll. Reads clearly as a
+  castle skyline; swap for tile/sprite art later.
+- No wall-jump/dash, no enemy variety beyond the goblin, no melee (the knight
+  has an attack sheet 12–17 if you want it), no bundled music (SFX presets only).
+- One hand-authored level — extend by copying nodes into the right GROUP
+  (`enemy`/`hazard`/`pit`/`checkpoint`/`platform`); `PlayerController` picks them
+  up with no extra wiring.

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

@@ -0,0 +1,77 @@
+# Structure — platformer-2d (Incanto)
+
+## `index.html`
+
+Full-window page: inline favicon, loading overlay (removed once the game boots),
+one `#game` canvas, an on-screen `#btn-jump` button (mobile parity), the
+iframe-embed GAME_SIZE script, and the module entry.
+
+## `src/game.scene.json`
+
+THE whole level (open it with `npx incanto-editor`):
+
+- scene header — `environment.background`, `viewport` (`design [960,540]`, `fit:
+  expand`), `physics.gravity [0,1800]`, `move`/`jump` input, and the
+  `knight`/`goblin` spritesheets + `coin`/`gem` texture `assets` (urls injected
+  in `main.ts`).
+- `Game` root — `ScoreKeeper` (`scoreToWin 100000`, `lives 3`).
+- Parallax castle backdrop — `Sky`/`Sun`/`Cloud1–3` (far), `CastleFar` band +
+  `TowerFarA–C`, `CastleNear` band + `BattlementA/B` — `ColorRect2D` +
+  `ParallaxLayer` (factor 0.6–0.96, higher = farther).
+- `GroundA–D` — `StaticBody2D` stone (brown body + green `Moss` cap) with GAPS
+  (pits) between them.
+- `Plat1–4` — static floating platforms; `MovePlat` (`Patrol` pingpong, group
+  `platform`) ferries the first pit; `Lift` (`Oscillate` vertical, group
+  `platform`) crosses the spike pit.
+- `Spikes1/2` (group `hazard`) and `DeathPlane` (group `pit`, far below).
+- `Checkpoint` (group `checkpoint`, blue flag) and `Goal` (group `goal`, gold
+  flag + gate).
+- `Gob1–3` — Node2D (group `enemy`) + `Patrol`; children `Skin`
+  (`AnimatedSprite2D` goblin) + `AI` (`GoblinSkin`).
+- `Coins/Coin1–12` — Area2D `Pickup` (value 10) with a bobbing `coin` sprite
+  child; `Gem1/2` — Area2D `Pickup` (value 50) with a bobbing `gem` sprite.
+- `Player` — `CharacterBody2D` (group `player`, capsule) + `PlayerController`;
+  children `Skin` (`AnimatedSprite2D` knight idle/run/jump) + `Feet` (Area2D
+  sensor for moving-platform carry).
+- `Camera` — `Camera2D` (`current`) + `FollowCam` (look-ahead, clamped `limits`,
+  screen-shake).
+- `SfxJump/Coin/Stomp/Hurt/Checkpoint/Win/Lose` — `AudioPlayer` SFX presets
+  (PlayerController plays jump/stomp/hurt/checkpoint directly; coins/win/lose via
+  `connections`).
+- `HUD` — UILayer (top-left, `HudUpdater`): Coin / Hearts / Lives / Hint Labels.
+  `BannerLayer` — UILayer (center) win/lose `Banner`.
+- `connections` — each coin/gem `collected → ScoreKeeper.addScore` (+ SFX); root
+  `won/lost → SfxWin/SfxLose`. (Stomp/hit/checkpoint/respawn/win-trigger are
+  resolved by `PlayerController`, not connections.)
+
+## `src/behaviors.ts`
+
+- `PlayerController` — the heart: run/gravity/coyote/buffer/double-jump/variable
+  height, stomp + bounce, side-hit knockback, hearts+lives, checkpoint respawn,
+  moving-platform carry (via the `Feet` sensor), sprite clip + facing + i-frame
+  blink. All enemy/hazard/pit/checkpoint/goal contact is AABB against groups in
+  `resolveContacts()`.
+- `GoblinSkin` — face the patrol heading + play the goblin walk clip.
+- `FollowCam` — follow (look-ahead + smoothing + world clamp) + `shake()`.
+- `ParallaxLayer` — re-anchor a backdrop to `cameraX · factor` for depth.
+- `HudUpdater` — score/hearts/lives Labels + win/lose banner.
+
+## `src/main.ts`
+
+Boot: inject the four built-in asset urls, `createGame2D({ canvas, scene,
+behaviors })`, optional `engine.music`, the JUMP button, remove the loader,
+expose `window.game`.
+
+## `verify.ts`
+
+Browserless proof via `incanto/test` `runScript`: run+jump (off the ground and
+back), coin scoring, STOMP (goblin removed + scored), side-hit costs a heart,
+checkpoint respawn (die → back at the flag), WIN (goal → `won`), LOSE (pit with
+the last life → `lost`). Run with `bun run verify`.
+
+## `docs/project-2d-rules.md`
+
+The vibe-coding rules: read the skills, JSON structure, built-ins first, omit
+uids, declared assets, y-down space, collider props, GROUP-DRIVEN centralised
+damage (§8), deferred engine access (§11), debug draw, delta discipline, verify
+like a user.

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

@@ -0,0 +1,61 @@
+<userRequest>
+YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template
+(Castle Run — a 2D adventure platformer):
+
+1. 📖 READ THE SKILLS FIRST: `node_modules/incanto/skills/` is the engine
+   manual, version-pinned to what is installed. Start with
+   `incanto-building-2d-games.md` and `incanto-scene-json-authoring.md`, then
+   `incanto-gameplay-behaviors.md` (Pickup/Patrol/Oscillate/ScoreKeeper) and
+   `incanto-physics-and-input.md` (2D bodies, the input map, units).
+2. 🧱 STRUCTURE IS JSON: scenes, nodes, props, assets, input maps and
+   connections all live in `src/game.scene.json`. Add level geometry there (or
+   with `npx incanto-editor`), NOT by constructing nodes ad-hoc in code.
+3. 🧠 LOGIC IS BEHAVIORS: prefer a BUILT-IN behavior over custom code (Pickup
+   coins/gems, Patrol goblins + the moving platform, Oscillate the lift +
+   bobbing pickups, ScoreKeeper score/lives/win-lose, AudioPlayer SFX — all
+   wired in JSON). Custom code = small TypeScript Behavior classes registered via
+   `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`,
+   `HudUpdater`.
+4. 🔑 UIDS ARE GENERATED: omit `uid` and the loader assigns one (via the engine's
+   `newUid`). NEVER hand-invent readable uid strings.
+5. 📦 ASSETS ARE DECLARED: `assets` entries need `type` + `url`; reference them as
+   `"$key"`. The knight + goblin sheets and the coin + gem textures are BUILT-INS
+   (`incanto/assets/...`) imported in `main.ts` and injected into the asset url
+   placeholders before boot. Free extra key-values are preserved — use them for
+   notes (frame ranges, license, source).
+6. ⬇️ Y IS DOWN: 2D space is y-down pixels, (0,0) top-left, clockwise degrees.
+   Positive gravity falls (`physics.gravity` is `[0, 1800]`). Up is NEGATIVE
+   velocity; a jump subtracts y.
+7. 🧲 COLLIDERS ARE PROPS: `"collider": { "shape": "rect"|"circle"|"capsule", … }`
+   on a body node — never child shape nodes. Wrong shapes hard-fail at load.
+7b. 🦶 STAND THE FEET ON THE GROUND: a sprite-sheet `anchor` is the artist's pivot
+   (hip/centre), NOT the feet, and the frame has transparent padding below the art —
+   so a character will FLOAT unless you align it. MEASURE the feet (bottom opaque row
+   ÷ frame height) and set `anchor.y` so the visible feet sit at the collider bottom
+   (here the knight is `0.464`, goblins `0.348`, not the sheet's ~0.61). See
+   `incanto-building-2d-games.md` → AnimatedSprite2D "stand the feet on the ground".
+8. 🎯 DAMAGE IS CENTRALISED + GROUP-DRIVEN: the player takes NO built-in Health —
+   `PlayerController` owns hearts/lives and resolves ALL contact by AABB against
+   GROUPS each frame, so there's one authority and never a stomp-vs-damage
+   double-trigger. Tag content with groups: `enemy` (stompable from above, hurts
+   on the side), `hazard` (spikes → lose a heart), `pit` (death plane → instant
+   life loss), `checkpoint` (sets respawn), `goal` (win), `platform` (a moving
+   body the Feet sensor rides). Add an enemy/hazard = add the node in the right
+   group; no wiring needed.
+9. 🐛 DEBUG WHEN UNSURE: `createGame2D({ debug: true })` (or `VITE_INCANTO_DEBUG=1`)
+   shows the Explorer/Inspector/Stats; `physics.debugDraw = true` draws colliders.
+10. 🎬 DELTA DISCIPLINE: only write props that differ from defaults — the loader
+    treats unknown/garbage props as hard errors, which is your friend.
+11. 🧭 ENGINE ACCESS IS DEFERRED: `this.engine` is NOT available in `onReady`
+    during `loadScene` (the scene isn't attached yet) — read scene config
+    (gravity, etc.) lazily on the first `fixedUpdate`. `getNode`/signals are fine
+    in `onReady`.
+12. ✅ VERIFY LIKE A USER: `bun run check` (scene valid) → `bun run verify`
+    (headless run/jump/coin/stomp/checkpoint/win/lose proof) → `bun run dev`,
+    open the browser, and actually PLAY what you changed (run, double-jump, stomp
+    a goblin, ride the lift, die and respawn at the flag) before declaring done.
+</userRequest>

package/templates-app/platformer-2d/index.html

@@ -0,0 +1,99 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><rect width=%22100%22 height=%22100%22 rx=%2220%22 fill=%22%236ee7dc%22/><text x=%2250%22 y=%2268%22 font-size=%2255%22 text-anchor=%22middle%22 font-family=%22Arial%22 font-weight=%22bold%22 fill=%22%230b0d14%22>in</text></svg>" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+    <title>Castle Run — Incanto platformer</title>
+    <style>
+      html,
+      body {
+        margin: 0;
+        padding: 0;
+        height: 100%;
+        overflow: hidden;
+        font-family: Arial, sans-serif;
+        background: #6aa9cf;
+      }
+      canvas {
+        display: block;
+        width: 100%;
+        height: 100%;
+      }
+      .loading-container {
+        position: fixed;
+        inset: 0;
+        z-index: 50;
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        background: #6aa9cf;
+        color: white;
+      }
+      .loading-title {
+        font-size: 1.5rem;
+        font-weight: bold;
+        margin-bottom: 1rem;
+      }
+      .spinner {
+        width: 30px;
+        height: 30px;
+        border: 3px solid rgba(255, 255, 255, 0.3);
+        border-radius: 50%;
+        border-top-color: white;
+        animation: spin 1s ease-in-out infinite;
+      }
+      @keyframes spin {
+        to {
+          transform: rotate(360deg);
+        }
+      }
+      .round-btn {
+        position: fixed;
+        bottom: 2rem;
+        right: 2rem;
+        z-index: 1001;
+        width: 88px;
+        height: 88px;
+        border: none;
+        border-radius: 9999px;
+        background: rgba(255, 209, 102, 0.45);
+        color: #1d2a44;
+        font-weight: bold;
+        font-size: 0.9rem;
+        cursor: pointer;
+        user-select: none;
+        -webkit-user-select: none;
+        touch-action: none;
+        transition: transform 0.1s;
+      }
+      .round-btn:active {
+        transform: scale(0.9);
+      }
+    </style>
+  </head>
+  <body>
+    <div class="loading-container" id="loading">
+      <h2 class="loading-title">Castle Run</h2>
+      <div class="spinner"></div>
+    </div>
+    <canvas id="game"></canvas>
+    <button type="button" id="btn-jump" class="round-btn">JUMP</button>
+    <script>
+      // agent8 embed harness: report the game size to a hosting iframe parent.
+      function postGameSize() {
+        window.parent.postMessage(
+          { type: 'GAME_SIZE_RESPONSE', width: document.body.scrollWidth, height: document.body.scrollHeight },
+          '*',
+        );
+      }
+      window.addEventListener('load', postGameSize);
+      window.addEventListener('resize', postGameSize);
+      window.addEventListener('message', (e) => {
+        if (e.data && e.data.type === 'REQUEST_GAME_SIZE') postGameSize();
+      });
+    </script>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

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

@@ -0,0 +1,23 @@
+{
+  "name": "platformer-2d",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "typecheck": "tsc --noEmit",
+    "check": "incanto-check src",
+    "verify": "bun verify.ts"
+  },
+  "dependencies": {
+    "@dimforge/rapier2d-compat": "0.19.3",
+    "incanto": "^0.59.0",
+    "three": "^0.184.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/three": "^0.184.1",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16"
+  }
+}