create-threenative 0.2.7 → 0.2.8

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 (154) hide show
  1. package/README.md +3 -1
  2. package/agent-docs/references/capability-reference.md +177 -7
  3. package/capabilities.json +247 -4
  4. package/dist/index.js +6 -1
  5. package/dist/threenative.js +3 -2
  6. package/package.json +4 -4
  7. package/templates/action-rpg/package.json +1 -1
  8. package/templates/minimal/package.json +1 -1
  9. package/templates/platformer/package.json +1 -1
  10. package/templates/puzzle/package.json +1 -1
  11. package/templates/racing/package.json +1 -1
  12. package/templates/rain/.codex/config.toml +19 -0
  13. package/templates/rain/.cursor/mcp.json +32 -0
  14. package/templates/rain/.gemini/settings.json +32 -0
  15. package/templates/rain/.mcp.json +32 -0
  16. package/templates/rain/.vscode/mcp.json +36 -0
  17. package/templates/rain/.zed/settings.json +36 -0
  18. package/templates/rain/AGENTS.md +96 -0
  19. package/templates/rain/CLAUDE.md +98 -0
  20. package/templates/rain/assets/rain-loop.wav +0 -0
  21. package/templates/rain/assets/thunder.wav +0 -0
  22. package/templates/rain/assets/wind-loop.wav +0 -0
  23. package/templates/rain/index.html +18 -0
  24. package/templates/rain/kit.json +7 -0
  25. package/templates/rain/native-playtests/boot.playtest.json +13 -0
  26. package/templates/rain/native-playtests/lightning.playtest.json +173 -0
  27. package/templates/rain/opencode.json +41 -0
  28. package/templates/rain/package.json +56 -0
  29. package/templates/rain/playtests/auto-lightning-clear.playtest.json +66 -0
  30. package/templates/rain/playtests/auto-lightning.playtest.json +26 -0
  31. package/templates/rain/playtests/automation.playtest.json +133 -0
  32. package/templates/rain/playtests/cinematic.playtest.json +59 -0
  33. package/templates/rain/playtests/flash.playtest.json +27 -0
  34. package/templates/rain/playtests/fly.playtest.json +54 -0
  35. package/templates/rain/playtests/lightning.playtest.json +220 -0
  36. package/templates/rain/playtests/loading.playtest.json +57 -0
  37. package/templates/rain/playtests/paused.playtest.json +59 -0
  38. package/templates/rain/playtests/performance.playtest.json +22 -0
  39. package/templates/rain/playtests/reduced-motion.playtest.json +87 -0
  40. package/templates/rain/playtests/simulation.playtest.json +20 -0
  41. package/templates/rain/playtests/storm.playtest.json +150 -0
  42. package/templates/rain/playtests/survives.playtest.json +58 -0
  43. package/templates/rain/playtests/tiers.playtest.json +179 -0
  44. package/templates/rain/playtests/weather.playtest.json +77 -0
  45. package/templates/rain/public/favicon.svg +5 -0
  46. package/templates/rain/src/audio/storm.ts +314 -0
  47. package/templates/rain/src/game.ts +114 -0
  48. package/templates/rain/src/main.ts +15 -0
  49. package/templates/rain/src/render/bloom-shader.ts +65 -0
  50. package/templates/rain/src/render/camera.ts +160 -0
  51. package/templates/rain/src/render/clouds-shader.ts +242 -0
  52. package/templates/rain/src/render/clouds.ts +142 -0
  53. package/templates/rain/src/render/lighting.ts +39 -0
  54. package/templates/rain/src/render/lightning.ts +360 -0
  55. package/templates/rain/src/render/loading.ts +327 -0
  56. package/templates/rain/src/render/materials.ts +19 -0
  57. package/templates/rain/src/render/noise-volume.ts +159 -0
  58. package/templates/rain/src/render/palette.ts +18 -0
  59. package/templates/rain/src/render/post-shader.ts +178 -0
  60. package/templates/rain/src/render/postprocessing.ts +226 -0
  61. package/templates/rain/src/render/quality.ts +135 -0
  62. package/templates/rain/src/render/rain.ts +299 -0
  63. package/templates/rain/src/render/sky.ts +28 -0
  64. package/templates/rain/src/render/world-shader.ts +680 -0
  65. package/templates/rain/src/render/world.ts +146 -0
  66. package/templates/rain/src/render/worldEnvironment.ts +809 -0
  67. package/templates/rain/src/scenes/Boot.ts +334 -0
  68. package/templates/rain/src/state.ts +257 -0
  69. package/templates/rain/src/style.css +1160 -0
  70. package/templates/rain/src/ui/App.tsx +29 -0
  71. package/templates/rain/src/ui/GameUi.tsx +187 -0
  72. package/templates/rain/src/ui/Hud.tsx +327 -0
  73. package/templates/rain/src/ui/LoadingOverlay.tsx +46 -0
  74. package/templates/rain/src/ui/Menu.tsx +370 -0
  75. package/templates/rain/src/ui/automation.ts +60 -0
  76. package/templates/rain/src/ui/main.tsx +7 -0
  77. package/templates/rain/src/ui/tempest.ts +149 -0
  78. package/templates/rain/tailwind.config.ts +2 -0
  79. package/templates/rain/threenative.config.ts +66 -0
  80. package/templates/rain/tools/generate-shaders.mjs +656 -0
  81. package/templates/rain/tools/make-storm-audio.mjs +387 -0
  82. package/templates/rain/tools/storm-dsp.mjs +177 -0
  83. package/templates/rain/tools/tempest-bloom.frag +10 -0
  84. package/templates/rain/tools/tempest-clouds.frag +86 -0
  85. package/templates/rain/tools/tempest-post.frag +47 -0
  86. package/templates/rain/tools/tempest-world.frag +210 -0
  87. package/templates/rain/tools/verify-noise-volume.mjs +61 -0
  88. package/templates/rain/tsconfig.json +17 -0
  89. package/templates/rain/vite.config.ts +37 -0
  90. package/templates/rts/package.json +1 -1
  91. package/templates/runner/package.json +1 -1
  92. package/templates/sailing/package.json +1 -1
  93. package/templates/shooter/package.json +1 -1
  94. package/templates/snow/.codex/config.toml +19 -0
  95. package/templates/snow/.cursor/mcp.json +32 -0
  96. package/templates/snow/.gemini/settings.json +32 -0
  97. package/templates/snow/.mcp.json +32 -0
  98. package/templates/snow/.vscode/mcp.json +36 -0
  99. package/templates/snow/.zed/settings.json +36 -0
  100. package/templates/snow/AGENTS.md +88 -0
  101. package/templates/snow/CLAUDE.md +90 -0
  102. package/templates/snow/README.md +26 -0
  103. package/templates/snow/assets/crunch.wav +0 -0
  104. package/templates/snow/assets/wind.wav +0 -0
  105. package/templates/snow/index.html +12 -0
  106. package/templates/snow/kit.json +7 -0
  107. package/templates/snow/native-playtests/snow-physics.playtest.json +150 -0
  108. package/templates/snow/native-playtests/survives.playtest.json +47 -0
  109. package/templates/snow/opencode.json +41 -0
  110. package/templates/snow/package.json +58 -0
  111. package/templates/snow/playtests/footsteps.playtest.json +95 -0
  112. package/templates/snow/playtests/performance.playtest.json +36 -0
  113. package/templates/snow/playtests/snow-physics.playtest.json +154 -0
  114. package/templates/snow/playtests/survives.playtest.json +56 -0
  115. package/templates/snow/playtests/touch-controls.playtest.json +71 -0
  116. package/templates/snow/playtests/weather.playtest.json +119 -0
  117. package/templates/snow/public/favicon.svg +5 -0
  118. package/templates/snow/src/audio.ts +58 -0
  119. package/templates/snow/src/commands.ts +8 -0
  120. package/templates/snow/src/entities/Explorer.ts +279 -0
  121. package/templates/snow/src/game.ts +69 -0
  122. package/templates/snow/src/main.ts +15 -0
  123. package/templates/snow/src/render/bootPrint.ts +50 -0
  124. package/templates/snow/src/render/camera.ts +84 -0
  125. package/templates/snow/src/render/explorer.ts +321 -0
  126. package/templates/snow/src/render/lighting.ts +50 -0
  127. package/templates/snow/src/render/loading.ts +325 -0
  128. package/templates/snow/src/render/materials.ts +36 -0
  129. package/templates/snow/src/render/palette.ts +17 -0
  130. package/templates/snow/src/render/postprocessing.ts +44 -0
  131. package/templates/snow/src/render/props.ts +42 -0
  132. package/templates/snow/src/render/quality.ts +135 -0
  133. package/templates/snow/src/render/scenery.ts +244 -0
  134. package/templates/snow/src/render/sky.ts +57 -0
  135. package/templates/snow/src/render/snowSurface.ts +259 -0
  136. package/templates/snow/src/render/touch-controls.ts +143 -0
  137. package/templates/snow/src/render/weather.ts +279 -0
  138. package/templates/snow/src/render/worldEnvironment.ts +809 -0
  139. package/templates/snow/src/scenes/Boot.ts +12 -0
  140. package/templates/snow/src/scenes/Snow.ts +635 -0
  141. package/templates/snow/src/state.ts +46 -0
  142. package/templates/snow/src/style.css +143 -0
  143. package/templates/snow/src/terrain.ts +64 -0
  144. package/templates/snow/src/ui/App.tsx +15 -0
  145. package/templates/snow/src/ui/Controls.tsx +322 -0
  146. package/templates/snow/src/ui/GameUi.tsx +354 -0
  147. package/templates/snow/src/ui/icons.tsx +54 -0
  148. package/templates/snow/src/ui/main.tsx +7 -0
  149. package/templates/snow/tailwind.config.ts +2 -0
  150. package/templates/snow/threenative.config.ts +51 -0
  151. package/templates/snow/tsconfig.json +17 -0
  152. package/templates/snow/vite.config.ts +37 -0
  153. package/templates/starter/package.json +1 -1
  154. package/templates/tower-defense/package.json +1 -1
@@ -0,0 +1,12 @@
1
+ import { Scene } from "@threenative/core";
2
+ import type { IPhysicsContext } from "@threenative/physics";
3
+ import type { GameState } from "../state.js";
4
+ import { Snow } from "./Snow.js";
5
+
6
+ export class Boot extends Scene<GameState, IPhysicsContext> {
7
+ static override readonly initialState = Snow.initialState;
8
+
9
+ override enter(ctx: Parameters<Snow["enter"]>[0]): void {
10
+ void ctx.goto("snow");
11
+ }
12
+ }
@@ -0,0 +1,635 @@
1
+ import {
2
+ GPUParticles3D,
3
+ type ICtx,
4
+ Scene,
5
+ type SceneFrame,
6
+ isMobile,
7
+ isTouchscreenAvailable,
8
+ } from "@threenative/core";
9
+ import type { SnowField } from "@threenative/core/world";
10
+ import {
11
+ CollisionShape3D,
12
+ type IPhysicsContext,
13
+ RigidBody3D,
14
+ attachSnowPhysics,
15
+ } from "@threenative/physics";
16
+ import type { Object3D, PerspectiveCamera } from "three";
17
+ import { SnowAudio } from "../audio.js";
18
+ import { type Command, commands } from "../commands.js";
19
+ import { Explorer, type IFootstep, STANCE } from "../entities/Explorer.js";
20
+ import { BOOT_AREA, bootPrint } from "../render/bootPrint.js";
21
+ import { OrbitFollow, setupCamera } from "../render/camera.js";
22
+ import { setupLighting } from "../render/lighting.js";
23
+ import { createLoadingScreen } from "../render/loading.js";
24
+ import { createMaterials } from "../render/materials.js";
25
+ import { setupPost } from "../render/postprocessing.js";
26
+ import { createBall, createCrate, createLog } from "../render/props.js";
27
+ import { createScenery } from "../render/scenery.js";
28
+ import { setupSky } from "../render/sky.js";
29
+ import { createSnowSurface } from "../render/snowSurface.js";
30
+ import { TouchControls } from "../render/touch-controls.js";
31
+ import { createWeather } from "../render/weather.js";
32
+ import { type CameraView, type GameState, PROBE_COLUMNS, PROBE_ROWS } from "../state.js";
33
+ import {
34
+ EXPLORER_LAYER,
35
+ FIELD_SIZE,
36
+ SNOW_LAYER,
37
+ WALK_LAYER,
38
+ createSnowfield,
39
+ walkSurface,
40
+ } from "../terrain.js";
41
+
42
+ export type GameCtx = ICtx<GameState, IPhysicsContext>;
43
+
44
+ const BALL_RADIUS = 0.25;
45
+ const BALL_MASS = 10;
46
+ /** Newton-seconds a push gives the ball: 2.4 m/s on a 10 kg ball, enough to carve on uphill. */
47
+ const KICK = 24;
48
+ const CRATE = { x: 0.5, y: 0.3, z: 0.4 } as const;
49
+ const LOG = { halfHeight: 0.35, radius: 0.14 } as const;
50
+ /** Where the explorer walks while auto-explore is on. */
51
+ const ROUTE: ReadonlyArray<readonly [number, number]> = [
52
+ [0.5, -5],
53
+ [-4, -8],
54
+ [-7, -3],
55
+ [-5, 4],
56
+ [0, 7],
57
+ [5, 3],
58
+ [3, -2],
59
+ ];
60
+ const VIEWS: readonly CameraView[] = ["follow", "surface", "overhead"];
61
+ /** Seconds between snowfall refills; recovery is rate-based, so this only sets the cadence. */
62
+ const REFILL_INTERVAL = 0.5;
63
+
64
+ /** One dynamic body that sits in the snow, with what a playtest needs to read back about it. */
65
+ function placeBody(
66
+ ctx: GameCtx,
67
+ snow: SnowField,
68
+ body: RigidBody3D,
69
+ at: { readonly x: number; readonly z: number },
70
+ lift: number,
71
+ ): void {
72
+ const half = FIELD_SIZE / 2 - 1;
73
+ const x = Math.max(-half, Math.min(half, at.x));
74
+ const z = Math.max(-half, Math.min(half, at.z));
75
+ const y = snow.heightAt(x, z) + lift;
76
+ ctx.physics.simulation.setBodyTransform(body.body.id, { x, y, z });
77
+ body.linearVelocity = { x: 0, y: 0, z: 0 };
78
+ }
79
+
80
+ export class Snow extends Scene<GameState, IPhysicsContext> {
81
+ static override readonly initialState: GameState = {
82
+ autoExplore: true,
83
+ ballGap: 0,
84
+ ballLoad: 0,
85
+ ballSink: 0,
86
+ blizzard: false,
87
+ compaction: false,
88
+ contacts: 0,
89
+ depth: 0.28,
90
+ fallSpeed: 0.55,
91
+ hardness: 0.22,
92
+ lastSink: 0,
93
+ muted: true,
94
+ paused: false,
95
+ probe: [],
96
+ recovery: 120,
97
+ snowfall: 0.58,
98
+ speed: 0,
99
+ storm: 0,
100
+ toast: "",
101
+ toastId: 0,
102
+ uiReady: false,
103
+ view: "follow",
104
+ wind: 0.4,
105
+ windNow: 0.4,
106
+ };
107
+
108
+ override enter(ctx: GameCtx): SceneFrame<GameState, IPhysicsContext> {
109
+ const initial = ctx.state.getState();
110
+ const mobile = isMobile();
111
+ const stormSky = setupSky(ctx.scene);
112
+ const lights = setupLighting(
113
+ ctx.scene,
114
+ ctx.renderer.raw as Parameters<typeof setupLighting>[1],
115
+ );
116
+ setupPost(ctx.renderer, ctx.scene, ctx.camera, {
117
+ mobile,
118
+ software: ctx.renderer.softwareAdapter !== undefined,
119
+ });
120
+ const loading = createLoadingScreen(ctx);
121
+ const camera = ctx.camera as PerspectiveCamera;
122
+ setupCamera(camera);
123
+ ctx.add(camera);
124
+ const orbit = new OrbitFollow();
125
+ const touchControls =
126
+ mobile && isTouchscreenAvailable()
127
+ ? ctx.entities.add("touch-controls", new TouchControls(camera))
128
+ : undefined;
129
+
130
+ const materials = createMaterials();
131
+ const snow = createSnowfield(initial.depth, initial.hardness);
132
+ const startDepth = snow.depth;
133
+ const surface = createSnowSurface(snow);
134
+ ctx.add(surface.mesh);
135
+ ctx.add(surface.outskirts);
136
+ const scenery = createScenery(materials, snow.depth);
137
+ ctx.add(scenery.root);
138
+
139
+ // Trees and rocks stop the explorer and the ball; the field's edge is a fence nobody sees.
140
+ for (const obstacle of scenery.obstacles) {
141
+ if (Math.abs(obstacle.x) > FIELD_SIZE / 2 + 2 || Math.abs(obstacle.z) > FIELD_SIZE / 2 + 2)
142
+ continue;
143
+ new RigidBody3D({
144
+ physics: ctx.physics,
145
+ position: { x: obstacle.x, y: obstacle.height / 2, z: obstacle.z },
146
+ shape: CollisionShape3D.capsule(
147
+ Math.max(0, obstacle.height / 2 - obstacle.radius),
148
+ obstacle.radius,
149
+ ),
150
+ type: "fixed",
151
+ });
152
+ }
153
+ const half = FIELD_SIZE / 2;
154
+ for (const [x, z, width, depth] of [
155
+ [0, -half - 0.5, FIELD_SIZE + 2, 1],
156
+ [0, half + 0.5, FIELD_SIZE + 2, 1],
157
+ [-half - 0.5, 0, 1, FIELD_SIZE + 2],
158
+ [half + 0.5, 0, 1, FIELD_SIZE + 2],
159
+ ] as const)
160
+ new RigidBody3D({
161
+ physics: ctx.physics,
162
+ position: { x, y: 1, z },
163
+ shape: CollisionShape3D.box(width, 6, depth),
164
+ type: "fixed",
165
+ });
166
+
167
+ // The snow binding owns the surface collider and presses solved contacts into the field.
168
+ const snowPhysics = attachSnowPhysics({
169
+ collisionLayer: SNOW_LAYER,
170
+ physics: ctx.physics,
171
+ snow,
172
+ });
173
+ // The explorer walks on a coarse copy of the ground plus fresh snow; only it collides with it.
174
+ const walk = (depth: number) => {
175
+ const field = walkSurface(depth);
176
+ return new RigidBody3D({
177
+ collisionLayer: WALK_LAYER,
178
+ collisionMask: EXPLORER_LAYER,
179
+ physics: ctx.physics,
180
+ position: { x: 0, y: 0, z: 0 },
181
+ shape: CollisionShape3D.heightfield(field.rows, field.columns, field.toColliderHeights(), {
182
+ x: FIELD_SIZE,
183
+ y: 1,
184
+ z: FIELD_SIZE,
185
+ }),
186
+ type: "fixed",
187
+ });
188
+ };
189
+ let walkBody = walk(snow.depth);
190
+
191
+ const ballObject = createBall(materials, BALL_RADIUS);
192
+ ballObject.position.set(2.2, snow.heightAt(2.2, -2) + BALL_RADIUS + 0.05, -2);
193
+ const ball = new RigidBody3D({
194
+ mass: BALL_MASS,
195
+ object: ballObject,
196
+ physics: ctx.physics,
197
+ shape: CollisionShape3D.sphere(BALL_RADIUS),
198
+ });
199
+ ctx.add(ballObject);
200
+ const crateObject = createCrate(materials, CRATE);
201
+ crateObject.position.set(-2.6, snow.heightAt(-2.6, -2.4) + CRATE.y / 2 + 0.05, -2.4);
202
+ crateObject.rotation.y = 0.5;
203
+ const crate = new RigidBody3D({
204
+ mass: 25,
205
+ object: crateObject,
206
+ physics: ctx.physics,
207
+ shape: CollisionShape3D.box(CRATE.x, CRATE.y, CRATE.z),
208
+ });
209
+ ctx.add(crateObject);
210
+ const logObject = createLog(materials, LOG.halfHeight, LOG.radius);
211
+ logObject.position.set(-1.6, snow.heightAt(-1.6, 2.8) + LOG.radius + 0.05, 2.8);
212
+ logObject.rotation.set(Math.PI / 2, 0, 0.6);
213
+ const log = new RigidBody3D({
214
+ mass: 20,
215
+ object: logObject,
216
+ physics: ctx.physics,
217
+ shape: CollisionShape3D.capsule(LOG.halfHeight, LOG.radius),
218
+ });
219
+ ctx.add(logObject);
220
+ for (const body of [ball, crate, log]) snowPhysics.add(body);
221
+
222
+ const weather = createWeather({
223
+ flakes: mobile ? 6_000 : 16_000,
224
+ particles: (options) => new GPUParticles3D(options),
225
+ });
226
+ ctx.add(weather.snowfall);
227
+ for (const burst of weather.bursts) ctx.add(burst);
228
+ const audio = new SnowAudio(camera, (name) => ctx.assets.audio(name));
229
+ ctx.entities.add("audio", audio.bus);
230
+
231
+ const recentSteps: IFootstep[] = [];
232
+ let lastStep: IFootstep = {
233
+ angle: Math.PI,
234
+ penetration: 0,
235
+ side: 1,
236
+ speed: 0,
237
+ x: 0,
238
+ y: 0,
239
+ z: 2,
240
+ };
241
+ const explorer = new Explorer(ctx.physics, snow, materials, { x: 0, z: 0 }, (step) => {
242
+ if (step.penetration <= 0) return;
243
+ lastStep = step;
244
+ recentSteps.push(step);
245
+ if (recentSteps.length > 8) recentSteps.shift();
246
+ weather.burst(step, step.penetration);
247
+ audio.footstep(step);
248
+ });
249
+ ctx.add(explorer.model.root);
250
+ // A short arrival trail, so the snow's memory is the first thing on screen.
251
+ for (let index = 0; index < 14; index += 1) {
252
+ const z = 6.4 - index * 0.46;
253
+ const x = 0.35 * Math.sin(z * 0.7) + (index % 2 ? -STANCE : STANCE);
254
+ const angle = Math.PI + Math.cos(z * 0.7) * 0.2;
255
+ const penetration = snow.stamp({
256
+ area: BOOT_AREA,
257
+ footprint: bootPrint,
258
+ load: 80 * 9.81,
259
+ rotation: angle,
260
+ x,
261
+ z,
262
+ });
263
+ lastStep = { angle, penetration, side: index % 2 ? -1 : 1, speed: 0, x, y: 0, z };
264
+ }
265
+
266
+ // ---- what a playtest reads back ----
267
+ const telemetry = {
268
+ airborneLoads: 0,
269
+ dropped: false,
270
+ kickedAt: undefined as { x: number; z: number } | undefined,
271
+ path: [] as Array<{ x: number; z: number }>,
272
+ turned: 0,
273
+ /** Ground the ball's centre covered since the kick, step by step. */
274
+ rolled: 0,
275
+ /** Farthest the ball got from where it was kicked. */
276
+ reach: 0,
277
+ lastRotation: { w: 1, x: 0, y: 0, z: 0 },
278
+ lastPosition: { x: 0, y: 0, z: 0 },
279
+ lastClearance: 0,
280
+ };
281
+ // Read the solver's own pose: the drawn ball is synced from it later in the frame, and one
282
+ // step stale is ten centimetres at the speed a dropped ball lands.
283
+ const solvedBall = () =>
284
+ ctx.physics.simulation.readBodyTransform?.(ball.body.id) ?? {
285
+ position: ballObject.position,
286
+ rotation: ballObject.quaternion,
287
+ };
288
+ const ballState = () => {
289
+ const p = solvedBall().position;
290
+ const inside = Math.abs(p.x) < half && Math.abs(p.z) < half;
291
+ const ground = inside ? snow.heightAt(p.x, p.z) : 0;
292
+ // Clearance is the closest the sphere's underside comes to the snow anywhere beneath it,
293
+ // not just under its centre: a ball rolling over the lip of its crater is touching the rim
294
+ // while its centre stands well above the crater floor.
295
+ let clearance = Number.POSITIVE_INFINITY;
296
+ for (const ring of [0, 0.5, 0.85]) {
297
+ for (let step = 0; step < (ring === 0 ? 1 : 8); step += 1) {
298
+ const angle = (step / 8) * Math.PI * 2;
299
+ const x = clampToField(p.x + Math.cos(angle) * ring * BALL_RADIUS);
300
+ const z = clampToField(p.z + Math.sin(angle) * ring * BALL_RADIUS);
301
+ const underside = p.y - Math.sqrt(1 - ring * ring) * BALL_RADIUS;
302
+ clearance = Math.min(clearance, underside - snow.heightAt(x, z));
303
+ }
304
+ }
305
+ return {
306
+ clearance,
307
+ gap: p.y - BALL_RADIUS - ground,
308
+ sink: inside ? snow.sample(p.x, p.z).indent : 0,
309
+ };
310
+ };
311
+ ctx.entities.add("ball", {
312
+ object: ballObject,
313
+ debug: () => {
314
+ const { clearance, gap, sink } = ballState();
315
+ const kick = telemetry.kickedAt;
316
+ const p = ballObject.position;
317
+ const travelled = kick === undefined ? 0 : Math.hypot(p.x - kick.x, p.z - kick.z);
318
+ // Every recorded point of the path since the kick must sit in pressed snow.
319
+ let trackGaps = 0;
320
+ for (const point of telemetry.path)
321
+ if (snow.sample(point.x, point.z).indent < 0.004) trackGaps += 1;
322
+ return {
323
+ airborne: clearance > 0.05,
324
+ clearance,
325
+ airborneLoads: telemetry.airborneLoads,
326
+ dropped: telemetry.dropped,
327
+ gap,
328
+ kicked: kick !== undefined,
329
+ load: snowPhysics.loadOf(ball),
330
+ position: [p.x, p.y, p.z],
331
+ // Turn times radius over the distance actually covered: 1 is rolling without slipping.
332
+ reach: telemetry.reach,
333
+ rollRatio:
334
+ telemetry.rolled > 0.05 ? (telemetry.turned * BALL_RADIUS) / telemetry.rolled : 0,
335
+ settled: Math.abs(gap) <= 0.02 && sink > 0.02,
336
+ sink,
337
+ trackGaps,
338
+ trackSamples: telemetry.path.length,
339
+ travelled,
340
+ };
341
+ },
342
+ });
343
+ const pressedUnder = (object: Object3D) => {
344
+ const p = object.position;
345
+ return Math.abs(p.x) < half && Math.abs(p.z) < half ? snow.sample(p.x, p.z).indent : 0;
346
+ };
347
+ ctx.entities.add("crate", {
348
+ object: crateObject,
349
+ debug: () => ({ load: snowPhysics.loadOf(crate), sink: pressedUnder(crateObject) }),
350
+ });
351
+ ctx.entities.add("log", {
352
+ object: logObject,
353
+ debug: () => ({ load: snowPhysics.loadOf(log), sink: pressedUnder(logObject) }),
354
+ });
355
+ ctx.entities.add("player", explorer);
356
+ // The first print of the arrival trail: nothing walks back over it unless steered there.
357
+ const trailStart = { x: 0.35 * Math.sin(6.4 * 0.7) + STANCE, z: 6.4 };
358
+ ctx.entities.add("snow", {
359
+ debug: () => ({
360
+ trailPressed: snow.sample(trailStart.x, trailStart.z).indent > 0.01,
361
+ ...snowPhysics.observe(),
362
+ activeCells: snow.activeCells,
363
+ depth: snow.depth,
364
+ memoryBytes: snow.memoryBytes,
365
+ pendingRows: surface.pendingRows,
366
+ renderError: surface.renderError(),
367
+ steps: snow.steps,
368
+ }),
369
+ });
370
+ ctx.entities.add("weather", { debug: () => ({ storm: weather.storm, wind: weather.wind }) });
371
+
372
+ // The surface view frames the newest print far enough from the explorer to be seen past them.
373
+ const surfaceTarget = () => {
374
+ const print =
375
+ [...recentSteps]
376
+ .reverse()
377
+ .find(
378
+ (step) => Math.hypot(step.x - explorer.position.x, step.z - explorer.position.z) > 1.2,
379
+ ) ?? lastStep;
380
+ return {
381
+ x: print.x,
382
+ y: snow.heightAt(clampToField(print.x), clampToField(print.z)) + 0.12,
383
+ z: print.z,
384
+ };
385
+ };
386
+ // ---- verbs: one function per action, shared by keys and the HUD ----
387
+ let toastId = 0;
388
+ let toast = "";
389
+ const say = (message: string) => {
390
+ toast = message;
391
+ toastId += 1;
392
+ };
393
+ let view = 0;
394
+ // The scene owns this; state only mirrors it, so a key and the panel never race the bridge.
395
+ let autoExplore = initial.autoExplore;
396
+ let blizzard = initial.blizzard;
397
+ const act = (command: Command): void => {
398
+ const state = ctx.state.getState();
399
+ if (command === "reset") {
400
+ snow.reset();
401
+ placeBody(ctx, snow, ball, { x: 2.2, z: -2 }, BALL_RADIUS + 0.02);
402
+ placeBody(ctx, snow, crate, { x: -2.6, z: -2.4 }, CRATE.y / 2 + 0.02);
403
+ placeBody(ctx, snow, log, { x: -1.6, z: 2.8 }, LOG.radius + 0.02);
404
+ telemetry.kickedAt = undefined;
405
+ telemetry.path.length = 0;
406
+ lastStep = { ...lastStep, penetration: 0 };
407
+ say("A fresh blanket of snow. All footprints cleared.");
408
+ } else if (command === "drop") {
409
+ const ahead = {
410
+ x: explorer.position.x + Math.sin(explorer.heading) * 1.8,
411
+ z: explorer.position.z + Math.cos(explorer.heading) * 1.8,
412
+ };
413
+ placeBody(ctx, snow, ball, ahead, 1.6);
414
+ telemetry.dropped = true;
415
+ telemetry.airborneLoads = 0;
416
+ telemetry.kickedAt = undefined;
417
+ telemetry.path.length = 0;
418
+ say("Ball dropped. Watch it settle into the snow.");
419
+ } else if (command === "kick") {
420
+ const p = ballObject.position;
421
+ let dx = p.x - explorer.position.x;
422
+ let dz = p.z - explorer.position.z;
423
+ const length = Math.hypot(dx, dz) || 1;
424
+ dx /= length;
425
+ dz /= length;
426
+ // A kick lifts as well as pushes: a dropped ball can sit ten centimetres down in its own
427
+ // crater, and a purely sideways shove only rolls it up the wall and back in.
428
+ ball.applyImpulse({ x: dx * KICK, y: KICK * 0.4, z: dz * KICK });
429
+ telemetry.kickedAt = { x: p.x, z: p.z };
430
+ telemetry.path.length = 0;
431
+ telemetry.turned = 0;
432
+ telemetry.rolled = 0;
433
+ telemetry.reach = 0;
434
+ say("Ball pushed. It rolls through the powder and carves its own track.");
435
+ } else if (command === "view") {
436
+ view = (view + 1) % VIEWS.length;
437
+ ctx.state.set({ view: VIEWS[view] });
438
+ if (VIEWS[view] === "surface") {
439
+ // Look back at the print from beyond it, so the explorer is never between.
440
+ const print = surfaceTarget();
441
+ orbit.yaw = Math.atan2(print.x - explorer.position.x, print.z - explorer.position.z);
442
+ }
443
+ } else if (command === "auto") {
444
+ autoExplore = !autoExplore;
445
+ say(autoExplore ? "Auto-explore on." : "You are in control. Hold Shift to run.");
446
+ } else if (command === "blizzard") {
447
+ blizzard = !blizzard;
448
+ say(
449
+ blizzard
450
+ ? "Blizzard building — wind and visibility are changing."
451
+ : "Returning to soft snowfall.",
452
+ );
453
+ } else if (command === "mute") {
454
+ audio.setMuted(!audio.muted);
455
+ ctx.state.set({ muted: audio.muted });
456
+ }
457
+ };
458
+
459
+ let refill = 0;
460
+ ctx.afterPhysics((dt) => {
461
+ // Solve → (this) consume contacts once, deform, refill → collider installed before the next
462
+ // step. The renderer collects what changed and draws it before the frame.
463
+ surface.collect();
464
+ refill += dt;
465
+ if (refill >= REFILL_INTERVAL) {
466
+ const state = ctx.state.getState();
467
+ const deposition = ((2 + 18 * weather.storm) * state.snowfall * state.recovery) / 3_600_000;
468
+ snow.recover(refill, deposition, weather.wind * weather.storm);
469
+ refill = 0;
470
+ surface.collect();
471
+ }
472
+ snowPhysics.step(dt);
473
+ // Ball telemetry: a load while the ball was clearly above the snow for the whole step — at
474
+ // its start and at its end — would be a contact nothing touched. A step that lands or
475
+ // kicks off legitimately touches at one end of it.
476
+ const clearance = ballState().clearance;
477
+ if (Math.min(clearance, telemetry.lastClearance) > 0.05 && snowPhysics.loadOf(ball) > 0)
478
+ telemetry.airborneLoads += 1;
479
+ telemetry.lastClearance = clearance;
480
+ const solved = solvedBall();
481
+ const rotation = solved.rotation;
482
+ const previous = telemetry.lastRotation;
483
+ const dot = Math.min(
484
+ 1,
485
+ Math.abs(
486
+ previous.x * rotation.x +
487
+ previous.y * rotation.y +
488
+ previous.z * rotation.z +
489
+ previous.w * rotation.w,
490
+ ),
491
+ );
492
+ const p = solved.position;
493
+ const moved = telemetry.lastPosition;
494
+ if (telemetry.kickedAt !== undefined) {
495
+ telemetry.turned += 2 * Math.acos(dot);
496
+ telemetry.rolled += Math.hypot(p.x - moved.x, p.z - moved.z);
497
+ telemetry.reach = Math.max(
498
+ telemetry.reach,
499
+ Math.hypot(p.x - telemetry.kickedAt.x, p.z - telemetry.kickedAt.z),
500
+ );
501
+ // Only where the ball is on the snow: a hop off the crater lip presses nothing beneath it.
502
+ const last = telemetry.path[telemetry.path.length - 1];
503
+ if (
504
+ clearance <= 0.01 &&
505
+ (last === undefined || Math.hypot(p.x - last.x, p.z - last.z) > 0.1)
506
+ )
507
+ telemetry.path.push({ x: p.x, z: p.z });
508
+ }
509
+ telemetry.lastRotation = { w: rotation.w, x: rotation.x, y: rotation.y, z: rotation.z };
510
+ telemetry.lastPosition = { x: p.x, y: p.y, z: p.z };
511
+ });
512
+ ctx.beforeRender(() => surface.refresh());
513
+
514
+ let waypoint = 0;
515
+ let pointer: { x: number; y: number } | undefined;
516
+ return (frameCtx, dt) => {
517
+ loading.update();
518
+ const input = frameCtx.input;
519
+ for (const command of commands.splice(0)) act(command);
520
+ for (const name of ["reset", "drop", "kick", "view", "auto", "blizzard", "mute"] as const)
521
+ if (input.justPressed(name)) act(name);
522
+ if (input.justPressed("compaction"))
523
+ frameCtx.state.set({ compaction: !frameCtx.state.getState().compaction });
524
+
525
+ const state = frameCtx.state.getState();
526
+ if (state.depth !== snow.depth) {
527
+ snow.setDepth(state.depth);
528
+ walkBody.dispose();
529
+ walkBody = walk(snow.depth);
530
+ surface.outskirts.position.y = snow.depth - startDepth;
531
+ }
532
+ snow.hardness = state.hardness;
533
+ surface.setCompactionView(state.compaction);
534
+
535
+ // Steering: the stick or the keys take over from auto-explore.
536
+ const stick = touchControls?.update(input.raw.pointers, frameCtx.viewport.size).move;
537
+ const keys = input.vector("move");
538
+ const sideways = keys.x + (stick?.x ?? 0);
539
+ const forward = keys.y + (stick?.y ?? 0);
540
+ if (autoExplore && Math.hypot(sideways, forward) > 0.1) {
541
+ autoExplore = false;
542
+ say(
543
+ touchControls === undefined
544
+ ? "You are in control. Hold Shift to run."
545
+ : "You are in control.",
546
+ );
547
+ }
548
+ let move: { x: number; z: number };
549
+ if (autoExplore) {
550
+ const [tx, tz] = ROUTE[waypoint] ?? [0, 0];
551
+ const dx = tx - explorer.position.x;
552
+ const dz = tz - explorer.position.z;
553
+ const distance = Math.hypot(dx, dz);
554
+ if (distance < 0.85) waypoint = (waypoint + 1) % ROUTE.length;
555
+ move = { x: dx / Math.max(0.01, distance), z: dz / Math.max(0.01, distance) };
556
+ } else {
557
+ const yaw = orbit.yaw;
558
+ move = {
559
+ x: Math.cos(yaw) * sideways - Math.sin(yaw) * forward,
560
+ z: -Math.sin(yaw) * sideways - Math.cos(yaw) * forward,
561
+ };
562
+ }
563
+ explorer.update(dt, move, input.pressed("run"), state.hardness);
564
+
565
+ weather.update(
566
+ dt,
567
+ explorer.position,
568
+ frameCtx.viewport.size.height / (2 * Math.tan((camera.fov * Math.PI) / 360)),
569
+ { ...state, blizzard },
570
+ );
571
+ lights.update(explorer.position, weather.storm);
572
+ stormSky(weather.storm);
573
+ surface.setStorm(weather.storm);
574
+ audio.update(weather.wind, weather.storm);
575
+
576
+ // Camera: drag to orbit (desktop), scroll or pinch to zoom.
577
+ const raw = input.raw.pointer;
578
+ if (touchControls === undefined && raw.down) {
579
+ if (pointer !== undefined)
580
+ orbit.drag(raw.position.x - pointer.x, raw.position.y - pointer.y);
581
+ pointer = { x: raw.position.x, y: raw.position.y };
582
+ } else pointer = undefined;
583
+ orbit.zoom(input.axis("zoom") * 16);
584
+ orbit.setView(state.view);
585
+ const target =
586
+ state.view === "surface"
587
+ ? surfaceTarget()
588
+ : {
589
+ x: explorer.position.x,
590
+ y: explorer.position.y + (state.view === "overhead" ? 0.25 : 0.8),
591
+ z: explorer.position.z,
592
+ };
593
+ orbit.update(camera, target, (x, z) => snow.heightAt(clampToField(x), clampToField(z)), dt);
594
+
595
+ const { gap, sink } = ballState();
596
+ frameCtx.state.set({
597
+ autoExplore,
598
+ blizzard,
599
+ ballGap: gap,
600
+ ballLoad: snowPhysics.loadOf(ball),
601
+ ballSink: sink,
602
+ contacts: snow.steps,
603
+ lastSink: lastStep.penetration,
604
+ muted: audio.muted,
605
+ probe: probeAround(snow, lastStep),
606
+ speed: explorer.speed,
607
+ storm: weather.storm,
608
+ toast,
609
+ toastId,
610
+ windNow: weather.wind,
611
+ });
612
+ };
613
+ }
614
+ }
615
+
616
+ function clampToField(value: number): number {
617
+ const half = FIELD_SIZE / 2 - 1e-3;
618
+ return Math.max(-half, Math.min(half, value));
619
+ }
620
+
621
+ /** The indentation under the last footprint, in the boot's own frame, for the HUD's probe. */
622
+ function probeAround(snow: SnowField, step: IFootstep): number[] {
623
+ const values: number[] = [];
624
+ const cos = Math.cos(step.angle);
625
+ const sin = Math.sin(step.angle);
626
+ for (let row = 0; row < PROBE_ROWS; row += 1) {
627
+ for (let column = 0; column < PROBE_COLUMNS; column += 1) {
628
+ const u = (column / (PROBE_COLUMNS - 1) - 0.5) * 0.56;
629
+ const v = (0.5 - row / (PROBE_ROWS - 1)) * 0.75;
630
+ const sample = snow.sample(step.x + u * cos + v * sin, step.z - u * sin + v * cos);
631
+ values.push(Math.round((sample.indent - sample.bank) * 1000) / 1000);
632
+ }
633
+ }
634
+ return values;
635
+ }
@@ -0,0 +1,46 @@
1
+ export type CameraView = "follow" | "surface" | "overhead";
2
+
3
+ export type GameState = {
4
+ uiReady: boolean;
5
+ paused: boolean;
6
+ /** The explorer walks the glade on its own until a movement key or the stick takes over. */
7
+ autoExplore: boolean;
8
+ blizzard: boolean;
9
+ /** 0 clear .. 1 full blizzard, eased, so the HUD and the weather agree mid-transition. */
10
+ storm: number;
11
+ /** Flake density, 0..1. */
12
+ snowfall: number;
13
+ /** Powder depth in metres. */
14
+ depth: number;
15
+ /** Falling speed of a flake in still air, m/s. */
16
+ fallSpeed: number;
17
+ /** 0..1 snow hardness. */
18
+ hardness: number;
19
+ /** Base wind in m/s before gusts and the storm. */
20
+ wind: number;
21
+ /** The wind actually blowing this frame, m/s. */
22
+ windNow: number;
23
+ /** How many times faster than real time fresh snow refills tracks. */
24
+ recovery: number;
25
+ compaction: boolean;
26
+ muted: boolean;
27
+ view: CameraView;
28
+ /** Contacts the field has taken since the last reset — footsteps and bodies together. */
29
+ contacts: number;
30
+ /** The last footfall's penetration, metres. */
31
+ lastSink: number;
32
+ speed: number;
33
+ /** Indentation under the last footfall, `PROBE_COLUMNS` x `PROBE_ROWS`, row-major, metres. */
34
+ probe: number[];
35
+ /** How far the ball's underside sits above (positive) or in (negative) the snow, metres. */
36
+ ballGap: number;
37
+ /** Indentation under the ball, metres. */
38
+ ballSink: number;
39
+ /** Load the ball's solved contacts pressed into the snow last step, newtons. */
40
+ ballLoad: number;
41
+ toast: string;
42
+ toastId: number;
43
+ };
44
+
45
+ export const PROBE_COLUMNS = 15;
46
+ export const PROBE_ROWS = 20;