create-threenative 0.2.0

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 (320) hide show
  1. package/README.md +16 -0
  2. package/dist/index.d.ts +30 -0
  3. package/dist/index.js +283 -0
  4. package/dist/threenative.d.ts +6 -0
  5. package/dist/threenative.js +757 -0
  6. package/package.json +44 -0
  7. package/templates/action-rpg/.mcp.json +16 -0
  8. package/templates/action-rpg/AGENTS.md +40 -0
  9. package/templates/action-rpg/CLAUDE.md +42 -0
  10. package/templates/action-rpg/index.html +13 -0
  11. package/templates/action-rpg/kit.json +7 -0
  12. package/templates/action-rpg/package.json +47 -0
  13. package/templates/action-rpg/playtests/combat.playtest.json +61 -0
  14. package/templates/action-rpg/playtests/fail.playtest.json +21 -0
  15. package/templates/action-rpg/playtests/inventory.playtest.json +111 -0
  16. package/templates/action-rpg/playtests/progress.playtest.json +99 -0
  17. package/templates/action-rpg/playtests/survives.playtest.json +32 -0
  18. package/templates/action-rpg/playtests/win.playtest.json +30 -0
  19. package/templates/action-rpg/public/favicon.svg +5 -0
  20. package/templates/action-rpg/src/abilities/Ability.ts +45 -0
  21. package/templates/action-rpg/src/entities/Enemy.ts +143 -0
  22. package/templates/action-rpg/src/entities/Player.ts +83 -0
  23. package/templates/action-rpg/src/game.ts +40 -0
  24. package/templates/action-rpg/src/items/Inventory.ts +163 -0
  25. package/templates/action-rpg/src/loot/drops.ts +40 -0
  26. package/templates/action-rpg/src/main.ts +15 -0
  27. package/templates/action-rpg/src/physics.ts +40 -0
  28. package/templates/action-rpg/src/playtest-events.ts +15 -0
  29. package/templates/action-rpg/src/progress.ts +35 -0
  30. package/templates/action-rpg/src/render/camera.ts +26 -0
  31. package/templates/action-rpg/src/render/lighting.ts +30 -0
  32. package/templates/action-rpg/src/render/loading.ts +90 -0
  33. package/templates/action-rpg/src/render/materials.ts +40 -0
  34. package/templates/action-rpg/src/render/palette.ts +9 -0
  35. package/templates/action-rpg/src/render/postprocessing.ts +18 -0
  36. package/templates/action-rpg/src/render/shapes.ts +110 -0
  37. package/templates/action-rpg/src/render/sky.ts +18 -0
  38. package/templates/action-rpg/src/render/types.ts +3 -0
  39. package/templates/action-rpg/src/scenes/Boot.ts +12 -0
  40. package/templates/action-rpg/src/scenes/Play.ts +449 -0
  41. package/templates/action-rpg/src/state.ts +40 -0
  42. package/templates/action-rpg/src/stats/StatBlock.ts +57 -0
  43. package/templates/action-rpg/src/style.css +32 -0
  44. package/templates/action-rpg/src/ui/AbilityBar.tsx +28 -0
  45. package/templates/action-rpg/src/ui/App.tsx +21 -0
  46. package/templates/action-rpg/src/ui/CharacterPanel.tsx +31 -0
  47. package/templates/action-rpg/src/ui/Hud.tsx +29 -0
  48. package/templates/action-rpg/src/ui/InventoryPanel.tsx +37 -0
  49. package/templates/action-rpg/tailwind.config.ts +7 -0
  50. package/templates/action-rpg/threenative.config.ts +29 -0
  51. package/templates/action-rpg/tsconfig.json +17 -0
  52. package/templates/action-rpg/vite.config.ts +8 -0
  53. package/templates/defense/.mcp.json +16 -0
  54. package/templates/defense/AGENTS.md +53 -0
  55. package/templates/defense/CLAUDE.md +55 -0
  56. package/templates/defense/README.md +9 -0
  57. package/templates/defense/index.html +13 -0
  58. package/templates/defense/kit.json +7 -0
  59. package/templates/defense/package.json +46 -0
  60. package/templates/defense/playtests/leak.playtest.json +18 -0
  61. package/templates/defense/playtests/placement.playtest.json +40 -0
  62. package/templates/defense/playtests/scan.playtest.json +20 -0
  63. package/templates/defense/playtests/survive.playtest.json +26 -0
  64. package/templates/defense/playtests/survives.playtest.json +36 -0
  65. package/templates/defense/public/favicon.svg +5 -0
  66. package/templates/defense/src/attackers/Attacker.ts +104 -0
  67. package/templates/defense/src/board/Route.ts +80 -0
  68. package/templates/defense/src/economy.ts +36 -0
  69. package/templates/defense/src/entities/Player.ts +44 -0
  70. package/templates/defense/src/game.ts +30 -0
  71. package/templates/defense/src/main.ts +15 -0
  72. package/templates/defense/src/physics.ts +43 -0
  73. package/templates/defense/src/placement/Buildable.ts +49 -0
  74. package/templates/defense/src/playtest-events.ts +15 -0
  75. package/templates/defense/src/render/camera.ts +10 -0
  76. package/templates/defense/src/render/lighting.ts +32 -0
  77. package/templates/defense/src/render/loading.ts +89 -0
  78. package/templates/defense/src/render/materials.ts +13 -0
  79. package/templates/defense/src/render/palette.ts +21 -0
  80. package/templates/defense/src/render/postprocessing.ts +14 -0
  81. package/templates/defense/src/render/shapes.ts +89 -0
  82. package/templates/defense/src/render/sky.ts +45 -0
  83. package/templates/defense/src/scenes/Boot.ts +12 -0
  84. package/templates/defense/src/scenes/Defense.ts +165 -0
  85. package/templates/defense/src/state.ts +50 -0
  86. package/templates/defense/src/style.css +32 -0
  87. package/templates/defense/src/towers/Tower.ts +96 -0
  88. package/templates/defense/src/towers/targeting.ts +53 -0
  89. package/templates/defense/src/ui/App.tsx +17 -0
  90. package/templates/defense/src/ui/Hud.tsx +61 -0
  91. package/templates/defense/src/ui/Menu.tsx +7 -0
  92. package/templates/defense/src/waves.ts +40 -0
  93. package/templates/defense/tailwind.config.ts +1 -0
  94. package/templates/defense/threenative.config.ts +29 -0
  95. package/templates/defense/tsconfig.json +17 -0
  96. package/templates/defense/vite.config.ts +5 -0
  97. package/templates/minimal/.mcp.json +16 -0
  98. package/templates/minimal/AGENTS.md +400 -0
  99. package/templates/minimal/CLAUDE.md +402 -0
  100. package/templates/minimal/assets/.gitkeep +0 -0
  101. package/templates/minimal/index.html +14 -0
  102. package/templates/minimal/kit.json +7 -0
  103. package/templates/minimal/package.json +40 -0
  104. package/templates/minimal/playtests/play.playtest.json +32 -0
  105. package/templates/minimal/playtests/survives.playtest.json +32 -0
  106. package/templates/minimal/public/.gitkeep +0 -0
  107. package/templates/minimal/public/favicon.svg +4 -0
  108. package/templates/minimal/public/icon.png +0 -0
  109. package/templates/minimal/src/entities/Player.ts +66 -0
  110. package/templates/minimal/src/game.ts +28 -0
  111. package/templates/minimal/src/main.ts +17 -0
  112. package/templates/minimal/src/render/camera.ts +11 -0
  113. package/templates/minimal/src/render/hud.ts +53 -0
  114. package/templates/minimal/src/render/lighting.ts +46 -0
  115. package/templates/minimal/src/render/loading.ts +113 -0
  116. package/templates/minimal/src/render/materials.ts +16 -0
  117. package/templates/minimal/src/render/palette.ts +9 -0
  118. package/templates/minimal/src/render/postprocessing.ts +20 -0
  119. package/templates/minimal/src/render/sky.ts +41 -0
  120. package/templates/minimal/src/scenes/Boot.ts +5 -0
  121. package/templates/minimal/src/scenes/Play.ts +65 -0
  122. package/templates/minimal/src/state.ts +1 -0
  123. package/templates/minimal/src/style.css +41 -0
  124. package/templates/minimal/threenative.config.ts +32 -0
  125. package/templates/minimal/tsconfig.json +16 -0
  126. package/templates/minimal/vite.config.ts +3 -0
  127. package/templates/platformer/.mcp.json +16 -0
  128. package/templates/platformer/AGENTS.md +199 -0
  129. package/templates/platformer/CLAUDE.md +201 -0
  130. package/templates/platformer/assets/.gitkeep +0 -0
  131. package/templates/platformer/index.html +13 -0
  132. package/templates/platformer/kit.json +7 -0
  133. package/templates/platformer/package.json +50 -0
  134. package/templates/platformer/playtests/avoidance.playtest.json +23 -0
  135. package/templates/platformer/playtests/buffer.playtest.json +17 -0
  136. package/templates/platformer/playtests/chase.playtest.json +21 -0
  137. package/templates/platformer/playtests/collect.playtest.json +56 -0
  138. package/templates/platformer/playtests/collision-layers.playtest.json +36 -0
  139. package/templates/platformer/playtests/coyote.playtest.json +21 -0
  140. package/templates/platformer/playtests/damage.playtest.json +31 -0
  141. package/templates/platformer/playtests/dash.playtest.json +21 -0
  142. package/templates/platformer/playtests/jump.playtest.json +21 -0
  143. package/templates/platformer/playtests/oneway.playtest.json +17 -0
  144. package/templates/platformer/playtests/patrol.playtest.json +13 -0
  145. package/templates/platformer/playtests/performance.playtest.json +21 -0
  146. package/templates/platformer/playtests/physics.playtest.json +14 -0
  147. package/templates/platformer/playtests/respawn.playtest.json +31 -0
  148. package/templates/platformer/playtests/stomp-rise.playtest.json +41 -0
  149. package/templates/platformer/playtests/stomp.playtest.json +34 -0
  150. package/templates/platformer/playtests/survives.playtest.json +32 -0
  151. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +29 -0
  152. package/templates/platformer/playtests/terminal-loop-win.playtest.json +52 -0
  153. package/templates/platformer/public/.gitkeep +0 -0
  154. package/templates/platformer/public/favicon.svg +4 -0
  155. package/templates/platformer/public/icon.png +0 -0
  156. package/templates/platformer/src/entities/Character.ts +218 -0
  157. package/templates/platformer/src/entities/Chaser.ts +118 -0
  158. package/templates/platformer/src/entities/Patrol.ts +88 -0
  159. package/templates/platformer/src/entities/Pickup.ts +72 -0
  160. package/templates/platformer/src/game.ts +27 -0
  161. package/templates/platformer/src/level/Checkpoints.ts +66 -0
  162. package/templates/platformer/src/level/Platform.ts +34 -0
  163. package/templates/platformer/src/main.ts +14 -0
  164. package/templates/platformer/src/playtest-events.ts +15 -0
  165. package/templates/platformer/src/render/camera.ts +8 -0
  166. package/templates/platformer/src/render/lighting.ts +38 -0
  167. package/templates/platformer/src/render/loading.ts +113 -0
  168. package/templates/platformer/src/render/materials.ts +11 -0
  169. package/templates/platformer/src/render/palette.ts +54 -0
  170. package/templates/platformer/src/render/postprocessing.ts +18 -0
  171. package/templates/platformer/src/render/rig.ts +60 -0
  172. package/templates/platformer/src/render/sky.ts +47 -0
  173. package/templates/platformer/src/render/terrain.ts +31 -0
  174. package/templates/platformer/src/render/touch-controls.ts +157 -0
  175. package/templates/platformer/src/render/touch-layout.ts +63 -0
  176. package/templates/platformer/src/scenes/Boot.ts +12 -0
  177. package/templates/platformer/src/scenes/Level.ts +176 -0
  178. package/templates/platformer/src/state.ts +23 -0
  179. package/templates/platformer/src/style.css +31 -0
  180. package/templates/platformer/src/ui/App.tsx +17 -0
  181. package/templates/platformer/src/ui/Hud.tsx +41 -0
  182. package/templates/platformer/src/ui/Menu.tsx +7 -0
  183. package/templates/platformer/tailwind.config.ts +2 -0
  184. package/templates/platformer/threenative.config.ts +32 -0
  185. package/templates/platformer/tsconfig.json +17 -0
  186. package/templates/platformer/vite.config.ts +5 -0
  187. package/templates/racing/.mcp.json +16 -0
  188. package/templates/racing/AGENTS.md +48 -0
  189. package/templates/racing/CLAUDE.md +50 -0
  190. package/templates/racing/index.html +13 -0
  191. package/templates/racing/kit.json +7 -0
  192. package/templates/racing/package.json +46 -0
  193. package/templates/racing/playtests/boost.playtest.json +45 -0
  194. package/templates/racing/playtests/outcome.playtest.json +78 -0
  195. package/templates/racing/playtests/ranking.playtest.json +37 -0
  196. package/templates/racing/playtests/rescue.playtest.json +28 -0
  197. package/templates/racing/playtests/reverse.playtest.json +37 -0
  198. package/templates/racing/playtests/shortcut.playtest.json +44 -0
  199. package/templates/racing/playtests/survives.playtest.json +32 -0
  200. package/templates/racing/public/favicon.svg +6 -0
  201. package/templates/racing/src/entities/RacingCar.ts +114 -0
  202. package/templates/racing/src/entities/Rival.ts +46 -0
  203. package/templates/racing/src/game.ts +29 -0
  204. package/templates/racing/src/kart/boost.ts +38 -0
  205. package/templates/racing/src/main.ts +15 -0
  206. package/templates/racing/src/playtest-events.ts +15 -0
  207. package/templates/racing/src/render/camera.ts +28 -0
  208. package/templates/racing/src/render/lighting.ts +32 -0
  209. package/templates/racing/src/render/loading.ts +58 -0
  210. package/templates/racing/src/render/materials.ts +15 -0
  211. package/templates/racing/src/render/palette.ts +30 -0
  212. package/templates/racing/src/render/postprocessing.ts +14 -0
  213. package/templates/racing/src/render/shapes.ts +37 -0
  214. package/templates/racing/src/render/sky.ts +45 -0
  215. package/templates/racing/src/scenes/Boot.ts +12 -0
  216. package/templates/racing/src/scenes/Race.ts +180 -0
  217. package/templates/racing/src/state.ts +35 -0
  218. package/templates/racing/src/style.css +32 -0
  219. package/templates/racing/src/track/Checkline.ts +19 -0
  220. package/templates/racing/src/track/Lap.ts +104 -0
  221. package/templates/racing/src/track/Ranking.ts +35 -0
  222. package/templates/racing/src/track/Track.ts +229 -0
  223. package/templates/racing/src/track/TrackSector.ts +77 -0
  224. package/templates/racing/src/track/rescue.ts +21 -0
  225. package/templates/racing/src/ui/App.tsx +17 -0
  226. package/templates/racing/src/ui/Hud.tsx +71 -0
  227. package/templates/racing/src/ui/Menu.tsx +7 -0
  228. package/templates/racing/tailwind.config.ts +2 -0
  229. package/templates/racing/threenative.config.ts +29 -0
  230. package/templates/racing/tsconfig.json +17 -0
  231. package/templates/racing/vite.config.ts +5 -0
  232. package/templates/shooter/.mcp.json +16 -0
  233. package/templates/shooter/AGENTS.md +69 -0
  234. package/templates/shooter/CLAUDE.md +71 -0
  235. package/templates/shooter/index.html +13 -0
  236. package/templates/shooter/kit.json +7 -0
  237. package/templates/shooter/package.json +46 -0
  238. package/templates/shooter/playtests/fail.playtest.json +30 -0
  239. package/templates/shooter/playtests/shooter.playtest.json +89 -0
  240. package/templates/shooter/playtests/survives.playtest.json +32 -0
  241. package/templates/shooter/public/favicon.svg +4 -0
  242. package/templates/shooter/src/combat/damage.ts +41 -0
  243. package/templates/shooter/src/entities/Pickup.ts +70 -0
  244. package/templates/shooter/src/entities/Player.ts +93 -0
  245. package/templates/shooter/src/entities/Target.ts +103 -0
  246. package/templates/shooter/src/game.ts +36 -0
  247. package/templates/shooter/src/level/SpawnPoints.ts +28 -0
  248. package/templates/shooter/src/main.ts +26 -0
  249. package/templates/shooter/src/physics.ts +49 -0
  250. package/templates/shooter/src/playtest-events.ts +15 -0
  251. package/templates/shooter/src/render/camera.ts +29 -0
  252. package/templates/shooter/src/render/lighting.ts +38 -0
  253. package/templates/shooter/src/render/loading.ts +86 -0
  254. package/templates/shooter/src/render/materials.ts +38 -0
  255. package/templates/shooter/src/render/palette.ts +9 -0
  256. package/templates/shooter/src/render/postprocessing.ts +19 -0
  257. package/templates/shooter/src/render/shapes.ts +194 -0
  258. package/templates/shooter/src/render/sky.ts +37 -0
  259. package/templates/shooter/src/render/types.ts +3 -0
  260. package/templates/shooter/src/render/ui.css +212 -0
  261. package/templates/shooter/src/render/ui.ts +59 -0
  262. package/templates/shooter/src/scenes/Boot.ts +12 -0
  263. package/templates/shooter/src/scenes/Play.ts +428 -0
  264. package/templates/shooter/src/state.ts +29 -0
  265. package/templates/shooter/src/ui/App.tsx +25 -0
  266. package/templates/shooter/src/ui/Hud.tsx +49 -0
  267. package/templates/shooter/src/ui/Menu.tsx +26 -0
  268. package/templates/shooter/src/waves.ts +50 -0
  269. package/templates/shooter/src/weapons/Hitscan.ts +43 -0
  270. package/templates/shooter/src/weapons/Projectile.ts +76 -0
  271. package/templates/shooter/tailwind.config.ts +5 -0
  272. package/templates/shooter/threenative.config.ts +29 -0
  273. package/templates/shooter/tsconfig.json +17 -0
  274. package/templates/shooter/vite.config.ts +8 -0
  275. package/templates/starter/.mcp.json +16 -0
  276. package/templates/starter/AGENTS.md +450 -0
  277. package/templates/starter/CLAUDE.md +452 -0
  278. package/templates/starter/assets/.gitkeep +0 -0
  279. package/templates/starter/index.html +13 -0
  280. package/templates/starter/kit.json +7 -0
  281. package/templates/starter/package.json +49 -0
  282. package/templates/starter/playtests/buffer.playtest.json +29 -0
  283. package/templates/starter/playtests/coyote.playtest.json +35 -0
  284. package/templates/starter/playtests/forward.playtest.json +15 -0
  285. package/templates/starter/playtests/hot-reload.playtest.json +28 -0
  286. package/templates/starter/playtests/look.playtest.json +43 -0
  287. package/templates/starter/playtests/monitoring.playtest.json +41 -0
  288. package/templates/starter/playtests/pause.playtest.json +33 -0
  289. package/templates/starter/playtests/play.playtest.json +16 -0
  290. package/templates/starter/playtests/respawn.playtest.json +28 -0
  291. package/templates/starter/playtests/restart.playtest.json +36 -0
  292. package/templates/starter/playtests/seed.playtest.json +18 -0
  293. package/templates/starter/playtests/survives.playtest.json +32 -0
  294. package/templates/starter/public/.gitkeep +0 -0
  295. package/templates/starter/public/favicon.svg +4 -0
  296. package/templates/starter/public/icon.png +0 -0
  297. package/templates/starter/public/native-proof.glb +0 -0
  298. package/templates/starter/public/native-proof.png +0 -0
  299. package/templates/starter/public/pickup.ogg +0 -0
  300. package/templates/starter/src/entities/Crate.ts +34 -0
  301. package/templates/starter/src/entities/Player.ts +80 -0
  302. package/templates/starter/src/game.ts +30 -0
  303. package/templates/starter/src/main.ts +15 -0
  304. package/templates/starter/src/render/camera.ts +57 -0
  305. package/templates/starter/src/render/lighting.ts +55 -0
  306. package/templates/starter/src/render/materials.ts +12 -0
  307. package/templates/starter/src/render/palette.ts +9 -0
  308. package/templates/starter/src/render/postprocessing.ts +18 -0
  309. package/templates/starter/src/render/shapes.ts +147 -0
  310. package/templates/starter/src/render/sky.ts +56 -0
  311. package/templates/starter/src/scenes/Play.ts +161 -0
  312. package/templates/starter/src/state.ts +10 -0
  313. package/templates/starter/src/style.css +45 -0
  314. package/templates/starter/src/ui/App.tsx +19 -0
  315. package/templates/starter/src/ui/Hud.tsx +37 -0
  316. package/templates/starter/src/ui/Menu.tsx +43 -0
  317. package/templates/starter/tailwind.config.ts +2 -0
  318. package/templates/starter/threenative.config.ts +31 -0
  319. package/templates/starter/tsconfig.json +17 -0
  320. package/templates/starter/vite.config.ts +8 -0
@@ -0,0 +1,32 @@
1
+ import type { IThreeNativeConfig } from "@threenative/core";
2
+
3
+ export default {
4
+ app: {
5
+ id: "com.threenative.__PROJECT_ID__",
6
+ name: "__PROJECT_NAME__",
7
+ version: "1.0.0",
8
+ build: 1,
9
+ icon: "public/icon.png",
10
+ },
11
+ display: {
12
+ orientation: "landscape", // Mobile viewport orientation.
13
+ fullscreen: true, // Keep the game surface edge to edge.
14
+ keepScreenOn: true, // Do not dim during a play session.
15
+ },
16
+ window: {
17
+ title: "__PROJECT_NAME__", // Desktop window title.
18
+ width: 1280,
19
+ height: 720,
20
+ resizable: true,
21
+ },
22
+ loading: {
23
+ // Read by src/render/loading.ts, which is your file. Delete that file to drop the screen.
24
+ backdropColor: "#0d1b2a",
25
+ trackColor: "#274060",
26
+ progressColor: "#8fd694",
27
+ showProgressBar: true,
28
+ // image: "public/logo.png", // drawn centred above the bar
29
+ },
30
+ nativeEntry: "src/game.ts",
31
+ renderer: { preferWebGPU: true }, // Use WebGPU when the host exposes it.
32
+ } satisfies IThreeNativeConfig;
@@ -0,0 +1,17 @@
1
+ {
2
+ "compilerOptions": {
3
+ "target": "ES2022",
4
+ "lib": ["ES2022", "DOM", "DOM.Iterable"],
5
+ "module": "ESNext",
6
+ "moduleResolution": "bundler",
7
+ "jsx": "react-jsx",
8
+ "types": ["vite/client"],
9
+ "strict": true,
10
+ "noUncheckedIndexedAccess": true,
11
+ "noEmit": true,
12
+ "skipLibCheck": true,
13
+ "verbatimModuleSyntax": true,
14
+ "isolatedModules": true
15
+ },
16
+ "include": ["src/**/*.ts", "src/**/*.tsx", "*.ts"]
17
+ }
@@ -0,0 +1,5 @@
1
+ import tailwindcss from "@tailwindcss/vite";
2
+ import react from "@vitejs/plugin-react";
3
+ import { defineConfig } from "vite";
4
+
5
+ export default defineConfig({ plugins: [react(), tailwindcss()] });
@@ -0,0 +1,16 @@
1
+ {
2
+ "mcpServers": {
3
+ "threenative-assets": {
4
+ "command": "node",
5
+ "args": ["./node_modules/threenative-asset-mcp/dist/index.js"],
6
+ "env": {
7
+ "ASSET_DOWNLOAD_DIR": "./public/assets",
8
+ "AUDIO_DOWNLOAD_DIR": "./public/audio"
9
+ }
10
+ },
11
+ "threenative-sculpt": {
12
+ "command": "node",
13
+ "args": ["./node_modules/threenative-sculpt-mcp/dist/server.js"]
14
+ }
15
+ }
16
+ }
@@ -0,0 +1,48 @@
1
+ # AGENTS.md — __PROJECT_NAME__ racing
2
+
3
+ This project is an editable Three.js circuit-racing starter. The framework owns the loop,
4
+ input, renderer, physics bindings, and playtest bridge; this repository owns the car feel,
5
+ track, race rules, rescue, HUD, and look.
6
+
7
+ ## Commands
8
+
9
+ ```sh
10
+ pnpm dev
11
+ pnpm build
12
+ pnpm build --target desktop
13
+ pnpm test
14
+ pnpm typecheck
15
+ ```
16
+
17
+ The portable entry is `src/game.ts`; React mounting stays in `src/main.ts`. The car uses
18
+ `CharacterBody3D`, not a package-level vehicle node. `src/track/` is ordinary user-owned
19
+ source: `Lap.ts` orders Area3D gate crossings, `TrackSector.ts` records the last ray-probed
20
+ road transform, and `Ranking.ts` ranks by route progress rather than world distance.
21
+
22
+ `src/render/` owns the palette, lighting, camera, materials, sky and postprocessing. The HUD is
23
+ `src/ui/Hud.tsx` and there is only one of it: this template used to draw a geometry HUD on top of
24
+ the React one, showing every number twice. A native build has no HUD until you add one.
25
+ There is no track format, racing-line solver, or `VehicleBody3D` abstraction. `Track.ts` uses
26
+ the generic `PathFollow3D` route follower directly. Change the circuit in `src/track/Track.ts`
27
+ and tune car constants in `src/entities/RacingCar.ts`.
28
+
29
+ `input.vector("move").y` is +up; the racing car treats it as throttle. Register entities with
30
+ `ctx.entities` so playtests can observe them. The HUD is a web convenience; the portable game
31
+ does not import React or the UI package.
32
+
33
+ `playtests/survives.playtest.json` is the durable smoke proof. Keep it when replacing the racing
34
+ gameplay; the other `playtests/` scenarios are examples for shortcuts, reversing, boosts,
35
+ rescues, rankings, and race outcomes.
36
+
37
+ The normal physics API selects the native backend on desktop and Android. The optional
38
+ `intersectRay` query is used when the host provides PRD-088's coarse ray probe; the track has
39
+ an ordinary Three.js fallback so the starter remains runnable before that backend is present.
40
+ No claim of physical mobile or performance parity is made by this template.
41
+
42
+ The asset MCP loop is:
43
+
44
+ 1. `asset_search_sources`
45
+ 2. `ambientcg_search_assets` / `polyhaven_search_assets` / `audio_search_assets`
46
+ 3. `ambientcg_list_files` / `polyhaven_list_files`
47
+ 4. `asset_download_file` / `audio_download_asset`
48
+ 5. Check returned license and attribution fields before committing an asset.
@@ -0,0 +1,50 @@
1
+ <!-- Generated mirror of AGENTS.md. Do not edit; edit AGENTS.md. -->
2
+
3
+ # AGENTS.md — __PROJECT_NAME__ racing
4
+
5
+ This project is an editable Three.js circuit-racing starter. The framework owns the loop,
6
+ input, renderer, physics bindings, and playtest bridge; this repository owns the car feel,
7
+ track, race rules, rescue, HUD, and look.
8
+
9
+ ## Commands
10
+
11
+ ```sh
12
+ pnpm dev
13
+ pnpm build
14
+ pnpm build --target desktop
15
+ pnpm test
16
+ pnpm typecheck
17
+ ```
18
+
19
+ The portable entry is `src/game.ts`; React mounting stays in `src/main.ts`. The car uses
20
+ `CharacterBody3D`, not a package-level vehicle node. `src/track/` is ordinary user-owned
21
+ source: `Lap.ts` orders Area3D gate crossings, `TrackSector.ts` records the last ray-probed
22
+ road transform, and `Ranking.ts` ranks by route progress rather than world distance.
23
+
24
+ `src/render/` owns the palette, lighting, camera, materials, sky and postprocessing. The HUD is
25
+ `src/ui/Hud.tsx` and there is only one of it: this template used to draw a geometry HUD on top of
26
+ the React one, showing every number twice. A native build has no HUD until you add one.
27
+ There is no track format, racing-line solver, or `VehicleBody3D` abstraction. `Track.ts` uses
28
+ the generic `PathFollow3D` route follower directly. Change the circuit in `src/track/Track.ts`
29
+ and tune car constants in `src/entities/RacingCar.ts`.
30
+
31
+ `input.vector("move").y` is +up; the racing car treats it as throttle. Register entities with
32
+ `ctx.entities` so playtests can observe them. The HUD is a web convenience; the portable game
33
+ does not import React or the UI package.
34
+
35
+ `playtests/survives.playtest.json` is the durable smoke proof. Keep it when replacing the racing
36
+ gameplay; the other `playtests/` scenarios are examples for shortcuts, reversing, boosts,
37
+ rescues, rankings, and race outcomes.
38
+
39
+ The normal physics API selects the native backend on desktop and Android. The optional
40
+ `intersectRay` query is used when the host provides PRD-088's coarse ray probe; the track has
41
+ an ordinary Three.js fallback so the starter remains runnable before that backend is present.
42
+ No claim of physical mobile or performance parity is made by this template.
43
+
44
+ The asset MCP loop is:
45
+
46
+ 1. `asset_search_sources`
47
+ 2. `ambientcg_search_assets` / `polyhaven_search_assets` / `audio_search_assets`
48
+ 3. `ambientcg_list_files` / `polyhaven_list_files`
49
+ 4. `asset_download_file` / `audio_download_asset`
50
+ 5. Check returned license and attribution fields before committing an asset.
@@ -0,0 +1,13 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
+ <link rel="icon" href="/favicon.svg" />
7
+ <title>__PROJECT_NAME__</title>
8
+ </head>
9
+ <body>
10
+ <div id="root"></div>
11
+ <script type="module" src="/src/main.ts"></script>
12
+ </body>
13
+ </html>
@@ -0,0 +1,7 @@
1
+ {
2
+ "name": "racing",
3
+ "title": "Circuit racing",
4
+ "blurb": "Three laps, ordered checklines, rescue sectors, boost pads, and route-progress ranking.",
5
+ "genre": "racing",
6
+ "kit": true
7
+ }
@@ -0,0 +1,46 @@
1
+ {
2
+ "name": "__PROJECT_NAME__",
3
+ "private": true,
4
+ "type": "module",
5
+ "scripts": {
6
+ "dev": "vite",
7
+ "build": "threenative build",
8
+ "build:web": "threenative build --target web",
9
+ "build:desktop": "threenative build --target desktop",
10
+ "build:android": "threenative build --target android",
11
+ "build:ios": "threenative build --target ios",
12
+ "pretest": "playwright install chromium",
13
+ "test": "vite build && pnpm run test:playtest",
14
+ "test:playtest": "threenative-playtest --scenario playtests/survives.playtest.json --url http://127.0.0.1:4173 --server-command \"pnpm dev --host 127.0.0.1 --port 4173 --strictPort\" --browser-recipe webgpu --headed && threenative-playtest --scenario playtests/shortcut.playtest.json --url http://127.0.0.1:4173 --server-command \"pnpm dev --host 127.0.0.1 --port 4173 --strictPort\" --browser-recipe webgpu --headed && threenative-playtest --scenario playtests/reverse.playtest.json --url http://127.0.0.1:4173 --server-command \"pnpm dev --host 127.0.0.1 --port 4173 --strictPort\" --browser-recipe webgpu --headed && threenative-playtest --scenario playtests/boost.playtest.json --url http://127.0.0.1:4173 --server-command \"pnpm dev --host 127.0.0.1 --port 4173 --strictPort\" --browser-recipe webgpu --headed && threenative-playtest --scenario playtests/rescue.playtest.json --url http://127.0.0.1:4173 --server-command \"pnpm dev --host 127.0.0.1 --port 4173 --strictPort\" --browser-recipe webgpu --headed && threenative-playtest --scenario playtests/ranking.playtest.json --url http://127.0.0.1:4173 --server-command \"pnpm dev --host 127.0.0.1 --port 4173 --strictPort\" --browser-recipe webgpu --headed && threenative-playtest --scenario playtests/outcome.playtest.json --url http://127.0.0.1:4173 --server-command \"pnpm dev --host 127.0.0.1 --port 4173 --strictPort\" --browser-recipe webgpu --headed",
15
+ "typecheck": "tsc --noEmit -p tsconfig.json"
16
+ },
17
+ "dependencies": {
18
+ "@threenative/core": "0.2.0",
19
+ "@threenative/physics": "0.2.0",
20
+ "@threenative/ui": "0.2.0",
21
+ "react": "19.2.0",
22
+ "react-dom": "19.2.0",
23
+ "three": "0.185.1"
24
+ },
25
+ "devDependencies": {
26
+ "@tailwindcss/vite": "4.3.3",
27
+ "@vitejs/plugin-react": "6.0.5",
28
+ "@threenative/playtest": "0.2.0",
29
+ "@types/react": "19.2.0",
30
+ "@types/react-dom": "19.2.0",
31
+ "@types/three": "0.185.3",
32
+ "create-threenative": "0.2.0",
33
+ "playwright": "1.62.1",
34
+ "tailwindcss": "4.3.3",
35
+ "threenative-asset-mcp": "0.4.0",
36
+ "threenative-sculpt-mcp": "0.1.0",
37
+ "typescript": "5.9.3",
38
+ "vite": "8.2.0"
39
+ },
40
+ "optionalDependencies": {
41
+ "@threenative/runtime-native": "0.2.0"
42
+ },
43
+ "pnpm": {
44
+ "onlyBuiltDependencies": ["@threenative/runtime-native"]
45
+ }
46
+ }
@@ -0,0 +1,45 @@
1
+ {
2
+ "name": "racing-boost-expires",
3
+ "schemaVersion": 1,
4
+ "target": "web",
5
+ "viewport": { "width": 1280, "height": 720 },
6
+ "warmupFrames": 10,
7
+ "subject": "player",
8
+ "steps": [
9
+ {
10
+ "kind": "input",
11
+ "label": "cross-boost-pad",
12
+ "press": "ArrowUp",
13
+ "holdTicks": 130,
14
+ "release": false
15
+ },
16
+ {
17
+ "kind": "input",
18
+ "label": "take-the-corner",
19
+ "press": ["ArrowUp", "ArrowRight"],
20
+ "holdTicks": 42,
21
+ "release": true
22
+ },
23
+ {
24
+ "kind": "input",
25
+ "label": "let-boost-expire",
26
+ "press": "ArrowUp",
27
+ "holdTicks": 150,
28
+ "release": true
29
+ }
30
+ ],
31
+ "assert": {
32
+ "diagnostics": { "noConsoleErrors": true, "runtimeReady": true },
33
+ "resources": [
34
+ { "id": "GameState", "path": "boostUses", "gte": 1, "changed": true },
35
+ { "id": "GameState", "path": "boostPeakSpeed", "gte": 9.01, "changed": true },
36
+ {
37
+ "id": "GameState",
38
+ "path": "boostActive",
39
+ "equals": false,
40
+ "allowTrivial": true
41
+ },
42
+ { "id": "GameState", "path": "speedAfterBoost", "equals": 9, "changed": true }
43
+ ]
44
+ }
45
+ }
@@ -0,0 +1,78 @@
1
+ {
2
+ "name": "racing-finish-behind-rival-is-dnf",
3
+ "schemaVersion": 1,
4
+ "target": "web",
5
+ "viewport": { "width": 1280, "height": 720 },
6
+ "warmupFrames": 10,
7
+ "subject": "player",
8
+ "steps": [
9
+ {
10
+ "kind": "input",
11
+ "label": "first-straight",
12
+ "press": "ArrowUp",
13
+ "holdTicks": 90,
14
+ "release": true
15
+ },
16
+ { "kind": "input", "press": ["ArrowUp", "ArrowRight"], "holdTicks": 60, "release": true },
17
+ { "kind": "input", "press": "ArrowUp", "holdTicks": 110, "release": true },
18
+ { "kind": "input", "press": ["ArrowUp", "ArrowRight"], "holdTicks": 60, "release": true },
19
+ { "kind": "input", "press": "ArrowUp", "holdTicks": 137, "release": true },
20
+ { "kind": "input", "press": ["ArrowUp", "ArrowRight"], "holdTicks": 60, "release": true },
21
+ { "kind": "input", "press": "ArrowUp", "holdTicks": 187, "release": true },
22
+ { "kind": "input", "press": ["ArrowUp", "ArrowRight"], "holdTicks": 60, "release": true },
23
+ { "kind": "input", "press": ["ArrowUp", "ArrowRight"], "holdTicks": 12, "release": true },
24
+ {
25
+ "kind": "input",
26
+ "label": "first-finish",
27
+ "press": "ArrowUp",
28
+ "holdTicks": 160,
29
+ "release": true
30
+ },
31
+ { "kind": "input", "press": ["ArrowUp", "ArrowRight"], "holdTicks": 60, "release": true },
32
+ { "kind": "input", "press": "ArrowUp", "holdTicks": 110, "release": true },
33
+ { "kind": "input", "press": ["ArrowUp", "ArrowRight"], "holdTicks": 60, "release": true },
34
+ { "kind": "input", "press": "ArrowUp", "holdTicks": 137, "release": true },
35
+ { "kind": "input", "press": ["ArrowUp", "ArrowRight"], "holdTicks": 60, "release": true },
36
+ { "kind": "input", "press": "ArrowUp", "holdTicks": 187, "release": true },
37
+ { "kind": "input", "press": ["ArrowUp", "ArrowRight"], "holdTicks": 60, "release": true },
38
+ { "kind": "input", "press": ["ArrowUp", "ArrowRight"], "holdTicks": 12, "release": true },
39
+ {
40
+ "kind": "input",
41
+ "label": "second-finish",
42
+ "press": "ArrowUp",
43
+ "holdTicks": 160,
44
+ "release": true
45
+ },
46
+ { "kind": "input", "press": ["ArrowUp", "ArrowRight"], "holdTicks": 60, "release": true },
47
+ { "kind": "input", "press": "ArrowUp", "holdTicks": 110, "release": true },
48
+ { "kind": "input", "press": ["ArrowUp", "ArrowRight"], "holdTicks": 60, "release": true },
49
+ { "kind": "input", "press": "ArrowUp", "holdTicks": 137, "release": true },
50
+ { "kind": "input", "press": ["ArrowUp", "ArrowRight"], "holdTicks": 60, "release": true },
51
+ { "kind": "input", "press": "ArrowUp", "holdTicks": 187, "release": true },
52
+ { "kind": "input", "press": ["ArrowUp", "ArrowRight"], "holdTicks": 60, "release": true },
53
+ { "kind": "input", "press": ["ArrowUp", "ArrowRight"], "holdTicks": 12, "release": true },
54
+ {
55
+ "kind": "input",
56
+ "label": "third-finish",
57
+ "press": "ArrowUp",
58
+ "holdTicks": 160,
59
+ "release": true
60
+ },
61
+ { "kind": "wait", "label": "observe-dnf", "waitTicks": 20, "release": true }
62
+ ],
63
+ "assert": {
64
+ "diagnostics": { "noConsoleErrors": true, "runtimeReady": true },
65
+ "resources": [
66
+ { "id": "GameState", "path": "completedLaps", "gte": 3, "changed": true },
67
+ { "id": "GameState", "path": "place", "gte": 2, "allowTrivial": true },
68
+ { "id": "GameState", "path": "rescues", "equals": 0, "allowTrivial": true },
69
+ {
70
+ "id": "GameState",
71
+ "path": "raceStatus",
72
+ "equals": "DNF",
73
+ "changed": true,
74
+ "atSteps": [{ "label": "observe-dnf", "equals": "DNF" }]
75
+ }
76
+ ]
77
+ }
78
+ }
@@ -0,0 +1,37 @@
1
+ {
2
+ "name": "racing-route-ranking",
3
+ "schemaVersion": 1,
4
+ "target": "web",
5
+ "viewport": { "width": 1280, "height": 720 },
6
+ "warmupFrames": 0,
7
+ "subject": "player",
8
+ "steps": [
9
+ {
10
+ "kind": "wait",
11
+ "label": "lap-aware-baseline",
12
+ "waitTicks": 1,
13
+ "release": true
14
+ },
15
+ {
16
+ "kind": "input",
17
+ "label": "advance-on-route",
18
+ "press": "ArrowUp",
19
+ "holdTicks": 30,
20
+ "release": true
21
+ }
22
+ ],
23
+ "assert": {
24
+ "diagnostics": { "noConsoleErrors": true, "runtimeReady": true },
25
+ "resources": [
26
+ {
27
+ "id": "GameState",
28
+ "path": "sameDistanceRanking",
29
+ "atSteps": [
30
+ { "label": "lap-aware-baseline", "equals": "lap-ahead" },
31
+ { "label": "advance-on-route", "equals": "lap-ahead" }
32
+ ]
33
+ },
34
+ { "id": "GameState", "path": "trackProgress", "gte": 142, "changed": true }
35
+ ]
36
+ }
37
+ }
@@ -0,0 +1,28 @@
1
+ {
2
+ "name": "racing-rescue-transform",
3
+ "schemaVersion": 1,
4
+ "target": "web",
5
+ "viewport": { "width": 1280, "height": 720 },
6
+ "warmupFrames": 10,
7
+ "subject": "player",
8
+ "steps": [
9
+ {
10
+ "kind": "input",
11
+ "label": "rescue",
12
+ "press": ["ArrowUp", "ArrowRight"],
13
+ "holdTicks": 150,
14
+ "release": true
15
+ }
16
+ ],
17
+ "assert": {
18
+ "diagnostics": { "noConsoleErrors": true, "runtimeReady": true },
19
+ "resources": [
20
+ { "id": "GameState", "path": "rescues", "gte": 1, "changed": true },
21
+ { "id": "GameState", "path": "lastOnRoad", "changed": true },
22
+ { "id": "GameState", "path": "rescueHeading", "changed": true },
23
+ { "id": "GameState", "path": "rescuePositionError", "equals": 0, "changed": true },
24
+ { "id": "GameState", "path": "rescueHeadingError", "equals": 0, "changed": true }
25
+ ],
26
+ "visibility": [{ "entity": "player", "minProjectedPixels": 20 }]
27
+ }
28
+ }
@@ -0,0 +1,37 @@
1
+ {
2
+ "name": "racing-reverse-finish-rejected",
3
+ "schemaVersion": 1,
4
+ "target": "web",
5
+ "viewport": { "width": 1280, "height": 720 },
6
+ "warmupFrames": 10,
7
+ "subject": "player",
8
+ "steps": [
9
+ {
10
+ "kind": "input",
11
+ "label": "reach-mid-course",
12
+ "press": "ArrowUp",
13
+ "holdTicks": 100,
14
+ "release": true
15
+ },
16
+ {
17
+ "kind": "input",
18
+ "label": "reverse-through-finish",
19
+ "press": "ArrowDown",
20
+ "holdTicks": 150,
21
+ "release": true
22
+ },
23
+ { "kind": "wait", "label": "observe-rejection", "waitTicks": 20, "release": true }
24
+ ],
25
+ "assert": {
26
+ "diagnostics": { "noConsoleErrors": true, "runtimeReady": true },
27
+ "resources": [
28
+ {
29
+ "id": "GameState",
30
+ "path": "completedLaps",
31
+ "equals": 0,
32
+ "allowTrivial": true
33
+ },
34
+ { "id": "GameState", "path": "reverseRejects", "gte": 1, "changed": true }
35
+ ]
36
+ }
37
+ }
@@ -0,0 +1,44 @@
1
+ {
2
+ "name": "racing-shortcut-rejected",
3
+ "schemaVersion": 1,
4
+ "target": "web",
5
+ "viewport": { "width": 1280, "height": 720 },
6
+ "warmupFrames": 10,
7
+ "subject": "player",
8
+ "artifacts": { "screenshots": "before-after" },
9
+ "steps": [
10
+ {
11
+ "kind": "input",
12
+ "label": "drive-directly-at-finish",
13
+ "press": "ArrowUp",
14
+ "holdTicks": 100,
15
+ "release": true
16
+ },
17
+ { "kind": "wait", "label": "observe-rejection", "waitTicks": 20, "release": true }
18
+ ],
19
+ "assert": {
20
+ "diagnostics": { "noConsoleErrors": true, "runtimeReady": true },
21
+ "movement": { "entity": "player", "minDistance": 3 },
22
+ "visual": [
23
+ { "frameDiff": { "minChangedPixelRatio": 0.01 } },
24
+ {
25
+ "region": {
26
+ "x": 0,
27
+ "y": 0,
28
+ "width": 1280,
29
+ "height": 720,
30
+ "minNonblankPixelRatio": 0.9
31
+ }
32
+ }
33
+ ],
34
+ "resources": [
35
+ {
36
+ "id": "GameState",
37
+ "path": "completedLaps",
38
+ "equals": 0,
39
+ "allowTrivial": true
40
+ },
41
+ { "id": "GameState", "path": "shortcutRejects", "gte": 1, "changed": true }
42
+ ]
43
+ }
44
+ }
@@ -0,0 +1,32 @@
1
+ {
2
+ "name": "survives",
3
+ "target": "web",
4
+ "schemaVersion": 1,
5
+ "viewport": { "width": 1280, "height": 720 },
6
+ "warmupFrames": 10,
7
+ "subject": "player",
8
+ "steps": [
9
+ { "kind": "input", "label": "move", "press": "ArrowUp", "holdTicks": 60, "release": true },
10
+ { "kind": "wait", "label": "settle", "waitTicks": 10, "release": true }
11
+ ],
12
+ "assert": {
13
+ "diagnostics": {
14
+ "noConsoleErrors": true,
15
+ "noNetworkErrors": true,
16
+ "noRuntimeDiagnostics": true,
17
+ "runtimeReady": true
18
+ },
19
+ "movement": { "entity": "player", "minDistance": 0.5 },
20
+ "visual": [
21
+ {
22
+ "region": {
23
+ "x": 0,
24
+ "y": 0,
25
+ "width": 1280,
26
+ "height": 720,
27
+ "minNonblankPixelRatio": 0.01
28
+ }
29
+ }
30
+ ]
31
+ }
32
+ }
@@ -0,0 +1,6 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
2
+ <rect width="64" height="64" rx="14" fill="#07111d"/>
3
+ <path d="M12 42h40L43 22H21z" fill="#ffcf4a"/>
4
+ <circle cx="21" cy="43" r="6" fill="#07111d"/>
5
+ <circle cx="43" cy="43" r="6" fill="#07111d"/>
6
+ </svg>