create-threenative 0.2.18 → 0.2.20

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 (183) hide show
  1. package/agent-docs/references/capability-reference.md +212 -4
  2. package/agent-docs/references/kit-racing.md +4 -2
  3. package/agent-docs/references/performance-basics.md +2 -1
  4. package/agent-docs/references/terrain-authoring.md +21 -7
  5. package/agent-files/.agents/skills/prd-creator/SKILL.md +24 -0
  6. package/dist/index.js +255 -236
  7. package/dist/quality.d.ts +5 -1
  8. package/dist/quality.js +75 -6
  9. package/dist/terrain-kit.js +1 -1
  10. package/dist/threenative.js +6 -4
  11. package/dist/web-engine-post-effects.js +6 -0
  12. package/dist/web-engine-runtime.js +211 -36
  13. package/package.json +6 -6
  14. package/template-assets/assets/floor-fern-0.glb +0 -0
  15. package/template-assets/assets/floor-litter-0.glb +0 -0
  16. package/template-assets/assets/floor-log-0.glb +0 -0
  17. package/template-assets/assets/floor-log-1.glb +0 -0
  18. package/template-assets/assets/floor-stump-0.glb +0 -0
  19. package/template-assets/assets/floor-twig-0.glb +0 -0
  20. package/template-assets/quality/eslint.config.js +1 -1
  21. package/templates/action-rpg/package.json +7 -7
  22. package/templates/action-rpg/src/loot/drops.ts +3 -7
  23. package/templates/action-rpg/src/render/camera.ts +2 -2
  24. package/templates/action-rpg/src/render/clouds.ts +3 -1
  25. package/templates/action-rpg/src/render/materials.ts +3 -2
  26. package/templates/action-rpg/src/render/touch-controls.ts +7 -6
  27. package/templates/action-rpg/src/scenes/Play.ts +1 -15
  28. package/templates/adventure/AGENTS.md +3 -3
  29. package/templates/adventure/CLAUDE.md +3 -3
  30. package/templates/adventure/native-playtests/survives.playtest.json +12 -0
  31. package/templates/adventure/native-playtests/woodland-floor.playtest.json +61 -0
  32. package/templates/adventure/package.json +7 -7
  33. package/templates/adventure/playtests/grass.playtest.json +61 -0
  34. package/templates/adventure/playtests/performance.playtest.json +1 -1
  35. package/templates/adventure/playtests/survives.playtest.json +2 -2
  36. package/templates/adventure/playtests/woodland-floor.playtest.json +61 -0
  37. package/templates/adventure/src/entities/LockOn.ts +42 -4
  38. package/templates/adventure/src/entities/Warden.ts +4 -1
  39. package/templates/adventure/src/level/Vale.ts +241 -16
  40. package/templates/adventure/src/render/camera.ts +2 -2
  41. package/templates/adventure/src/render/foliage.ts +64 -20
  42. package/templates/adventure/src/render/grass.ts +325 -0
  43. package/templates/adventure/src/render/materials.ts +3 -2
  44. package/templates/adventure/src/render/palette.ts +3 -0
  45. package/templates/adventure/src/render/touch-controls.ts +4 -1
  46. package/templates/adventure/src/scenes/Play.ts +96 -1
  47. package/templates/collectathon/package.json +7 -7
  48. package/templates/collectathon/src/level/Course.ts +2 -7
  49. package/templates/collectathon/src/level/terrain.ts +2 -1
  50. package/templates/collectathon/src/render/camera.ts +2 -2
  51. package/templates/collectathon/src/render/ground.ts +4 -4
  52. package/templates/collectathon/src/render/hero.ts +1 -1
  53. package/templates/collectathon/src/render/materials.ts +0 -1
  54. package/templates/collectathon/src/render/sky.ts +4 -3
  55. package/templates/kart/package.json +6 -6
  56. package/templates/kart/src/entities/Kart.ts +2 -1
  57. package/templates/kart/src/render/course.ts +2 -1
  58. package/templates/kart/src/track/Course.ts +3 -1
  59. package/templates/minimal/package.json +6 -6
  60. package/templates/minimal/src/render/camera.ts +2 -2
  61. package/templates/minimal/src/render/clouds.ts +3 -1
  62. package/templates/minimal/src/render/materials.ts +3 -2
  63. package/templates/minimal/src/render/touch-controls.ts +7 -6
  64. package/templates/platformer/package.json +7 -7
  65. package/templates/platformer/playtests/collect.playtest.json +4 -1
  66. package/templates/platformer/src/level/Stage.ts +2 -6
  67. package/templates/platformer/src/scenes/Play.ts +2 -1
  68. package/templates/puzzle/package.json +7 -7
  69. package/templates/puzzle/src/entities/Warden.ts +3 -3
  70. package/templates/puzzle/src/render/camera.ts +2 -2
  71. package/templates/puzzle/src/render/touch-controls.ts +7 -6
  72. package/templates/racing/AGENTS.md +2 -2
  73. package/templates/racing/CLAUDE.md +2 -2
  74. package/templates/racing/CREDITS.md +29 -0
  75. package/templates/racing/assets/engine-loop.wav +0 -0
  76. package/templates/racing/assets/grass/Grass004_color.jpg +0 -0
  77. package/templates/racing/assets/grass/Grass004_normal.jpg +0 -0
  78. package/templates/racing/assets/grass/Grass004_roughness.jpg +0 -0
  79. package/templates/racing/assets/nitro-burst.wav +0 -0
  80. package/templates/racing/assets/tyre-squeal.wav +0 -0
  81. package/templates/racing/package.json +7 -7
  82. package/templates/racing/playtests/drift-natural.playtest.json +68 -0
  83. package/templates/racing/playtests/drift.playtest.json +100 -0
  84. package/templates/racing/playtests/hud.playtest.json +117 -0
  85. package/templates/racing/playtests/launch-pose.playtest.json +34 -0
  86. package/templates/racing/playtests/nitro.playtest.json +158 -0
  87. package/templates/racing/playtests/outcome.playtest.json +4 -4
  88. package/templates/racing/playtests/performance.playtest.json +1 -1
  89. package/templates/racing/playtests/steady-camera.playtest.json +88 -0
  90. package/templates/racing/src/audio/engine.ts +138 -0
  91. package/templates/racing/src/entities/CarBody.ts +83 -10
  92. package/templates/racing/src/entities/Drift.ts +243 -0
  93. package/templates/racing/src/entities/LineDriver.ts +2 -2
  94. package/templates/racing/src/entities/Nitro.ts +72 -0
  95. package/templates/racing/src/entities/RacingCar.ts +86 -21
  96. package/templates/racing/src/entities/Rival.ts +35 -21
  97. package/templates/racing/src/game.ts +6 -0
  98. package/templates/racing/src/gauges.ts +74 -0
  99. package/templates/racing/src/render/camera.ts +29 -4
  100. package/templates/racing/src/render/clouds.ts +3 -1
  101. package/templates/racing/src/render/effects.ts +244 -0
  102. package/templates/racing/src/render/materials.ts +43 -8
  103. package/templates/racing/src/render/shapes.ts +37 -0
  104. package/templates/racing/src/render/skids.ts +84 -0
  105. package/templates/racing/src/render/touch-controls.ts +10 -10
  106. package/templates/racing/src/scenes/Race.ts +277 -25
  107. package/templates/racing/src/state.ts +35 -0
  108. package/templates/racing/src/style.css +3 -0
  109. package/templates/racing/src/track/Track.ts +132 -58
  110. package/templates/racing/src/track/TrackSector.ts +19 -1
  111. package/templates/racing/src/track/circuit.ts +21 -15
  112. package/templates/racing/src/ui/GameUi.tsx +0 -2
  113. package/templates/racing/src/ui/Hud.tsx +417 -50
  114. package/templates/racing/threenative.config.ts +15 -0
  115. package/templates/racing/tools/make-racing-audio.mjs +388 -0
  116. package/templates/rain/package.json +6 -6
  117. package/templates/rain/src/render/noise-volume.ts +2 -1
  118. package/templates/rain/src/state.ts +3 -1
  119. package/templates/rain/src/ui/GameUi.tsx +1 -1
  120. package/templates/rain/src/ui/automation.ts +10 -8
  121. package/templates/rain/src/ui/tempest.ts +3 -4
  122. package/templates/rts/package.json +6 -6
  123. package/templates/rts/src/sim/terrain.ts +1 -0
  124. package/templates/rts/src/sim/types.ts +1 -0
  125. package/templates/runner/package.json +7 -7
  126. package/templates/runner/src/render/clouds.ts +3 -1
  127. package/templates/runner/src/render/materials.ts +3 -2
  128. package/templates/runner/src/render/touch-controls.ts +7 -6
  129. package/templates/runner/src/scenes/Run.ts +4 -9
  130. package/templates/sailing/package.json +7 -7
  131. package/templates/sailing/src/render/touch-controls.ts +7 -6
  132. package/templates/shooter/package.json +7 -7
  133. package/templates/shooter/src/render/clouds.ts +3 -1
  134. package/templates/snow/package.json +7 -7
  135. package/templates/snow/src/entities/Explorer.ts +6 -12
  136. package/templates/snow/src/render/bootPrint.ts +3 -1
  137. package/templates/snow/src/render/camera.ts +3 -2
  138. package/templates/snow/src/render/scenery.ts +3 -3
  139. package/templates/snow/src/render/touch-controls.ts +7 -6
  140. package/templates/snow/src/render/weather.ts +3 -5
  141. package/templates/snow/src/terrain.ts +2 -1
  142. package/templates/starter/native-playtests/render-chain.playtest.json +9 -9
  143. package/templates/starter/package.json +7 -7
  144. package/templates/starter/src/entities/Player.ts +10 -2
  145. package/templates/starter/src/render/camera.ts +2 -2
  146. package/templates/starter/src/render/clouds.ts +3 -1
  147. package/templates/starter/src/render/materials.ts +3 -2
  148. package/templates/starter/src/render/touch-controls.ts +7 -6
  149. package/templates/starter/src/scenes/Play.ts +1 -14
  150. package/templates/tower-defense/package.json +7 -7
  151. package/templates/tower-defense/src/render/shapes.ts +1 -2
  152. package/templates/tower-defense/src/scenes/Battle.ts +3 -8
  153. package/template-assets/terrain/alpine/assets.json +0 -12
  154. package/template-assets/terrain/alpine/bake.mjs +0 -6
  155. package/template-assets/terrain/alpine/credits.json +0 -164
  156. package/template-assets/terrain/alpine/heightmap.r16 +0 -0
  157. package/template-assets/terrain/alpine/recipe.json +0 -119
  158. package/template-assets/terrain/alpine/surface.json +0 -53
  159. package/template-assets/terrain/coastal/assets.json +0 -11
  160. package/template-assets/terrain/coastal/bake.mjs +0 -6
  161. package/template-assets/terrain/coastal/credits.json +0 -117
  162. package/template-assets/terrain/coastal/heightmap.r16 +0 -0
  163. package/template-assets/terrain/coastal/recipe.json +0 -113
  164. package/template-assets/terrain/coastal/surface.json +0 -41
  165. package/template-assets/terrain/desert/assets.json +0 -12
  166. package/template-assets/terrain/desert/bake.mjs +0 -6
  167. package/template-assets/terrain/desert/credits.json +0 -164
  168. package/template-assets/terrain/desert/heightmap.r16 +0 -0
  169. package/template-assets/terrain/desert/recipe.json +0 -108
  170. package/template-assets/terrain/desert/surface.json +0 -54
  171. package/template-assets/terrain/forest/assets.json +0 -65
  172. package/template-assets/terrain/forest/bake.mjs +0 -8
  173. package/template-assets/terrain/forest/credits.json +0 -225
  174. package/template-assets/terrain/forest/heightmap.r16 +0 -0
  175. package/template-assets/terrain/forest/recipe.json +0 -350
  176. package/template-assets/terrain/forest/surface.json +0 -79
  177. package/template-assets/terrain/tundra/assets.json +0 -12
  178. package/template-assets/terrain/tundra/bake.mjs +0 -6
  179. package/template-assets/terrain/tundra/credits.json +0 -164
  180. package/template-assets/terrain/tundra/heightmap.r16 +0 -0
  181. package/template-assets/terrain/tundra/recipe.json +0 -277
  182. package/template-assets/terrain/tundra/surface.json +0 -54
  183. package/templates/racing/src/ui/Menu.tsx +0 -7
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-threenative",
3
- "version": "0.2.18",
3
+ "version": "0.2.20",
4
4
  "license": "MIT",
5
5
  "description": "Scaffold a readable ThreeNative game project.",
6
6
  "keywords": [
@@ -95,13 +95,13 @@
95
95
  "@typescript-eslint/parser": "8.72.0",
96
96
  "@typescript-eslint/eslint-plugin": "8.72.0",
97
97
  "@types/estree": "1.0.8",
98
- "@threenative/assets": "0.3.14",
99
- "@threenative/blender-bridge": "0.2.6",
100
- "@threenative/core": "0.3.13",
101
- "@threenative/physics": "0.3.13"
98
+ "@threenative/assets": "0.3.16",
99
+ "@threenative/physics": "0.3.15",
100
+ "@threenative/core": "0.3.15",
101
+ "@threenative/blender-bridge": "0.2.8"
102
102
  },
103
103
  "peerDependencies": {
104
- "@threenative/assets": ">=0.3.14 <0.4.0"
104
+ "@threenative/assets": ">=0.3.16 <0.4.0"
105
105
  },
106
106
  "scripts": {
107
107
  "build": "tsup --config tsup.config.ts && publint",
@@ -1,3 +1,3 @@
1
1
  import { qualityConfig } from "create-threenative/quality";
2
2
 
3
- export default qualityConfig({ root: import.meta.dirname });
3
+ export default qualityConfig({ root: import.meta.dirname, reinventions: true });
@@ -19,9 +19,9 @@
19
19
  "format:check": "biome format src"
20
20
  },
21
21
  "dependencies": {
22
- "@threenative/core": "0.3.13",
23
- "@threenative/physics": "0.3.13",
24
- "@threenative/ui": "0.3.13",
22
+ "@threenative/core": ">=0.3.15",
23
+ "@threenative/physics": ">=0.3.15",
24
+ "@threenative/ui": ">=0.3.15",
25
25
  "react": "19.2.0",
26
26
  "react-dom": "19.2.0",
27
27
  "three": "0.187.0"
@@ -29,13 +29,13 @@
29
29
  "devDependencies": {
30
30
  "@gltf-transform/cli": "4.4.2",
31
31
  "@tailwindcss/vite": "4.3.3",
32
- "@threenative/assets": "0.3.14",
33
- "@threenative/playtest": "0.3.13",
32
+ "@threenative/assets": ">=0.3.16",
33
+ "@threenative/playtest": ">=0.3.15",
34
34
  "@types/react": "19.2.0",
35
35
  "@types/react-dom": "19.2.0",
36
36
  "@types/three": "0.187.0",
37
37
  "@vitejs/plugin-react": "6.0.5",
38
- "create-threenative": "0.2.18",
38
+ "create-threenative": "0.2.20",
39
39
  "esbuild": "0.27.0",
40
40
  "playwright": "1.62.1",
41
41
  "tailwindcss": "4.3.3",
@@ -45,7 +45,7 @@
45
45
  "eslint": "10.13.0"
46
46
  },
47
47
  "optionalDependencies": {
48
- "@threenative/runtime-native": "0.3.13"
48
+ "@threenative/runtime-native": ">=0.3.15"
49
49
  },
50
50
  "overrides": {
51
51
  "sharp": ">=0.35.4",
@@ -1,3 +1,4 @@
1
+ import { createRandom } from "@threenative/core";
1
2
  import type { ItemId } from "../items/Inventory.js";
2
3
 
3
4
  export interface IDrop {
@@ -10,19 +11,14 @@ const TABLE: readonly { readonly itemId: ItemId; readonly weight: number }[] = [
10
11
  { itemId: "ember-blade", weight: 30 },
11
12
  ];
12
13
 
13
- function next(seed: number): number {
14
- return (Math.imul(seed, 1_664_525) + 1_013_904_223) >>> 0;
15
- }
16
-
17
14
  export function rollDrops(seed: number, rolls = 2): IDrop[] {
18
15
  if (!Number.isInteger(seed) || seed < 0)
19
16
  throw new RangeError("Drop seeds must be non-negative integers.");
20
17
  if (!Number.isInteger(rolls) || rolls < 1) throw new RangeError("Drop rolls must be positive.");
21
- let state = seed >>> 0;
18
+ const random = createRandom(seed);
22
19
  const drops: IDrop[] = [];
23
20
  for (let index = 0; index < rolls; index += 1) {
24
- state = next(state);
25
- const pick = (state / 4_294_967_296) * 100;
21
+ const pick = random() * 100;
26
22
  let cursor = 0;
27
23
  for (const entry of TABLE) {
28
24
  cursor += entry.weight;
@@ -3,7 +3,7 @@
3
3
  // The action-RPG three-quarter view: high and behind, far enough back that the room reads as a
4
4
  // room. It has to clear the **south wall**, which stands at z = +6 and is low so the camera can
5
5
  // see over it — the oldest trick in an isometric dungeon, and it costs one row of wall table.
6
- import { type PerspectiveCamera, Vector3 } from "three";
6
+ import { MathUtils, type PerspectiveCamera, Vector3 } from "three";
7
7
 
8
8
  /** Where the camera sits relative to the player's body centre. */
9
9
  const OFFSET = new Vector3(0, 10.2, 9.2);
@@ -25,7 +25,7 @@ export function createDungeonCamera(camera: PerspectiveCamera): ICameraRig {
25
25
  return {
26
26
  follow: (target, dt) => {
27
27
  _desired.copy(target).add(OFFSET);
28
- camera.position.lerp(_desired, 1 - Math.exp(-dt / 0.2));
28
+ camera.position.lerp(_desired, MathUtils.damp(0, 1, 5, dt));
29
29
  camera.lookAt(_aim.copy(target).add(AIM));
30
30
  },
31
31
  snap: pose,
@@ -6,6 +6,8 @@
6
6
  // Independent CPU implementation. The material samples four Unreal textures that this repository
7
7
  // must not carry, so each one is regenerated here from a seeded noise whose per-channel value
8
8
  // quantiles and correlation lengths match the Unreal texture (measured, see the spec).
9
+ import { MathUtils } from "three";
10
+
9
11
  import {
10
12
  BOTTOM_KM,
11
13
  CAMERA_KM,
@@ -110,7 +112,7 @@ const PROFILE_COEFFICIENTS = [
110
112
  const clamp = (v: number): number => Math.max(0, Math.min(1, v));
111
113
  const smooth = (v: number): number => {
112
114
  const t = clamp(v);
113
- return t * t * (3 - 2 * t);
115
+ return MathUtils.smoothstep(t, 0, 1);
114
116
  };
115
117
  const mod = (a: number, n: number): number => ((a % n) + n) % n;
116
118
 
@@ -11,6 +11,7 @@ import {
11
11
  DataTexture,
12
12
  Float32BufferAttribute,
13
13
  LinearMipmapLinearFilter,
14
+ MathUtils,
14
15
  MeshStandardMaterial,
15
16
  RepeatWrapping,
16
17
  SRGBColorSpace,
@@ -84,8 +85,8 @@ function grainNormalTexture(size = 128): DataTexture {
84
85
  const y0 = Math.floor(v);
85
86
  const fx = u - x0;
86
87
  const fy = v - y0;
87
- const sx = fx * fx * (3 - 2 * fx);
88
- const sy = fy * fy * (3 - 2 * fy);
88
+ const sx = MathUtils.smoothstep(fx, 0, 1);
89
+ const sy = MathUtils.smoothstep(fy, 0, 1);
89
90
  const at = (i: number, j: number): number =>
90
91
  values[(((j % count) + count) % count) * count + (((i % count) + count) % count)] ?? 0;
91
92
  const top = at(x0, y0) + (at(x0 + 1, y0) - at(x0, y0)) * sx;
@@ -15,6 +15,9 @@ const MOVE_RADIUS = 72;
15
15
  const BUTTON_RADIUS = 58;
16
16
  const EDGE = 36;
17
17
 
18
+ /** The knob's next point: `update` runs every frame, so it uses one instance. */
19
+ const knobPosition = new Vector2();
20
+
18
21
  export interface ITouchPointer {
19
22
  readonly position: Vector2;
20
23
  }
@@ -122,13 +125,11 @@ export class TouchControls {
122
125
  }
123
126
 
124
127
  const center = this.#hasMoveAnchor ? this.#moveAnchor : this.#resting;
125
- place(
126
- this.#moveKnob,
127
- new Vector2(
128
- center.x + this.#input.move.x * MOVE_RADIUS,
129
- center.y - this.#input.move.y * MOVE_RADIUS,
130
- ),
128
+ knobPosition.set(
129
+ center.x + this.#input.move.x * MOVE_RADIUS,
130
+ center.y - this.#input.move.y * MOVE_RADIUS,
131
131
  );
132
+ place(this.#moveKnob, knobPosition);
132
133
  this.#ability.material = ability ? this.#activeMaterial : this.#idleMaterial;
133
134
  this.#attack.material = attack ? this.#activeMaterial : this.#idleMaterial;
134
135
  this.#input.abilityPressed = ability && !this.#wasAbility;
@@ -580,7 +580,6 @@ export class Play extends Scene<GameState, IPhysicsContext> {
580
580
  }
581
581
 
582
582
  currentRoom = roomFor(player.mesh.position.x);
583
- const previous = frameCtx.state.getState();
584
583
  frameState.abilityCooldown = quantize(ability.cooldownRemaining, 1000);
585
584
  frameState.baseDamage = damageStats.base;
586
585
  frameState.damage = Math.round(damageStats.value(elapsed));
@@ -595,20 +594,7 @@ export class Play extends Scene<GameState, IPhysicsContext> {
595
594
  visibleEnemy.state === "aggro" || visibleEnemy.state === "attack" ? 1 : 0;
596
595
  frameState.wallEnemyAggro =
597
596
  wallEnemy.state === "aggro" || wallEnemy.state === "attack" ? 1 : 0;
598
- const changed =
599
- frameState.abilityCooldown !== previous.abilityCooldown ||
600
- frameState.baseDamage !== previous.baseDamage ||
601
- frameState.damage !== previous.damage ||
602
- frameState.health !== previous.health ||
603
- frameState.lineOfSightBlocked !== previous.lineOfSightBlocked ||
604
- frameState.modifierActive !== previous.modifierActive ||
605
- frameState.playerX !== previous.playerX ||
606
- frameState.playerY !== previous.playerY ||
607
- frameState.playerZ !== previous.playerZ ||
608
- frameState.room !== previous.room ||
609
- frameState.visibleEnemyAggro !== previous.visibleEnemyAggro ||
610
- frameState.wallEnemyAggro !== previous.wallEnemyAggro;
611
- if (changed) frameCtx.state.set(frameState);
597
+ frameCtx.state.set(frameState);
612
598
  if (currentRoom !== lastSavedRoom) {
613
599
  lastSavedRoom = currentRoom;
614
600
  saveRequested = true;
@@ -38,12 +38,12 @@ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
38
38
 
39
39
  <!-- shared: kit-files -->
40
40
  Source in `src/`: `entities/`, `game.ts`, `interact.ts`, `level/`, `main.ts`, `render/`, `scenes/`, `state.ts`, `ui/`.
41
- 15 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
41
+ 17 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
42
42
  Kit notes: `node_modules/create-threenative/agent-docs/references/kit-adventure.md`.
43
43
  <!-- /shared -->
44
44
 
45
- `ADVENTURE_FEEL` in `src/entities/Hero.ts` is Wren's one table of feel constants; `playtests/move.playtest.json` proves it. `src/interact.ts` is the one interact prompt picker. Every model is procedural.
46
- `pnpm test` proves the web target. Desktop is claimed only where `native-playtests/survives.playtest.json` ran with `--target desktop`; Android and iOS have not run for this kit.
45
+ `ADVENTURE_FEEL` in `src/entities/Hero.ts` is Wren's one table of feel constants; `playtests/move.playtest.json` proves it. `src/interact.ts` is the one interact prompt picker. Every model is procedural except the baked forest-floor props, `assets/floor-*.glb` (PRD-889).
46
+ `pnpm test` proves the web target. Desktop is claimed only where `native-playtests/survives.playtest.json` and `native-playtests/woodland-floor.playtest.json` ran with `--target desktop`; Android and iOS have not run for this kit.
47
47
 
48
48
  <!-- shared: kit-commands -->
49
49
  ## Commands
@@ -40,12 +40,12 @@ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
40
40
 
41
41
  <!-- shared: kit-files -->
42
42
  Source in `src/`: `entities/`, `game.ts`, `interact.ts`, `level/`, `main.ts`, `render/`, `scenes/`, `state.ts`, `ui/`.
43
- 15 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
43
+ 17 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
44
44
  Kit notes: `node_modules/create-threenative/agent-docs/references/kit-adventure.md`.
45
45
  <!-- /shared -->
46
46
 
47
- `ADVENTURE_FEEL` in `src/entities/Hero.ts` is Wren's one table of feel constants; `playtests/move.playtest.json` proves it. `src/interact.ts` is the one interact prompt picker. Every model is procedural.
48
- `pnpm test` proves the web target. Desktop is claimed only where `native-playtests/survives.playtest.json` ran with `--target desktop`; Android and iOS have not run for this kit.
47
+ `ADVENTURE_FEEL` in `src/entities/Hero.ts` is Wren's one table of feel constants; `playtests/move.playtest.json` proves it. `src/interact.ts` is the one interact prompt picker. Every model is procedural except the baked forest-floor props, `assets/floor-*.glb` (PRD-889).
48
+ `pnpm test` proves the web target. Desktop is claimed only where `native-playtests/survives.playtest.json` and `native-playtests/woodland-floor.playtest.json` ran with `--target desktop`; Android and iOS have not run for this kit.
49
49
 
50
50
  <!-- shared: kit-commands -->
51
51
  ## Commands
@@ -42,6 +42,18 @@
42
42
  "gte": -0.3,
43
43
  "lte": 0.3,
44
44
  "allowTrivial": "The capsule's origin is Wren's waist, so feet near zero after 300 ticks prove she stands on the clearing floor on the native host too."
45
+ },
46
+ {
47
+ "entity": "grass",
48
+ "component": "visibleChunks",
49
+ "gte": 1,
50
+ "allowTrivial": "Streamed grass chunks draw round Wren on the native host, from the same GrassField3D as the web."
51
+ },
52
+ {
53
+ "entity": "grass",
54
+ "component": "standNear",
55
+ "lte": 0.6,
56
+ "allowTrivial": "The grass next to Wren is pushed over on the native host too."
45
57
  }
46
58
  ],
47
59
  "movement": {
@@ -0,0 +1,61 @@
1
+ {
2
+ "assert": {
3
+ "components": [
4
+ {
5
+ "allowTrivial": "Baked logs, stumps, twigs, litter and ferns draw round Wren on the native host too: the owned engine's own scatter, not a browser-only path.",
6
+ "component": "instances",
7
+ "entity": "floor",
8
+ "gte": 20
9
+ },
10
+ {
11
+ "allowTrivial": "At least three streamed floor tiles stand inside the draw distance on the native host.",
12
+ "component": "visibleTiles",
13
+ "entity": "floor",
14
+ "gte": 3
15
+ }
16
+ ],
17
+ "diagnostics": {
18
+ "noConsoleErrors": true,
19
+ "noNetworkErrors": true,
20
+ "noRuntimeDiagnostics": true,
21
+ "runtimeReady": true
22
+ },
23
+ "movement": {
24
+ "entity": "player",
25
+ "minDistance": 1.0
26
+ }
27
+ },
28
+ "artifacts": {
29
+ "screenshots": "after"
30
+ },
31
+ "name": "adventure-native-woodland-floor",
32
+ "schemaVersion": 1,
33
+ "setup": {
34
+ "aim": {
35
+ "pitch": -0.1,
36
+ "yaw": 0.72
37
+ }
38
+ },
39
+ "steps": [
40
+ {
41
+ "holdTicks": 30,
42
+ "kind": "input",
43
+ "label": "walk out under the old trees",
44
+ "press": "KeyW",
45
+ "release": true
46
+ },
47
+ {
48
+ "kind": "wait",
49
+ "label": "stand on the forest floor",
50
+ "release": true,
51
+ "waitTicks": 80
52
+ }
53
+ ],
54
+ "subject": "player",
55
+ "target": "desktop",
56
+ "viewport": {
57
+ "height": 720,
58
+ "width": 1280
59
+ },
60
+ "warmupFrames": 10
61
+ }
@@ -19,9 +19,9 @@
19
19
  "format:check": "biome format src"
20
20
  },
21
21
  "dependencies": {
22
- "@threenative/core": "0.3.13",
23
- "@threenative/physics": "0.3.13",
24
- "@threenative/ui": "0.3.13",
22
+ "@threenative/core": ">=0.3.15",
23
+ "@threenative/physics": ">=0.3.15",
24
+ "@threenative/ui": ">=0.3.15",
25
25
  "react": "19.2.0",
26
26
  "react-dom": "19.2.0",
27
27
  "three": "0.187.0"
@@ -30,11 +30,11 @@
30
30
  "@tailwindcss/vite": "4.3.3",
31
31
  "@vitejs/plugin-react": "6.0.5",
32
32
  "@types/three": "0.187.0",
33
- "@threenative/assets": "0.3.14",
34
- "@threenative/playtest": "0.3.13",
33
+ "@threenative/assets": ">=0.3.16",
34
+ "@threenative/playtest": ">=0.3.15",
35
35
  "@types/react": "19.2.0",
36
36
  "@types/react-dom": "19.2.0",
37
- "create-threenative": "0.2.18",
37
+ "create-threenative": "0.2.20",
38
38
  "esbuild": "0.27.0",
39
39
  "playwright": "1.62.1",
40
40
  "tailwindcss": "4.3.3",
@@ -45,7 +45,7 @@
45
45
  "eslint": "10.13.0"
46
46
  },
47
47
  "optionalDependencies": {
48
- "@threenative/runtime-native": "0.3.13"
48
+ "@threenative/runtime-native": ">=0.3.15"
49
49
  },
50
50
  "overrides": {
51
51
  "sharp": ">=0.35.4",
@@ -0,0 +1,61 @@
1
+ {
2
+ "name": "adventure-grass",
3
+ "target": "web",
4
+ "schemaVersion": 1,
5
+ "viewport": {
6
+ "width": 1280,
7
+ "height": 720
8
+ },
9
+ "warmupFrames": 10,
10
+ "subject": "player",
11
+ "artifacts": {
12
+ "screenshots": "after"
13
+ },
14
+ "steps": [
15
+ {
16
+ "kind": "input",
17
+ "label": "walk off the path into the grass",
18
+ "press": "KeyA",
19
+ "holdTicks": 45,
20
+ "release": true
21
+ },
22
+ {
23
+ "kind": "wait",
24
+ "label": "stand in the grass",
25
+ "waitTicks": 90,
26
+ "release": true
27
+ }
28
+ ],
29
+ "assert": {
30
+ "diagnostics": {
31
+ "noConsoleErrors": true,
32
+ "noNetworkErrors": true,
33
+ "noRuntimeDiagnostics": true,
34
+ "runtimeReady": true
35
+ },
36
+ "components": [
37
+ {
38
+ "entity": "grass",
39
+ "component": "visibleChunks",
40
+ "gte": 1,
41
+ "allowTrivial": "Streamed grass chunks draw round the camera at the spawn."
42
+ },
43
+ {
44
+ "entity": "grass",
45
+ "component": "standNear",
46
+ "lte": 0.6,
47
+ "allowTrivial": "A blade half a metre from Wren is pushed over: its standing height is at most 0.6 of rest."
48
+ },
49
+ {
50
+ "entity": "grass",
51
+ "component": "standFar",
52
+ "gte": 0.9,
53
+ "allowTrivial": "A blade 3 m from Wren stands at its resting lean, out of her reach."
54
+ }
55
+ ],
56
+ "movement": {
57
+ "entity": "player",
58
+ "minDistance": 1.5
59
+ }
60
+ }
61
+ }
@@ -6,7 +6,7 @@
6
6
  "assert": {
7
7
  "performance": {
8
8
  "maxDrawCalls": 600,
9
- "maxTriangles": 190000
9
+ "maxTriangles": 480000
10
10
  },
11
11
  "renderChain": {
12
12
  "tier": "high",
@@ -157,8 +157,8 @@
157
157
  {
158
158
  "id": "state",
159
159
  "path": "assetLoads",
160
- "equals": 5,
161
- "allowTrivial": "Every model and the sky are built in code; the loader is asked only for the five shared tiling photos in src/render/surface.ts."
160
+ "equals": 11,
161
+ "allowTrivial": "Every model and the sky are built in code; the loader is asked for the five shared tiling photos in src/render/surface.ts and the six baked forest-floor props in assets/floor-*.glb (PRD-889)."
162
162
  },
163
163
  {
164
164
  "id": "state",
@@ -0,0 +1,61 @@
1
+ {
2
+ "name": "adventure-woodland-floor",
3
+ "target": "web",
4
+ "schemaVersion": 1,
5
+ "viewport": {
6
+ "width": 1280,
7
+ "height": 720
8
+ },
9
+ "warmupFrames": 10,
10
+ "subject": "player",
11
+ "artifacts": {
12
+ "screenshots": "after"
13
+ },
14
+ "steps": [
15
+ {
16
+ "holdTicks": 30,
17
+ "kind": "input",
18
+ "label": "walk out under the old trees",
19
+ "press": "KeyW",
20
+ "release": true
21
+ },
22
+ {
23
+ "kind": "wait",
24
+ "label": "stand on the forest floor",
25
+ "release": true,
26
+ "waitTicks": 80
27
+ }
28
+ ],
29
+ "assert": {
30
+ "diagnostics": {
31
+ "noConsoleErrors": true,
32
+ "noNetworkErrors": true,
33
+ "noRuntimeDiagnostics": true,
34
+ "runtimeReady": true
35
+ },
36
+ "components": [
37
+ {
38
+ "entity": "floor",
39
+ "component": "instances",
40
+ "gte": 20,
41
+ "allowTrivial": "Baked logs, stumps, twigs, litter and ferns draw round Wren: the floor is not empty."
42
+ },
43
+ {
44
+ "entity": "floor",
45
+ "component": "visibleTiles",
46
+ "gte": 3,
47
+ "allowTrivial": "At least three streamed floor tiles stand inside the draw distance."
48
+ }
49
+ ],
50
+ "movement": {
51
+ "entity": "player",
52
+ "minDistance": 1.0
53
+ }
54
+ },
55
+ "setup": {
56
+ "aim": {
57
+ "pitch": -0.1,
58
+ "yaw": 0.72
59
+ }
60
+ }
61
+ }
@@ -1,5 +1,5 @@
1
1
  import type { Group, PerspectiveCamera, Vector3 } from "three";
2
- import { Box3, MathUtils, Vector3 as V3 } from "three";
2
+ import { Box3, MathUtils, Mesh, Vector3 as V3 } from "three";
3
3
  import { createReticle } from "../render/creatures.js";
4
4
 
5
5
  /** Anything Wren can lock onto and cut: Mosslings, the Warden, the practice dummies. */
@@ -60,6 +60,12 @@ export class LockOn {
60
60
  readonly #view = new V3();
61
61
  readonly #to = new V3();
62
62
  readonly #marker = new Box3();
63
+ /** The reticle's own box, measured once: it only moves, turns and scales. */
64
+ readonly #reticleBox = new Box3().setFromObject(this.reticle);
65
+ readonly #partBox = new Box3();
66
+ /** The target's meshes, collected once per target. */
67
+ #meshSource: ITarget | undefined;
68
+ #meshes: Mesh[] = [];
63
69
 
64
70
  update(
65
71
  dt: number,
@@ -94,14 +100,32 @@ export class LockOn {
94
100
  this.#sticky = this.target !== undefined;
95
101
  this.justAcquired = this.target !== undefined;
96
102
  }
103
+ }
104
+
105
+ /**
106
+ * Bounds and reticle for this frame, after everything that moves has moved.
107
+ *
108
+ * Called separately from `update` because the lock must be picked before the hero reads its
109
+ * target, while the creatures it frames move later in the frame; placing it here is what keeps
110
+ * the arrow on the body rather than a frame behind it.
111
+ */
112
+ place(camera: PerspectiveCamera, dt: number): void {
97
113
  const target = this.target;
98
114
  this.reticle.visible = target !== undefined;
99
115
  this.markerLift = 0;
100
116
  this.markerTop = 0;
101
117
  if (target !== undefined) {
102
118
  // The target's live bounds, not a fixed offset: a rearing Warden or a hopping Mossling keeps
103
- // the arrow over its real top.
104
- const box = this.bounds.setFromObject(target.mesh);
119
+ // the arrow over its real top. The meshes are collected once per target and each frame only
120
+ // transforms its own box, which is what `setFromObject` did without the per-frame walk.
121
+ target.mesh.updateWorldMatrix(true, true);
122
+ const box = this.bounds.makeEmpty();
123
+ for (const mesh of this.#meshesOf(target)) {
124
+ if (mesh.geometry.boundingBox === null) mesh.geometry.computeBoundingBox();
125
+ const part = mesh.geometry.boundingBox;
126
+ if (part === null) continue;
127
+ box.union(this.#partBox.copy(part).applyMatrix4(mesh.matrixWorld));
128
+ }
105
129
  const tall = MathUtils.clamp((box.max.y - box.min.y) / 1.8, 0.75, 1.25);
106
130
  this.#spin += dt * 1.6;
107
131
  const lift = LIFT + 0.05 * tall + Math.sin(this.#spin * 2.5) * 0.06;
@@ -118,12 +142,26 @@ export class LockOn {
118
142
  Math.tan(MathUtils.degToRad(camera.fov / 2));
119
143
  this.reticle.scale.setScalar(Math.max(tall, (MIN_SCREEN_SHARE * span) / ARROW_HEIGHT));
120
144
  // Measured, not assumed: the gap from the target's top to the marker's own lowest point.
121
- const marker = this.#marker.setFromObject(this.reticle);
145
+ this.reticle.updateWorldMatrix(true, false);
146
+ const marker = this.#marker.copy(this.#reticleBox).applyMatrix4(this.reticle.matrixWorld);
122
147
  this.markerLift = marker.min.y - box.max.y;
123
148
  this.markerTop = marker.max.y;
124
149
  }
125
150
  }
126
151
 
152
+ /** The meshes a target's bounds cover: `setFromObject` walked them every frame, and a creature's
153
+ * mesh set never changes while it is locked. */
154
+ #meshesOf(target: ITarget): readonly Mesh[] {
155
+ if (this.#meshSource !== target) {
156
+ this.#meshes = [];
157
+ target.mesh.traverse((object) => {
158
+ if (object instanceof Mesh) this.#meshes.push(object);
159
+ });
160
+ this.#meshSource = target;
161
+ }
162
+ return this.#meshes;
163
+ }
164
+
127
165
  /**
128
166
  * The toggle's next target: with none locked, the same pick a hold makes; with one locked, the
129
167
  * next farther hostile in range, and `undefined` (drop) after the farthest.
@@ -7,6 +7,9 @@ import type { ITarget } from "./LockOn.js";
7
7
  const CAPSULE = { halfHeight: 0.55, radius: 0.75 } as const;
8
8
  const FOOT_OFFSET = CAPSULE.halfHeight + CAPSULE.radius;
9
9
 
10
+ /** The vector from the Warden to the hero: `update` runs every frame, so it uses one instance. */
11
+ const toHero = new Vector3();
12
+
10
13
  /** The Warden's numbers, in metres and seconds. Kit design values. */
11
14
  export const WARDEN_FEEL = {
12
15
  health: 3,
@@ -101,7 +104,7 @@ export class Warden implements ITarget {
101
104
  const feel = WARDEN_FEEL;
102
105
  this.#timer += dt;
103
106
  this.#flash = Math.max(0, this.#flash - dt);
104
- const to = new Vector3().subVectors(hero.mesh.position, this.mesh.position).setY(0);
107
+ const to = toHero.subVectors(hero.mesh.position, this.mesh.position).setY(0);
105
108
  let speed = 0;
106
109
  switch (this.state) {
107
110
  case "dormant":