create-threenative 0.2.1 → 0.2.3

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 (343) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +10 -2
  3. package/agent-docs/asset-mcp-loop.md +33 -0
  4. package/agent-docs/ctx-surface.md +69 -0
  5. package/agent-docs/engine-capabilities.md +4 -0
  6. package/agent-docs/framework-blocks-you.md +60 -0
  7. package/agent-docs/look-at-it-and-budget-the-look.md +27 -0
  8. package/agent-docs/performance-default.md +42 -0
  9. package/agent-docs/pixel-budget.md +20 -0
  10. package/agent-docs/playtest-fail-closed.md +23 -0
  11. package/agent-docs/references/assertion-reference.md +652 -0
  12. package/agent-docs/references/capability-reference.md +3279 -0
  13. package/agent-docs/references/capture-the-frame.md +53 -0
  14. package/agent-docs/references/ctx-cookbook.md +51 -0
  15. package/agent-docs/references/debug-surface.md +63 -0
  16. package/agent-docs/references/finding-assets.md +147 -0
  17. package/agent-docs/references/gameplay-recipes.md +54 -0
  18. package/agent-docs/references/menu-screens.md +69 -0
  19. package/agent-docs/references/mobile-memory-budget.md +87 -0
  20. package/agent-docs/references/sculpt-from-a-reference.md +39 -0
  21. package/agent-docs/references/visual-baseline.md +133 -0
  22. package/agent-docs/references/webview-ui.md +113 -0
  23. package/agent-docs/sculpt-loop.md +16 -0
  24. package/agent-files/.agents/skills/threenative-builder/SKILL.md +7 -0
  25. package/agent-files/.agents/skills/threenative-verifier/SKILL.md +7 -0
  26. package/agent-files/.claude/agents/threenative-builder.md +7 -0
  27. package/agent-files/.claude/agents/threenative-verifier.md +7 -0
  28. package/agent-files/.threenative/agents/builder.md +32 -0
  29. package/agent-files/.threenative/agents/verifier.md +31 -0
  30. package/agent-files/AGENT-ROLES.md +26 -0
  31. package/capabilities.json +3542 -0
  32. package/dist/index.d.ts +191 -3
  33. package/dist/index.js +1707 -73
  34. package/dist/threenative.d.ts +9 -2
  35. package/dist/threenative.js +1825 -148
  36. package/package.json +30 -6
  37. package/template-assets/loading.ts +315 -0
  38. package/template-assets/patches/three@0.185.1.patch +287 -0
  39. package/templates/action-rpg/.codex/config.toml +15 -0
  40. package/templates/action-rpg/.mcp.json +6 -2
  41. package/templates/action-rpg/AGENTS.md +370 -6
  42. package/templates/action-rpg/CLAUDE.md +370 -6
  43. package/templates/action-rpg/index.html +0 -1
  44. package/templates/action-rpg/package.json +15 -11
  45. package/templates/action-rpg/playtests/combat.playtest.json +23 -9
  46. package/templates/action-rpg/playtests/fail.playtest.json +3 -3
  47. package/templates/action-rpg/playtests/inventory.playtest.json +16 -10
  48. package/templates/action-rpg/playtests/performance.playtest.json +22 -0
  49. package/templates/action-rpg/playtests/progress.playtest.json +18 -13
  50. package/templates/action-rpg/playtests/win.playtest.json +10 -4
  51. package/templates/action-rpg/public/icon.png +0 -0
  52. package/templates/action-rpg/src/entities/Enemy.ts +14 -4
  53. package/templates/action-rpg/src/game.ts +21 -0
  54. package/templates/action-rpg/src/render/lighting.ts +6 -1
  55. package/templates/action-rpg/src/render/loading.ts +267 -42
  56. package/templates/action-rpg/src/render/postprocessing.ts +68 -15
  57. package/templates/action-rpg/src/render/worldEnvironment.ts +583 -0
  58. package/templates/action-rpg/src/scenes/Play.ts +49 -19
  59. package/templates/action-rpg/src/state.ts +4 -0
  60. package/templates/action-rpg/src/style.css +45 -1
  61. package/templates/action-rpg/src/ui/AbilityBar.tsx +9 -7
  62. package/templates/action-rpg/src/ui/App.tsx +9 -8
  63. package/templates/action-rpg/src/ui/CharacterPanel.tsx +10 -8
  64. package/templates/action-rpg/src/ui/GameUi.tsx +24 -0
  65. package/templates/action-rpg/src/ui/Hud.tsx +10 -8
  66. package/templates/action-rpg/src/ui/InventoryPanel.tsx +9 -7
  67. package/templates/action-rpg/src/ui/main.tsx +14 -0
  68. package/templates/action-rpg/threenative.config.ts +21 -8
  69. package/templates/action-rpg/vite.config.ts +32 -2
  70. package/templates/defense/.codex/config.toml +15 -0
  71. package/templates/defense/.mcp.json +6 -2
  72. package/templates/defense/AGENTS.md +371 -8
  73. package/templates/defense/CLAUDE.md +371 -8
  74. package/templates/defense/README.md +2 -1
  75. package/templates/defense/index.html +0 -1
  76. package/templates/defense/package.json +16 -12
  77. package/templates/defense/playtests/leak.playtest.json +9 -4
  78. package/templates/defense/playtests/performance.playtest.json +22 -0
  79. package/templates/defense/playtests/placement.playtest.json +5 -5
  80. package/templates/defense/playtests/pointer-placement.playtest.json +89 -0
  81. package/templates/defense/playtests/scan.playtest.json +3 -3
  82. package/templates/defense/playtests/survive.playtest.json +11 -6
  83. package/templates/defense/public/icon.png +0 -0
  84. package/templates/defense/src/attackers/Attacker.ts +28 -12
  85. package/templates/defense/src/game.ts +24 -2
  86. package/templates/defense/src/render/lighting.ts +6 -1
  87. package/templates/defense/src/render/loading.ts +263 -37
  88. package/templates/defense/src/render/postprocessing.ts +70 -13
  89. package/templates/defense/src/render/shapes.ts +38 -0
  90. package/templates/defense/src/render/worldEnvironment.ts +583 -0
  91. package/templates/defense/src/scenes/Defense.ts +109 -50
  92. package/templates/defense/src/state.ts +6 -0
  93. package/templates/defense/src/style.css +45 -1
  94. package/templates/defense/src/ui/App.tsx +9 -4
  95. package/templates/defense/src/ui/GameUi.tsx +20 -0
  96. package/templates/defense/src/ui/Hud.tsx +6 -5
  97. package/templates/defense/src/ui/main.tsx +14 -0
  98. package/templates/defense/threenative.config.ts +21 -8
  99. package/templates/defense/vite.config.ts +34 -1
  100. package/templates/minimal/.codex/config.toml +15 -0
  101. package/templates/minimal/.mcp.json +6 -2
  102. package/templates/minimal/AGENTS.md +360 -255
  103. package/templates/minimal/CLAUDE.md +360 -255
  104. package/templates/minimal/index.html +0 -1
  105. package/templates/minimal/package.json +14 -11
  106. package/templates/minimal/playtests/atmosphere.playtest.json +32 -0
  107. package/templates/minimal/playtests/play.playtest.json +17 -5
  108. package/templates/minimal/public/icon.png +0 -0
  109. package/templates/minimal/src/game.ts +1 -0
  110. package/templates/minimal/src/render/camera.ts +1 -1
  111. package/templates/minimal/src/render/hud.ts +24 -8
  112. package/templates/minimal/src/render/lighting.ts +23 -2
  113. package/templates/minimal/src/render/loading.ts +23 -103
  114. package/templates/minimal/src/render/postprocessing.ts +92 -14
  115. package/templates/minimal/src/render/sky.ts +37 -32
  116. package/templates/minimal/src/render/worldEnvironment.ts +583 -0
  117. package/templates/minimal/src/scenes/Play.ts +91 -13
  118. package/templates/minimal/src/state.ts +8 -1
  119. package/templates/minimal/threenative.config.ts +15 -10
  120. package/templates/minimal/vite.config.ts +28 -1
  121. package/templates/platformer/.codex/config.toml +15 -0
  122. package/templates/platformer/.mcp.json +6 -2
  123. package/templates/platformer/AGENTS.md +385 -130
  124. package/templates/platformer/CLAUDE.md +385 -130
  125. package/templates/platformer/index.html +0 -1
  126. package/templates/platformer/package.json +17 -14
  127. package/templates/platformer/playtests/avoidance.playtest.json +6 -1
  128. package/templates/platformer/playtests/branding.playtest.json +29 -0
  129. package/templates/platformer/playtests/buffer.playtest.json +1 -1
  130. package/templates/platformer/playtests/collect.playtest.json +1 -1
  131. package/templates/platformer/playtests/collision-layers.playtest.json +2 -2
  132. package/templates/platformer/playtests/coyote.playtest.json +42 -8
  133. package/templates/platformer/playtests/damage.playtest.json +4 -1
  134. package/templates/platformer/playtests/dash.playtest.json +2 -2
  135. package/templates/platformer/playtests/jump.playtest.json +2 -3
  136. package/templates/platformer/playtests/native/touch-controls.playtest.json +33 -0
  137. package/templates/platformer/playtests/oneway.playtest.json +1 -1
  138. package/templates/platformer/playtests/performance.playtest.json +6 -5
  139. package/templates/platformer/playtests/respawn.playtest.json +2 -2
  140. package/templates/platformer/playtests/stomp-rise.playtest.json +17 -3
  141. package/templates/platformer/playtests/stomp.playtest.json +11 -3
  142. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +13 -4
  143. package/templates/platformer/playtests/terminal-loop-win.playtest.json +3 -3
  144. package/templates/platformer/playtests/touch-controls-web.playtest.json +46 -0
  145. package/templates/platformer/public/icon.png +0 -0
  146. package/templates/platformer/src/entities/Character.ts +16 -10
  147. package/templates/platformer/src/entities/Patrol.ts +5 -0
  148. package/templates/platformer/src/game.ts +24 -1
  149. package/templates/platformer/src/render/lighting.ts +6 -1
  150. package/templates/platformer/src/render/loading.ts +270 -61
  151. package/templates/platformer/src/render/postprocessing.ts +68 -15
  152. package/templates/platformer/src/render/touch-controls.ts +54 -36
  153. package/templates/platformer/src/render/worldEnvironment.ts +583 -0
  154. package/templates/platformer/src/scenes/Level.ts +47 -22
  155. package/templates/platformer/src/state.ts +4 -0
  156. package/templates/platformer/src/style.css +45 -1
  157. package/templates/platformer/src/ui/App.tsx +9 -4
  158. package/templates/platformer/src/ui/GameUi.tsx +20 -0
  159. package/templates/platformer/src/ui/Hud.tsx +6 -5
  160. package/templates/platformer/src/ui/main.tsx +14 -0
  161. package/templates/platformer/threenative.config.ts +20 -10
  162. package/templates/platformer/vite.config.ts +34 -1
  163. package/templates/racing/.codex/config.toml +15 -0
  164. package/templates/racing/.mcp.json +6 -2
  165. package/templates/racing/AGENTS.md +370 -6
  166. package/templates/racing/CLAUDE.md +370 -6
  167. package/templates/racing/index.html +0 -1
  168. package/templates/racing/package.json +16 -12
  169. package/templates/racing/playtests/boost.playtest.json +5 -5
  170. package/templates/racing/playtests/outcome.playtest.json +14 -4
  171. package/templates/racing/playtests/performance.playtest.json +22 -0
  172. package/templates/racing/playtests/ranking.playtest.json +2 -2
  173. package/templates/racing/playtests/rescue.playtest.json +12 -6
  174. package/templates/racing/playtests/reverse.playtest.json +3 -3
  175. package/templates/racing/playtests/shortcut.playtest.json +3 -3
  176. package/templates/racing/public/icon.png +0 -0
  177. package/templates/racing/src/game.ts +24 -1
  178. package/templates/racing/src/render/camera.ts +10 -6
  179. package/templates/racing/src/render/lighting.ts +6 -1
  180. package/templates/racing/src/render/loading.ts +291 -34
  181. package/templates/racing/src/render/postprocessing.ts +70 -13
  182. package/templates/racing/src/render/worldEnvironment.ts +583 -0
  183. package/templates/racing/src/scenes/Race.ts +68 -36
  184. package/templates/racing/src/state.ts +4 -0
  185. package/templates/racing/src/style.css +45 -1
  186. package/templates/racing/src/track/Lap.ts +20 -9
  187. package/templates/racing/src/track/Ranking.ts +53 -14
  188. package/templates/racing/src/track/Track.ts +29 -16
  189. package/templates/racing/src/track/TrackSector.ts +14 -4
  190. package/templates/racing/src/ui/App.tsx +9 -4
  191. package/templates/racing/src/ui/GameUi.tsx +20 -0
  192. package/templates/racing/src/ui/Hud.tsx +6 -5
  193. package/templates/racing/src/ui/main.tsx +14 -0
  194. package/templates/racing/threenative.config.ts +21 -8
  195. package/templates/racing/vite.config.ts +34 -1
  196. package/templates/sailing/.codex/config.toml +15 -0
  197. package/templates/sailing/.mcp.json +20 -0
  198. package/templates/sailing/AGENTS.md +388 -0
  199. package/templates/sailing/CLAUDE.md +390 -0
  200. package/templates/sailing/README.md +25 -0
  201. package/templates/sailing/index.html +12 -0
  202. package/templates/sailing/kit.json +7 -0
  203. package/templates/sailing/native-playtests/survives.playtest.json +21 -0
  204. package/templates/sailing/package.json +52 -0
  205. package/templates/sailing/playtests/fail.playtest.json +24 -0
  206. package/templates/sailing/playtests/performance.playtest.json +21 -0
  207. package/templates/sailing/playtests/survives.playtest.json +38 -0
  208. package/templates/sailing/playtests/win.playtest.json +31 -0
  209. package/templates/sailing/public/favicon.svg +5 -0
  210. package/templates/sailing/public/icon.png +0 -0
  211. package/templates/sailing/src/entities/Ship.ts +96 -0
  212. package/templates/sailing/src/game.ts +40 -0
  213. package/templates/sailing/src/main.ts +15 -0
  214. package/templates/sailing/src/render/camera.ts +21 -0
  215. package/templates/sailing/src/render/lighting.ts +36 -0
  216. package/templates/sailing/src/render/loading.ts +315 -0
  217. package/templates/sailing/src/render/materials.ts +28 -0
  218. package/templates/sailing/src/render/palette.ts +24 -0
  219. package/templates/sailing/src/render/postprocessing.ts +33 -0
  220. package/templates/sailing/src/render/props.ts +52 -0
  221. package/templates/sailing/src/render/sky.ts +32 -0
  222. package/templates/sailing/src/render/water-material.ts +14 -0
  223. package/templates/sailing/src/render/water-shaders.ts +12 -0
  224. package/templates/sailing/src/render/wave-nodes.ts +10 -0
  225. package/templates/sailing/src/render/worldEnvironment.ts +590 -0
  226. package/templates/sailing/src/scenes/Boot.ts +12 -0
  227. package/templates/sailing/src/scenes/Sailing.ts +106 -0
  228. package/templates/sailing/src/state.ts +10 -0
  229. package/templates/sailing/src/style.css +61 -0
  230. package/templates/sailing/src/ui/App.tsx +15 -0
  231. package/templates/sailing/src/ui/GameUi.tsx +12 -0
  232. package/templates/sailing/src/ui/Hud.tsx +55 -0
  233. package/templates/sailing/src/ui/Menu.tsx +30 -0
  234. package/templates/sailing/src/ui/main.tsx +7 -0
  235. package/templates/sailing/tailwind.config.ts +2 -0
  236. package/templates/sailing/threenative.config.ts +34 -0
  237. package/templates/sailing/tsconfig.json +17 -0
  238. package/templates/sailing/vite.config.ts +34 -0
  239. package/templates/shooter/.codex/config.toml +15 -0
  240. package/templates/shooter/.mcp.json +6 -2
  241. package/templates/shooter/AGENTS.md +373 -7
  242. package/templates/shooter/CLAUDE.md +373 -7
  243. package/templates/shooter/index.html +0 -1
  244. package/templates/shooter/package.json +16 -11
  245. package/templates/shooter/playtests/fail.playtest.json +5 -4
  246. package/templates/shooter/playtests/input-control.playtest.json +131 -0
  247. package/templates/shooter/playtests/per-item.playtest.json +59 -0
  248. package/templates/shooter/playtests/performance.playtest.json +22 -0
  249. package/templates/shooter/playtests/shooter.playtest.json +22 -18
  250. package/templates/shooter/playtests/survives.playtest.json +1 -1
  251. package/templates/shooter/public/favicon.svg +1 -1
  252. package/templates/shooter/public/icon.png +0 -0
  253. package/templates/shooter/src/game.ts +24 -1
  254. package/templates/shooter/src/main.ts +3 -13
  255. package/templates/shooter/src/render/camera.ts +62 -12
  256. package/templates/shooter/src/render/lighting.ts +6 -1
  257. package/templates/shooter/src/render/loading.ts +262 -33
  258. package/templates/shooter/src/render/palette.ts +1 -1
  259. package/templates/shooter/src/render/postprocessing.ts +68 -16
  260. package/templates/shooter/src/render/shapes.ts +178 -0
  261. package/templates/shooter/src/render/ui.css +34 -1
  262. package/templates/shooter/src/render/worldEnvironment.ts +583 -0
  263. package/templates/shooter/src/scenes/Play.ts +246 -73
  264. package/templates/shooter/src/state.ts +13 -0
  265. package/templates/shooter/src/style.css +26 -0
  266. package/templates/shooter/src/ui/App.tsx +10 -12
  267. package/templates/shooter/src/ui/GameUi.tsx +20 -0
  268. package/templates/shooter/src/ui/Hud.tsx +8 -10
  269. package/templates/shooter/src/ui/Menu.tsx +24 -9
  270. package/templates/shooter/src/ui/main.tsx +15 -0
  271. package/templates/shooter/src/weapons/Projectile.ts +21 -10
  272. package/templates/shooter/threenative.config.ts +21 -8
  273. package/templates/shooter/vite.config.ts +32 -2
  274. package/templates/starter/.codex/config.toml +15 -0
  275. package/templates/starter/.mcp.json +6 -2
  276. package/templates/starter/AGENTS.md +429 -326
  277. package/templates/starter/CLAUDE.md +429 -326
  278. package/templates/starter/assets/pickup.wav +0 -0
  279. package/templates/starter/gitignore +4 -0
  280. package/templates/starter/index.html +0 -1
  281. package/templates/starter/native-playtests/react-hud.playtest.json +20 -0
  282. package/templates/starter/native-playtests/render-chain.playtest.json +12 -0
  283. package/templates/starter/package.json +16 -12
  284. package/templates/starter/playtests/assets.playtest.json +65 -0
  285. package/templates/starter/playtests/buffer.playtest.json +59 -9
  286. package/templates/starter/playtests/cloth.playtest.json +113 -0
  287. package/templates/starter/playtests/coyote.playtest.json +60 -8
  288. package/templates/starter/playtests/forward.playtest.json +29 -4
  289. package/templates/starter/playtests/gameover.playtest.json +66 -0
  290. package/templates/starter/playtests/goal.playtest.json +67 -0
  291. package/templates/starter/playtests/hot-reload.playtest.json +48 -8
  292. package/templates/starter/playtests/look.playtest.json +34 -6
  293. package/templates/starter/playtests/models-baseline.png +0 -0
  294. package/templates/starter/playtests/models.playtest.json +74 -0
  295. package/templates/starter/playtests/monitoring.playtest.json +38 -7
  296. package/templates/starter/playtests/odometer.playtest.json +54 -0
  297. package/templates/starter/playtests/pause.playtest.json +27 -4
  298. package/templates/starter/playtests/play.playtest.json +43 -7
  299. package/templates/starter/playtests/respawn.playtest.json +46 -6
  300. package/templates/starter/playtests/restart.playtest.json +65 -10
  301. package/templates/starter/playtests/seed.playtest.json +44 -8
  302. package/templates/starter/playtests/survives.playtest.json +27 -4
  303. package/templates/starter/playtests/textures-baseline.png +0 -0
  304. package/templates/starter/playtests/textures.playtest.json +74 -0
  305. package/templates/starter/playtests/zoom-pinch.playtest.json +86 -0
  306. package/templates/starter/playtests/zoom-wheel.playtest.json +59 -0
  307. package/templates/starter/public/icon.png +0 -0
  308. package/templates/starter/src/entities/Goal.ts +122 -0
  309. package/templates/starter/src/entities/Player.ts +40 -2
  310. package/templates/starter/src/game.ts +25 -0
  311. package/templates/starter/src/render/camera.ts +31 -5
  312. package/templates/starter/src/render/easing.ts +5 -0
  313. package/templates/starter/src/render/effects/gradualBackground.ts +48 -0
  314. package/templates/starter/src/render/effects/lensDistortion.ts +43 -0
  315. package/templates/starter/src/render/effects/sparkle.ts +49 -0
  316. package/templates/starter/src/render/lighting.ts +6 -1
  317. package/templates/starter/src/render/loading.ts +315 -0
  318. package/templates/starter/src/render/materials.ts +17 -1
  319. package/templates/starter/src/render/pennant.ts +54 -0
  320. package/templates/starter/src/render/postprocessing.ts +46 -15
  321. package/templates/starter/src/render/scenery.ts +83 -0
  322. package/templates/starter/src/render/shapes.ts +9 -21
  323. package/templates/starter/src/render/worldEnvironment.ts +583 -0
  324. package/templates/starter/src/scenes/Play.ts +146 -36
  325. package/templates/starter/src/state.ts +12 -0
  326. package/templates/starter/src/style.css +45 -1
  327. package/templates/starter/src/ui/App.tsx +9 -6
  328. package/templates/starter/src/ui/GameUi.tsx +20 -0
  329. package/templates/starter/src/ui/Hud.tsx +52 -29
  330. package/templates/starter/src/ui/Menu.tsx +25 -23
  331. package/templates/starter/src/ui/main.tsx +14 -0
  332. package/templates/starter/threenative.config.ts +27 -9
  333. package/templates/starter/tools/look.mjs +109 -0
  334. package/templates/starter/vite.config.ts +32 -2
  335. package/templates/minimal/assets/.gitkeep +0 -0
  336. package/templates/minimal/public/.gitkeep +0 -0
  337. package/templates/platformer/assets/.gitkeep +0 -0
  338. package/templates/platformer/public/.gitkeep +0 -0
  339. package/templates/starter/assets/.gitkeep +0 -0
  340. package/templates/starter/public/.gitkeep +0 -0
  341. package/templates/starter/public/pickup.ogg +0 -0
  342. /package/templates/starter/{public → assets}/native-proof.glb +0 -0
  343. /package/templates/starter/{public → assets}/native-proof.png +0 -0
@@ -1,4 +1,4 @@
1
- import { type ICtx, Scene, type SceneFrame } from "@threenative/core";
1
+ import { type ICtx, Scene, type SceneFrame, isMobile } from "@threenative/core";
2
2
  import type { IPhysicsContext } from "@threenative/physics";
3
3
  import { type PerspectiveCamera, Vector3 } from "three";
4
4
  import { RACING_FEEL, RacingCar } from "../entities/RacingCar.js";
@@ -13,7 +13,7 @@ import { flag } from "../render/shapes.js";
13
13
  import { setupSky } from "../render/sky.js";
14
14
  import { type GameState, type RaceStatus, resolveRaceStatus } from "../state.js";
15
15
  import { Lap } from "../track/Lap.js";
16
- import { rankRacers } from "../track/Ranking.js";
16
+ import { type IRankedRacer, type IRankedRacerScratch, rankRacers } from "../track/Ranking.js";
17
17
  import { TOTAL_LAPS, buildTrack, intersectRay, roadRayProbe } from "../track/Track.js";
18
18
  import { TrackSector } from "../track/TrackSector.js";
19
19
 
@@ -22,8 +22,22 @@ export type GameCtx = ICtx<GameState, IPhysicsContext>;
22
22
  const SPAWN = new Vector3(2, 0.55, -18);
23
23
  const TIME_LIMIT = 90;
24
24
 
25
+ function playerRanking(ranked: readonly IRankedRacer[]): IRankedRacer | undefined {
26
+ for (let index = 0; index < ranked.length; index += 1) {
27
+ const racer = ranked[index];
28
+ if (racer?.id === "player") return racer;
29
+ }
30
+ return undefined;
31
+ }
32
+
33
+ function quantize(value: number, scale: number): number {
34
+ return Math.round(value * scale) / scale;
35
+ }
36
+
25
37
  export class Race extends Scene<GameState, IPhysicsContext> {
26
38
  static override readonly initialState: GameState = {
39
+ paused: false,
40
+ uiReady: false,
27
41
  boostActive: false,
28
42
  boostPeakSpeed: 0,
29
43
  boostUses: 0,
@@ -49,8 +63,10 @@ export class Race extends Scene<GameState, IPhysicsContext> {
49
63
 
50
64
  override enter(ctx: GameCtx): SceneFrame<GameState, IPhysicsContext> {
51
65
  setupSky(ctx.scene);
52
- setupLighting(ctx.scene, ctx.renderer.raw as Parameters<typeof setupLighting>[1]);
53
- setupPost(ctx.renderer, ctx.scene, ctx.camera);
66
+ const sun = setupLighting(ctx.scene, ctx.renderer.raw as Parameters<typeof setupLighting>[1]);
67
+ // isMobile() arrives as an argument because src/render/ imports no framework package: the
68
+ // platform decision is made here, in portable game code, exactly like createRandom.
69
+ setupPost(ctx.renderer, ctx.scene, ctx.camera, { godraysLight: sun, mobile: isMobile() });
54
70
  const loading = createLoadingScreen(ctx);
55
71
  const camera = ctx.camera as PerspectiveCamera;
56
72
  setupCamera(camera);
@@ -77,13 +93,17 @@ export class Race extends Scene<GameState, IPhysicsContext> {
77
93
  TOTAL_LAPS,
78
94
  (completed) => emitPlaytestEvent({ entity: "player", lap: completed, name: "lap-completed" }),
79
95
  );
80
- const rankRace = () =>
81
- rankRacers(track.route, [
82
- { id: "player", lap: lap.completed, position: car.mesh.position },
83
- { id: "rival", lap: rival.lap, position: rival.mesh.position },
84
- ]);
96
+ const playerRankingInput = { id: "player", lap: lap.completed, position: car.mesh.position };
97
+ const rivalRankingInput = { id: "rival", lap: rival.lap, position: rival.mesh.position };
98
+ const rankingInputs = [playerRankingInput, rivalRankingInput];
99
+ const rankingBuffer: IRankedRacerScratch[] = [];
100
+ const rankRace = () => {
101
+ playerRankingInput.lap = lap.completed;
102
+ rivalRankingInput.lap = rival.lap;
103
+ return rankRacers(track.route, rankingInputs, undefined, rankingBuffer);
104
+ };
85
105
  const initialRanked = rankRace();
86
- const initialPlayer = initialRanked.find((entry) => entry.id === "player");
106
+ const initialPlayer = playerRanking(initialRanked);
87
107
  if (initialPlayer === undefined) throw new Error("Race ranking lost the player at spawn.");
88
108
  const fallbackProbe = roadRayProbe(track.roadMeshes);
89
109
  const sector = new TrackSector({
@@ -105,6 +125,9 @@ export class Race extends Scene<GameState, IPhysicsContext> {
105
125
  let speedAfterBoost = 0;
106
126
  let boostSettled = false;
107
127
  let sameDistanceRanking = initialRanked[0]?.id === "rival" ? "lap-ahead" : "lap-behind";
128
+ let place = initialPlayer.place;
129
+ let positionLabel = `P${place}`;
130
+ const lastOnRoad: [number, number, number] = [SPAWN.x, SPAWN.y, SPAWN.z];
108
131
  const observedPosition = SPAWN.clone();
109
132
  sector.update(SPAWN, car.forward, 0);
110
133
  chaseCamera(camera, car.mesh.position, car.forward, 1);
@@ -118,15 +141,18 @@ export class Race extends Scene<GameState, IPhysicsContext> {
118
141
  sector.update(car.mesh.position, car.forward, dt);
119
142
  if (sector.rescue(car)) {
120
143
  rescues += 1;
121
- rescuePositionError = Number(
122
- car.mesh.position.distanceTo(sector.lastOnRoadPosition).toFixed(4),
144
+ rescuePositionError = quantize(
145
+ car.mesh.position.distanceTo(sector.lastOnRoadPosition),
146
+ 10_000,
123
147
  );
124
- rescueHeadingError = Number(car.forward.angleTo(sector.lastOnRoadHeading).toFixed(4));
148
+ rescueHeadingError = quantize(car.forward.angleTo(sector.lastOnRoadHeading), 10_000);
125
149
  emitPlaytestEvent({ entity: "player", name: "rescued" });
126
150
  }
127
151
  if (elapsed >= TIME_LIMIT || rescues >= 4) status = "DNF";
128
152
  };
129
153
 
154
+ const statePatch: Partial<GameState> = {};
155
+
130
156
  return (frameCtx, dt) => {
131
157
  loading.update();
132
158
  if (frameCtx.input.justPressed("restart")) {
@@ -145,34 +171,40 @@ export class Race extends Scene<GameState, IPhysicsContext> {
145
171
  }
146
172
  }
147
173
  const ranked = rankRace();
148
- const player = ranked.find((entry) => entry.id === "player");
174
+ const player = playerRanking(ranked);
149
175
  if (player === undefined) throw new Error("Race ranking lost the player.");
150
176
  sameDistanceRanking = ranked[0]?.id === "rival" ? "lap-ahead" : "lap-behind";
151
177
  status = resolveRaceStatus(status, lap.completed, TOTAL_LAPS, player.place);
178
+ if (player.place !== place) {
179
+ place = player.place;
180
+ positionLabel = `P${place}`;
181
+ }
152
182
  const previous = frameCtx.state.getState();
153
183
  const boostPeakSpeed = Math.max(previous.boostPeakSpeed, car.boost.active ? car.speed : 0);
154
- frameCtx.state.set({
155
- boostActive: car.boost.active,
156
- boostPeakSpeed,
157
- boostUses: car.boost.uses,
158
- completedLaps: lap.completed,
159
- elapsed,
160
- lastOnRoad: sector.lastOnRoadPosition.toArray() as [number, number, number],
161
- place: player.place,
162
- position: `P${player.place}`,
163
- raceStatus: status,
164
- rescueHeading: Math.atan2(sector.lastOnRoadHeading.z, sector.lastOnRoadHeading.x),
165
- rescueHeadingError,
166
- rescuePositionError,
167
- rescues,
168
- shortcutRejects: lap.shortcutRejects,
169
- speed: car.speed,
170
- speedAfterBoost,
171
- sameDistanceRanking,
172
- topSpeed: Math.max(previous.topSpeed, car.topSpeed),
173
- trackProgress: player.routeProgress,
174
- reverseRejects: lap.reverseRejects,
175
- });
184
+ lastOnRoad[0] = sector.lastOnRoadPosition.x;
185
+ lastOnRoad[1] = sector.lastOnRoadPosition.y;
186
+ lastOnRoad[2] = sector.lastOnRoadPosition.z;
187
+ statePatch.boostActive = car.boost.active;
188
+ statePatch.boostPeakSpeed = boostPeakSpeed;
189
+ statePatch.boostUses = car.boost.uses;
190
+ statePatch.completedLaps = lap.completed;
191
+ statePatch.elapsed = elapsed;
192
+ statePatch.lastOnRoad = lastOnRoad;
193
+ statePatch.place = player.place;
194
+ statePatch.position = positionLabel;
195
+ statePatch.raceStatus = status;
196
+ statePatch.rescueHeading = Math.atan2(sector.lastOnRoadHeading.z, sector.lastOnRoadHeading.x);
197
+ statePatch.rescueHeadingError = rescueHeadingError;
198
+ statePatch.rescuePositionError = rescuePositionError;
199
+ statePatch.rescues = rescues;
200
+ statePatch.shortcutRejects = lap.shortcutRejects;
201
+ statePatch.speed = car.speed;
202
+ statePatch.speedAfterBoost = speedAfterBoost;
203
+ statePatch.sameDistanceRanking = sameDistanceRanking;
204
+ statePatch.topSpeed = Math.max(previous.topSpeed, car.topSpeed);
205
+ statePatch.trackProgress = player.routeProgress;
206
+ statePatch.reverseRejects = lap.reverseRejects;
207
+ frameCtx.state.set(statePatch);
176
208
  chaseCamera(camera, car.mesh.position, car.forward, dt);
177
209
  cameraRoll(camera, car.forward);
178
210
  };
@@ -11,6 +11,10 @@ export function resolveRaceStatus(
11
11
  }
12
12
 
13
13
  export type GameState = {
14
+ /** Set from the UI\'s pause and resume intents, and read back by the menu. */
15
+ paused: boolean;
16
+ /** True once the UI layer has rendered and published its interactive rectangles. */
17
+ uiReady: boolean;
14
18
  boostActive: boolean;
15
19
  boostPeakSpeed: number;
16
20
  speedAfterBoost: number;
@@ -25,8 +25,52 @@ body,
25
25
  }
26
26
 
27
27
  body {
28
- background: var(--color-ink);
29
28
  color: var(--color-text);
30
29
  font-family: var(--font-mono);
31
30
  -webkit-font-smoothing: antialiased;
32
31
  }
32
+
33
+ /*
34
+ * The page's backdrop belongs to the web document's own mount point, never to `body`.
35
+ * `src/ui/main.tsx` imports this same stylesheet, and on native that file is what the platform's
36
+ * transparent web view loads over the game: a `body` background there paints an opaque sheet over
37
+ * the frame the game just rendered, and the HUD appears to float on nothing. `#root` exists only
38
+ * in the web page, so the backdrop stays where it belongs and the UI layer stays see-through.
39
+ */
40
+
41
+ #root {
42
+ background: var(--color-ink);
43
+ }
44
+
45
+ /* The debug surface is framework plumbing; its default presentation is yours to change. */
46
+ [data-threenative-debug-overlay="true"] {
47
+ position: fixed;
48
+ top: 1rem;
49
+ right: 1rem;
50
+ z-index: 50;
51
+ max-width: 24rem;
52
+ padding: 0.75rem;
53
+ pointer-events: none;
54
+ background: rgb(2 6 23 / 90%);
55
+ box-shadow: 0 10px 15px -3px rgb(0 0 0 / 30%);
56
+ color: #cffafe;
57
+ font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
58
+ font-size: 12px;
59
+ line-height: 1.5;
60
+ }
61
+
62
+ [data-threenative-debug-overlay="true"] table {
63
+ width: 100%;
64
+ table-layout: fixed;
65
+ }
66
+
67
+ [data-threenative-debug-overlay="true"] th,
68
+ [data-threenative-debug-overlay="true"] td {
69
+ padding-right: 1rem;
70
+ text-align: left;
71
+ }
72
+
73
+ [data-threenative-debug-overlay="true"] td:last-child {
74
+ overflow-wrap: anywhere;
75
+ word-break: break-all;
76
+ }
@@ -1,5 +1,5 @@
1
1
  import type { PhysicsBody3D } from "@threenative/physics";
2
- import type { Vector3 } from "three";
2
+ import { Vector3 } from "three";
3
3
  import type { Checkline } from "./Checkline.js";
4
4
 
5
5
  export interface ILapTarget {
@@ -15,8 +15,13 @@ export class Lap {
15
15
  reverseRejects = 0;
16
16
  #target: ILapTarget;
17
17
  #gates: readonly Checkline[];
18
+ #gateNormals: Vector3[] = [];
18
19
  #onLap: (lap: number) => void;
19
20
  #unsubscribe: (() => void)[] = [];
21
+ #targetDirection = new Vector3();
22
+ #gateDirection = new Vector3();
23
+ #before = new Vector3();
24
+ #after = new Vector3();
20
25
 
21
26
  constructor(
22
27
  target: ILapTarget,
@@ -31,8 +36,11 @@ export class Lap {
31
36
  this.#gates = gates;
32
37
  this.totalLaps = totalLaps;
33
38
  this.#onLap = onLap;
34
- for (const [index, gate] of gates.entries()) {
39
+ for (let index = 0; index < gates.length; index += 1) {
40
+ const gate = gates[index];
41
+ if (gate === undefined) throw new Error("Lap gate is missing.");
35
42
  const expected = gate.forward.clone().setY(0).normalize();
43
+ this.#gateNormals.push(expected);
36
44
  this.#unsubscribe.push(
37
45
  gate.area.on("bodyEntered", (body) => {
38
46
  if (body !== this.#target.body || this.completed >= this.totalLaps) return;
@@ -49,11 +57,11 @@ export class Lap {
49
57
  return false;
50
58
  }
51
59
  const direction = gateForward ?? gate.forward;
52
- const travel = this.#target.forward
53
- .clone()
60
+ const travel = this.#targetDirection
61
+ .copy(this.#target.forward)
54
62
  .setY(0)
55
63
  .normalize()
56
- .dot(direction.clone().setY(0).normalize());
64
+ .dot(this.#gateDirection.copy(direction).setY(0).normalize());
57
65
  if (travel <= 0.2) {
58
66
  this.reverseRejects += 1;
59
67
  return false;
@@ -72,10 +80,13 @@ export class Lap {
72
80
 
73
81
  /** Sweeps a car transform between frames so a fast body cannot skip a thin sensor. */
74
82
  observe(previous: Vector3, current: Vector3): void {
75
- for (const [index, gate] of this.#gates.entries()) {
76
- const normal = gate.forward.clone().setY(0).normalize();
77
- const before = previous.clone().sub(gate.at).dot(normal);
78
- const after = current.clone().sub(gate.at).dot(normal);
83
+ for (let index = 0; index < this.#gates.length; index += 1) {
84
+ const gate = this.#gates[index];
85
+ if (gate === undefined) throw new Error("Lap gate is missing.");
86
+ const normal = this.#gateNormals[index];
87
+ if (normal === undefined) throw new Error("Lap gate normal is missing.");
88
+ const before = this.#before.copy(previous).sub(gate.at).dot(normal);
89
+ const after = this.#after.copy(current).sub(gate.at).dot(normal);
79
90
  const crossedForward = before < 0 && after >= 0;
80
91
  const crossedReverse = before >= 0 && after < 0;
81
92
  if (crossedForward || crossedReverse) this.cross(index);
@@ -1,5 +1,5 @@
1
- import type { PathFollow3D } from "@threenative/core";
2
- import type { Vector3 } from "three";
1
+ import type { IPathFollow3DProjection, PathFollow3D } from "@threenative/core";
2
+ import { Vector3 } from "three";
3
3
 
4
4
  export interface IRacerProgress {
5
5
  readonly id: string;
@@ -12,24 +12,63 @@ export interface IRankedRacer extends IRacerProgress {
12
12
  readonly routeProgress: number;
13
13
  }
14
14
 
15
- export function routeProgress(route: PathFollow3D, position: Vector3, lap: number): number {
15
+ export interface IRankedRacerScratch {
16
+ id: string;
17
+ lap: number;
18
+ position: Vector3;
19
+ place: number;
20
+ routeProgress: number;
21
+ }
22
+
23
+ const projectionScratch: IPathFollow3DProjection = {
24
+ distanceFromStart: 0,
25
+ lateralDistance: 0,
26
+ point: new Vector3(0, 0, 0),
27
+ segment: 0,
28
+ tangent: new Vector3(0, 0, 1),
29
+ };
30
+
31
+ function compareRankedRacers(left: IRankedRacerScratch, right: IRankedRacerScratch): number {
32
+ return right.routeProgress - left.routeProgress || left.id.localeCompare(right.id);
33
+ }
34
+
35
+ export function routeProgress(
36
+ route: PathFollow3D,
37
+ position: Vector3,
38
+ lap: number,
39
+ target: IPathFollow3DProjection = projectionScratch,
40
+ ): number {
16
41
  if (!Number.isInteger(lap) || lap < 0)
17
42
  throw new Error("Racing route lap must be a non-negative integer.");
18
- return lap * route.totalLength + route.project(position).distanceFromStart;
43
+ return lap * route.totalLength + route.project(position, target).distanceFromStart;
19
44
  }
20
45
 
21
46
  export function rankRacers(
22
47
  route: PathFollow3D,
23
48
  racers: readonly IRacerProgress[],
49
+ target: IPathFollow3DProjection = projectionScratch,
50
+ buffer: IRankedRacerScratch[] = [],
24
51
  ): readonly IRankedRacer[] {
25
- const ranked = racers
26
- .map((racer) => ({
27
- ...racer,
28
- place: 0,
29
- routeProgress: routeProgress(route, racer.position, racer.lap),
30
- }))
31
- .sort(
32
- (left, right) => right.routeProgress - left.routeProgress || left.id.localeCompare(right.id),
33
- );
34
- return ranked.map((racer, index) => ({ ...racer, place: index + 1 }));
52
+ if (buffer.length > racers.length) buffer.length = racers.length;
53
+ for (let index = buffer.length; index < racers.length; index += 1) {
54
+ buffer.push({ id: "", lap: 0, position: projectionScratch.point, place: 0, routeProgress: 0 });
55
+ }
56
+ for (let index = 0; index < racers.length; index += 1) {
57
+ const racer = racers[index];
58
+ if (racer === undefined) throw new Error("Racing racer input is missing.");
59
+ const ranked = buffer[index];
60
+ if (ranked === undefined) throw new Error("Racing ranking buffer slot is missing.");
61
+ ranked.id = racer.id;
62
+ ranked.lap = racer.lap;
63
+ ranked.position = racer.position;
64
+ ranked.routeProgress = routeProgress(route, racer.position, racer.lap, target);
65
+ ranked.place = 0;
66
+ }
67
+ buffer.sort(compareRankedRacers);
68
+ for (let index = 0; index < buffer.length; index += 1) {
69
+ const racer = buffer[index];
70
+ if (racer === undefined) throw new Error("Racing ranked racer is missing.");
71
+ racer.place = index + 1;
72
+ }
73
+ return buffer;
35
74
  }
@@ -1,4 +1,4 @@
1
- import { type ICtx, PathFollow3D } from "@threenative/core";
1
+ import { type ICtx, InstancedBatch, PathFollow3D } from "@threenative/core";
2
2
  import { Area3D, CollisionShape3D, type IPhysicsContext, RigidBody3D } from "@threenative/physics";
3
3
  import { BoxGeometry, Color, Group, Mesh, MeshStandardMaterial, Raycaster, Vector3 } from "three";
4
4
  import { Boost } from "../kart/boost.js";
@@ -54,24 +54,24 @@ function roadSegment(
54
54
  return road;
55
55
  }
56
56
 
57
- function addCurb(
58
- ctx: TrackCtx,
59
- a: Vector3,
60
- b: Vector3,
61
- side: number,
62
- materials: ReturnType<typeof createMaterials>,
63
- ): void {
57
+ /**
58
+ * One kerb stone, recorded into a shared batch rather than drawn on its own.
59
+ *
60
+ * Every kerb is the same box at a different length and angle, so a unit box scaled per placement
61
+ * draws exactly what a per-segment `BoxGeometry` drew — as one draw for the whole track instead of
62
+ * two per sector. Change `materials.curb` and every kerb changes with it; the batch picks nothing.
63
+ */
64
+ function addCurb(curbs: InstancedBatch, a: Vector3, b: Vector3, side: number): void {
64
65
  const direction = b.clone().sub(a).setY(0).normalize();
65
66
  const normal = new Vector3(-direction.z, 0, direction.x).multiplyScalar(
66
67
  side * (TRACK_WIDTH / 2 + 0.28),
67
68
  );
68
69
  const midpoint = a.clone().lerp(b, 0.5).add(normal);
69
- const length = a.distanceTo(b);
70
- const curb = new Mesh(new BoxGeometry(length, 0.18, 0.42), materials.curb);
71
- curb.position.set(midpoint.x, 0.08, midpoint.z);
72
- curb.rotation.y = Math.atan2(direction.z, direction.x);
73
- curb.castShadow = true;
74
- ctx.add(curb);
70
+ curbs.place({
71
+ position: [midpoint.x, 0.08, midpoint.z],
72
+ rotation: [0, Math.atan2(direction.z, direction.x), 0],
73
+ scale: [a.distanceTo(b), 0.18, 0.42],
74
+ });
75
75
  }
76
76
 
77
77
  function gate(
@@ -200,21 +200,34 @@ export function buildTrack(ctx: TrackCtx): ITrackBuild {
200
200
  type: "fixed",
201
201
  });
202
202
 
203
+ // Every kerb is the same box at a different length and angle, so they are gathered into one
204
+ // batch and drawn once instead of twice per sector. The count is not known before the route has
205
+ // been walked, which is exactly what `InstancedBatch` is for — `new InstancedMesh` would need it
206
+ // up front.
207
+ const curbs = new InstancedBatch({
208
+ geometry: new BoxGeometry(1, 1, 1),
209
+ material: materials.curb,
210
+ });
211
+
203
212
  const roadMeshes: Mesh[] = [];
204
213
  for (let index = 0; index < ROUTE_POINTS.length; index += 1) {
205
214
  const a = ROUTE_POINTS[index];
206
215
  const b = ROUTE_POINTS[(index + 1) % ROUTE_POINTS.length];
207
216
  if (a === undefined || b === undefined) continue;
208
217
  roadMeshes.push(roadSegment(ctx, a, b, materials));
209
- addCurb(ctx, a, b, 1, materials);
210
- addCurb(ctx, a, b, -1, materials);
218
+ addCurb(curbs, a, b, 1);
219
+ addCurb(curbs, a, b, -1);
211
220
  }
221
+ const curbMesh = curbs.build({ castShadow: true, name: "track-curbs" });
222
+ if (curbMesh !== undefined) ctx.add(curbMesh);
212
223
 
213
224
  const gates = [
214
225
  gate(ctx, "mid", new Vector3(18, 0, 0), new Vector3(0, 0, 1), TRACK_WIDTH),
215
226
  gate(ctx, "finish", new Vector3(10, 0, -18), new Vector3(1, 0, 0), TRACK_WIDTH),
216
227
  ];
217
228
  const pad = boostPad(ctx, new Vector3(14, 0, -18), materials);
229
+ // The five corner markers stay ordinary meshes on purpose: a batch is worth its two extra lines
230
+ // when the count is unknown or large, and five is neither.
218
231
  for (const [index, point] of ROUTE_POINTS.entries()) {
219
232
  const marker = new Mesh(
220
233
  new BoxGeometry(0.2, 1.2, 0.2),
@@ -1,4 +1,4 @@
1
- import type { PathFollow3D } from "@threenative/core";
1
+ import type { IPathFollow3DProjection, PathFollow3D } from "@threenative/core";
2
2
  import { Vector3 } from "three";
3
3
  import { type IRescueTarget, rescueToLastValid } from "./rescue.js";
4
4
 
@@ -33,6 +33,15 @@ export class TrackSector {
33
33
  readonly #intersectRay: IntersectRay;
34
34
  readonly #rescueDelay: number;
35
35
  readonly #rayHeight: number;
36
+ readonly #origin = new Vector3();
37
+ readonly #direction = new Vector3(0, -1, 0);
38
+ readonly #projection: IPathFollow3DProjection = {
39
+ distanceFromStart: 0,
40
+ lateralDistance: 0,
41
+ point: new Vector3(),
42
+ segment: 0,
43
+ tangent: new Vector3(0, 0, 1),
44
+ };
36
45
 
37
46
  constructor(options: ITrackSectorOptions) {
38
47
  this.#route = options.route;
@@ -45,13 +54,14 @@ export class TrackSector {
45
54
  update(position: Vector3, heading: Vector3, dt: number): boolean {
46
55
  if (!Number.isFinite(dt) || dt < 0)
47
56
  throw new Error("TrackSector.update requires a finite non-negative dt.");
48
- const origin = position.clone().add(new Vector3(0, this.#rayHeight, 0));
49
- const hit = this.#intersectRay(origin, new Vector3(0, -1, 0), this.#rayHeight + 2);
57
+ const origin = this.#origin.copy(position);
58
+ origin.y += this.#rayHeight;
59
+ const hit = this.#intersectRay(origin, this.#direction, this.#rayHeight + 2);
50
60
  const onRoad = hit !== undefined && hit.distance >= 0 && hit.distance <= this.#rayHeight + 2;
51
61
  if (onRoad) {
52
62
  this.lastOnRoadPosition.copy(position);
53
63
  this.lastOnRoadHeading.copy(heading).setY(0).normalize();
54
- this.currentSector = this.#route.project(position).segment;
64
+ this.currentSector = this.#route.project(position, this.#projection).segment;
55
65
  this.#hasOnRoadSample = true;
56
66
  this.#offRoadTime = 0;
57
67
  return true;
@@ -2,15 +2,20 @@ import type { IGame } from "@threenative/core";
2
2
  import type { IPhysicsContext } from "@threenative/physics";
3
3
  import { DebugOverlay, GameCanvas } from "@threenative/ui";
4
4
  import type { GameState } from "../state.js";
5
- import { Hud } from "./Hud.js";
6
- import { Menu } from "./Menu.js";
5
+ import { GameUi } from "./GameUi.js";
7
6
 
7
+ /**
8
+ * The web target's page: the canvas, then the same UI every other target renders.
9
+ *
10
+ * `GameCanvas` hosts the renderer and everything after it paints on top; keep the canvas first.
11
+ * The UI itself comes from `GameUi`, unchanged — this file exists only because the web build also
12
+ * has to put a canvas on the page.
13
+ */
8
14
  export function App({ game }: { game: IGame<GameState, IPhysicsContext> }) {
9
15
  return (
10
16
  <main className="relative h-screen w-screen overflow-hidden bg-ink">
11
17
  <GameCanvas className="absolute inset-0" game={game} />
12
- <Hud game={game} />
13
- <Menu />
18
+ <GameUi />
14
19
  <DebugOverlay />
15
20
  </main>
16
21
  );
@@ -0,0 +1,20 @@
1
+ import { UiLayer } from "@threenative/ui";
2
+ import { Hud } from "./Hud.js";
3
+ import { Menu } from "./Menu.js";
4
+
5
+ /**
6
+ * Everything the player sees that is not the scene.
7
+ *
8
+ * One component, mounted twice by two entries that differ only in what else is on the page:
9
+ * `src/main.ts` puts it beside the canvas on the web target, and `src/ui/main.tsx` is the whole
10
+ * page the native web view loads. Keeping both entries pointed at this file is what makes "the
11
+ * same UI on every target" a fact rather than an intention.
12
+ */
13
+ export function GameUi() {
14
+ return (
15
+ <UiLayer>
16
+ <Hud />
17
+ <Menu />
18
+ </UiLayer>
19
+ );
20
+ }
@@ -1,14 +1,15 @@
1
- import type { IGame } from "@threenative/core";
2
- import type { IPhysicsContext } from "@threenative/physics";
3
- import { useGameState } from "@threenative/ui";
1
+ import { useUiState } from "@threenative/ui";
4
2
  import type { GameState } from "../state.js";
5
3
 
6
4
  function clock(seconds: number): string {
7
5
  return `${String(Math.floor(seconds / 60)).padStart(2, "0")}:${String(Math.floor(seconds % 60)).padStart(2, "0")}.${String(Math.floor((seconds % 1) * 10))}`;
8
6
  }
9
7
 
10
- export function Hud({ game }: { game: IGame<GameState, IPhysicsContext> }) {
11
- const state = useGameState(game, (value) => value);
8
+ export function Hud() {
9
+ const state = useUiState<GameState>();
10
+ // Nothing to draw until the game publishes its first snapshot, a few milliseconds in.
11
+ // Rendering zeroes instead would put wrong numbers on screen and then correct them.
12
+ if (state === undefined) return null;
12
13
  const statusClass =
13
14
  state.raceStatus === "WON"
14
15
  ? "text-win"
@@ -0,0 +1,14 @@
1
+ import { createRoot } from "react-dom/client";
2
+ import { GameUi } from "./GameUi.js";
3
+ import "../style.css";
4
+
5
+ /**
6
+ * The UI entry the native web view loads.
7
+ *
8
+ * It mounts the UI and nothing else — no scene, no simulation, no renderer. The game runs beside
9
+ * it in the native runtime and reaches it only through published state and intents, which is why
10
+ * this file imports no game code at all.
11
+ */
12
+ const root = document.getElementById("tn-ui");
13
+ if (root === null) throw new Error("Missing #tn-ui element.");
14
+ createRoot(root).render(<GameUi />);
@@ -1,16 +1,19 @@
1
1
  import type { IThreeNativeConfig } from "@threenative/core";
2
2
 
3
- export default {
3
+ const config: IThreeNativeConfig = {
4
4
  app: {
5
5
  id: "com.threenative.__PROJECT_ID__",
6
6
  name: "__PROJECT_NAME__",
7
7
  version: "1.0.0",
8
8
  build: 1,
9
+ icon: "public/icon.png",
10
+ icons: { web: { favicon: "public/favicon.svg" } },
9
11
  },
10
12
  display: {
11
13
  orientation: "landscape",
12
14
  fullscreen: true,
13
15
  keepScreenOn: true,
16
+ maxFps: 60,
14
17
  },
15
18
  window: {
16
19
  title: "__PROJECT_NAME__",
@@ -18,12 +21,22 @@ export default {
18
21
  height: 720,
19
22
  resizable: true,
20
23
  },
21
- loading: {
22
- backdropColor: "#07111d",
23
- trackColor: "#16324a",
24
- progressColor: "#ffcf4a",
25
- showProgressBar: true,
24
+ bootSplash: {
25
+ backgroundColor: "#07111d",
26
26
  },
27
27
  nativeEntry: "src/game.ts",
28
- renderer: { preferWebGPU: true },
29
- } satisfies IThreeNativeConfig;
28
+ renderer: {
29
+ preferWebGPU: true, // Use WebGPU when the host exposes it.
30
+ // The engine holds the `display.maxFps` budget by scaling the 3D drawing buffer, and reports
31
+ // the scale it settled on in every `TN_FRAME_BUDGET` window. Replace with a number in (0, 1]
32
+ // to pin it — the loop stops and the reporting does not. CSS, UI and camera framing never move.
33
+ resolutionScale: "auto",
34
+ },
35
+ // One UI on every target: src/ui/ renders through the platform's own browser-class renderer,
36
+ // so the same React, Tailwind, CSS and SVG run on web, desktop, Android and iOS alike.
37
+ // Switch to "native" for a UI drawn as part of the rendered frame, with no web view and no
38
+ // extra process — and own the appearance difference that comes with it.
39
+ ui: { renderer: "web" },
40
+ };
41
+
42
+ export default config;