incanto 0.77.0 → 0.78.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/README.md +9 -4
  2. package/dist/index.js +1 -1
  3. package/dist/{src-DygJfhOb.js → src-SWXe-bub.js} +1 -1
  4. package/dist/vite.js +1 -1
  5. package/package.json +1 -1
  6. package/skills/incanto-building-2d-games.md +6 -0
  7. package/skills/incanto-building-3d-games.md +6 -0
  8. package/skills/incanto-editor.md +2 -2
  9. package/skills/incanto-multiplayer.md +1 -1
  10. package/skills/incanto-save-slots.md +1 -1
  11. package/skills/incanto-scene-json-authoring.md +1 -1
  12. package/skills/incanto-verifying-your-game.md +2 -2
  13. package/skills/incanto-web-integration.md +40 -2
  14. package/skills/incanto-your-first-game.md +6 -1
  15. package/templates-app/beacon-isle-3d/PROJECT/Structure.md +2 -1
  16. package/templates-app/beacon-isle-3d/index.html +5 -2
  17. package/templates-app/beacon-isle-3d/package.json +6 -1
  18. package/templates-app/beacon-isle-3d/src/App.tsx +77 -0
  19. package/templates-app/beacon-isle-3d/src/main.tsx +9 -0
  20. package/templates-app/beacon-isle-3d/tsconfig.json +2 -1
  21. package/templates-app/beacon-isle-3d/vite.config.ts +4 -1
  22. package/templates-app/molehill-2d/PROJECT/Structure.md +2 -1
  23. package/templates-app/molehill-2d/index.html +5 -2
  24. package/templates-app/molehill-2d/package.json +6 -1
  25. package/templates-app/molehill-2d/src/App.tsx +58 -0
  26. package/templates-app/molehill-2d/src/main.tsx +9 -0
  27. package/templates-app/molehill-2d/tsconfig.json +2 -1
  28. package/templates-app/molehill-2d/vite.config.ts +4 -1
  29. package/templates-app/platformer-2d/PROJECT/Context.md +1 -1
  30. package/templates-app/platformer-2d/PROJECT/Requirements.md +2 -2
  31. package/templates-app/platformer-2d/PROJECT/Status.md +1 -1
  32. package/templates-app/platformer-2d/PROJECT/Structure.md +2 -2
  33. package/templates-app/platformer-2d/docs/project-2d-rules.md +1 -1
  34. package/templates-app/platformer-2d/index.html +5 -2
  35. package/templates-app/platformer-2d/package.json +6 -1
  36. package/templates-app/platformer-2d/src/App.tsx +115 -0
  37. package/templates-app/platformer-2d/src/main.tsx +9 -0
  38. package/templates-app/platformer-2d/tsconfig.json +2 -1
  39. package/templates-app/platformer-2d/vite.config.ts +4 -1
  40. package/templates-app/star-survivor/PROJECT/Context.md +1 -1
  41. package/templates-app/star-survivor/PROJECT/Requirements.md +1 -1
  42. package/templates-app/star-survivor/PROJECT/Status.md +1 -1
  43. package/templates-app/star-survivor/PROJECT/Structure.md +2 -2
  44. package/templates-app/star-survivor/docs/project-2d-rules.md +1 -1
  45. package/templates-app/star-survivor/index.html +5 -2
  46. package/templates-app/star-survivor/package.json +6 -1
  47. package/templates-app/star-survivor/src/App.tsx +94 -0
  48. package/templates-app/star-survivor/src/main.tsx +9 -0
  49. package/templates-app/star-survivor/tsconfig.json +2 -1
  50. package/templates-app/star-survivor/vite.config.ts +4 -1
  51. package/templates-app/tps-3d/PROJECT/Status.md +1 -1
  52. package/templates-app/tps-3d/PROJECT/Structure.md +2 -2
  53. package/templates-app/tps-3d/index.html +5 -2
  54. package/templates-app/tps-3d/package.json +6 -1
  55. package/templates-app/tps-3d/src/App.tsx +124 -0
  56. package/templates-app/tps-3d/src/main.tsx +9 -0
  57. package/templates-app/tps-3d/tsconfig.json +2 -1
  58. package/templates-app/tps-3d/vite.config.ts +4 -1
  59. package/templates-app/village-quest-3d/PROJECT/Structure.md +3 -2
  60. package/templates-app/village-quest-3d/index.html +5 -2
  61. package/templates-app/village-quest-3d/package.json +6 -1
  62. package/templates-app/village-quest-3d/src/App.tsx +79 -0
  63. package/templates-app/village-quest-3d/src/main.tsx +9 -0
  64. package/templates-app/village-quest-3d/tsconfig.json +2 -1
  65. package/templates-app/village-quest-3d/vite.config.ts +4 -1
  66. package/templates-app/beacon-isle-3d/src/main.ts +0 -60
  67. package/templates-app/molehill-2d/src/main.ts +0 -41
  68. package/templates-app/platformer-2d/src/main.ts +0 -97
  69. package/templates-app/star-survivor/src/main.ts +0 -77
  70. package/templates-app/tps-3d/src/main.ts +0 -107
  71. package/templates-app/village-quest-3d/src/main.ts +0 -62
package/templates-app/platformer-2d/index.html CHANGED
@@ -49,6 +49,9 @@
49
49
  transform: rotate(360deg);
50
50
  }
51
51
  }
52
+ #root {
53
+ display: contents;
54
+ }
52
55
  </style>
53
56
  </head>
54
57
  <body>
@@ -56,7 +59,7 @@
56
59
  <h2 class="loading-title">Castle Run</h2>
57
60
  <div class="spinner"></div>
58
61
  </div>
59
- <canvas id="game"></canvas>
62
+ <div id="root"></div>
60
63
  <script>
61
64
  // agent8 embed harness: report the game size to a hosting iframe parent.
62
65
  function postGameSize() {
@@ -71,6 +74,6 @@
71
74
  if (e.data && e.data.type === 'REQUEST_GAME_SIZE') postGameSize();
72
75
  });
73
76
  </script>
74
- <script type="module" src="/src/main.ts"></script>
77
+ <script type="module" src="/src/main.tsx"></script>
75
78
  </body>
76
79
  </html>
package/templates-app/platformer-2d/package.json CHANGED
@@ -11,12 +11,17 @@
11
11
  },
12
12
  "dependencies": {
13
13
  "@dimforge/rapier2d-compat": "0.19.3",
14
- "incanto": "^0.77.0",
14
+ "incanto": "^0.78.1",
15
+ "react": "^18.3.1",
16
+ "react-dom": "^18.3.1",
15
17
  "three": "^0.184.0"
16
18
  },
17
19
  "devDependencies": {
18
20
  "@types/node": "^24.0.0",
21
+ "@types/react": "^18.3.12",
22
+ "@types/react-dom": "^18.3.1",
19
23
  "@types/three": "^0.184.1",
24
+ "@vitejs/plugin-react": "^6.0.3",
20
25
  "typescript": "^6.0.3",
21
26
  "vite": "^8.0.16"
22
27
  }
package/templates-app/platformer-2d/src/App.tsx ADDED
@@ -0,0 +1,115 @@
1
+ /**
2
+ * Castle Run — a polished 2D adventure PLATFORMER on Incanto. Run a medieval
3
+ * knight through a castle: A/D (or arrows) to run, Space/W to jump — tap again in
4
+ * the air to DOUBLE-JUMP, and the controller forgives you with coyote-time +
5
+ * jump-buffering. STOMP goblins from above (and chain-bounce), ride the moving
6
+ * platform and the lift, grab coins + gems, dodge the spikes and the pit, touch
7
+ * the Checkpoint flag so a fall sends you back there, and reach the gold flag to
8
+ * clear the castle. Three hearts per life, three lives.
9
+ *
10
+ * The level is JSON: StaticBody2D platforms, Patrol/Oscillate moving platforms +
11
+ * goblins, Pickup coins/gems, ScoreKeeper score/lives/win-lose, AudioPlayer SFX —
12
+ * all wired in `game.scene.json`. The custom TypeScript is the game FEEL the
13
+ * built-ins leave open: PlayerController (coyote/buffer/double-jump/variable
14
+ * height/stomp/knockback/checkpoint-respawn/platform-carry), GoblinSkin,
15
+ * FollowCam (follow + screen-shake), ParallaxLayer, HudUpdater.
16
+ */
17
+ import { createGame2D, showBootFailure } from 'incanto/2d';
18
+ import goblinUrl from 'incanto/assets/characters/goblin.png';
19
+ import knightUrl from 'incanto/assets/characters/medieval-knight.png';
20
+ import coinUrl from 'incanto/assets/items/coin.png';
21
+ import gemUrl from 'incanto/assets/items/gem.png';
22
+ import { useEffect, useRef } from 'react';
23
+ import { FollowCam, GoblinSkin, HudUpdater, ParallaxLayer, PlayerController } from './behaviors';
24
+ import sceneJson from './game.scene.json';
25
+
26
+ export function App() {
27
+ const canvasRef = useRef<HTMLCanvasElement>(null);
28
+
29
+ useEffect(() => {
30
+ const canvas = canvasRef.current;
31
+ // StrictMode runs this effect twice against the SAME canvas element, and a
32
+ // second engine on one canvas is two renderers fighting for one context.
33
+ // The flag lives on the element, so it lasts exactly as long as the thing
34
+ // it guards — a page-level game like this one never unmounts otherwise.
35
+ if (!canvas || (canvas as { _incanto?: true })._incanto) return;
36
+ (canvas as { _incanto?: true })._incanto = true;
37
+
38
+ void (async () => {
39
+ // Built-in sprite art ships in the package — import the URLs and inject them into
40
+ // the scene's asset placeholders before boot (the engine clones the scene).
41
+
42
+ // OPTIONAL looping music (large tracks aren't bundled). Point at any URL to loop.
43
+ const MUSIC_URL = '';
44
+
45
+ const behaviors = { PlayerController, GoblinSkin, FollowCam, ParallaxLayer, HudUpdater };
46
+
47
+ const scene = structuredClone(sceneJson) as typeof sceneJson & {
48
+ assets: {
49
+ knight: { url: string };
50
+ goblin: { url: string };
51
+ coin: { url: string };
52
+ gem: { url: string };
53
+ };
54
+ };
55
+ scene.assets.knight.url = knightUrl;
56
+ scene.assets.goblin.url = goblinUrl;
57
+ scene.assets.coin.url = coinUrl;
58
+ scene.assets.gem.url = gemUrl;
59
+
60
+ /** Dev-only surfaces: the ☰ debug overlay, and the editor behind it. */
61
+ const DEBUG = import.meta.env.VITE_INCANTO_DEBUG === '1';
62
+
63
+ const game = await createGame2D({
64
+ debug: DEBUG,
65
+ // The editor's 📚 buttons, served by `incantoLibrary()` in vite.config.ts.
66
+ // BOTH halves are the opt-in, and this half was missing from every shipped
67
+ // template: the plugin alone left a vite config whose own comment promised
68
+ // "the agent8 asset catalog behind the 📚 buttons" and no button anywhere.
69
+ // Gated on the same flag, because `editor` DEFAULTS to `debug` and an object
70
+ // here would turn the editor on in a production build.
71
+ editor: DEBUG && { library: true },
72
+ canvas,
73
+ scene,
74
+ behaviors,
75
+ }).catch((e) => {
76
+ // Without this the player watches the loading overlay sit at 100% forever:
77
+ // `#loading` is removed on the line below, so anything that rejects here (no
78
+ // WebGL context, a scene that will not load) leaves the bar up and the reason
79
+ // in a console nobody opens.
80
+ showBootFailure(e);
81
+ throw e;
82
+ });
83
+
84
+ // The console handle FIRST, before any wiring of your own can throw.
85
+ // `game.stats()`, `game.assetErrors()`, `game.frame()` and `game.engine.log`
86
+ // are the entire in-page diagnostic surface, and a static build has no other.
87
+ // Assigned after the wiring, one mistake below took all of them with it.
88
+ (window as unknown as { game: typeof game }).game = game;
89
+
90
+ // And the loading overlay comes down LAST. Everything between here and there is
91
+ // your code; a throw in it used to leave a level that renders perfectly with no
92
+ // player, no error UI, and no way to ask the page what happened.
93
+ try {
94
+ if (MUSIC_URL) {
95
+ game.engine.music.play(MUSIC_URL, { loop: true, fadeIn: 1.5 });
96
+ game.engine.audio.music = 0.3;
97
+ }
98
+
99
+ // No hand-rolled touch button here: the scene declares `"touch": "button"` on
100
+ // `jump` and `"touch": "joystick"` on `move`, so the ENGINE draws both on a
101
+ // coarse pointer — safe-area aware, off the home-indicator band, and sized to
102
+ // its own rules. This template used to draw an 88 px disc of its own at a flat
103
+ // `bottom: 2rem`, which covered 78% of the engine's jump button and put its
104
+ // lower edge inside the band iOS reserves for the leave-the-app swipe.
105
+ } catch (e) {
106
+ showBootFailure(e);
107
+ throw e;
108
+ }
109
+
110
+ document.querySelector('#loading')?.remove();
111
+ })();
112
+ }, []);
113
+
114
+ return <canvas ref={canvasRef} id="game" />;
115
+ }
package/templates-app/platformer-2d/src/main.tsx ADDED
@@ -0,0 +1,9 @@
1
+ import { StrictMode } from 'react';
2
+ import { createRoot } from 'react-dom/client';
3
+ import { App } from './App';
4
+
5
+ createRoot(document.getElementById('root') as HTMLElement).render(
6
+ <StrictMode>
7
+ <App />
8
+ </StrictMode>,
9
+ );
package/templates-app/platformer-2d/tsconfig.json CHANGED
@@ -7,7 +7,8 @@
7
7
  "noEmit": true,
8
8
  "skipLibCheck": true,
9
9
  "resolveJsonModule": true,
10
- "types": ["vite/client", "node"]
10
+ "types": ["vite/client", "node"],
11
+ "jsx": "react-jsx"
11
12
  },
12
13
  "include": ["src", "verify.ts", "vite.config.ts"]
13
14
  }
package/templates-app/platformer-2d/vite.config.ts CHANGED
@@ -1,12 +1,15 @@
1
+ import react from '@vitejs/plugin-react';
1
2
  import { incantoLibrary, incantoScenes } from 'incanto/vite';
2
3
  import { defineConfig } from 'vite';
3
4
 
4
5
  export default defineConfig({
5
6
  base: './',
7
+ // react(): the app entry is React — src/main.tsx mounts <App />, and App.tsx
8
+ // owns the canvas the engine draws into.
6
9
  // Dev-server only, and both are why the editor is useful here:
7
10
  // - incantoScenes(): validates every *.scene.json the moment you save it,
8
11
  // AND serves this project's scenes, so the editor (☰ debug ▸ edit this
9
12
  // scene ▸ scenes) can open, create and save any scene in the project.
10
13
  // - incantoLibrary(): the agent8 asset catalog behind the 📚 buttons.
11
- plugins: [incantoScenes(), incantoLibrary()],
14
+ plugins: [react(), incantoScenes(), incantoLibrary()],
12
15
  });
package/templates-app/star-survivor/PROJECT/Context.md CHANGED
@@ -21,7 +21,7 @@ _Exact versions are in `package.json`._
21
21
  AnimatedSprite2D, ColorRect2D, Camera2D, AudioPlayer) + `incanto/gameplay`
22
22
  (auto-registered Spawner, Chase, Health, DamageOnContact, ScoreKeeper, …).
23
23
  - **Art**: built-in animated sheets `medieval-knight` (player), `goblin` + `ghost`
24
- (enemies), bundler-imported in `main.ts` and injected into the scene asset urls.
24
+ (enemies), bundler-imported in `App.tsx` and injected into the scene asset urls.
25
25
  Arena/bolts/XP shards are `ColorRect2D`.
26
26
  - **Audio**: procedural SFX presets (shoot/coin/hurt/win/lose). HUD is DOM.
27
27
  - **Build/Lang**: Vite, TypeScript. **Headless verify**: `incanto/test` (`runScript`).
package/templates-app/star-survivor/PROJECT/Requirements.md CHANGED
@@ -42,6 +42,6 @@
42
42
  - The clone path is internal, so spawning leans on built-in `Spawner` + `Director`
43
43
  scatter; bolts/XP are managed `ColorRect2D`s (no per-projectile behavior).
44
44
  - Sprites: `medieval-knight`/`goblin` (192px frames), `ghost` (112×128). Swap a sheet
45
- by changing only its asset entry + the import in `main.ts`.
45
+ by changing only its asset entry + the import in `App.tsx`.
46
46
  - Difficulty ramps with elapsed time (spawn rate + enemy HP/speed); tune in `Director`
47
47
  and the `Survivor` constants. Music is OPTIONAL (`MUSIC_URL` empty; SFX need no files).
package/templates-app/star-survivor/PROJECT/Status.md CHANGED
@@ -14,7 +14,7 @@
14
14
  - Custom `src/behaviors.ts`: `Survivor` (move + auto-attack managed bolts + XP magnet
15
15
  + level-up/upgrades + pause via `engine.stop/start` + DOM HUD), `Director`
16
16
  (ring-scatter spawns + time escalation), `EnemyDrop`, `EnemyFace`.
17
- - `main.ts` injects the three sheet urls; `vite.config.ts` aliases `incanto/assets`.
17
+ - `App.tsx` injects the three sheet urls; `vite.config.ts` aliases `incanto/assets`.
18
18
 
19
19
  ## Works (verified)
20
20
 
package/templates-app/star-survivor/PROJECT/Structure.md CHANGED
@@ -14,7 +14,7 @@ The arena + horde, mostly BUILT-INS:
14
14
 
15
15
  - header — `background`, `viewport` (`design [960,540]`, `fit: expand`),
16
16
  `physics.gravity [0,0]` (top-down), `move` input (WASD+arrows), and the
17
- `knight`/`goblin`/`ghost` spritesheet `assets` (urls injected in `main.ts`).
17
+ `knight`/`goblin`/`ghost` spritesheet `assets` (urls injected in `App.tsx`).
18
18
  - `Game` root — `ScoreKeeper` (`scoreToWin 1`, `lives 1`).
19
19
  - `Arena`/`ArenaPad`/`ArenaRing*` — dark `ColorRect2D` floor + a centre marker.
20
20
  - `Player` — `CharacterBody2D` (group `player`) + `Survivor`; children `Skin`
@@ -42,7 +42,7 @@ The arena + horde, mostly BUILT-INS:
42
42
  group `xp` with an `_xp` value) + `Survivor.addKill()`.
43
43
  - `EnemyFace` — flip the enemy sprite toward travel + play `move`.
44
44
 
45
- ## `src/main.ts`
45
+ ## `src/main.tsx` and `src/App.tsx`
46
46
 
47
47
  Inject the knight/goblin/ghost urls, `createGame2D({ canvas, scene, behaviors })`,
48
48
  optional music, remove the loader, expose `window.game`.
package/templates-app/star-survivor/docs/project-2d-rules.md CHANGED
@@ -17,7 +17,7 @@ YOU MUST follow these rules EXACTLY when vibe-coding on this Incanto template
17
17
  escalation), `EnemyDrop` (XP shard + kill on death), `EnemyFace` (sprite facing).
18
18
  4. 🔑 UIDS ARE GENERATED: omit `uid` and the loader assigns one. Never hand-invent.
19
19
  5. 📦 ASSETS ARE DECLARED: `assets` entries need `type` + `url`; reference as `"$key"`.
20
- The knight/goblin/ghost sheets are BUILT-INS imported in `main.ts` and injected
20
+ The knight/goblin/ghost sheets are BUILT-INS imported in `App.tsx` and injected
21
21
  into the asset url placeholders before boot. ⚠️ For `incanto/assets/*` imports to
22
22
  resolve in `bun run dev`, `vite.config.ts` needs an `'incanto/assets'` ALIAS to
23
23
  `../../packages/engine/assets` (see this template's config).
package/templates-app/star-survivor/index.html CHANGED
@@ -190,6 +190,9 @@
190
190
  text-shadow: 0 2px 14px rgba(0, 0, 0, 0.9);
191
191
  transition: opacity 0.3s;
192
192
  }
193
+ #root {
194
+ display: contents;
195
+ }
193
196
  </style>
194
197
  </head>
195
198
  <body>
@@ -197,7 +200,7 @@
197
200
  <h2 class="loading-title">Hollow Horde</h2>
198
201
  <div class="spinner"></div>
199
202
  </div>
200
- <canvas id="game"></canvas>
203
+ <div id="root"></div>
201
204
  <div id="hud">
202
205
  <div class="bar-track" id="hp-track"><div class="bar-fill" id="hp-fill"></div></div>
203
206
  <div id="hp-text">100</div>
@@ -227,6 +230,6 @@
227
230
  if (e.data && e.data.type === 'REQUEST_GAME_SIZE') postGameSize();
228
231
  });
229
232
  </script>
230
- <script type="module" src="/src/main.ts"></script>
233
+ <script type="module" src="/src/main.tsx"></script>
231
234
  </body>
232
235
  </html>
package/templates-app/star-survivor/package.json CHANGED
@@ -11,12 +11,17 @@
11
11
  },
12
12
  "dependencies": {
13
13
  "@dimforge/rapier2d-compat": "0.19.3",
14
- "incanto": "^0.77.0",
14
+ "incanto": "^0.78.1",
15
+ "react": "^18.3.1",
16
+ "react-dom": "^18.3.1",
15
17
  "three": "^0.184.0"
16
18
  },
17
19
  "devDependencies": {
18
20
  "@types/node": "^24.0.0",
21
+ "@types/react": "^18.3.12",
22
+ "@types/react-dom": "^18.3.1",
19
23
  "@types/three": "^0.184.1",
24
+ "@vitejs/plugin-react": "^6.0.3",
20
25
  "typescript": "^6.0.3",
21
26
  "vite": "^8.0.16"
22
27
  }
package/templates-app/star-survivor/src/App.tsx ADDED
@@ -0,0 +1,94 @@
1
+ /**
2
+ * Hollow Horde — a top-down SURVIVORS-LIKE (Vampire Survivors genre) on Incanto.
3
+ * Move with WASD / arrows; your knight AUTO-ATTACKS the nearest enemy. Goblins and
4
+ * faster ghosts pour in from every side and grow tougher over time. Cut them down,
5
+ * vacuum up the XP shards they drop, and on each LEVEL-UP pick one of three
6
+ * upgrades. Survive 90 seconds to win — let the horde drain your HP and you fall.
7
+ *
8
+ * The horde is BUILT-IN gameplay wired in `game.scene.json`: two `Spawner`s clone
9
+ * goblin/ghost templates, each enemy `Chase`s the player, and a `DamageOnContact`
10
+ * hitbox drains `Health`. The custom TypeScript is the survivor FEEL the library
11
+ * leaves open: `Survivor` (move + auto-attack + XP/level-up/upgrades + HUD),
12
+ * `Director` (ring-spawn around the player + escalation), `EnemyDrop`, `EnemyFace`.
13
+ */
14
+ import { createGame2D, showBootFailure } from 'incanto/2d';
15
+ import ghostUrl from 'incanto/assets/characters/ghost.png';
16
+ import goblinUrl from 'incanto/assets/characters/goblin.png';
17
+ import knightUrl from 'incanto/assets/characters/medieval-knight.png';
18
+ import { useEffect, useRef } from 'react';
19
+ import { Director, EnemyDrop, EnemyFace, GridFloor, Survivor } from './behaviors';
20
+ import sceneJson from './game.scene.json';
21
+
22
+ export function App() {
23
+ const canvasRef = useRef<HTMLCanvasElement>(null);
24
+
25
+ useEffect(() => {
26
+ const canvas = canvasRef.current;
27
+ // StrictMode runs this effect twice against the SAME canvas element, and a
28
+ // second engine on one canvas is two renderers fighting for one context.
29
+ // The flag lives on the element, so it lasts exactly as long as the thing
30
+ // it guards — a page-level game like this one never unmounts otherwise.
31
+ if (!canvas || (canvas as { _incanto?: true })._incanto) return;
32
+ (canvas as { _incanto?: true })._incanto = true;
33
+
34
+ void (async () => {
35
+ const MUSIC_URL = '';
36
+
37
+ const behaviors = { Survivor, Director, EnemyDrop, EnemyFace, GridFloor };
38
+
39
+ const scene = structuredClone(sceneJson) as typeof sceneJson & {
40
+ assets: { knight: { url: string }; goblin: { url: string }; ghost: { url: string } };
41
+ };
42
+ scene.assets.knight.url = knightUrl;
43
+ scene.assets.goblin.url = goblinUrl;
44
+ scene.assets.ghost.url = ghostUrl;
45
+
46
+ /** Dev-only surfaces: the ☰ debug overlay, and the editor behind it. */
47
+ const DEBUG = import.meta.env.VITE_INCANTO_DEBUG === '1';
48
+
49
+ const game = await createGame2D({
50
+ debug: DEBUG,
51
+ // The editor's 📚 buttons, served by `incantoLibrary()` in vite.config.ts.
52
+ // BOTH halves are the opt-in, and this half was missing from every shipped
53
+ // template: the plugin alone left a vite config whose own comment promised
54
+ // "the agent8 asset catalog behind the 📚 buttons" and no button anywhere.
55
+ // Gated on the same flag, because `editor` DEFAULTS to `debug` and an object
56
+ // here would turn the editor on in a production build.
57
+ editor: DEBUG && { library: true },
58
+ canvas,
59
+ scene,
60
+ behaviors,
61
+ }).catch((e) => {
62
+ // Without this the player watches the loading overlay sit at 100% forever:
63
+ // `#loading` is removed on the line below, so anything that rejects here (no
64
+ // WebGL context, a scene that will not load) leaves the bar up and the reason
65
+ // in a console nobody opens.
66
+ showBootFailure(e);
67
+ throw e;
68
+ });
69
+
70
+ // The console handle FIRST, before any wiring of your own can throw.
71
+ // `game.stats()`, `game.assetErrors()`, `game.frame()` and `game.engine.log`
72
+ // are the entire in-page diagnostic surface, and a static build has no other.
73
+ // Assigned after the wiring, one mistake below took all of them with it.
74
+ (window as unknown as { game: typeof game }).game = game;
75
+
76
+ // And the loading overlay comes down LAST. Everything between here and there is
77
+ // your code; a throw in it used to leave a level that renders perfectly with no
78
+ // player, no error UI, and no way to ask the page what happened.
79
+ try {
80
+ if (MUSIC_URL) {
81
+ game.engine.music.play(MUSIC_URL, { loop: true, fadeIn: 1.5 });
82
+ game.engine.audio.music = 0.3;
83
+ }
84
+ } catch (e) {
85
+ showBootFailure(e);
86
+ throw e;
87
+ }
88
+
89
+ document.querySelector('#loading')?.remove();
90
+ })();
91
+ }, []);
92
+
93
+ return <canvas ref={canvasRef} id="game" />;
94
+ }
package/templates-app/star-survivor/src/main.tsx ADDED
@@ -0,0 +1,9 @@
1
+ import { StrictMode } from 'react';
2
+ import { createRoot } from 'react-dom/client';
3
+ import { App } from './App';
4
+
5
+ createRoot(document.getElementById('root') as HTMLElement).render(
6
+ <StrictMode>
7
+ <App />
8
+ </StrictMode>,
9
+ );
package/templates-app/star-survivor/tsconfig.json CHANGED
@@ -7,7 +7,8 @@
7
7
  "noEmit": true,
8
8
  "skipLibCheck": true,
9
9
  "resolveJsonModule": true,
10
- "types": ["vite/client", "node"]
10
+ "types": ["vite/client", "node"],
11
+ "jsx": "react-jsx"
11
12
  },
12
13
  "include": ["src", "verify.ts", "vite.config.ts"]
13
14
  }
package/templates-app/star-survivor/vite.config.ts CHANGED
@@ -1,12 +1,15 @@
1
+ import react from '@vitejs/plugin-react';
1
2
  import { incantoLibrary, incantoScenes } from 'incanto/vite';
2
3
  import { defineConfig } from 'vite';
3
4
 
4
5
  export default defineConfig({
5
6
  base: './',
7
+ // react(): the app entry is React — src/main.tsx mounts <App />, and App.tsx
8
+ // owns the canvas the engine draws into.
6
9
  // Dev-server only, and both are why the editor is useful here:
7
10
  // - incantoScenes(): validates every *.scene.json the moment you save it,
8
11
  // AND serves this project's scenes, so the editor (☰ debug ▸ edit this
9
12
  // scene ▸ scenes) can open, create and save any scene in the project.
10
13
  // - incantoLibrary(): the agent8 asset catalog behind the 📚 buttons.
11
- plugins: [incantoScenes(), incantoLibrary()],
14
+ plugins: [react(), incantoScenes(), incantoLibrary()],
12
15
  });
package/templates-app/tps-3d/PROJECT/Status.md CHANGED
@@ -24,7 +24,7 @@
24
24
  - `src/behaviors.ts`: `Shoot` (18-round clip, hitscan within a ~9° crosshair cone
25
25
  to 70 m, tracer + muzzle flash, face-aim on fire, reload) and `HudUpdater`
26
26
  (HP/Kills/Wave/Ammo + health bar + SECURE/FAILED banner).
27
- - `src/main.ts`: preloads the GLB + animation assets with a progress bar
27
+ - `src/App.tsx`: preloads the GLB + animation assets with a progress bar
28
28
  (`preloadUrls(assetUrls(scene.assets))`), then `createGame3D` with
29
29
  `pointer: true`, looping music, on-screen FIRE/JUMP buttons, `window.game`.
30
30
  - `index.html`: canvas + center crosshair + HUD overlay + banner + mobile buttons.
package/templates-app/tps-3d/PROJECT/Structure.md CHANGED
@@ -31,7 +31,7 @@ owns the ammo clip/reload, and `faceAim()`s the soldier to the shot direction.
31
31
  `HudUpdater` — reads ScoreKeeper/Health/Shoot/wave each frame into the HTML HUD
32
32
  and flips the banner (guarded so headless runs are a no-op).
33
33
 
34
- ## `src/main.ts`
34
+ ## `src/main.tsx` and `src/App.tsx`
35
35
 
36
36
  Boot: `createGame3D({ scene, behaviors: { Shoot, HudUpdater }, pointer: true })`,
37
37
  loop the bundled music, wire the on-screen buttons, expose `window.game`.
@@ -47,7 +47,7 @@ Chase closing in, the autopilot aiming + firing the hitscan to clear all waves
47
47
 
48
48
  `src/cover.scene.json` and `src/pillar.scene.json` are the two cover blocks and
49
49
  two pillars of the arena, placed from `game.scene.json` with `instance:` and a
50
- `position` override each — the first 3D prefabs in the repo. `main.ts` hands
50
+ `position` override each — the first 3D prefabs in the repo. `App.tsx` hands
51
51
  the loader every `*.scene.json` beside it through vite's `import.meta.glob`;
52
52
  `verify.ts` imports the two by name (bun has no glob). Every CLI resolves a
53
53
  prefab relative to the scene on its own; the harness and the game are the two
package/templates-app/tps-3d/index.html CHANGED
@@ -200,6 +200,9 @@
200
200
  margin-top: 0.5rem;
201
201
  font-size: 0.9rem;
202
202
  }
203
+ #root {
204
+ display: contents;
205
+ }
203
206
  </style>
204
207
  </head>
205
208
  <body>
@@ -208,7 +211,7 @@
208
211
  <div class="progress-track"><div class="progress-fill" id="progress"></div></div>
209
212
  <div class="progress-text" id="progress-text">0%</div>
210
213
  </div>
211
- <canvas id="game"></canvas>
214
+ <div id="root"></div>
212
215
  <div id="hud">
213
216
  <div id="hud-wave">Wave 1 / 3</div>
214
217
  <div id="hud-hp">HP 100</div>
@@ -241,6 +244,6 @@
241
244
  if (e.data && e.data.type === 'REQUEST_GAME_SIZE') postGameSize();
242
245
  });
243
246
  </script>
244
- <script type="module" src="/src/main.ts"></script>
247
+ <script type="module" src="/src/main.tsx"></script>
245
248
  </body>
246
249
  </html>
package/templates-app/tps-3d/package.json CHANGED
@@ -13,12 +13,17 @@
13
13
  "@dimforge/rapier2d-compat": "0.19.3",
14
14
  "@dimforge/rapier3d-compat": "0.19.3",
15
15
  "@pixiv/three-vrm": "^3.5.3",
16
- "incanto": "^0.77.0",
16
+ "incanto": "^0.78.1",
17
+ "react": "^18.3.1",
18
+ "react-dom": "^18.3.1",
17
19
  "three": "^0.184.0"
18
20
  },
19
21
  "devDependencies": {
20
22
  "@types/node": "^24.0.0",
23
+ "@types/react": "^18.3.12",
24
+ "@types/react-dom": "^18.3.1",
21
25
  "@types/three": "^0.184.1",
26
+ "@vitejs/plugin-react": "^6.0.3",
22
27
  "typescript": "^6.0.3",
23
28
  "vite": "^8.0.16"
24
29
  }
package/templates-app/tps-3d/src/App.tsx ADDED
@@ -0,0 +1,124 @@
1
+ /**
2
+ * Vanguard — a 3D THIRD-PERSON shooter built on Incanto. Move with WASD, look
3
+ * with the mouse (click locks the pointer), Shift to sprint, Space to jump,
4
+ * left-click / F to fire your hitscan rifle, R to reload, Enter to restart once
5
+ * the mission ends. The camera rides over
6
+ * your soldier's shoulder (CharacterController3D `view: 'free'`); the crosshair
7
+ * is where you shoot. Clear three waves of chasing enemies to SECURE THE AREA;
8
+ * let them drain your HP to 0 and the MISSION FAILS.
9
+ *
10
+ * The whole loop is composed from built-in gameplay behaviors wired in
11
+ * `game.scene.json` (third-person movement+camera, enemy AI via Chase, contact
12
+ * damage, WaveSpawner, Health, ScoreKeeper). The only custom TypeScript is
13
+ * `Shoot` (the click-to-fire hitscan + face-aim) and `HudUpdater` (the HUD +
14
+ * win/lose banner).
15
+ */
16
+ import type { SceneJson } from 'incanto';
17
+ import { assetUrls, preloadUrls } from 'incanto';
18
+ import { createGame3D, showBootFailure } from 'incanto/3d';
19
+ import musicUrl from 'incanto/assets/audio/spells_cast.mp3';
20
+ import { useEffect, useRef } from 'react';
21
+ import { HudUpdater, Shoot } from './behaviors';
22
+ import sceneJson from './game.scene.json';
23
+
24
+ export function App() {
25
+ const canvasRef = useRef<HTMLCanvasElement>(null);
26
+
27
+ useEffect(() => {
28
+ const canvas = canvasRef.current;
29
+ // StrictMode runs this effect twice against the SAME canvas element, and a
30
+ // second engine on one canvas is two renderers fighting for one context.
31
+ // The flag lives on the element, so it lasts exactly as long as the thing
32
+ // it guards — a page-level game like this one never unmounts otherwise.
33
+ if (!canvas || (canvas as { _incanto?: true })._incanto) return;
34
+ (canvas as { _incanto?: true })._incanto = true;
35
+
36
+ void (async () => {
37
+ // A bundled clip looped as low ambience (no large music files ship in the
38
+ // package — see incanto-audio.md). vite resolves + hashes the real file.
39
+
40
+ /**
41
+ * The sub-scenes this scene `instance:`s — `cover.scene.json` and
42
+ * `pillar.scene.json` — handed to the loader by path. `loadScene` never reads
43
+ * files; vite's `import.meta.glob` gathers every scene beside this one.
44
+ */
45
+ const prefabs = import.meta.glob('./*.scene.json', {
46
+ eager: true,
47
+ import: 'default',
48
+ }) as Record<string, SceneJson>;
49
+ const resolveScene = (path: string): SceneJson | null => prefabs[`./${path}`] ?? null;
50
+
51
+ // The soldier is a real GLB character (base-model.glb) animated by mixamo clips
52
+ // (idle/walk/run/jump) — declared in the scene `assets`. Warm the HTTP cache with
53
+ // a progress bar before booting; the arena, enemies, SFX + music stay zero-fetch.
54
+ const fill = document.querySelector('#progress') as HTMLElement | null;
55
+ const text = document.querySelector('#progress-text') as HTMLElement | null;
56
+ await preloadUrls(assetUrls(sceneJson.assets), (done, total) => {
57
+ const pct = total > 0 ? Math.round((done / total) * 100) : 100;
58
+ if (fill) fill.style.width = `${pct}%`;
59
+ if (text) text.textContent = `${pct}%`;
60
+ });
61
+ // createGame3D boots everything: register (gameplay behaviors auto-registered) →
62
+ // load → physics (auto; the scene has bodies) → keyboard + pointer-lock look →
63
+ // renderer → start. We pass the two custom behaviors.
64
+ /** Dev-only surfaces: the ☰ debug overlay, and the editor behind it. */
65
+ const DEBUG = import.meta.env.VITE_INCANTO_DEBUG === '1';
66
+
67
+ const game = await createGame3D({
68
+ debug: DEBUG,
69
+ // The editor's 📚 buttons, served by `incantoLibrary()` in vite.config.ts.
70
+ // BOTH halves are the opt-in, and this half was missing from every shipped
71
+ // template: the plugin alone left a vite config whose own comment promised
72
+ // "the agent8 asset catalog behind the 📚 buttons" and no button anywhere.
73
+ // Gated on the same flag, because `editor` DEFAULTS to `debug` and an object
74
+ // here would turn the editor on in a production build.
75
+ editor: DEBUG && { library: true },
76
+ canvas,
77
+ scene: sceneJson,
78
+ resolveScene,
79
+ behaviors: { Shoot, HudUpdater },
80
+ pointer: true, // pointer-lock mouse look (lockOnClick) — drives the free-view yaw/pitch
81
+ }).catch((e) => {
82
+ // Without this the player watches the loading overlay sit at 100% forever:
83
+ // `#loading` is removed on the line below, so anything that rejects here (no
84
+ // WebGL context, a scene that will not load) leaves the bar up and the reason
85
+ // in a console nobody opens.
86
+ showBootFailure(e);
87
+ throw e;
88
+ });
89
+
90
+ // The console handle FIRST, before any wiring of your own can throw.
91
+ // `game.stats()`, `game.assetErrors()`, `game.frame()` and `game.engine.log`
92
+ // are the entire in-page diagnostic surface, and a static build has no other.
93
+ // Assigned after the wiring, one mistake below took all of them with it.
94
+ (window as unknown as { game: typeof game }).game = game;
95
+
96
+ // And the loading overlay comes down LAST. Everything between here and there is
97
+ // your code; a throw in it used to leave a level that renders perfectly with no
98
+ // player, no error UI, and no way to ask the page what happened.
99
+ try {
100
+ // Looping background music on the music bus (a calm tense pad). The engine
101
+ // auto-resumes a gesture-blocked track on the first click/keypress.
102
+ game.engine.music.play(musicUrl, { loop: true, fadeIn: 1.5 });
103
+ game.engine.audio.music = 0.3;
104
+
105
+ // On-screen FIRE / JUMP buttons (mobile + desktop parity).
106
+ for (const [id, code] of [
107
+ ['btn-fire', 'KeyF'],
108
+ ['btn-jump', 'Space'],
109
+ ] as const) {
110
+ const el = document.querySelector(`#${id}`);
111
+ el?.addEventListener('pointerdown', () => game.engine.input.handleKey(code, true));
112
+ el?.addEventListener('pointerup', () => game.engine.input.handleKey(code, false));
113
+ }
114
+ } catch (e) {
115
+ showBootFailure(e);
116
+ throw e;
117
+ }
118
+
119
+ document.querySelector('#loading')?.remove();
120
+ })();
121
+ }, []);
122
+
123
+ return <canvas ref={canvasRef} id="game" />;
124
+ }