incanto 0.56.0 → 0.58.0

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.58.0",
+    "three": "^0.184.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/three": "^0.184.1",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16"
+  }
+}