create-threenative 0.2.18 → 0.2.21

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 (186) hide show
  1. package/agent-docs/references/assertion-reference.md +1 -1
  2. package/agent-docs/references/capability-reference.md +792 -5
  3. package/agent-docs/references/kit-racing.md +4 -2
  4. package/agent-docs/references/performance-basics.md +2 -1
  5. package/agent-docs/references/terrain-authoring.md +25 -7
  6. package/agent-files/.agents/skills/prd-creator/SKILL.md +24 -0
  7. package/dist/index.js +268 -237
  8. package/dist/quality.d.ts +5 -1
  9. package/dist/quality.js +75 -6
  10. package/dist/terrain-kit.js +1 -1
  11. package/dist/threenative.js +7 -5
  12. package/dist/web-engine-post-effects.js +6 -0
  13. package/dist/web-engine-runtime.js +407 -38
  14. package/package.json +6 -6
  15. package/template-assets/assets/floor-fern-0.glb +0 -0
  16. package/template-assets/assets/floor-litter-0.glb +0 -0
  17. package/template-assets/assets/floor-log-0.glb +0 -0
  18. package/template-assets/assets/floor-log-1.glb +0 -0
  19. package/template-assets/assets/floor-stump-0.glb +0 -0
  20. package/template-assets/assets/floor-twig-0.glb +0 -0
  21. package/template-assets/patches/three@0.187.0.patch +108 -21
  22. package/template-assets/quality/eslint.config.js +1 -1
  23. package/templates/action-rpg/package.json +7 -7
  24. package/templates/action-rpg/src/loot/drops.ts +3 -7
  25. package/templates/action-rpg/src/render/camera.ts +2 -2
  26. package/templates/action-rpg/src/render/clouds.ts +3 -1
  27. package/templates/action-rpg/src/render/materials.ts +3 -2
  28. package/templates/action-rpg/src/render/touch-controls.ts +7 -6
  29. package/templates/action-rpg/src/scenes/Play.ts +1 -15
  30. package/templates/adventure/AGENTS.md +3 -3
  31. package/templates/adventure/CLAUDE.md +3 -3
  32. package/templates/adventure/native-playtests/survives.playtest.json +12 -0
  33. package/templates/adventure/native-playtests/woodland-floor.playtest.json +61 -0
  34. package/templates/adventure/package.json +7 -7
  35. package/templates/adventure/playtests/grass.playtest.json +61 -0
  36. package/templates/adventure/playtests/performance.playtest.json +1 -1
  37. package/templates/adventure/playtests/survives.playtest.json +2 -2
  38. package/templates/adventure/playtests/woodland-floor.playtest.json +61 -0
  39. package/templates/adventure/src/entities/LockOn.ts +42 -4
  40. package/templates/adventure/src/entities/Warden.ts +12 -3
  41. package/templates/adventure/src/level/Vale.ts +241 -16
  42. package/templates/adventure/src/render/camera.ts +2 -2
  43. package/templates/adventure/src/render/foliage.ts +64 -20
  44. package/templates/adventure/src/render/grass.ts +325 -0
  45. package/templates/adventure/src/render/materials.ts +3 -2
  46. package/templates/adventure/src/render/palette.ts +3 -0
  47. package/templates/adventure/src/render/touch-controls.ts +4 -1
  48. package/templates/adventure/src/scenes/Play.ts +96 -1
  49. package/templates/collectathon/package.json +7 -7
  50. package/templates/collectathon/src/level/Course.ts +2 -7
  51. package/templates/collectathon/src/level/terrain.ts +2 -1
  52. package/templates/collectathon/src/render/camera.ts +2 -2
  53. package/templates/collectathon/src/render/ground.ts +4 -4
  54. package/templates/collectathon/src/render/hero.ts +1 -1
  55. package/templates/collectathon/src/render/materials.ts +0 -1
  56. package/templates/collectathon/src/render/sky.ts +4 -3
  57. package/templates/kart/package.json +6 -6
  58. package/templates/kart/src/entities/Kart.ts +2 -1
  59. package/templates/kart/src/render/course.ts +2 -1
  60. package/templates/kart/src/track/Course.ts +3 -1
  61. package/templates/minimal/package.json +6 -6
  62. package/templates/minimal/src/render/camera.ts +2 -2
  63. package/templates/minimal/src/render/clouds.ts +3 -1
  64. package/templates/minimal/src/render/materials.ts +3 -2
  65. package/templates/minimal/src/render/touch-controls.ts +7 -6
  66. package/templates/platformer/package.json +7 -7
  67. package/templates/platformer/playtests/collect.playtest.json +4 -1
  68. package/templates/platformer/src/level/Stage.ts +2 -6
  69. package/templates/platformer/src/scenes/Play.ts +2 -1
  70. package/templates/puzzle/package.json +7 -7
  71. package/templates/puzzle/src/entities/Warden.ts +3 -3
  72. package/templates/puzzle/src/render/camera.ts +2 -2
  73. package/templates/puzzle/src/render/touch-controls.ts +7 -6
  74. package/templates/racing/AGENTS.md +2 -2
  75. package/templates/racing/CLAUDE.md +2 -2
  76. package/templates/racing/CREDITS.md +29 -0
  77. package/templates/racing/assets/engine-loop.wav +0 -0
  78. package/templates/racing/assets/grass/Grass004_color.jpg +0 -0
  79. package/templates/racing/assets/grass/Grass004_normal.jpg +0 -0
  80. package/templates/racing/assets/grass/Grass004_roughness.jpg +0 -0
  81. package/templates/racing/assets/nitro-burst.wav +0 -0
  82. package/templates/racing/assets/tyre-squeal.wav +0 -0
  83. package/templates/racing/package.json +7 -7
  84. package/templates/racing/playtests/drift-natural.playtest.json +68 -0
  85. package/templates/racing/playtests/drift.playtest.json +100 -0
  86. package/templates/racing/playtests/hud.playtest.json +117 -0
  87. package/templates/racing/playtests/launch-pose.playtest.json +34 -0
  88. package/templates/racing/playtests/nitro.playtest.json +158 -0
  89. package/templates/racing/playtests/outcome.playtest.json +4 -4
  90. package/templates/racing/playtests/performance.playtest.json +1 -1
  91. package/templates/racing/playtests/steady-camera.playtest.json +88 -0
  92. package/templates/racing/src/audio/engine.ts +138 -0
  93. package/templates/racing/src/entities/CarBody.ts +83 -10
  94. package/templates/racing/src/entities/Drift.ts +243 -0
  95. package/templates/racing/src/entities/LineDriver.ts +2 -2
  96. package/templates/racing/src/entities/Nitro.ts +72 -0
  97. package/templates/racing/src/entities/RacingCar.ts +86 -21
  98. package/templates/racing/src/entities/Rival.ts +35 -21
  99. package/templates/racing/src/game.ts +6 -0
  100. package/templates/racing/src/gauges.ts +74 -0
  101. package/templates/racing/src/render/camera.ts +29 -4
  102. package/templates/racing/src/render/clouds.ts +3 -1
  103. package/templates/racing/src/render/effects.ts +244 -0
  104. package/templates/racing/src/render/materials.ts +43 -8
  105. package/templates/racing/src/render/shapes.ts +37 -0
  106. package/templates/racing/src/render/skids.ts +84 -0
  107. package/templates/racing/src/render/touch-controls.ts +10 -10
  108. package/templates/racing/src/scenes/Race.ts +277 -25
  109. package/templates/racing/src/state.ts +35 -0
  110. package/templates/racing/src/style.css +3 -0
  111. package/templates/racing/src/track/Ranking.ts +8 -4
  112. package/templates/racing/src/track/Track.ts +132 -58
  113. package/templates/racing/src/track/TrackSector.ts +19 -1
  114. package/templates/racing/src/track/circuit.ts +21 -15
  115. package/templates/racing/src/ui/GameUi.tsx +0 -2
  116. package/templates/racing/src/ui/Hud.tsx +417 -50
  117. package/templates/racing/threenative.config.ts +15 -0
  118. package/templates/racing/tools/make-racing-audio.mjs +388 -0
  119. package/templates/rain/package.json +6 -6
  120. package/templates/rain/src/render/noise-volume.ts +2 -1
  121. package/templates/rain/src/state.ts +3 -1
  122. package/templates/rain/src/ui/GameUi.tsx +1 -1
  123. package/templates/rain/src/ui/automation.ts +10 -8
  124. package/templates/rain/src/ui/tempest.ts +3 -4
  125. package/templates/rts/package.json +6 -6
  126. package/templates/rts/src/sim/terrain.ts +1 -0
  127. package/templates/rts/src/sim/types.ts +1 -0
  128. package/templates/runner/package.json +7 -7
  129. package/templates/runner/src/render/clouds.ts +3 -1
  130. package/templates/runner/src/render/materials.ts +3 -2
  131. package/templates/runner/src/render/touch-controls.ts +7 -6
  132. package/templates/runner/src/scenes/Run.ts +4 -9
  133. package/templates/sailing/package.json +7 -7
  134. package/templates/sailing/src/render/touch-controls.ts +7 -6
  135. package/templates/shooter/package.json +7 -7
  136. package/templates/shooter/src/render/clouds.ts +3 -1
  137. package/templates/snow/package.json +7 -7
  138. package/templates/snow/src/entities/Explorer.ts +6 -12
  139. package/templates/snow/src/render/bootPrint.ts +3 -1
  140. package/templates/snow/src/render/camera.ts +3 -2
  141. package/templates/snow/src/render/scenery.ts +3 -3
  142. package/templates/snow/src/render/touch-controls.ts +7 -6
  143. package/templates/snow/src/render/weather.ts +3 -5
  144. package/templates/snow/src/terrain.ts +2 -1
  145. package/templates/starter/native-playtests/render-chain.playtest.json +9 -9
  146. package/templates/starter/package.json +7 -7
  147. package/templates/starter/src/entities/Player.ts +10 -2
  148. package/templates/starter/src/render/camera.ts +2 -2
  149. package/templates/starter/src/render/clouds.ts +3 -1
  150. package/templates/starter/src/render/materials.ts +3 -2
  151. package/templates/starter/src/render/touch-controls.ts +7 -6
  152. package/templates/starter/src/scenes/Play.ts +1 -14
  153. package/templates/tower-defense/package.json +7 -7
  154. package/templates/tower-defense/src/render/shapes.ts +1 -2
  155. package/templates/tower-defense/src/scenes/Battle.ts +3 -8
  156. package/template-assets/terrain/alpine/assets.json +0 -12
  157. package/template-assets/terrain/alpine/bake.mjs +0 -6
  158. package/template-assets/terrain/alpine/credits.json +0 -164
  159. package/template-assets/terrain/alpine/heightmap.r16 +0 -0
  160. package/template-assets/terrain/alpine/recipe.json +0 -119
  161. package/template-assets/terrain/alpine/surface.json +0 -53
  162. package/template-assets/terrain/coastal/assets.json +0 -11
  163. package/template-assets/terrain/coastal/bake.mjs +0 -6
  164. package/template-assets/terrain/coastal/credits.json +0 -117
  165. package/template-assets/terrain/coastal/heightmap.r16 +0 -0
  166. package/template-assets/terrain/coastal/recipe.json +0 -113
  167. package/template-assets/terrain/coastal/surface.json +0 -41
  168. package/template-assets/terrain/desert/assets.json +0 -12
  169. package/template-assets/terrain/desert/bake.mjs +0 -6
  170. package/template-assets/terrain/desert/credits.json +0 -164
  171. package/template-assets/terrain/desert/heightmap.r16 +0 -0
  172. package/template-assets/terrain/desert/recipe.json +0 -108
  173. package/template-assets/terrain/desert/surface.json +0 -54
  174. package/template-assets/terrain/forest/assets.json +0 -65
  175. package/template-assets/terrain/forest/bake.mjs +0 -8
  176. package/template-assets/terrain/forest/credits.json +0 -225
  177. package/template-assets/terrain/forest/heightmap.r16 +0 -0
  178. package/template-assets/terrain/forest/recipe.json +0 -350
  179. package/template-assets/terrain/forest/surface.json +0 -79
  180. package/template-assets/terrain/tundra/assets.json +0 -12
  181. package/template-assets/terrain/tundra/bake.mjs +0 -6
  182. package/template-assets/terrain/tundra/credits.json +0 -164
  183. package/template-assets/terrain/tundra/heightmap.r16 +0 -0
  184. package/template-assets/terrain/tundra/recipe.json +0 -277
  185. package/template-assets/terrain/tundra/surface.json +0 -54
  186. package/templates/racing/src/ui/Menu.tsx +0 -7
@@ -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,
@@ -50,6 +53,8 @@ export class Warden implements ITarget {
50
53
  #flash = 0;
51
54
  #heading = new Vector3();
52
55
  #last = new Vector3();
56
+ /** Charge steps in a row that covered under a third of what they asked for. */
57
+ #blocked = 0;
53
58
 
54
59
  constructor(
55
60
  readonly id: string,
@@ -101,7 +106,7 @@ export class Warden implements ITarget {
101
106
  const feel = WARDEN_FEEL;
102
107
  this.#timer += dt;
103
108
  this.#flash = Math.max(0, this.#flash - dt);
104
- const to = new Vector3().subVectors(hero.mesh.position, this.mesh.position).setY(0);
109
+ const to = toHero.subVectors(hero.mesh.position, this.mesh.position).setY(0);
105
110
  let speed = 0;
106
111
  switch (this.state) {
107
112
  case "dormant":
@@ -113,15 +118,19 @@ export class Warden implements ITarget {
113
118
  this.#heading.copy(to).normalize();
114
119
  this.#face(Math.atan2(to.x, to.z), 1);
115
120
  this.#last.copy(this.mesh.position);
121
+ this.#blocked = 0;
116
122
  this.#set("charge");
117
123
  }
118
124
  break;
119
125
  case "charge": {
120
126
  speed = feel.chargeSpeed;
121
- // Met a wall: it covered under a third of what it asked for in the last step.
127
+ // Met a wall: it covered under a third of what it asked for in two steps running. A wall
128
+ // stops every step; a lone short step is the character controller catching a floor
129
+ // triangle's edge, and the charge goes on.
122
130
  const moved = this.#last.distanceTo(this.mesh.position);
123
131
  this.#last.copy(this.mesh.position);
124
- if (this.#timer > 0.15 && moved < feel.chargeSpeed * dt * 0.3) {
132
+ this.#blocked = moved < feel.chargeSpeed * dt * 0.3 ? this.#blocked + 1 : 0;
133
+ if (this.#timer > 0.15 && this.#blocked >= 2) {
125
134
  this.stuns += 1;
126
135
  this.#set("stunned");
127
136
  speed = 0;
@@ -1,13 +1,24 @@
1
+ import { ScatterField3D } from "@threenative/core";
1
2
  import {
3
+ Box3,
2
4
  BoxGeometry,
5
+ type BufferGeometry,
3
6
  CylinderGeometry,
4
7
  Group,
8
+ type Material,
9
+ MathUtils,
5
10
  Mesh,
6
11
  type Object3D,
7
12
  PlaneGeometry,
8
13
  Vector3,
9
14
  } from "three";
10
- import { type IValeSite, plantVale, valeGround } from "../render/foliage.js";
15
+ import {
16
+ type FloorKind,
17
+ type IValeSite,
18
+ floorPart,
19
+ plantVale,
20
+ valeGround,
21
+ } from "../render/foliage.js";
11
22
  import { flat, mottle } from "../render/materials.js";
12
23
  import { C } from "../render/palette.js";
13
24
  import { createHut, createPitcherLantern, createSign } from "../render/props.js";
@@ -17,6 +28,7 @@ import { surfaced } from "../render/surface.js";
17
28
  export function makeRng(seed: number): () => number {
18
29
  let state = seed >>> 0;
19
30
  return () => {
31
+ // eslint-disable-next-line no-restricted-syntax -- The clearing is authored against this mulberry32 stream; the engine's seeded RNG is an LCG, so swapping it builds a different level.
20
32
  state = (state + 0x6d2b79f5) >>> 0;
21
33
  let t = state;
22
34
  t = Math.imul(t ^ (t >>> 15), t | 1);
@@ -44,6 +56,15 @@ export interface IVale {
44
56
  readonly hut: { readonly at: Vector3; readonly lanterns: number };
45
57
  /** Flagstones laid along the path, and the share of the path's centre line they cover. */
46
58
  readonly path: { readonly stones: number; readonly cover: number };
59
+ /** True on open ground: off the path, out of the ruin's lane and clear of the play spaces. */
60
+ readonly clear: (x: number, z: number, width: number) => boolean;
61
+ /** The old trees that frame the clearing, with the trunk radius nothing scatters inside. */
62
+ readonly trees: readonly { readonly radius: number; readonly x: number; readonly z: number }[];
63
+ /**
64
+ * 0..1 leaf litter under the old trees, easing out to the open meadow. The ground paints its soil
65
+ * by it, the grass thins by it and the debris scatters by it, so the three cannot disagree.
66
+ */
67
+ readonly floorZone: (x: number, z: number) => number;
47
68
  }
48
69
 
49
70
  // ------------------------------------------------------------------------------------ the ground
@@ -52,7 +73,7 @@ export interface IVale {
52
73
 
53
74
  const smooth = (a: number, b: number, t: number): number => {
54
75
  const u = Math.min(1, Math.max(0, (t - a) / (b - a)));
55
- return u * u * (3 - 2 * u);
76
+ return MathUtils.smoothstep(u, 0, 1);
56
77
  };
57
78
  /** 0..1 rolling noise from two crossed sine sheets. */
58
79
  const wave = (x: number, z: number, f: number): number =>
@@ -103,16 +124,24 @@ export const STREAM = {
103
124
  water: -0.3,
104
125
  };
105
126
 
106
- const distanceToSegment = (
127
+ /** Plain length: `Math.hypot` costs several times more, and the grass asks once per blade. */
128
+ const hyp = (dx: number, dz: number): number => Math.sqrt(dx * dx + dz * dz);
129
+
130
+ /** Squared distance to a segment; the caller takes one square root for the nearest. */
131
+ const distanceSqToSegment = (
107
132
  x: number,
108
133
  z: number,
109
- [ax, az]: readonly [number, number],
110
- [bx, bz]: readonly [number, number],
134
+ a: readonly [number, number],
135
+ b: readonly [number, number],
111
136
  ): number => {
112
- const dx = bx - ax;
113
- const dz = bz - az;
137
+ const ax = a[0];
138
+ const az = a[1];
139
+ const dx = b[0] - ax;
140
+ const dz = b[1] - az;
114
141
  const t = Math.min(1, Math.max(0, ((x - ax) * dx + (z - az) * dz) / (dx * dx + dz * dz)));
115
- return Math.hypot(x - ax - t * dx, z - az - t * dz);
142
+ const ex = x - ax - t * dx;
143
+ const ez = z - az - t * dz;
144
+ return ex * ex + ez * ez;
116
145
  };
117
146
 
118
147
  /** Metres from the stream's centre line. */
@@ -121,18 +150,35 @@ export function streamDistance(x: number, z: number): number {
121
150
  for (let i = 1; i < STREAM.points.length; i += 1) {
122
151
  const a = STREAM.points[i - 1];
123
152
  const b = STREAM.points[i];
124
- if (a !== undefined && b !== undefined) best = Math.min(best, distanceToSegment(x, z, a, b));
153
+ if (a !== undefined && b !== undefined) best = Math.min(best, distanceSqToSegment(x, z, a, b));
125
154
  }
126
- return best;
155
+ return Math.sqrt(best);
156
+ }
157
+
158
+ /** Where the streamed grass grows, 0..1: bare on the path, in the stream, under the hut and in the cave mouth. */
159
+ export function grassCover(x: number, z: number): number {
160
+ if (z < CLEARING.north + 1 && Math.abs(x) < 3.5) return 0;
161
+ return (
162
+ smooth(1.5, 2.3, Math.abs(x - pathX(z))) *
163
+ smooth(1.3, 2.4, streamDistance(x, z)) *
164
+ smooth(2.4, 3.4, hyp(x - HUT.x, z - HUT.z))
165
+ );
127
166
  }
128
167
 
168
+ /** The square the grass grows in: the clearing and the first hills round it. */
169
+ export const GRASS_BOUNDS = {
170
+ maxX: CLEARING.half + 10,
171
+ maxZ: CLEARING.south + 10,
172
+ minX: -CLEARING.half - 10,
173
+ minZ: CLEARING.north - 6,
174
+ };
175
+
129
176
  /** 1 on a play space, the path or the cave approach, easing to 0 over a few metres round them. */
130
177
  function flatness(x: number, z: number): number {
131
178
  let f = 1 - smooth(2.2, 4.4, Math.abs(x - pathX(z)));
132
179
  if (z < -15) f = Math.max(f, 1 - smooth(3.5, 5.5, Math.abs(x)));
133
- f = Math.max(f, 1 - smooth(HUT.radius, HUT.radius + 1.6, Math.hypot(x - HUT.x, z - HUT.z)));
134
- for (const [px, pz, r] of PADS)
135
- f = Math.max(f, 1 - smooth(r, r + 3.2, Math.hypot(x - px, z - pz)));
180
+ f = Math.max(f, 1 - smooth(HUT.radius, HUT.radius + 1.6, hyp(x - HUT.x, z - HUT.z)));
181
+ for (const [px, pz, r] of PADS) f = Math.max(f, 1 - smooth(r, r + 3.2, hyp(x - px, z - pz)));
136
182
  return f;
137
183
  }
138
184
 
@@ -140,15 +186,14 @@ function flatness(x: number, z: number): number {
140
186
  export function valeHeight(x: number, z: number): number {
141
187
  // The rise to the cave mouth: the clearing's north end climbs 1.2 m to the cliff.
142
188
  const rise = 1.2 * smooth(-11, -17, z);
143
- const ledge =
144
- HUT.lift * (1 - smooth(HUT.radius, HUT.radius + 1.6, Math.hypot(x - HUT.x, z - HUT.z)));
189
+ const ledge = HUT.lift * (1 - smooth(HUT.radius, HUT.radius + 1.6, hyp(x - HUT.x, z - HUT.z)));
145
190
  // Inside the walls: rolling banks, higher toward the walls, and the outcrops.
146
191
  const edge = Math.min(CLEARING.half - Math.abs(x), z - CLEARING.north, CLEARING.south - z);
147
192
  const tunnel = Math.abs(x) < 3.5 && z < CLEARING.north + 1;
148
193
  let relief = 0.35 + 1.3 * wave(x, z, 0.23) + 0.45 * wave(x + 7, z - 3, 0.61);
149
194
  if (edge > 0) relief += 1.4 * (1 - smooth(0, 4.5, edge));
150
195
  for (const [ox, oz, r, h] of OUTCROPS)
151
- relief += h * (1 - smooth(r * 0.5, r, Math.hypot(x - ox, z - oz)));
196
+ relief += h * (1 - smooth(r * 0.5, r, hyp(x - ox, z - oz)));
152
197
  // Outside them: a steep rocky bank, then wooded hills.
153
198
  if (edge < 0 && !tunnel)
154
199
  relief += 2.2 * smooth(0, 3, -edge) + (0.8 + 3.4 * wave(x, z, 0.09)) * smooth(2, 14, -edge);
@@ -357,8 +402,19 @@ export function buildVale(rng: () => number): IVale {
357
402
  ground.inner.userData.solid = true;
358
403
  group.add(planting.group, ground.inner, ground.outer);
359
404
 
405
+ const oldTrees = trees.map(([x, z, s]) => ({ radius: 0.6 * s, x, z }));
360
406
  return {
361
407
  caveExit: at(0, -17),
408
+ clear: site.clear,
409
+ floorZone: (x, z) => {
410
+ let zone = 0;
411
+ for (const tree of oldTrees) {
412
+ const d = Math.hypot(x - tree.x, z - tree.z);
413
+ zone = Math.max(zone, 1 - smooth(tree.radius * 2.4, tree.radius * 8, d));
414
+ }
415
+ return zone;
416
+ },
417
+ trees: oldTrees,
362
418
  caveMouth: at(0, -23),
363
419
  dummies: [at(-1.6, 4), at(1.8, 4.5)],
364
420
  group,
@@ -381,3 +437,172 @@ export function buildVale(rng: () => number): IVale {
381
437
  export function isSolid(object: Object3D): boolean {
382
438
  return object.userData.solid === true;
383
439
  }
440
+
441
+ // ------------------------------------------------------------------------- the woodland floor
442
+ // Baked props, streamed round Wren. The generators live in @threenative/procedural-environment and
443
+ // the bytes in ../template-assets/assets (regenerate with `pnpm tsx scripts/bake-floor-assets.ts`);
444
+ // the material is the kit's own, in render/foliage.ts.
445
+
446
+ /** What this needs of the loader: `ctx.assets` satisfies it. */
447
+ export interface IFloorLoader {
448
+ model(path: string): Promise<{ readonly scene: Object3D }>;
449
+ }
450
+
451
+ /** One baked prop, its levels of detail near to far, and how many a square metre holds. */
452
+ interface IFloorProp {
453
+ readonly density: number;
454
+ readonly drawDistance: number;
455
+ readonly files: readonly string[];
456
+ readonly kind: FloorKind;
457
+ readonly scale: readonly [number, number];
458
+ }
459
+
460
+ const FLOOR_PROPS: Readonly<Record<string, IFloorProp>> = {
461
+ // The kit's grass stands knee-high, so a prop that should read is sized to clear it.
462
+ fern: {
463
+ density: 0.5,
464
+ drawDistance: 24,
465
+ files: ["floor-fern-0.glb"],
466
+ kind: "frond",
467
+ scale: [1.5, 2.2],
468
+ },
469
+ litter: {
470
+ density: 1.6,
471
+ drawDistance: 18,
472
+ files: ["floor-litter-0.glb"],
473
+ kind: "litter",
474
+ scale: [2.2, 3.2],
475
+ },
476
+ log: {
477
+ density: 0.08,
478
+ drawDistance: 30,
479
+ files: ["floor-log-0.glb", "floor-log-1.glb"],
480
+ kind: "wood",
481
+ scale: [1.6, 2.2],
482
+ },
483
+ stump: {
484
+ density: 0.07,
485
+ drawDistance: 30,
486
+ files: ["floor-stump-0.glb"],
487
+ kind: "wood",
488
+ scale: [1.5, 2.1],
489
+ },
490
+ twig: {
491
+ density: 0.35,
492
+ drawDistance: 20,
493
+ files: ["floor-twig-0.glb"],
494
+ kind: "wood",
495
+ scale: [2.2, 3.2],
496
+ },
497
+ };
498
+
499
+ export interface IWoodlandFloor {
500
+ readonly group: Group;
501
+ /** One streamed field per prop; the playtest reads their totals. */
502
+ readonly fields: readonly ScatterField3D[];
503
+ /** Builds every tile on the next update regardless of budget: on load, behind the curtain. */
504
+ prewarm(): void;
505
+ update(follow: Vector3): void;
506
+ }
507
+
508
+ /** 0..1 from a point and a salt: a placement is the same whatever order the tiles build in. */
509
+ const jitter = (x: number, z: number, salt: number): number => {
510
+ const h = Math.sin(x * 127.1 + z * 311.7 + salt * 74.7) * 43758.5453;
511
+ return h - Math.floor(h);
512
+ };
513
+
514
+ /** A loaded GLB's primitives in the kit's look: one part per glTF material. */
515
+ function chainsOf(
516
+ model: { readonly scene: Object3D },
517
+ kind: FloorKind,
518
+ ): {
519
+ geometries: BufferGeometry[];
520
+ material: Material;
521
+ }[] {
522
+ const chains: { geometries: BufferGeometry[]; material: Material }[] = [];
523
+ model.scene.traverse((object) => {
524
+ const mesh = object as Mesh;
525
+ if (mesh.isMesh !== true) return;
526
+ const part = floorPart(mesh, kind);
527
+ chains.push({ geometries: [part.geometry], material: part.material });
528
+ });
529
+ return chains;
530
+ }
531
+
532
+ /**
533
+ * The forest floor: logs, stumps, twigs and leaf litter under the old trees, with ferns among them.
534
+ * Every prop is a baked GLB streamed by `ScatterField3D`, placed off the path, out of the play spaces
535
+ * and clear of the trunks, so nothing floats over the ruin's lane or grows out of a tree.
536
+ */
537
+ export async function buildWoodlandFloor(
538
+ assets: IFloorLoader,
539
+ vale: IVale,
540
+ seed = 1986,
541
+ ): Promise<IWoodlandFloor> {
542
+ const group = new Group();
543
+ group.name = "woodland floor";
544
+ const fields: ScatterField3D[] = [];
545
+ let salt = 1;
546
+ for (const [name, prop] of Object.entries(FLOOR_PROPS)) {
547
+ const models = await Promise.all(prop.files.map((file) => assets.model(file)));
548
+ const near = models[0] as { scene: Object3D };
549
+ // Each baked level replaces its part's geometry; the kit's material and the instances stay.
550
+ const chains = chainsOf(near, prop.kind);
551
+ for (const model of models.slice(1)) {
552
+ chainsOf(model, prop.kind).forEach((deeper, index) => {
553
+ const chain = chains[index];
554
+ if (chain !== undefined) chain.geometries.push(...deeper.geometries);
555
+ });
556
+ }
557
+ const propSalt = salt;
558
+ salt += 1;
559
+ // The bake leaves each prop where its own generator put it — a fern's fronds start 0.19 m under
560
+ // its origin, a stump's base 0.06 m over — so the prop is lifted by its own lowest point once
561
+ // the instance scale is known, and nothing floats or sinks.
562
+ const sunk = new Box3().setFromObject(near.scene).min.y;
563
+ const lift = Number.isFinite(sunk) ? -sunk : 0;
564
+ const field = new ScatterField3D({
565
+ // A tile draws once per part, so the floor takes tiles four times the default area: five
566
+ // fields at 16 m tiles add enough lone draws to tip the scene's projection to declining.
567
+ chunkSize: 32,
568
+ density: prop.density,
569
+ drawDistance: prop.drawDistance,
570
+ // The same zone the ground paints and the grass thins by: debris gathers at the foot of the
571
+ // old trees instead of sprinkling evenly over ground that is all grass.
572
+ getDensity: (x, z) => vale.floorZone(x, z),
573
+ getHeight: valeHeight,
574
+ parts: chains.map(({ geometries, material }) => ({ lods: geometries, material })),
575
+ place: (point, out) => {
576
+ if (!vale.clear(point.x, point.z, 0.9)) return false;
577
+ // Deadwood and litter gather at the foot of the old trees, so only the trunk itself is out of
578
+ // bounds: a prop half a metre from a trunk is the look, one inside it is a clipped mesh.
579
+ for (const tree of vale.trees)
580
+ if (Math.hypot(point.x - tree.x, point.z - tree.z) < tree.radius) return false;
581
+ out.x = point.x;
582
+ out.z = point.z;
583
+ out.yaw = jitter(point.x, point.z, propSalt) * Math.PI * 2;
584
+ out.scale =
585
+ prop.scale[0] + jitter(point.x, point.z, propSalt + 7) * (prop.scale[1] - prop.scale[0]);
586
+ out.y = point.y + lift * out.scale + 0.002;
587
+ return true;
588
+ },
589
+ farDensity: 0.45,
590
+ seed: seed + propSalt,
591
+ thinEnd: 24,
592
+ thinStart: 8,
593
+ });
594
+ field.name = `floor ${name}`;
595
+ fields.push(field);
596
+ group.add(field);
597
+ }
598
+ return {
599
+ fields,
600
+ group,
601
+ prewarm: () => {
602
+ for (const field of fields) field.prewarm();
603
+ },
604
+ update: (follow) => {
605
+ for (const field of fields) field.update(follow);
606
+ },
607
+ };
608
+ }
@@ -335,8 +335,8 @@ export function setupCamera(
335
335
  return yaw;
336
336
  },
337
337
  update(focus: Vector3, lock: ILockFrame | undefined, dt: number, watch?: Box3): void {
338
- const rate = 1 - Math.exp(-YAW_RATE * dt);
339
- const quick = 1 - Math.exp(-FRAME_RATE * dt);
338
+ const rate = MathUtils.damp(0, 1, YAW_RATE, dt);
339
+ const quick = MathUtils.damp(0, 1, FRAME_RATE, dt);
340
340
  if (lock !== undefined) {
341
341
  lock.bounds.getCenter(middle);
342
342
  const line = Math.atan2(focus.x - middle.x, focus.z - middle.z);