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
@@ -0,0 +1,325 @@
1
+ // Generated for you. This is ordinary Three.js TSL — edit or delete it freely.
2
+ //
3
+ // The vale's grass look: the blade shape and the material that bends, sways, thins and colours it.
4
+ // `GrassField3D` (built in `scenes/Play.ts`) owns the streaming, the scatter, the LOD and the
5
+ // pushers; everything you see is decided here. Each blade bends along a quadratic Bezier from its
6
+ // root: a resting lean, a gust field that scrolls downwind, a per-blade flutter, and the pushers'
7
+ // pull, which lays it flat round Wren. Far blades thin out by priority while the ones left widen,
8
+ // so the field holds its cover and nothing pops. Lighting is the scene's own (sun, sky, exposure,
9
+ // fog), plus light through the blade when the sun is behind it and darker roots.
10
+ import { BufferAttribute, BufferGeometry, Color, DoubleSide, type Vector4 } from "three";
11
+ import {
12
+ Fn,
13
+ abs,
14
+ attribute,
15
+ cameraPosition,
16
+ cos,
17
+ cross,
18
+ dot,
19
+ float,
20
+ floor,
21
+ fract,
22
+ max,
23
+ min,
24
+ mix,
25
+ modelWorldMatrix,
26
+ normalize,
27
+ positionGeometry,
28
+ positionWorld,
29
+ pow,
30
+ sin,
31
+ smoothstep,
32
+ sqrt,
33
+ time,
34
+ transformNormalToView,
35
+ varying,
36
+ vec2,
37
+ vec3,
38
+ vec4,
39
+ } from "three/tsl";
40
+ import { MeshStandardNodeMaterial, type Node, type UniformNode } from "three/webgpu";
41
+ import { C } from "./palette.js";
42
+ import { SUN_DIRECTION } from "./sky.js";
43
+
44
+ /** Every look value, in one place. Shape and wind are live through the uniforms below. */
45
+ export const GRASS = {
46
+ /** Blade segments near, mid and far: each level is one draw range of the same geometry. */
47
+ segments: [4, 2, 1],
48
+ bladeHeight: 0.5,
49
+ /** ± share of `bladeHeight`. */
50
+ heightVariation: 0.4,
51
+ bladeWidth: 0.05,
52
+ /** Higher stays wide longer, then a sharper tip. */
53
+ taper: 1.7,
54
+ /** Resting lean, 0 upright to 1 flat. */
55
+ lean: 0.34,
56
+ leanVariation: 0.2,
57
+ /** Where the bend happens: low arcs from the root, high is a straight stem with a drooping tip. */
58
+ curve: 0.6,
59
+ /** 0 is a uniform lawn, 1 strong tufts. */
60
+ clumpStrength: 0.75,
61
+ /** Widens edge-on blades so they do not alias into lines. */
62
+ viewThicken: 0.55,
63
+ /** Sinks the roots to hide the seam with the floor. */
64
+ rootSink: 0.03,
65
+ /** Each far blade is this many times wider, holding the cover the thinning took. */
66
+ farWidth: 2.8,
67
+ /** Degrees in the ground plane the wind blows toward (0 = +X, 90 = +Z). */
68
+ windDirection: 25,
69
+ /** Gust fronts travel this fast, m/s, and are this big, metres. */
70
+ windSpeed: 4.5,
71
+ gustScale: 26,
72
+ /** Lean added at the peak of a gust, and the per-blade jitter. */
73
+ windStrength: 0.55,
74
+ flutter: 0.07,
75
+ /** Gusts brighten the blades they bend, which makes wind read as waves from afar. */
76
+ gustHighlight: 0.45,
77
+ /** How far a pusher lays the blades over. */
78
+ pushStrength: 1,
79
+ baseColor: C.grassRoot,
80
+ tipColor: C.grassTip,
81
+ /** Broad patches drift toward this colour. */
82
+ dryColor: C.grassDry,
83
+ dryAmount: 0.35,
84
+ patchScale: 22,
85
+ /** Per-tuft brightness spread. */
86
+ colorVariation: 0.4,
87
+ /** Darkening toward the roots. */
88
+ ambientOcclusion: 0.45,
89
+ /** Sunlight through a blade lit from behind. */
90
+ translucency: 0.7,
91
+ /** 0 lights each blade by its own normal, 1 like the ground under it (calmer). */
92
+ terrainNormalBlend: 0.6,
93
+ } as const;
94
+
95
+ const rgb = (hex: number): Node<"vec3"> => {
96
+ const c = new Color(hex);
97
+ return vec3(c.r, c.g, c.b);
98
+ };
99
+
100
+ /** The sun colour the translucency carries, as the key light's colour. */
101
+ const SUN_COLOR = new Color(0xffd9a0);
102
+
103
+ /** The field's uniforms the material reads: what `GrassField3D` hands to `grassMaterial`. */
104
+ export interface IGrassFieldUniforms {
105
+ readonly thinStart: UniformNode<"float", number>;
106
+ readonly thinEnd: UniformNode<"float", number>;
107
+ readonly farDensity: UniformNode<"float", number>;
108
+ readonly fadeStart: UniformNode<"float", number>;
109
+ readonly drawDistance: UniformNode<"float", number>;
110
+ readonly pushers: readonly UniformNode<"vec4", Vector4>[];
111
+ push(rootWorld: Node<"vec3">): Node<"vec3">;
112
+ }
113
+
114
+ /** Every LOD of one blade in one geometry, x across (-0.5..0.5) and y along it (0 root, 1 tip). */
115
+ export function grassBlade(): {
116
+ geometry: BufferGeometry;
117
+ lods: { start: number; count: number }[];
118
+ reach: number;
119
+ } {
120
+ const pos: number[] = [];
121
+ const idx: number[] = [];
122
+ const lods: { start: number; count: number }[] = [];
123
+ for (const seg of GRASS.segments) {
124
+ const base = pos.length / 3;
125
+ const start = idx.length;
126
+ for (let r = 0; r < seg; r++) pos.push(-0.5, r / seg, 0, 0.5, r / seg, 0);
127
+ pos.push(0, 1, 0);
128
+ for (let r = 0; r < seg - 1; r++) {
129
+ const a = base + r * 2;
130
+ idx.push(a, a + 1, a + 2, a + 1, a + 3, a + 2);
131
+ }
132
+ const a = base + (seg - 1) * 2;
133
+ idx.push(a, a + 1, a + 2);
134
+ lods.push({ start, count: idx.length - start });
135
+ }
136
+ const geometry = new BufferGeometry();
137
+ geometry.setAttribute("position", new BufferAttribute(new Float32Array(pos), 3));
138
+ geometry.setIndex(idx);
139
+ return { geometry, lods, reach: GRASS.bladeHeight * (1 + GRASS.heightVariation) };
140
+ }
141
+
142
+ const hash2 = (p: Node<"vec2">): Node<"float"> => {
143
+ const q = fract(p.mul(vec2(123.34, 456.21)));
144
+ const r = q.add(dot(q, q.add(45.32)));
145
+ return fract(r.x.mul(r.y));
146
+ };
147
+
148
+ /** Smooth value noise, 0..1. */
149
+ const noise = Fn(([p]: [Node<"vec2">]) => {
150
+ const i = floor(p);
151
+ const f = fract(p);
152
+ const u = f.mul(f).mul(float(3).sub(f.mul(2)));
153
+ return mix(
154
+ mix(hash2(i), hash2(i.add(vec2(1, 0))), u.x),
155
+ mix(hash2(i.add(vec2(0, 1))), hash2(i.add(vec2(1, 1))), u.x),
156
+ u.y,
157
+ );
158
+ });
159
+
160
+ /**
161
+ * The blade material for `GrassField3D`: reads the field's instance attributes (`grassRoot`,
162
+ * `grassRand`, `grassClump`) and uniforms. Its thinning uses the field's own ranges, so the CPU
163
+ * trim only drops blades this material already hid.
164
+ */
165
+ export function grassMaterial(field: IGrassFieldUniforms): MeshStandardNodeMaterial {
166
+ const g = GRASS;
167
+ const root = attribute("grassRoot", "vec3");
168
+ const rand = attribute("grassRand", "vec4");
169
+ const clump = attribute("grassClump", "vec4");
170
+ const windAngle = (g.windDirection * Math.PI) / 180;
171
+ const wind = vec2(Math.cos(windAngle), Math.sin(windAngle));
172
+ // The blade's own vertex: after `positionNode` moves it, `positionLocal` reads the moved
173
+ // vertex, whose y is the ground height, not the share of the blade.
174
+ const t = positionGeometry.y;
175
+ const side = positionGeometry.x.mul(2);
176
+ const rootWorld = modelWorldMatrix.mul(vec4(root, 1)).xyz;
177
+ const dist = rootWorld.distance(cameraPosition);
178
+ const r0 = fract(sin(rand.z.mul(9871.13).add(0.71)).mul(43758.5453));
179
+ const r1 = fract(r0.mul(57.31).add(rand.x.mul(3.17)));
180
+
181
+ // Distance thinning: blades past this distance's priority cut-off shrink away; the far edge sinks.
182
+ const thinT = smoothstep(field.thinStart, field.thinEnd, dist);
183
+ const keepEdge = mix(float(1.1), field.farDensity, thinT);
184
+ const keep = float(1).sub(smoothstep(keepEdge.sub(0.1), keepEdge, rand.z));
185
+ const fadeSpan = field.drawDistance.sub(field.fadeStart);
186
+ const fadeT = smoothstep(
187
+ field.fadeStart,
188
+ field.drawDistance,
189
+ dist.add(r0.mul(fadeSpan).mul(0.5)),
190
+ );
191
+ const grow = rand.w.mul(keep).mul(float(1).sub(fadeT));
192
+
193
+ // Facing: random, pulled outward from the tuft centre.
194
+ const a = rand.x.mul(Math.PI * 2);
195
+ const facing = normalize(
196
+ mix(vec2(cos(a), sin(a)), vec2(cos(clump.x), sin(clump.x)), g.clumpStrength * 0.65).add(1e-4),
197
+ );
198
+ const height = float(g.bladeHeight)
199
+ .mul(mix(float(1 - g.heightVariation), float(1 + g.heightVariation), rand.y))
200
+ .mul(mix(float(1), clump.y.add(0.5), g.clumpStrength))
201
+ .mul(grow);
202
+
203
+ // Wind: a gust field scrolling downwind, plus per-blade flutter.
204
+ const wuv = rootWorld.xz.sub(wind.mul(time).mul(g.windSpeed)).div(g.gustScale);
205
+ const gust = smoothstep(
206
+ 0.25,
207
+ 0.8,
208
+ noise(wuv)
209
+ .mul(0.6)
210
+ .add(noise(wuv.mul(2.31).add(17.3)).mul(0.4)),
211
+ );
212
+ const fl = gust.mul(0.6).add(0.4).mul(g.flutter);
213
+ const flutA = sin(time.mul(r0.mul(2.2).add(2.6)).add(r1.mul(Math.PI * 2))).mul(fl);
214
+ const flutB = sin(time.mul(r1.mul(2).add(3.3)).add(r0.mul(Math.PI * 2))).mul(fl);
215
+ const pushed = field.push(rootWorld);
216
+ const press = pushed.z;
217
+ const tipRaw = facing
218
+ .mul(
219
+ max(
220
+ r1
221
+ .sub(0.5)
222
+ .mul(2 * g.leanVariation)
223
+ .add(g.lean),
224
+ 0,
225
+ ),
226
+ )
227
+ .add(wind.mul(gust.mul(0.88).add(0.12).mul(g.windStrength).add(flutA)))
228
+ .add(vec2(wind.y.negate(), wind.x).mul(flutB))
229
+ .add(pushed.xy.mul(g.pushStrength));
230
+ const tip = tipRaw.mul(min(1, float(0.96).div(max(tipRaw.length(), 1e-4))));
231
+ const tipY = sqrt(max(float(1).sub(dot(tip, tip)), 0));
232
+ const h = height.mul(float(1).sub(press.mul(0.3)));
233
+
234
+ // Quadratic Bezier: root, a control point straight up, the tip.
235
+ const p1 = vec3(0, g.curve, 0);
236
+ const p2 = vec3(tip.x, tipY, tip.y);
237
+ const it = float(1).sub(t);
238
+ const curve = p1.mul(it.mul(t).mul(2)).add(p2.mul(t.mul(t)));
239
+ const tangent = normalize(p1.mul(it.mul(2)).add(p2.sub(p1).mul(t.mul(2))));
240
+ // The flat of the blade turns toward the way it bends.
241
+ const f2 = normalize(facing.mul(0.6).add(tip).add(1e-4));
242
+ const across = vec3(f2.y.negate(), 0, f2.x);
243
+ const bladeNormal = normalize(cross(across, tangent));
244
+ const width = float(g.bladeWidth * 0.5)
245
+ .mul(mix(float(1), float(g.farWidth), thinT))
246
+ .mul(r1.mul(0.5).add(0.75))
247
+ .mul(float(1).sub(pow(t, g.taper)))
248
+ .mul(sqrt(grow));
249
+ // Edge-on blades turn a little toward the camera.
250
+ const toCam = normalize(cameraPosition.sub(rootWorld));
251
+ const edge = float(1).sub(abs(dot(bladeNormal, toCam)));
252
+ const thick = edge.mul(edge).mul(g.viewThicken);
253
+ const local = root
254
+ .add(curve.mul(h))
255
+ .add(across.add(bladeNormal.mul(thick)).mul(side.mul(width)))
256
+ .sub(vec3(0, it.mul(g.rootSink), 0));
257
+
258
+ // Per-blade values the fragment stage reads.
259
+ const ground = vec3(
260
+ clump.z,
261
+ sqrt(max(float(1).sub(clump.z.mul(clump.z)).sub(clump.w.mul(clump.w)), 0)),
262
+ clump.w,
263
+ );
264
+ const vNormal = varying(
265
+ normalize(mix(bladeNormal, ground, mix(float(g.terrainNormalBlend), float(1), thinT))),
266
+ );
267
+ const vT = varying(t);
268
+ const vFar = varying(thinT);
269
+ const vTuft = varying(clump.y.mul(0.65).add(r0.mul(0.35)));
270
+ const patchUv = rootWorld.xz.div(g.patchScale);
271
+ const vPatch = varying(
272
+ smoothstep(
273
+ 0.3,
274
+ 0.8,
275
+ noise(patchUv.add(91.7))
276
+ .mul(0.65)
277
+ .add(noise(patchUv.mul(2.7).add(5.3)).mul(0.35)),
278
+ ),
279
+ );
280
+ const vGust = varying(gust);
281
+
282
+ const material = new MeshStandardNodeMaterial({ roughness: 0.75, side: DoubleSide });
283
+ material.name = "GrassBlades";
284
+ material.positionNode = local;
285
+ // The blade's normal, turned to face the viewer: a thin blade is lit on the side you see.
286
+ const view = cameraPosition.sub(positionWorld);
287
+ material.normalNode = transformNormalToView(
288
+ vNormal.mul(dot(vNormal, view).sign().add(0.5).sign()),
289
+ );
290
+ // Far blades converge on one mid colour with little root shade, so the thinned field reads as a surface.
291
+ const tc = mix(vT.mul(vT.mul(0.65).add(0.35)), max(vT, 0.5), vFar.mul(0.8));
292
+ const albedo = mix(rgb(g.baseColor), rgb(g.tipColor), tc);
293
+ const dried = mix(albedo, rgb(g.dryColor), vPatch.mul(g.dryAmount).mul(tc.mul(0.65).add(0.35)));
294
+ const occlusion = mix(
295
+ float(1 - g.ambientOcclusion).add(vFar.mul(0.75 * g.ambientOcclusion)),
296
+ float(1),
297
+ vT,
298
+ );
299
+ material.colorNode = vec4(
300
+ dried
301
+ .mul(vTuft.sub(0.5).mul(g.colorVariation).add(1))
302
+ .mul(vGust.sub(0.4).mul(g.gustHighlight).mul(vT).add(1)),
303
+ 1,
304
+ );
305
+ material.aoNode = occlusion;
306
+ // Sun on the far side of the blade: light comes through, warmer and more saturated.
307
+ const sun = vec3(SUN_DIRECTION.x, SUN_DIRECTION.y, SUN_DIRECTION.z);
308
+ const back = max(dot(vNormal, sun).negate(), 0);
309
+ const through = pow(max(dot(normalize(view), sun.negate()), 0), 5);
310
+ const sunColor = vec3(SUN_COLOR.r, SUN_COLOR.g, SUN_COLOR.b);
311
+ material.emissiveNode = dried
312
+ .mul(vec3(1.05, 1.2, 0.5))
313
+ .mul(sunColor)
314
+ .mul(back.mul(0.45).add(through.mul(back.mul(0.65).add(0.35)).mul(1.1)))
315
+ .mul(vT.mul(0.7).add(0.3))
316
+ .mul(g.translucency);
317
+ return material;
318
+ }
319
+
320
+ /** A blade's standing height at `(x, z)` as a share of its rest height: the CPU mirror of the bend under a pusher. */
321
+ export function grassStandAt(press: number): number {
322
+ const lean = GRASS.lean + press * GRASS.pushStrength;
323
+ const reach = Math.min(lean, 0.96);
324
+ return (1 - 0.3 * press) * Math.sqrt(1 - reach * reach);
325
+ }
@@ -15,6 +15,7 @@ import {
15
15
  LinearFilter,
16
16
  LinearMipmapLinearFilter,
17
17
  type Material,
18
+ MathUtils,
18
19
  MeshBasicMaterial,
19
20
  MeshStandardMaterial,
20
21
  NoColorSpace,
@@ -56,8 +57,8 @@ export function detailTexture(): DataTexture {
56
57
  const tx = fx - x0;
57
58
  const ty = fy - y0;
58
59
  const at = (i: number, j: number): number => rng(((j % cells) * cells + (i % cells)) * 1.37);
59
- const sx = tx * tx * (3 - 2 * tx);
60
- const sy = ty * ty * (3 - 2 * ty);
60
+ const sx = MathUtils.smoothstep(tx, 0, 1);
61
+ const sy = MathUtils.smoothstep(ty, 0, 1);
61
62
  const top = at(x0, y0) + (at(x0 + 1, y0) - at(x0, y0)) * sx;
62
63
  const bottom = at(x0, y0 + 1) + (at(x0 + 1, y0 + 1) - at(x0, y0 + 1)) * sx;
63
64
  return top + (bottom - top) * sy;
@@ -24,6 +24,9 @@ export const palette = {
24
24
  export const C = {
25
25
  grassDark: 0x4e7a2a,
26
26
  grassTip: 0x7f9e44,
27
+ /** The streamed grass: the dark root shade and the colour dry patches drift toward. */
28
+ grassRoot: 0x3b5a1d,
29
+ grassDry: 0xa89a4c,
27
30
  dirt: 0x8b6a48,
28
31
  path: 0xb39a72,
29
32
  stoneDark: 0x5d5a52,
@@ -36,6 +36,9 @@ const STICK_RADIUS = 72;
36
36
  const BUTTON_RADIUS = 46;
37
37
  const EDGE = 36;
38
38
 
39
+ /** The resting stick centre: `update` runs every frame, so it uses one instance. */
40
+ const restPoint = new Vector2();
41
+
39
42
  /** Where each button sits: a quarter-circle fan around the bottom-right corner. */
40
43
  function buttonPoint(size: ITouchViewport, index: number): Vector2 {
41
44
  const cx = size.width - EDGE - BUTTON_RADIUS;
@@ -84,7 +87,7 @@ export class TouchControls {
84
87
  }
85
88
 
86
89
  update(pointers: ReadonlyMap<number, ITouchPointer>, size: ITouchViewport): ITouchInput {
87
- const rest = new Vector2(STICK_RADIUS + EDGE, size.height - STICK_RADIUS - EDGE);
90
+ const rest = restPoint.set(STICK_RADIUS + EDGE, size.height - STICK_RADIUS - EDGE);
88
91
  let thumb: ITouchPointer | undefined;
89
92
  for (const pointer of pointers.values()) {
90
93
  if (pointer.position.x < size.width * 0.45 && pointer.position.y > size.height * 0.4) {
@@ -1,11 +1,13 @@
1
1
  import {
2
2
  GPUParticles3D,
3
+ GrassField3D,
3
4
  Scene,
4
5
  type SceneFrame,
5
6
  afterPhysics,
6
7
  isMobile,
7
8
  isTouchscreenAvailable,
8
9
  } from "@threenative/core";
10
+ import { warmUnculled } from "@threenative/core/world";
9
11
  import { type IPhysicsContext, buildStaticColliders } from "@threenative/physics";
10
12
  import {
11
13
  Box3,
@@ -38,8 +40,13 @@ import { Warden } from "../entities/Warden.js";
38
40
  import { Interactions } from "../interact.js";
39
41
  import { type IHollow, buildHollow } from "../level/Hollow.js";
40
42
  import {
43
+ GRASS_BOUNDS,
41
44
  type IVale,
45
+ type IWoodlandFloor,
46
+ STREAM,
42
47
  buildVale,
48
+ buildWoodlandFloor,
49
+ grassCover,
43
50
  isSolid,
44
51
  makeRng,
45
52
  measureRelief,
@@ -47,10 +54,12 @@ import {
47
54
  } from "../level/Vale.js";
48
55
  import { setupCamera } from "../render/camera.js";
49
56
  import { BURSTS, EFFECTS } from "../render/effects.js";
57
+ import { grassBlade, grassMaterial, grassStandAt } from "../render/grass.js";
50
58
  import { setupLighting } from "../render/lighting.js";
51
59
  import { createLoadingScreen } from "../render/loading.js";
52
60
  import { setupPost } from "../render/postprocessing.js";
53
61
  import { createCompanion, createHeartVessel } from "../render/props.js";
62
+ import { resolveQualityTier } from "../render/quality.js";
54
63
  import { type ISky, createSky, setupSky } from "../render/sky.js";
55
64
  import { loadSurfaces, untexturedSurfaces, updateSurfaceSampling } from "../render/surface.js";
56
65
  import { TouchControls } from "../render/touch-controls.js";
@@ -126,6 +135,8 @@ export class Play extends Scene<GameState, IPhysicsContext> {
126
135
 
127
136
  #sky: ISky | undefined;
128
137
  #vale: IVale | undefined;
138
+ #floor: IWoodlandFloor | undefined;
139
+ #grass: GrassField3D | undefined;
129
140
  #hollow: IHollow | undefined;
130
141
  #hero: Hero | undefined;
131
142
  #dummies: Dummy[] = [];
@@ -147,6 +158,20 @@ export class Play extends Scene<GameState, IPhysicsContext> {
147
158
  this.#sky = createSky();
148
159
  setupSky(ctx.scene, this.#sky);
149
160
  const vale = buildVale(makeRng(1986));
161
+ // The forest floor: baked debris and ferns scattered under the old trees (PRD-889). The `low`
162
+ // tier (a software adapter, or a GPU the tier table rates low) leaves it out: on a CPU adapter
163
+ // it held the first frame window past three minutes. Pass `tier` here to force it either way.
164
+ const tier = resolveQualityTier({
165
+ gpuClass: ctx.renderer.gpuClass?.class,
166
+ mobile: isMobile(),
167
+ software: ctx.renderer.softwareAdapter !== undefined,
168
+ });
169
+ if (tier === "low") console.info("TN_WOODLAND_FLOOR off: quality tier low");
170
+ else {
171
+ const floor = await buildWoodlandFloor(ctx.assets, vale);
172
+ vale.group.add(floor.group);
173
+ this.#floor = floor;
174
+ }
150
175
  const hollow = buildHollow(makeRng(1998));
151
176
  this.#vale = vale;
152
177
  this.#hollow = hollow;
@@ -157,6 +182,54 @@ export class Play extends Scene<GameState, IPhysicsContext> {
157
182
  hero.mesh.position.set(vale.spawn.x, vale.spawn.y + FOOT_OFFSET, vale.spawn.z);
158
183
  hero.mesh.rotation.y = vale.spawnYaw;
159
184
  this.#hero = ctx.entities.add("player", hero);
185
+ // The vale's grass: streamed chunks round the camera, its look in `render/grass.ts`. It lives in
186
+ // the vale's group, so it hides with the vale when Wren is in the Hollow.
187
+ const grass = new GrassField3D({
188
+ blade: grassBlade(),
189
+ bounds: GRASS_BOUNDS,
190
+ // Bigger chunks are fewer draws: the engine's per-draw cost outweighed finer culling here.
191
+ buildBudgetMs: 2,
192
+ chunkSize: 16,
193
+ density: 18,
194
+ drawDistance: 40,
195
+ // Thinned under the old trees, where the floor's litter lies: knee-high grass over a flat leaf
196
+ // layer hides the very thing the layer is there to show.
197
+ getDensity: (x: number, z: number) => grassCover(x, z) * (1 - 0.78 * vale.floorZone(x, z)),
198
+ getHeight: valeHeight,
199
+ lodDistances: [7, 16],
200
+ material: grassMaterial,
201
+ minAltitude: STREAM.water + 0.05,
202
+ thinEnd: 30,
203
+ thinStart: 6,
204
+ });
205
+ vale.group.add(grass);
206
+ this.#grass = grass;
207
+ // What a scenario reads: how many chunks draw, and how high a blade stands beside Wren.
208
+ const standAt = (dx: number): number => {
209
+ const x = hero.mesh.position.x + dx;
210
+ const z = hero.mesh.position.z;
211
+ return grassStandAt(grass.pressAt(x, valeHeight(x, z), z));
212
+ };
213
+ ctx.entities.add("grass", {
214
+ debug: () => ({
215
+ blades: grass.stats.blades,
216
+ pending: grass.stats.pending,
217
+ standFar: standAt(3),
218
+ standNear: standAt(0.5),
219
+ visibleChunks: grass.stats.visibleChunks,
220
+ }),
221
+ });
222
+ ctx.entities.add("floor", {
223
+ debug: () => {
224
+ // No fields when the `low` tier left the floor out, so every total reads 0.
225
+ const fields = this.#floor?.fields ?? [];
226
+ return {
227
+ instances: fields.reduce((total, field) => total + field.stats.instances, 0),
228
+ tiles: fields.reduce((total, field) => total + field.stats.tiles, 0),
229
+ visibleTiles: fields.reduce((total, field) => total + field.stats.visibleTiles, 0),
230
+ };
231
+ },
232
+ });
160
233
  vale.dummies.forEach((at, i) => {
161
234
  this.#dummies.push(ctx.entities.add(`dummy.${i}`, new Dummy(`dummy.${i}`, at)));
162
235
  });
@@ -209,6 +282,26 @@ export class Play extends Scene<GameState, IPhysicsContext> {
209
282
  this.#sky === undefined
210
283
  )
211
284
  throw new Error("Play.enter ran before load() built the world.");
285
+ const floor = this.#floor;
286
+ if (floor !== undefined) {
287
+ floor.prewarm();
288
+ ctx.beforeRender(() => {
289
+ if (vale.group.visible) floor.update(hero.mesh.position);
290
+ });
291
+ }
292
+ const grass = this.#grass;
293
+ if (grass !== undefined) {
294
+ // Once per drawn frame: Wren's feet flatten the grass, then the field streams round the camera.
295
+ grass.prewarm();
296
+ ctx.beforeRender(() => {
297
+ if (!vale.group.visible) return;
298
+ const at = hero.mesh.position;
299
+ grass.pushers[0]?.set(at.x, at.y - FOOT_OFFSET, at.z, 1.2);
300
+ grass.update(ctx.camera);
301
+ });
302
+ // The first chunks draw unculled so their pipeline compiles behind the loading curtain.
303
+ ctx.startup.hold("grass", warmUnculled(ctx, grass));
304
+ }
212
305
  ctx.beforeRender(() => {
213
306
  updateSurfaceSampling(
214
307
  ctx.renderer.temporalUpscale?.() === true ? ctx.renderer.surface().resolutionScale : 1,
@@ -609,7 +702,7 @@ export class Play extends Scene<GameState, IPhysicsContext> {
609
702
  hero.mesh.position.z - f.x * 0.7 - f.z * 0.4 + Math.sin(orb.clock * 1.3) * 0.15,
610
703
  );
611
704
  if (companion.group.position.distanceTo(orbGoal) > 6) companion.group.position.copy(orbGoal);
612
- else companion.group.position.lerp(orbGoal, 1 - Math.exp(-dt * 4));
705
+ else companion.group.position.lerp(orbGoal, MathUtils.damp(0, 1, 4, dt));
613
706
  const orbGap = companion.group.position.distanceTo(head);
614
707
  orb.nearest = Math.min(orb.nearest, orbGap);
615
708
  orb.farthest = Math.max(orb.farthest, orbGap);
@@ -774,6 +867,8 @@ export class Play extends Scene<GameState, IPhysicsContext> {
774
867
  Object.assign(seen, { blocks: hero.shieldBlocks, clanks, hits: hero.slashHits });
775
868
  warden.update(dt, hero);
776
869
  for (const dummy of dummies) dummy.update(dt);
870
+ // Everything that moves has moved, so the lock's bounds and reticle are this frame's pose.
871
+ lock.place(camera, dt);
777
872
  // A target falls inside Wren's slash, so count the fallen after everything has moved.
778
873
  for (const fallen of targets) {
779
874
  if (fallen.alive || counted.has(fallen)) continue;
@@ -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",
@@ -1,4 +1,4 @@
1
- import { type IAssetLoader, WaveField } from "@threenative/core";
1
+ import { type IAssetLoader, WaveField, createRandom } from "@threenative/core";
2
2
  import {
3
3
  Box3,
4
4
  BoxGeometry,
@@ -228,13 +228,8 @@ function boulderGeometry(size: number, rng: () => number): BufferGeometry {
228
228
  }
229
229
 
230
230
  export function makeRng(seed: number): () => number {
231
- let state = seed >>> 0;
232
- return () => {
233
- state = (state * 1664525 + 1013904223) >>> 0;
234
- return state / 0x1_0000_0000;
235
- };
231
+ return createRandom(seed);
236
232
  }
237
-
238
233
  /**
239
234
  * The island planted: drawn from `site` on a run that has nothing stored, and read back from
240
235
  * `memo` on the next run of this build, so `buildPlanting` has the same placements either way.
@@ -1,4 +1,5 @@
1
1
  import { Heightfield } from "@threenative/core/world";
2
+ import { MathUtils } from "three";
2
3
 
3
4
  /** A rectangle [x min, x max, z min, z max] or a disc [x, z, radius] of level ground at y = 0. */
4
5
  export type LevelZone =
@@ -35,7 +36,7 @@ const HEADLAND = { x: 2, z: -60, rx: 30, rz: 26 } as const;
35
36
  const clamp01 = (t: number): number => Math.min(1, Math.max(0, t));
36
37
  const smooth = (from: number, to: number, value: number): number => {
37
38
  const t = clamp01((value - from) / (to - from));
38
- return t * t * (3 - 2 * t);
39
+ return MathUtils.smoothstep(t, 0, 1);
39
40
  };
40
41
  const lerp = (a: number, b: number, t: number): number => a + (b - a) * t;
41
42
 
@@ -151,10 +151,10 @@ export function createOrbitCamera(camera: PerspectiveCamera): IOrbitCamera {
151
151
  // Running at the camera does not spin it round: only travel within 120° of the view swings it.
152
152
  if (Math.abs(turn) < (Math.PI * 2) / 3) {
153
153
  const rate = CAMERA_RIG.swingRate * Math.min(1, speed / 9.6);
154
- yaw += turn * (1 - Math.exp(-dt * rate));
154
+ yaw = MathUtils.damp(yaw, yaw + turn, rate, dt);
155
155
  }
156
156
  }
157
- place(target, probe, 1 - Math.exp(-dt * CAMERA_RIG.followRate));
157
+ place(target, probe, MathUtils.damp(0, 1, CAMERA_RIG.followRate, dt));
158
158
  },
159
159
  debug() {
160
160
  return { closest, cuts, distance, elevation, peakElevation, pulledIn, tilt, yaw };
@@ -3,7 +3,7 @@
3
3
  // The island's ground: one terrain mesh whose vertex attributes say where grass, worn grass, the
4
4
  // sandy dirt path, beach sand and rock lie, by height, slope and distance to the path. The textures
5
5
  // and the blend are `groundMaterial` in surface.ts.
6
- import { BufferAttribute, BufferGeometry, Color, Mesh } from "three";
6
+ import { BufferAttribute, BufferGeometry, Color, MathUtils, Mesh } from "three";
7
7
  import { lit, seeded } from "./materials.js";
8
8
  import { C } from "./palette.js";
9
9
 
@@ -29,8 +29,8 @@ export function valueNoise(cells: number, seed: number): (u: number, v: number)
29
29
  const y = v * cells;
30
30
  const i = Math.floor(x);
31
31
  const j = Math.floor(y);
32
- const fx = (x - i) * (x - i) * (3 - 2 * (x - i));
33
- const fy = (y - j) * (y - j) * (3 - 2 * (y - j));
32
+ const fx = MathUtils.smoothstep(x - i, 0, 1);
33
+ const fy = MathUtils.smoothstep(y - j, 0, 1);
34
34
  const top = at(i, j) + (at(i + 1, j) - at(i, j)) * fx;
35
35
  const bottom = at(i, j + 1) + (at(i + 1, j + 1) - at(i, j + 1)) * fx;
36
36
  return top + (bottom - top) * fy;
@@ -39,7 +39,7 @@ export function valueNoise(cells: number, seed: number): (u: number, v: number)
39
39
 
40
40
  const smooth = (from: number, to: number, value: number): number => {
41
41
  const t = Math.min(1, Math.max(0, (value - from) / (to - from)));
42
- return t * t * (3 - 2 * t);
42
+ return MathUtils.smoothstep(t, 0, 1);
43
43
  };
44
44
 
45
45
  /**
@@ -366,7 +366,7 @@ export function createHero(): IHero {
366
366
  update(pose: IHeroPose): void {
367
367
  time += pose.dt;
368
368
  const run = Math.min(1, pose.speed / 9.6);
369
- const k = 1 - Math.exp(-pose.dt * 18);
369
+ const k = MathUtils.damp(0, 1, 18, pose.dt);
370
370
  let pitch = 0;
371
371
  let roll = 0;
372
372
  let squash = 1;
@@ -186,7 +186,6 @@ export function seeded(seed: number): () => number {
186
186
  return state / 0x1_0000_0000;
187
187
  };
188
188
  }
189
-
190
189
  /** The surfaces the island is made of, resolved once. */
191
190
  export function createMaterials() {
192
191
  return {