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.
- package/README.md +3 -1
- package/agent-docs/references/capability-reference.md +177 -7
- package/capabilities.json +247 -4
- package/dist/index.js +6 -1
- package/dist/threenative.js +3 -2
- package/package.json +4 -4
- package/templates/action-rpg/package.json +1 -1
- package/templates/minimal/package.json +1 -1
- package/templates/platformer/package.json +1 -1
- package/templates/puzzle/package.json +1 -1
- package/templates/racing/package.json +1 -1
- package/templates/rain/.codex/config.toml +19 -0
- package/templates/rain/.cursor/mcp.json +32 -0
- package/templates/rain/.gemini/settings.json +32 -0
- package/templates/rain/.mcp.json +32 -0
- package/templates/rain/.vscode/mcp.json +36 -0
- package/templates/rain/.zed/settings.json +36 -0
- package/templates/rain/AGENTS.md +96 -0
- package/templates/rain/CLAUDE.md +98 -0
- package/templates/rain/assets/rain-loop.wav +0 -0
- package/templates/rain/assets/thunder.wav +0 -0
- package/templates/rain/assets/wind-loop.wav +0 -0
- package/templates/rain/index.html +18 -0
- package/templates/rain/kit.json +7 -0
- package/templates/rain/native-playtests/boot.playtest.json +13 -0
- package/templates/rain/native-playtests/lightning.playtest.json +173 -0
- package/templates/rain/opencode.json +41 -0
- package/templates/rain/package.json +56 -0
- package/templates/rain/playtests/auto-lightning-clear.playtest.json +66 -0
- package/templates/rain/playtests/auto-lightning.playtest.json +26 -0
- package/templates/rain/playtests/automation.playtest.json +133 -0
- package/templates/rain/playtests/cinematic.playtest.json +59 -0
- package/templates/rain/playtests/flash.playtest.json +27 -0
- package/templates/rain/playtests/fly.playtest.json +54 -0
- package/templates/rain/playtests/lightning.playtest.json +220 -0
- package/templates/rain/playtests/loading.playtest.json +57 -0
- package/templates/rain/playtests/paused.playtest.json +59 -0
- package/templates/rain/playtests/performance.playtest.json +22 -0
- package/templates/rain/playtests/reduced-motion.playtest.json +87 -0
- package/templates/rain/playtests/simulation.playtest.json +20 -0
- package/templates/rain/playtests/storm.playtest.json +150 -0
- package/templates/rain/playtests/survives.playtest.json +58 -0
- package/templates/rain/playtests/tiers.playtest.json +179 -0
- package/templates/rain/playtests/weather.playtest.json +77 -0
- package/templates/rain/public/favicon.svg +5 -0
- package/templates/rain/src/audio/storm.ts +314 -0
- package/templates/rain/src/game.ts +114 -0
- package/templates/rain/src/main.ts +15 -0
- package/templates/rain/src/render/bloom-shader.ts +65 -0
- package/templates/rain/src/render/camera.ts +160 -0
- package/templates/rain/src/render/clouds-shader.ts +242 -0
- package/templates/rain/src/render/clouds.ts +142 -0
- package/templates/rain/src/render/lighting.ts +39 -0
- package/templates/rain/src/render/lightning.ts +360 -0
- package/templates/rain/src/render/loading.ts +327 -0
- package/templates/rain/src/render/materials.ts +19 -0
- package/templates/rain/src/render/noise-volume.ts +159 -0
- package/templates/rain/src/render/palette.ts +18 -0
- package/templates/rain/src/render/post-shader.ts +178 -0
- package/templates/rain/src/render/postprocessing.ts +226 -0
- package/templates/rain/src/render/quality.ts +135 -0
- package/templates/rain/src/render/rain.ts +299 -0
- package/templates/rain/src/render/sky.ts +28 -0
- package/templates/rain/src/render/world-shader.ts +680 -0
- package/templates/rain/src/render/world.ts +146 -0
- package/templates/rain/src/render/worldEnvironment.ts +809 -0
- package/templates/rain/src/scenes/Boot.ts +334 -0
- package/templates/rain/src/state.ts +257 -0
- package/templates/rain/src/style.css +1160 -0
- package/templates/rain/src/ui/App.tsx +29 -0
- package/templates/rain/src/ui/GameUi.tsx +187 -0
- package/templates/rain/src/ui/Hud.tsx +327 -0
- package/templates/rain/src/ui/LoadingOverlay.tsx +46 -0
- package/templates/rain/src/ui/Menu.tsx +370 -0
- package/templates/rain/src/ui/automation.ts +60 -0
- package/templates/rain/src/ui/main.tsx +7 -0
- package/templates/rain/src/ui/tempest.ts +149 -0
- package/templates/rain/tailwind.config.ts +2 -0
- package/templates/rain/threenative.config.ts +66 -0
- package/templates/rain/tools/generate-shaders.mjs +656 -0
- package/templates/rain/tools/make-storm-audio.mjs +387 -0
- package/templates/rain/tools/storm-dsp.mjs +177 -0
- package/templates/rain/tools/tempest-bloom.frag +10 -0
- package/templates/rain/tools/tempest-clouds.frag +86 -0
- package/templates/rain/tools/tempest-post.frag +47 -0
- package/templates/rain/tools/tempest-world.frag +210 -0
- package/templates/rain/tools/verify-noise-volume.mjs +61 -0
- package/templates/rain/tsconfig.json +17 -0
- package/templates/rain/vite.config.ts +37 -0
- package/templates/rts/package.json +1 -1
- package/templates/runner/package.json +1 -1
- package/templates/sailing/package.json +1 -1
- package/templates/shooter/package.json +1 -1
- package/templates/snow/.codex/config.toml +19 -0
- package/templates/snow/.cursor/mcp.json +32 -0
- package/templates/snow/.gemini/settings.json +32 -0
- package/templates/snow/.mcp.json +32 -0
- package/templates/snow/.vscode/mcp.json +36 -0
- package/templates/snow/.zed/settings.json +36 -0
- package/templates/snow/AGENTS.md +88 -0
- package/templates/snow/CLAUDE.md +90 -0
- package/templates/snow/README.md +26 -0
- package/templates/snow/assets/crunch.wav +0 -0
- package/templates/snow/assets/wind.wav +0 -0
- package/templates/snow/index.html +12 -0
- package/templates/snow/kit.json +7 -0
- package/templates/snow/native-playtests/snow-physics.playtest.json +150 -0
- package/templates/snow/native-playtests/survives.playtest.json +47 -0
- package/templates/snow/opencode.json +41 -0
- package/templates/snow/package.json +58 -0
- package/templates/snow/playtests/footsteps.playtest.json +95 -0
- package/templates/snow/playtests/performance.playtest.json +36 -0
- package/templates/snow/playtests/snow-physics.playtest.json +154 -0
- package/templates/snow/playtests/survives.playtest.json +56 -0
- package/templates/snow/playtests/touch-controls.playtest.json +71 -0
- package/templates/snow/playtests/weather.playtest.json +119 -0
- package/templates/snow/public/favicon.svg +5 -0
- package/templates/snow/src/audio.ts +58 -0
- package/templates/snow/src/commands.ts +8 -0
- package/templates/snow/src/entities/Explorer.ts +279 -0
- package/templates/snow/src/game.ts +69 -0
- package/templates/snow/src/main.ts +15 -0
- package/templates/snow/src/render/bootPrint.ts +50 -0
- package/templates/snow/src/render/camera.ts +84 -0
- package/templates/snow/src/render/explorer.ts +321 -0
- package/templates/snow/src/render/lighting.ts +50 -0
- package/templates/snow/src/render/loading.ts +325 -0
- package/templates/snow/src/render/materials.ts +36 -0
- package/templates/snow/src/render/palette.ts +17 -0
- package/templates/snow/src/render/postprocessing.ts +44 -0
- package/templates/snow/src/render/props.ts +42 -0
- package/templates/snow/src/render/quality.ts +135 -0
- package/templates/snow/src/render/scenery.ts +244 -0
- package/templates/snow/src/render/sky.ts +57 -0
- package/templates/snow/src/render/snowSurface.ts +259 -0
- package/templates/snow/src/render/touch-controls.ts +143 -0
- package/templates/snow/src/render/weather.ts +279 -0
- package/templates/snow/src/render/worldEnvironment.ts +809 -0
- package/templates/snow/src/scenes/Boot.ts +12 -0
- package/templates/snow/src/scenes/Snow.ts +635 -0
- package/templates/snow/src/state.ts +46 -0
- package/templates/snow/src/style.css +143 -0
- package/templates/snow/src/terrain.ts +64 -0
- package/templates/snow/src/ui/App.tsx +15 -0
- package/templates/snow/src/ui/Controls.tsx +322 -0
- package/templates/snow/src/ui/GameUi.tsx +354 -0
- package/templates/snow/src/ui/icons.tsx +54 -0
- package/templates/snow/src/ui/main.tsx +7 -0
- package/templates/snow/tailwind.config.ts +2 -0
- package/templates/snow/threenative.config.ts +51 -0
- package/templates/snow/tsconfig.json +17 -0
- package/templates/snow/vite.config.ts +37 -0
- package/templates/starter/package.json +1 -1
- package/templates/tower-defense/package.json +1 -1
package/README.md
CHANGED
|
@@ -7,7 +7,7 @@ pnpm create threenative my-game
|
|
|
7
7
|
```
|
|
8
8
|
|
|
9
9
|
The default template is `starter`. Choose `minimal`, `platformer`, `action-rpg`, `tower-defense`,
|
|
10
|
-
`racing`, `sailing`,
|
|
10
|
+
`racing`, `sailing`, `rain`, `shooter`, or `snow` for a different starting point:
|
|
11
11
|
|
|
12
12
|
```sh
|
|
13
13
|
pnpm create threenative my-game --template minimal
|
|
@@ -17,7 +17,9 @@ pnpm create threenative my-game --template action-rpg
|
|
|
17
17
|
pnpm create threenative my-game --template tower-defense
|
|
18
18
|
pnpm create threenative my-game --template racing
|
|
19
19
|
pnpm create threenative my-game --template sailing
|
|
20
|
+
pnpm create threenative my-game --template rain
|
|
20
21
|
pnpm create threenative my-game --template shooter
|
|
22
|
+
pnpm create threenative my-game --template snow
|
|
21
23
|
```
|
|
22
24
|
|
|
23
25
|
Prerequisites are Node.js 20.19.0 or newer and pnpm 10 or newer. npm is also supported for the
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
|
|
4
4
|
# Capability reference
|
|
5
5
|
|
|
6
|
-
Every public class and function export represented by this manifest across `@threenative/assets`, `@threenative/core`, `@threenative/metahuman`, `@threenative/physics`, `@threenative/playtest`, `@threenative/raw-unreal`, `@threenative/ueformat`, `@threenative/ui`, `template:starter`, and `three`,
|
|
6
|
+
Every public class and function export represented by this manifest across `@threenative/assets`, `@threenative/core`, `@threenative/metahuman`, `@threenative/physics`, `@threenative/playtest`, `@threenative/raw-unreal`, `@threenative/ueformat`, `@threenative/ui`, `template:rain`, `template:starter`, and `three`,
|
|
7
7
|
generated from the doc tags the engine itself compiles, so this page cannot disagree with
|
|
8
8
|
the code. Look here before writing a replacement; ask `engine_search_capabilities` when an
|
|
9
9
|
MCP server is available.
|
|
@@ -618,8 +618,8 @@ model.step(1 / 60, { turn: -1, pitch: 0.4 });
|
|
|
618
618
|
export class AudioBus { … }
|
|
619
619
|
```
|
|
620
620
|
|
|
621
|
-
- **Use when:** play a sound effect with a volume bus · mute or adjust a category of game audio · keep a gunshot audible at 20 metres by tuning positional falloff · play cannon, wave, and ship sound effects
|
|
622
|
-
- **Constraints:** create buses before playing clips and dispose them with the game · refDistance and rolloffFactor tune positional falloff and apply to playAt only
|
|
621
|
+
- **Use when:** play a sound effect with a volume bus · mute or adjust a category of game audio · keep a gunshot audible at 20 metres by tuning positional falloff · hold a loud mix below clipping with a compressor on the bus · play cannon, wave, and ship sound effects
|
|
622
|
+
- **Constraints:** create buses before playing clips and dispose them with the game · refDistance and rolloffFactor tune positional falloff and apply to playAt only · compressor takes threshold, knee, ratio, attack and release from the game and takes effect on the bus sum
|
|
623
623
|
- **Supersedes (writing this fails `pnpm budgets`):** new Audio(
|
|
624
624
|
|
|
625
625
|
```ts
|
|
@@ -1284,7 +1284,7 @@ if (isMobile()) showTouchControls();
|
|
|
1284
1284
|
export class GPUParticles3D extends Sprite implements IComputeDriven { … }
|
|
1285
1285
|
```
|
|
1286
1286
|
|
|
1287
|
-
- **Use when:** emit sparks, smoke, or other transient effects · update many small visual particles · trail dust, exhaust, or spray behind a moving object · emit cannon smoke and muzzle flash particles · fire a cannonball projectile with cannon smoke particles
|
|
1287
|
+
- **Use when:** emit sparks, smoke, or other transient effects · update many small visual particles · trail dust, exhaust, or spray behind a moving object · emit cannon smoke and muzzle flash particles · fire a cannonball projectile with cannon smoke particles · falling snowflakes, rain or ash around the player that thicken into a windy storm or blizzard · kick up a spray of powder snow or dust where a foot or a ball lands
|
|
1288
1288
|
- **Constraints:** geometry, color, and timing remain supplied by the game
|
|
1289
1289
|
|
|
1290
1290
|
```ts
|
|
@@ -2093,7 +2093,7 @@ defineGame({ display: { maxFps: 60 }, scenes: { Play } });
|
|
|
2093
2093
|
export class Scheduler { … }
|
|
2094
2094
|
```
|
|
2095
2095
|
|
|
2096
|
-
- **Use when:** delay an enemy patrol transition · run a callback every simulation tick · tween a numeric property with a game-owned curve
|
|
2096
|
+
- **Use when:** delay an enemy patrol transition · run a callback every simulation tick · tween a numeric property with a game-owned curve · a countdown timer: end the level when its time limit runs out
|
|
2097
2097
|
- **Constraints:** dispose returned handles when the owning scene exits · ease receives progress in the range 0 to 1 and its return value is the interpolation factor
|
|
2098
2098
|
|
|
2099
2099
|
```ts
|
|
@@ -2358,7 +2358,7 @@ invalidateStatic(drawbridge);
|
|
|
2358
2358
|
export class TracerPool3D { … }
|
|
2359
2359
|
```
|
|
2360
2360
|
|
|
2361
|
-
- **Use when:** show where a hitscan round went · draw incoming fire without spawning projectiles
|
|
2361
|
+
- **Use when:** show where a hitscan round went · show each round a weapon fires, one tracer per trigger press · draw incoming fire without spawning projectiles
|
|
2362
2362
|
- **Constraints:** the surface comes from the game; pooling, travel, and fading belong to the engine · update once per frame and dispose with the owning scene
|
|
2363
2363
|
|
|
2364
2364
|
```ts
|
|
@@ -2874,7 +2874,7 @@ const capabilities = getWorldCapabilities({ limits: adapter.limits, cpuFallbackI
|
|
|
2874
2874
|
export class Heightfield extends Group implements IComputeDriven { … }
|
|
2875
2875
|
```
|
|
2876
2876
|
|
|
2877
|
-
- **Use when:** build terrain geometry and collision from one game-authored height function · generate a terrain a player can walk across · query the same ground height or normal that a player sees and collides with · ask how high the ground is here · build islands and coastlines from terrain
|
|
2877
|
+
- **Use when:** build terrain geometry and collision from one game-authored height function · generate a terrain a player can walk across · query the same ground height or normal that a player sees and collides with · ask how high the ground is here · build islands and coastlines from terrain · keep a collider or other copy of a deforming terrain in step without rescanning the whole field (`trackChanges`)
|
|
2878
2878
|
- **Constraints:** sampleHeight owns the terrain shape and stays in game source; the framework stores and interpolates its output · rows and columns are vertex counts; geometry is row-major z-then-x and collider export transposes once into Rapier's column-major matrix order
|
|
2879
2879
|
- **Overrides:** rows, columns, width, depth, origin, and sampleHeight are explicit on every field
|
|
2880
2880
|
|
|
@@ -2929,6 +2929,43 @@ export async function loadWorldHeightmap(url: string): Promise<Uint16Array> {
|
|
|
2929
2929
|
const data = await loadWorldHeightmap("/world/terrain/heightmap.u16");
|
|
2930
2930
|
```
|
|
2931
2931
|
|
|
2932
|
+
### `snowDiscFootprint`
|
|
2933
|
+
|
|
2934
|
+
`function` — A circular contact footprint, sized from a radius the caller measures. The shape a sphere, a ball, a wheel or a probe presses into snow, and the default the physics binding derives from a sphere's contact geometry. Flat inside the radius, eased over the softness band, with a raised rim just outside it.
|
|
2935
|
+
|
|
2936
|
+
```ts
|
|
2937
|
+
export function snowDiscFootprint( radius: number, options: ISnowDiscFootprintOptions = { … }
|
|
2938
|
+
```
|
|
2939
|
+
|
|
2940
|
+
- **Use when:** press a ball, wheel or probe into snow · give a sphere a physically sized snow contact instead of a boot shape
|
|
2941
|
+
- **Constraints:** radius is metres; the footprint never grows with load, only deeper
|
|
2942
|
+
- **Overrides:** softness widens the eased edge without changing the contact radius
|
|
2943
|
+
|
|
2944
|
+
```ts
|
|
2945
|
+
const footprint = snowDiscFootprint(0.25);
|
|
2946
|
+
```
|
|
2947
|
+
|
|
2948
|
+
### `SnowField`
|
|
2949
|
+
|
|
2950
|
+
`class` — Persistent snow deformation over one canonical heightfield. Snow keeps four channels per cell — indentation, displaced bank, compaction and disturbance — and writes the combined surface (`terrain + depth + bank - indent`) back into the heightfield it was given. Queries, rendered geometry and collider export therefore all read one surface, and no second terrain representation exists. The field is numeric only: it never chooses a boot, a tread, a particle, a material or a camera. Games supply terrain heights, the snow depth, the contact profile and the response coefficients; this class owns the storage, the load-dependent penetration and the bounded recovery. It is a heightfield approximation — not granular snow, displaced-volume conservation, avalanches, melting or a calibrated material law.
|
|
2951
|
+
|
|
2952
|
+
```ts
|
|
2953
|
+
export class SnowField { … }
|
|
2954
|
+
```
|
|
2955
|
+
|
|
2956
|
+
- **Use when:** leave footprints, tracks and tyre ruts in snow that persist and fill in over time · let a pushed sphere carve a connected track and a dropped one settle into a crater · store snow deformation that rendered geometry and collision both read · reset a snowfield between rounds or change its depth at runtime · show how packed the snow is where people have walked or objects have rested
|
|
2957
|
+
- **Constraints:** the field composes onto a Heightfield; construct the terrain first and let this own the surface · zero depth is bare ground: contacts register no indentation at all · out-of-region heightAt and normalAt follow Heightfield's error contract; sample returns zeros
|
|
2958
|
+
- **Requires:** @threenative/core/world Heightfield as the canonical terrain and surface
|
|
2959
|
+
- **Overrides:** depth, hardness, yieldFraction, maxBank and responseTime name the response coefficients
|
|
2960
|
+
|
|
2961
|
+
```ts
|
|
2962
|
+
import { Heightfield } from "@threenative/core/world";
|
|
2963
|
+
const terrain = Heightfield.fromSampler({ rows: 129, columns: 129, width: 64, depth: 64, origin: { x: 0, z: 0 }, sampleHeight: (x, z) => Math.sin(x * 0.1) * 0.5 });
|
|
2964
|
+
const snow = new SnowField({ field: terrain, depth: 0.28, hardness: 0.3 });
|
|
2965
|
+
snow.stamp({ x: 0, z: 0, area: 0.074, load: 784, duration: 0.1, footprint: snowDiscFootprint(0.12) });
|
|
2966
|
+
snow.recover(1 / 60, 0.0012, 0.4);
|
|
2967
|
+
```
|
|
2968
|
+
|
|
2932
2969
|
### `TerrainTiles`
|
|
2933
2970
|
|
|
2934
2971
|
`class` — Stream a bounded square of game-authored heightfields and keep their render and physics units together. The class composes ordinary THREE.LOD objects and leaves frustum/projection culling to the renderer's existing scene path.
|
|
@@ -3100,6 +3137,39 @@ export class Area3D { … }
|
|
|
3100
3137
|
const goal = new Area3D({ physics: ctx.physics, shape: CollisionShape3D.sphere(1.2), position: { x: 0, y: 0.5, z: -8 } });
|
|
3101
3138
|
```
|
|
3102
3139
|
|
|
3140
|
+
### `attachSnowPhysics`
|
|
3141
|
+
|
|
3142
|
+
`function` — Drive a `SnowField` from real solved contacts. The binding creates the snow surface collider from the field's own canonical samples and keeps it in step with them, so a body lands on the surface a query would report. Each fixed step it reads the solver's persistent contacts — not collision start/stop events, which carry no point or load — deforms the snow only where a contact is supported and loaded downward, then republishes the surface before the next step. Airborne bodies, side contacts and unrelated colliders never deform anything. A dropped sphere settles on the surface it made; a pushed one rotates and carves a connected track without its transform being copied anywhere. Footprints come from the body's own collision shape and orientation unless the game supplies one. Contact load is `impulse / deltaTime * loadScale`: a solver impulse over a step, which estimates a contact force and is not measured. `observe().loadProvenance` says so.
|
|
3143
|
+
|
|
3144
|
+
```ts
|
|
3145
|
+
export function attachSnowPhysics(options: ISnowPhysicsOptions): ISnowPhysicsBinding { … }
|
|
3146
|
+
```
|
|
3147
|
+
|
|
3148
|
+
- **Use when:** leave footprints and tracks where physical bodies actually touch snow · let a dropped or pushed sphere carve and settle into deformable snow · make a crate, capsule or ball compress the surface it rests on
|
|
3149
|
+
- **Constraints:** register `rapier()` before attaching, and call `step` once per fixed step after the physics step · the backend must expose persistent solved contacts and in-place shape refresh; one that does not fails at attach · verified on browser WebGPU and the native Linux desktop host; Android and iOS share the native seam but have not run it · automatic profiles cover sphere, box and capsule; any other shape needs an explicit footprint
|
|
3150
|
+
- **Requires:** @threenative/core/world SnowField as the surface it deforms
|
|
3151
|
+
- **Overrides:** loadScale, supportNormal, colliderTolerance, deposition, wind, collisionLayer and collisionMask name the binding's own behaviour
|
|
3152
|
+
|
|
3153
|
+
```ts
|
|
3154
|
+
const snowPhysics = attachSnowPhysics({ physics: ctx.physics, snow, bodies: [ball] });
|
|
3155
|
+
afterPhysics(ctx, (dt) => snowPhysics.step(dt));
|
|
3156
|
+
```
|
|
3157
|
+
|
|
3158
|
+
### `boxFootprint`
|
|
3159
|
+
|
|
3160
|
+
`function` — A rectangular contact: the face a box rests on, in the contact's own frame. Coverage is full across the face and fades just outside it; the bank rises beyond that.
|
|
3161
|
+
|
|
3162
|
+
```ts
|
|
3163
|
+
export function boxFootprint(halfWidth: number, halfDepth: number): ISnowFootprint { … }
|
|
3164
|
+
```
|
|
3165
|
+
|
|
3166
|
+
- **Use when:** let a crate, platform or plank press a rectangular pit into snow · imprint a box's own footprint rather than a circle around it
|
|
3167
|
+
- **Constraints:** halfWidth and halfDepth are metres; rotation comes from the contact, not the footprint
|
|
3168
|
+
|
|
3169
|
+
```ts
|
|
3170
|
+
const footprint = boxFootprint(0.4, 0.25);
|
|
3171
|
+
```
|
|
3172
|
+
|
|
3103
3173
|
### `buildStaticColliders`
|
|
3104
3174
|
|
|
3105
3175
|
`function` — Build fixed trimesh bodies from the meshes a game authored in a scene root.
|
|
@@ -3131,6 +3201,21 @@ export class Buoyancy3D { … }
|
|
|
3131
3201
|
new Buoyancy3D({ body, surface: field, hullPoints, density: 1_000, drag: 4 });
|
|
3132
3202
|
```
|
|
3133
3203
|
|
|
3204
|
+
### `capsuleFootprint`
|
|
3205
|
+
|
|
3206
|
+
`function` — A stadium contact: a rectangle of half-length `halfHeight` and half-width `radius`, capped by two half-discs of `radius`. The shape a capsule lies on, so a knocked-over body sinks along a line instead of at a point. Coverage is full across the body's own width and fades just outside it, so the body's edge never rests on a half-pressed rim; the bank rises beyond that.
|
|
3207
|
+
|
|
3208
|
+
```ts
|
|
3209
|
+
export function capsuleFootprint(halfHeight: number, radius: number): ISnowFootprint { … }
|
|
3210
|
+
```
|
|
3211
|
+
|
|
3212
|
+
- **Use when:** let a fallen capsule, limb or barrel leave a linear imprint in snow · give a capsule a shape-appropriate snow contact instead of a sphere's dot
|
|
3213
|
+
- **Constraints:** radius and halfHeight are metres and never grow with load
|
|
3214
|
+
|
|
3215
|
+
```ts
|
|
3216
|
+
const footprint = capsuleFootprint(0.5, 0.2);
|
|
3217
|
+
```
|
|
3218
|
+
|
|
3134
3219
|
### `CharacterBody3D`
|
|
3135
3220
|
|
|
3136
3221
|
`class` — Move a character body with collision-aware sliding.
|
|
@@ -5448,6 +5533,23 @@ export function useUiState<TState extends object>(): TState | undefined;
|
|
|
5448
5533
|
const score = useUiState<GameState, number>((state) => state.score);
|
|
5449
5534
|
```
|
|
5450
5535
|
|
|
5536
|
+
## `src/audio/storm.ts`
|
|
5537
|
+
|
|
5538
|
+
### `createStormAudio`
|
|
5539
|
+
|
|
5540
|
+
`function` — The storm's sound as generated source, mixed through the engine's own `AudioBus`: a rain hiss, a wind bed, and thunder queued strike by strike and delayed and filtered by how far away it was struck.
|
|
5541
|
+
|
|
5542
|
+
```ts
|
|
5543
|
+
createStormAudio(ctx: ICtx<GameState>): IStormAudio
|
|
5544
|
+
```
|
|
5545
|
+
|
|
5546
|
+
- **Use when:** rain hiss, wind bed, thunder, a storm you can hear · delay thunder by the distance it was struck · sound that follows pause, mute and tab visibility · audio that queues strikes instead of cutting each other off
|
|
5547
|
+
- **Constraints:** `queueStrike({ at, metres })` queues: a second strike does not overwrite one still crossing the air, and `at` is absolute simulation time, which is what lets a strike survive a freeze. · Two holds, kept apart so neither latches the other: `setSilenced` is the game's own pause intent, `setHidden` is the UI realm or engine lifecycle visibility. The bus is released only when both are clear. · `update(state)` is the frame's truth and is called once per frame after the simulation advances; `debug()` is what a playtest reads back. · The caller owns entity registration, updates and disposal; creating the helper does not register it. · Audio begins only after a user gesture — the bus's unlock error is surfaced rather than swallowed. · The three clips are baked by `tools/make-storm-audio.mjs` from the study's own maths; this file plays them, it does not synthesise them live. · The helper requests the source's compressor settings ahead of master gain: threshold -15 dB, knee 30 dB, ratio 5, attack 0.003 s and release 0.25 s. · Each thunder voice is a labelled `thunder` cue, so a playtest's `audio` assertion reads it from the runtime ledger; the rain kit's `playtests/lightning.playtest.json` proves one cue after a strike, sounded only once the strike's `distance / 343` delay had passed. · This entry describes the Rain starter scaffold's own generated `src/audio/storm.ts`, not a `@threenative/` or three export — there is no installed package to import it from.
|
|
5548
|
+
|
|
5549
|
+
```ts
|
|
5550
|
+
src/audio/storm.ts — register the returned helper, call update(state) after advancing the simulation, and dispose it with the owning scene
|
|
5551
|
+
```
|
|
5552
|
+
|
|
5451
5553
|
## `src/game.ts`
|
|
5452
5554
|
|
|
5453
5555
|
### `renderer.matrixWorld`
|
|
@@ -5498,6 +5600,74 @@ renderer.projection?: boolean | { materialChecks?: 'spread' | 'everyFrame' }
|
|
|
5498
5600
|
renderer: { projection: false } // in threenative.config.ts
|
|
5499
5601
|
```
|
|
5500
5602
|
|
|
5603
|
+
## `src/render/lightning.ts`
|
|
5604
|
+
|
|
5605
|
+
### `createStormLightning`
|
|
5606
|
+
|
|
5607
|
+
`function` — A branching lightning bolt as generated Rain source: `makeBolt(end, random)` walks a 30-segment channel down from the cloud deck with side branches, and one additive camera-facing ribbon draw (gaussian core inside a wide halo) shows it while the caller's flash envelope is above zero. `strike(position, random)` returns where the bolt entered the sky.
|
|
5608
|
+
|
|
5609
|
+
```ts
|
|
5610
|
+
createStormLightning(scene: Scene, camera: PerspectiveCamera): IStormLightning
|
|
5611
|
+
```
|
|
5612
|
+
|
|
5613
|
+
- **Use when:** generate branching lightning ribbon geometry · a lightning strike that lights the scene and the clouds · a camera-facing ribbon or beam that stays the same pixel width at any distance · a flash envelope that stutters rather than fades once
|
|
5614
|
+
- **Constraints:** Pass the game's seeded random so a strike is reproducible; a non-finite position or random value throws rather than drawing NaN geometry. · The buffers hold the worst case (30 channel segments plus 24 branches of 9) and are allocated once; a strike rewrites them and opens the draw range, never reallocating. · `update(flash)` takes an envelope already gated on photosensitivity mode by the caller; below 0.003 the mesh is hidden. Register it with `alwaysRender`: its quads are projected by its own vertex stage, so its bounds say nothing about where it lands. · It depth-tests against the coast's written depth, so a bolt behind the headland is hidden by it. · This entry describes the Rain starter scaffold's own generated `src/render/lightning.ts`, not a `@threenative/` or three export — there is no installed package to import it from.
|
|
5615
|
+
|
|
5616
|
+
```ts
|
|
5617
|
+
src/render/lightning.ts — the bolt; src/state.ts `flashAt` for the envelope; src/scenes/Boot.ts strike() for the thunder delay
|
|
5618
|
+
```
|
|
5619
|
+
|
|
5620
|
+
## `src/render/noise-volume.ts`
|
|
5621
|
+
|
|
5622
|
+
### `createNoiseVolume`
|
|
5623
|
+
|
|
5624
|
+
`function` — The 64³ RGBA cloud noise volume as generated Rain source: `{ data: Uint8Array, texture: Data3DTexture }`. Its authored seed, octave weights and source-exact generator define the storm's cloud shapes.
|
|
5625
|
+
|
|
5626
|
+
```ts
|
|
5627
|
+
createNoiseVolume(): INoiseVolume
|
|
5628
|
+
```
|
|
5629
|
+
|
|
5630
|
+
- **Use when:** generate a 3D noise volume instead of shipping one as an asset · rebuild the storm's clouds procedurally at startup · tileable 3D noise that does not crease at the edges · four octave scales packed into one texture
|
|
5631
|
+
- **Constraints:** Seed 13291 uses the source's mulberry32 sequence. The generated volume matches all 1,048,576 reference bytes; changing the authored seed or generator changes its appearance. · Two distinct failure channels, not one: `TN_NOISE_CHANNEL` is a channel value that does not fit a byte, `TN_NOISE_LENGTH` is a byte count that does not fill the volume. Both throw rather than uploading a volume the shader would read wrong. · 64³ of RGBA is 1 MiB, and `NOISE_SIZE` is what the loops and the byte count are written against; changing the size changes the memory cost with it. · Indices wrap at every face, which is what makes the volume tile, and the fractional part is smoothed by `f²(3 − 2f)` so lattice edges do not show as creases in the cloud. · This entry describes the Rain starter scaffold's own generated `src/render/noise-volume.ts`, not a `@threenative/` or three export — there is no installed package to import it from.
|
|
5632
|
+
|
|
5633
|
+
```ts
|
|
5634
|
+
src/render/noise-volume.ts — edit the seed, the lattices or the channel weights there
|
|
5635
|
+
```
|
|
5636
|
+
|
|
5637
|
+
## `src/render/rain.ts`
|
|
5638
|
+
|
|
5639
|
+
### `createStormRain`
|
|
5640
|
+
|
|
5641
|
+
`function` — Camera-anchored falling rain as generated Rain source: one instanced draw whose vertex stage hashes each drop from its index, wraps it in a 66 × 30 × 66 m cell that follows the camera in 12 m steps, and projects a quad stretched along its own fall — no particle simulation, no texture.
|
|
5642
|
+
|
|
5643
|
+
```ts
|
|
5644
|
+
createStormRain(scene: Scene, camera: PerspectiveCamera): IStormRain
|
|
5645
|
+
```
|
|
5646
|
+
|
|
5647
|
+
- **Use when:** rain streaks around the camera · thousands of falling drops in one draw · rain that leans with the wind and lights up in a lightning flash
|
|
5648
|
+
- **Constraints:** The drawn count is `round(rainBudget × weather.rain)` for the tier, read back from `geometry.instanceCount` (`instanceCount`), not from the budget. · Stateless by design: a drop's position is a function of its index and the clock, so pausing the clock freezes the rain and nothing accumulates. `GPUParticles3D` is the engine's emitter with lifetimes; reach for it when drops must spawn, live and die. · Register it with `alwaysRender`: the vertex stage places every drop, so the geometry's own bounds do not. · This entry describes the Rain starter scaffold's own generated `src/render/rain.ts`, not a `@threenative/` or three export — there is no installed package to import it from.
|
|
5649
|
+
|
|
5650
|
+
```ts
|
|
5651
|
+
src/render/rain.ts — the drop maths; `STUDY_TIERS` in src/render/quality.ts for the per-tier budget
|
|
5652
|
+
```
|
|
5653
|
+
|
|
5654
|
+
## `src/render/world.ts`
|
|
5655
|
+
|
|
5656
|
+
### `createWeatherWorld`
|
|
5657
|
+
|
|
5658
|
+
`function` — The raymarched coastal storm as generated source: one screen quad whose TSL shader draws the sky, the sea, the coast, the road, the forest and the lamps, and whose wet ground reflects them, written from the uniforms the game feeds it each frame. The sky it samples is the live cloud pass this call builds, not a stand-in gradient. Returns `{ quad, update(options), dispose() }`.
|
|
5659
|
+
|
|
5660
|
+
```ts
|
|
5661
|
+
createWeatherWorld(scene: Scene, camera: PerspectiveCamera): IWeatherWorld
|
|
5662
|
+
```
|
|
5663
|
+
|
|
5664
|
+
- **Use when:** a procedural storm, sea, coastline or open horizon drawn from maths rather than geometry · rain and wind that change how a scene looks without swapping a mesh · a lightning flash that lights the coast and the sky at once · wet reflections on a ground plane · sky that darkens as cloud cover rises
|
|
5665
|
+
- **Constraints:** `update` takes `{ elapsed, flash, weather, strike, quality }`: absolute seconds, a flash envelope already gated on the photosensitivity switch by the caller, the bolt's entry point in the cloud deck in metres (what the clouds glow around and the coast is lit from), and a quality name of `performance | balanced | high | ultra`. · The tier's cloud resolution share, march steps and reflection switch come from `STUDY_TIERS` in src/render/quality.ts; `performance` skips the 36-step reflection march, so a low tier loses reflections, not the coast. `clouds()` reads back the cloud target the renderer really drew and its steps. · Its colours and lights are uniforms set once from src/render/palette.ts, sky.ts, lighting.ts and materials.ts; the shader itself is generated from tools/tempest-*.frag by tools/generate-shaders.mjs — edit the .frag, not the generated file. · The engine's `Scene` and `PerspectiveCamera` are injected as arguments; the file holds no engine lifetime of its own. `dispose()` removes the quad and disposes the geometry, material and sky texture — the scene does not do it for you. · The quad has `frustumCulled = false`, because its two-metre bounds would otherwise be culled the moment the camera looks along the coast. · The cloud pass is built first and its texture feeds the world shader (sampled with the render-target flip); `update` also drives the clouds. Rain streaks and the bolt are separate draws: `createStormRain`, `createStormLightning`. · This entry describes the Rain starter scaffold's own generated `src/render/world.ts`, not a `@threenative/` or three export — there is no installed package to import it from. Appearance lives in that source with no package import at all; nothing in packages/ decides how this storm looks.
|
|
5666
|
+
|
|
5667
|
+
```ts
|
|
5668
|
+
src/render/world.ts — edit the shader there, or the weather it is fed from src/state.ts
|
|
5669
|
+
```
|
|
5670
|
+
|
|
5501
5671
|
## `src/render/worldEnvironment.ts`
|
|
5502
5672
|
|
|
5503
5673
|
### `WorldEnvironment`
|
package/capabilities.json
CHANGED
|
@@ -794,7 +794,8 @@
|
|
|
794
794
|
"aliases": [],
|
|
795
795
|
"constraints": [
|
|
796
796
|
"create buses before playing clips and dispose them with the game",
|
|
797
|
-
"refDistance and rolloffFactor tune positional falloff and apply to playAt only"
|
|
797
|
+
"refDistance and rolloffFactor tune positional falloff and apply to playAt only",
|
|
798
|
+
"compressor takes threshold, knee, ratio, attack and release from the game and takes effect on the bus sum"
|
|
798
799
|
],
|
|
799
800
|
"example": "const effects = new AudioBus({ camera });",
|
|
800
801
|
"importPath": "@threenative/core",
|
|
@@ -806,6 +807,7 @@
|
|
|
806
807
|
"play a sound effect with a volume bus",
|
|
807
808
|
"mute or adjust a category of game audio",
|
|
808
809
|
"keep a gunshot audible at 20 metres by tuning positional falloff",
|
|
810
|
+
"hold a loud mix below clipping with a compressor on the bus",
|
|
809
811
|
"play cannon, wave, and ship sound effects"
|
|
810
812
|
],
|
|
811
813
|
"summary": "Route effects through a named audio bus.",
|
|
@@ -1662,7 +1664,9 @@
|
|
|
1662
1664
|
"update many small visual particles",
|
|
1663
1665
|
"trail dust, exhaust, or spray behind a moving object",
|
|
1664
1666
|
"emit cannon smoke and muzzle flash particles",
|
|
1665
|
-
"fire a cannonball projectile with cannon smoke particles"
|
|
1667
|
+
"fire a cannonball projectile with cannon smoke particles",
|
|
1668
|
+
"falling snowflakes, rain or ash around the player that thicken into a windy storm or blizzard",
|
|
1669
|
+
"kick up a spray of powder snow or dust where a foot or a ball lands"
|
|
1666
1670
|
],
|
|
1667
1671
|
"summary": "Dispatch a game-owned particle surface and process function through a pooled system.",
|
|
1668
1672
|
"supersedes": [],
|
|
@@ -2686,7 +2690,8 @@
|
|
|
2686
2690
|
"situations": [
|
|
2687
2691
|
"delay an enemy patrol transition",
|
|
2688
2692
|
"run a callback every simulation tick",
|
|
2689
|
-
"tween a numeric property with a game-owned curve"
|
|
2693
|
+
"tween a numeric property with a game-owned curve",
|
|
2694
|
+
"a countdown timer: end the level when its time limit runs out"
|
|
2690
2695
|
],
|
|
2691
2696
|
"summary": "Schedule delayed and repeating callbacks or tween numeric properties with game-owned cleanup.",
|
|
2692
2697
|
"supersedes": [],
|
|
@@ -3042,6 +3047,7 @@
|
|
|
3042
3047
|
"signature": "export class TracerPool3D { … }",
|
|
3043
3048
|
"situations": [
|
|
3044
3049
|
"show where a hitscan round went",
|
|
3050
|
+
"show each round a weapon fires, one tracer per trigger press",
|
|
3045
3051
|
"draw incoming fire without spawning projectiles"
|
|
3046
3052
|
],
|
|
3047
3053
|
"summary": "Pool travelling bullet-streak meshes for hitscan shots.",
|
|
@@ -3658,7 +3664,8 @@
|
|
|
3658
3664
|
"generate a terrain a player can walk across",
|
|
3659
3665
|
"query the same ground height or normal that a player sees and collides with",
|
|
3660
3666
|
"ask how high the ground is here",
|
|
3661
|
-
"build islands and coastlines from terrain"
|
|
3667
|
+
"build islands and coastlines from terrain",
|
|
3668
|
+
"keep a collider or other copy of a deforming terrain in step without rescanning the whole field (`trackChanges`)"
|
|
3662
3669
|
],
|
|
3663
3670
|
"summary": "One height buffer shared by world queries, rendered geometry, and a physics heightfield. The game supplies every value, so changing the terrain's shape never requires a package edit. `fromSampler` evaluates that game function exactly once at each vertex and retains only the resulting numbers. Queries interpolate those same numbers instead of evaluating the function again.",
|
|
3664
3671
|
"supersedes": [],
|
|
@@ -3719,6 +3726,50 @@
|
|
|
3719
3726
|
"supersedes": [],
|
|
3720
3727
|
"symbol": "loadWorldHeightmap"
|
|
3721
3728
|
},
|
|
3729
|
+
{
|
|
3730
|
+
"aliases": [],
|
|
3731
|
+
"constraints": ["radius is metres; the footprint never grows with load, only deeper"],
|
|
3732
|
+
"example": "const footprint = snowDiscFootprint(0.25);",
|
|
3733
|
+
"importPath": "@threenative/core/world",
|
|
3734
|
+
"kind": "function",
|
|
3735
|
+
"overrides": ["softness widens the eased edge without changing the contact radius"],
|
|
3736
|
+
"package": "@threenative/core",
|
|
3737
|
+
"signature": "export function snowDiscFootprint( radius: number, options: ISnowDiscFootprintOptions = { … }",
|
|
3738
|
+
"situations": [
|
|
3739
|
+
"press a ball, wheel or probe into snow",
|
|
3740
|
+
"give a sphere a physically sized snow contact instead of a boot shape"
|
|
3741
|
+
],
|
|
3742
|
+
"summary": "A circular contact footprint, sized from a radius the caller measures. The shape a sphere, a ball, a wheel or a probe presses into snow, and the default the physics binding derives from a sphere's contact geometry. Flat inside the radius, eased over the softness band, with a raised rim just outside it.",
|
|
3743
|
+
"supersedes": [],
|
|
3744
|
+
"symbol": "snowDiscFootprint"
|
|
3745
|
+
},
|
|
3746
|
+
{
|
|
3747
|
+
"aliases": [],
|
|
3748
|
+
"constraints": [
|
|
3749
|
+
"the field composes onto a Heightfield; construct the terrain first and let this own the surface",
|
|
3750
|
+
"zero depth is bare ground: contacts register no indentation at all",
|
|
3751
|
+
"out-of-region heightAt and normalAt follow Heightfield's error contract; sample returns zeros"
|
|
3752
|
+
],
|
|
3753
|
+
"example": "import { Heightfield } from \"@threenative/core/world\";\nconst terrain = Heightfield.fromSampler({ rows: 129, columns: 129, width: 64, depth: 64, origin: { x: 0, z: 0 }, sampleHeight: (x, z) => Math.sin(x * 0.1) * 0.5 });\nconst snow = new SnowField({ field: terrain, depth: 0.28, hardness: 0.3 });\nsnow.stamp({ x: 0, z: 0, area: 0.074, load: 784, duration: 0.1, footprint: snowDiscFootprint(0.12) });\nsnow.recover(1 / 60, 0.0012, 0.4);",
|
|
3754
|
+
"importPath": "@threenative/core/world",
|
|
3755
|
+
"kind": "class",
|
|
3756
|
+
"overrides": [
|
|
3757
|
+
"depth, hardness, yieldFraction, maxBank and responseTime name the response coefficients"
|
|
3758
|
+
],
|
|
3759
|
+
"package": "@threenative/core",
|
|
3760
|
+
"requires": ["@threenative/core/world Heightfield as the canonical terrain and surface"],
|
|
3761
|
+
"signature": "export class SnowField { … }",
|
|
3762
|
+
"situations": [
|
|
3763
|
+
"leave footprints, tracks and tyre ruts in snow that persist and fill in over time",
|
|
3764
|
+
"let a pushed sphere carve a connected track and a dropped one settle into a crater",
|
|
3765
|
+
"store snow deformation that rendered geometry and collision both read",
|
|
3766
|
+
"reset a snowfield between rounds or change its depth at runtime",
|
|
3767
|
+
"show how packed the snow is where people have walked or objects have rested"
|
|
3768
|
+
],
|
|
3769
|
+
"summary": "Persistent snow deformation over one canonical heightfield. Snow keeps four channels per cell — indentation, displaced bank, compaction and disturbance — and writes the combined surface (`terrain + depth + bank - indent`) back into the heightfield it was given. Queries, rendered geometry and collider export therefore all read one surface, and no second terrain representation exists. The field is numeric only: it never chooses a boot, a tread, a particle, a material or a camera. Games supply terrain heights, the snow depth, the contact profile and the response coefficients; this class owns the storage, the load-dependent penetration and the bounded recovery. It is a heightfield approximation — not granular snow, displaced-volume conservation, avalanches, melting or a calibrated material law.",
|
|
3770
|
+
"supersedes": [],
|
|
3771
|
+
"symbol": "SnowField"
|
|
3772
|
+
},
|
|
3722
3773
|
{
|
|
3723
3774
|
"aliases": ["stream terrain across chunks"],
|
|
3724
3775
|
"constraints": [
|
|
@@ -3928,6 +3979,51 @@
|
|
|
3928
3979
|
"supersedes": [],
|
|
3929
3980
|
"symbol": "Area3D"
|
|
3930
3981
|
},
|
|
3982
|
+
{
|
|
3983
|
+
"aliases": [],
|
|
3984
|
+
"constraints": [
|
|
3985
|
+
"register `rapier()` before attaching, and call `step` once per fixed step after the physics step",
|
|
3986
|
+
"the backend must expose persistent solved contacts and in-place shape refresh; one that does not fails at attach",
|
|
3987
|
+
"verified on browser WebGPU and the native Linux desktop host; Android and iOS share the native seam but have not run it",
|
|
3988
|
+
"automatic profiles cover sphere, box and capsule; any other shape needs an explicit footprint"
|
|
3989
|
+
],
|
|
3990
|
+
"example": "const snowPhysics = attachSnowPhysics({ physics: ctx.physics, snow, bodies: [ball] });\nafterPhysics(ctx, (dt) => snowPhysics.step(dt));",
|
|
3991
|
+
"importPath": "@threenative/physics",
|
|
3992
|
+
"kind": "function",
|
|
3993
|
+
"overrides": [
|
|
3994
|
+
"loadScale, supportNormal, colliderTolerance, deposition, wind, collisionLayer and collisionMask name the binding's own behaviour"
|
|
3995
|
+
],
|
|
3996
|
+
"package": "@threenative/physics",
|
|
3997
|
+
"requires": ["@threenative/core/world SnowField as the surface it deforms"],
|
|
3998
|
+
"signature": "export function attachSnowPhysics(options: ISnowPhysicsOptions): ISnowPhysicsBinding { … }",
|
|
3999
|
+
"situations": [
|
|
4000
|
+
"leave footprints and tracks where physical bodies actually touch snow",
|
|
4001
|
+
"let a dropped or pushed sphere carve and settle into deformable snow",
|
|
4002
|
+
"make a crate, capsule or ball compress the surface it rests on"
|
|
4003
|
+
],
|
|
4004
|
+
"summary": "Drive a `SnowField` from real solved contacts. The binding creates the snow surface collider from the field's own canonical samples and keeps it in step with them, so a body lands on the surface a query would report. Each fixed step it reads the solver's persistent contacts — not collision start/stop events, which carry no point or load — deforms the snow only where a contact is supported and loaded downward, then republishes the surface before the next step. Airborne bodies, side contacts and unrelated colliders never deform anything. A dropped sphere settles on the surface it made; a pushed one rotates and carves a connected track without its transform being copied anywhere. Footprints come from the body's own collision shape and orientation unless the game supplies one. Contact load is `impulse / deltaTime * loadScale`: a solver impulse over a step, which estimates a contact force and is not measured. `observe().loadProvenance` says so.",
|
|
4005
|
+
"supersedes": [],
|
|
4006
|
+
"symbol": "attachSnowPhysics"
|
|
4007
|
+
},
|
|
4008
|
+
{
|
|
4009
|
+
"aliases": [],
|
|
4010
|
+
"constraints": [
|
|
4011
|
+
"halfWidth and halfDepth are metres; rotation comes from the contact, not the footprint"
|
|
4012
|
+
],
|
|
4013
|
+
"example": "const footprint = boxFootprint(0.4, 0.25);",
|
|
4014
|
+
"importPath": "@threenative/physics",
|
|
4015
|
+
"kind": "function",
|
|
4016
|
+
"overrides": [],
|
|
4017
|
+
"package": "@threenative/physics",
|
|
4018
|
+
"signature": "export function boxFootprint(halfWidth: number, halfDepth: number): ISnowFootprint { … }",
|
|
4019
|
+
"situations": [
|
|
4020
|
+
"let a crate, platform or plank press a rectangular pit into snow",
|
|
4021
|
+
"imprint a box's own footprint rather than a circle around it"
|
|
4022
|
+
],
|
|
4023
|
+
"summary": "A rectangular contact: the face a box rests on, in the contact's own frame. Coverage is full across the face and fades just outside it; the bank rises beyond that.",
|
|
4024
|
+
"supersedes": [],
|
|
4025
|
+
"symbol": "boxFootprint"
|
|
4026
|
+
},
|
|
3931
4027
|
{
|
|
3932
4028
|
"aliases": [],
|
|
3933
4029
|
"constraints": [
|
|
@@ -3962,6 +4058,23 @@
|
|
|
3962
4058
|
"supersedes": [],
|
|
3963
4059
|
"symbol": "Buoyancy3D"
|
|
3964
4060
|
},
|
|
4061
|
+
{
|
|
4062
|
+
"aliases": [],
|
|
4063
|
+
"constraints": ["radius and halfHeight are metres and never grow with load"],
|
|
4064
|
+
"example": "const footprint = capsuleFootprint(0.5, 0.2);",
|
|
4065
|
+
"importPath": "@threenative/physics",
|
|
4066
|
+
"kind": "function",
|
|
4067
|
+
"overrides": [],
|
|
4068
|
+
"package": "@threenative/physics",
|
|
4069
|
+
"signature": "export function capsuleFootprint(halfHeight: number, radius: number): ISnowFootprint { … }",
|
|
4070
|
+
"situations": [
|
|
4071
|
+
"let a fallen capsule, limb or barrel leave a linear imprint in snow",
|
|
4072
|
+
"give a capsule a shape-appropriate snow contact instead of a sphere's dot"
|
|
4073
|
+
],
|
|
4074
|
+
"summary": "A stadium contact: a rectangle of half-length `halfHeight` and half-width `radius`, capped by two half-discs of `radius`. The shape a capsule lies on, so a knocked-over body sinks along a line instead of at a point. Coverage is full across the body's own width and fades just outside it, so the body's edge never rests on a half-pressed rim; the bank rises beyond that.",
|
|
4075
|
+
"supersedes": [],
|
|
4076
|
+
"symbol": "capsuleFootprint"
|
|
4077
|
+
},
|
|
3965
4078
|
{
|
|
3966
4079
|
"aliases": [
|
|
3967
4080
|
"raised platform gap hazard restart",
|
|
@@ -6626,6 +6739,35 @@
|
|
|
6626
6739
|
"supersedes": [],
|
|
6627
6740
|
"symbol": "useUiState"
|
|
6628
6741
|
},
|
|
6742
|
+
{
|
|
6743
|
+
"symbol": "createStormAudio",
|
|
6744
|
+
"package": "template:rain",
|
|
6745
|
+
"importPath": "src/audio/storm.ts",
|
|
6746
|
+
"kind": "function",
|
|
6747
|
+
"signature": "createStormAudio(ctx: ICtx<GameState>): IStormAudio",
|
|
6748
|
+
"summary": "The storm's sound as generated source, mixed through the engine's own `AudioBus`: a rain hiss, a wind bed, and thunder queued strike by strike and delayed and filtered by how far away it was struck.",
|
|
6749
|
+
"situations": [
|
|
6750
|
+
"rain hiss, wind bed, thunder, a storm you can hear",
|
|
6751
|
+
"delay thunder by the distance it was struck",
|
|
6752
|
+
"sound that follows pause, mute and tab visibility",
|
|
6753
|
+
"audio that queues strikes instead of cutting each other off"
|
|
6754
|
+
],
|
|
6755
|
+
"example": "src/audio/storm.ts — register the returned helper, call update(state) after advancing the simulation, and dispose it with the owning scene",
|
|
6756
|
+
"constraints": [
|
|
6757
|
+
"`queueStrike({ at, metres })` queues: a second strike does not overwrite one still crossing the air, and `at` is absolute simulation time, which is what lets a strike survive a freeze.",
|
|
6758
|
+
"Two holds, kept apart so neither latches the other: `setSilenced` is the game's own pause intent, `setHidden` is the UI realm or engine lifecycle visibility. The bus is released only when both are clear.",
|
|
6759
|
+
"`update(state)` is the frame's truth and is called once per frame after the simulation advances; `debug()` is what a playtest reads back.",
|
|
6760
|
+
"The caller owns entity registration, updates and disposal; creating the helper does not register it.",
|
|
6761
|
+
"Audio begins only after a user gesture — the bus's unlock error is surfaced rather than swallowed.",
|
|
6762
|
+
"The three clips are baked by `tools/make-storm-audio.mjs` from the study's own maths; this file plays them, it does not synthesise them live.",
|
|
6763
|
+
"The helper requests the source's compressor settings ahead of master gain: threshold -15 dB, knee 30 dB, ratio 5, attack 0.003 s and release 0.25 s.",
|
|
6764
|
+
"Each thunder voice is a labelled `thunder` cue, so a playtest's `audio` assertion reads it from the runtime ledger; the rain kit's `playtests/lightning.playtest.json` proves one cue after a strike, sounded only once the strike's `distance / 343` delay had passed.",
|
|
6765
|
+
"This entry describes the Rain starter scaffold's own generated `src/audio/storm.ts`, not a `@threenative/` or three export — there is no installed package to import it from."
|
|
6766
|
+
],
|
|
6767
|
+
"overrides": [],
|
|
6768
|
+
"supersedes": [],
|
|
6769
|
+
"aliases": []
|
|
6770
|
+
},
|
|
6629
6771
|
{
|
|
6630
6772
|
"symbol": "renderer.matrixWorld",
|
|
6631
6773
|
"package": "@threenative/core",
|
|
@@ -6721,6 +6863,107 @@
|
|
|
6721
6863
|
"supersedes": [],
|
|
6722
6864
|
"aliases": []
|
|
6723
6865
|
},
|
|
6866
|
+
{
|
|
6867
|
+
"symbol": "createStormLightning",
|
|
6868
|
+
"package": "template:rain",
|
|
6869
|
+
"importPath": "src/render/lightning.ts",
|
|
6870
|
+
"kind": "function",
|
|
6871
|
+
"signature": "createStormLightning(scene: Scene, camera: PerspectiveCamera): IStormLightning",
|
|
6872
|
+
"summary": "A branching lightning bolt as generated Rain source: `makeBolt(end, random)` walks a 30-segment channel down from the cloud deck with side branches, and one additive camera-facing ribbon draw (gaussian core inside a wide halo) shows it while the caller's flash envelope is above zero. `strike(position, random)` returns where the bolt entered the sky.",
|
|
6873
|
+
"situations": [
|
|
6874
|
+
"generate branching lightning ribbon geometry",
|
|
6875
|
+
"a lightning strike that lights the scene and the clouds",
|
|
6876
|
+
"a camera-facing ribbon or beam that stays the same pixel width at any distance",
|
|
6877
|
+
"a flash envelope that stutters rather than fades once"
|
|
6878
|
+
],
|
|
6879
|
+
"example": "src/render/lightning.ts — the bolt; src/state.ts `flashAt` for the envelope; src/scenes/Boot.ts strike() for the thunder delay",
|
|
6880
|
+
"constraints": [
|
|
6881
|
+
"Pass the game's seeded random so a strike is reproducible; a non-finite position or random value throws rather than drawing NaN geometry.",
|
|
6882
|
+
"The buffers hold the worst case (30 channel segments plus 24 branches of 9) and are allocated once; a strike rewrites them and opens the draw range, never reallocating.",
|
|
6883
|
+
"`update(flash)` takes an envelope already gated on photosensitivity mode by the caller; below 0.003 the mesh is hidden. Register it with `alwaysRender`: its quads are projected by its own vertex stage, so its bounds say nothing about where it lands.",
|
|
6884
|
+
"It depth-tests against the coast's written depth, so a bolt behind the headland is hidden by it.",
|
|
6885
|
+
"This entry describes the Rain starter scaffold's own generated `src/render/lightning.ts`, not a `@threenative/` or three export — there is no installed package to import it from."
|
|
6886
|
+
],
|
|
6887
|
+
"overrides": [],
|
|
6888
|
+
"supersedes": [],
|
|
6889
|
+
"aliases": []
|
|
6890
|
+
},
|
|
6891
|
+
{
|
|
6892
|
+
"symbol": "createNoiseVolume",
|
|
6893
|
+
"package": "template:rain",
|
|
6894
|
+
"importPath": "src/render/noise-volume.ts",
|
|
6895
|
+
"kind": "function",
|
|
6896
|
+
"signature": "createNoiseVolume(): INoiseVolume",
|
|
6897
|
+
"summary": "The 64³ RGBA cloud noise volume as generated Rain source: `{ data: Uint8Array, texture: Data3DTexture }`. Its authored seed, octave weights and source-exact generator define the storm's cloud shapes.",
|
|
6898
|
+
"situations": [
|
|
6899
|
+
"generate a 3D noise volume instead of shipping one as an asset",
|
|
6900
|
+
"rebuild the storm's clouds procedurally at startup",
|
|
6901
|
+
"tileable 3D noise that does not crease at the edges",
|
|
6902
|
+
"four octave scales packed into one texture"
|
|
6903
|
+
],
|
|
6904
|
+
"example": "src/render/noise-volume.ts — edit the seed, the lattices or the channel weights there",
|
|
6905
|
+
"constraints": [
|
|
6906
|
+
"Seed 13291 uses the source's mulberry32 sequence. The generated volume matches all 1,048,576 reference bytes; changing the authored seed or generator changes its appearance.",
|
|
6907
|
+
"Two distinct failure channels, not one: `TN_NOISE_CHANNEL` is a channel value that does not fit a byte, `TN_NOISE_LENGTH` is a byte count that does not fill the volume. Both throw rather than uploading a volume the shader would read wrong.",
|
|
6908
|
+
"64³ of RGBA is 1 MiB, and `NOISE_SIZE` is what the loops and the byte count are written against; changing the size changes the memory cost with it.",
|
|
6909
|
+
"Indices wrap at every face, which is what makes the volume tile, and the fractional part is smoothed by `f²(3 − 2f)` so lattice edges do not show as creases in the cloud.",
|
|
6910
|
+
"This entry describes the Rain starter scaffold's own generated `src/render/noise-volume.ts`, not a `@threenative/` or three export — there is no installed package to import it from."
|
|
6911
|
+
],
|
|
6912
|
+
"overrides": [],
|
|
6913
|
+
"supersedes": [],
|
|
6914
|
+
"aliases": []
|
|
6915
|
+
},
|
|
6916
|
+
{
|
|
6917
|
+
"symbol": "createStormRain",
|
|
6918
|
+
"package": "template:rain",
|
|
6919
|
+
"importPath": "src/render/rain.ts",
|
|
6920
|
+
"kind": "function",
|
|
6921
|
+
"signature": "createStormRain(scene: Scene, camera: PerspectiveCamera): IStormRain",
|
|
6922
|
+
"summary": "Camera-anchored falling rain as generated Rain source: one instanced draw whose vertex stage hashes each drop from its index, wraps it in a 66 × 30 × 66 m cell that follows the camera in 12 m steps, and projects a quad stretched along its own fall — no particle simulation, no texture.",
|
|
6923
|
+
"situations": [
|
|
6924
|
+
"rain streaks around the camera",
|
|
6925
|
+
"thousands of falling drops in one draw",
|
|
6926
|
+
"rain that leans with the wind and lights up in a lightning flash"
|
|
6927
|
+
],
|
|
6928
|
+
"example": "src/render/rain.ts — the drop maths; `STUDY_TIERS` in src/render/quality.ts for the per-tier budget",
|
|
6929
|
+
"constraints": [
|
|
6930
|
+
"The drawn count is `round(rainBudget × weather.rain)` for the tier, read back from `geometry.instanceCount` (`instanceCount`), not from the budget.",
|
|
6931
|
+
"Stateless by design: a drop's position is a function of its index and the clock, so pausing the clock freezes the rain and nothing accumulates. `GPUParticles3D` is the engine's emitter with lifetimes; reach for it when drops must spawn, live and die.",
|
|
6932
|
+
"Register it with `alwaysRender`: the vertex stage places every drop, so the geometry's own bounds do not.",
|
|
6933
|
+
"This entry describes the Rain starter scaffold's own generated `src/render/rain.ts`, not a `@threenative/` or three export — there is no installed package to import it from."
|
|
6934
|
+
],
|
|
6935
|
+
"overrides": [],
|
|
6936
|
+
"supersedes": [],
|
|
6937
|
+
"aliases": []
|
|
6938
|
+
},
|
|
6939
|
+
{
|
|
6940
|
+
"symbol": "createWeatherWorld",
|
|
6941
|
+
"package": "template:rain",
|
|
6942
|
+
"importPath": "src/render/world.ts",
|
|
6943
|
+
"kind": "function",
|
|
6944
|
+
"signature": "createWeatherWorld(scene: Scene, camera: PerspectiveCamera): IWeatherWorld",
|
|
6945
|
+
"summary": "The raymarched coastal storm as generated source: one screen quad whose TSL shader draws the sky, the sea, the coast, the road, the forest and the lamps, and whose wet ground reflects them, written from the uniforms the game feeds it each frame. The sky it samples is the live cloud pass this call builds, not a stand-in gradient. Returns `{ quad, update(options), dispose() }`.",
|
|
6946
|
+
"situations": [
|
|
6947
|
+
"a procedural storm, sea, coastline or open horizon drawn from maths rather than geometry",
|
|
6948
|
+
"rain and wind that change how a scene looks without swapping a mesh",
|
|
6949
|
+
"a lightning flash that lights the coast and the sky at once",
|
|
6950
|
+
"wet reflections on a ground plane",
|
|
6951
|
+
"sky that darkens as cloud cover rises"
|
|
6952
|
+
],
|
|
6953
|
+
"example": "src/render/world.ts — edit the shader there, or the weather it is fed from src/state.ts",
|
|
6954
|
+
"constraints": [
|
|
6955
|
+
"`update` takes `{ elapsed, flash, weather, strike, quality }`: absolute seconds, a flash envelope already gated on the photosensitivity switch by the caller, the bolt's entry point in the cloud deck in metres (what the clouds glow around and the coast is lit from), and a quality name of `performance | balanced | high | ultra`.",
|
|
6956
|
+
"The tier's cloud resolution share, march steps and reflection switch come from `STUDY_TIERS` in src/render/quality.ts; `performance` skips the 36-step reflection march, so a low tier loses reflections, not the coast. `clouds()` reads back the cloud target the renderer really drew and its steps.",
|
|
6957
|
+
"Its colours and lights are uniforms set once from src/render/palette.ts, sky.ts, lighting.ts and materials.ts; the shader itself is generated from tools/tempest-*.frag by tools/generate-shaders.mjs — edit the .frag, not the generated file.",
|
|
6958
|
+
"The engine's `Scene` and `PerspectiveCamera` are injected as arguments; the file holds no engine lifetime of its own. `dispose()` removes the quad and disposes the geometry, material and sky texture — the scene does not do it for you.",
|
|
6959
|
+
"The quad has `frustumCulled = false`, because its two-metre bounds would otherwise be culled the moment the camera looks along the coast.",
|
|
6960
|
+
"The cloud pass is built first and its texture feeds the world shader (sampled with the render-target flip); `update` also drives the clouds. Rain streaks and the bolt are separate draws: `createStormRain`, `createStormLightning`.",
|
|
6961
|
+
"This entry describes the Rain starter scaffold's own generated `src/render/world.ts`, not a `@threenative/` or three export — there is no installed package to import it from. Appearance lives in that source with no package import at all; nothing in packages/ decides how this storm looks."
|
|
6962
|
+
],
|
|
6963
|
+
"overrides": [],
|
|
6964
|
+
"supersedes": [],
|
|
6965
|
+
"aliases": []
|
|
6966
|
+
},
|
|
6724
6967
|
{
|
|
6725
6968
|
"symbol": "WorldEnvironment",
|
|
6726
6969
|
"package": "three",
|
package/dist/index.js
CHANGED
|
@@ -2244,7 +2244,12 @@ var AUTHORING_GITIGNORE_RULES = [
|
|
|
2244
2244
|
"node_modules/",
|
|
2245
2245
|
".env",
|
|
2246
2246
|
".env.*",
|
|
2247
|
-
"!.env.example"
|
|
2247
|
+
"!.env.example",
|
|
2248
|
+
// The asset pipeline's compiled outputs: any project with an assets/ folder gets them in public/
|
|
2249
|
+
// on its first dev run or build. Hand-owned public files (favicon, icons) stay committed.
|
|
2250
|
+
"public/assets.manifest.json",
|
|
2251
|
+
"public/bake.receipt.json",
|
|
2252
|
+
"public/*.[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f].*"
|
|
2248
2253
|
];
|
|
2249
2254
|
var REFERENCE_TOKEN_PATTERN = new RegExp(
|
|
2250
2255
|
`\`${REFERENCE_BUNDLE_PREFIX}([a-z0-9][a-z0-9./-]*\\.md)\`|\\[[^\\]]*\\]\\(${REFERENCE_BUNDLE_PREFIX}([^)#]+\\.md)\\)`,
|