create-threenative 0.2.18 → 0.2.20
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/agent-docs/references/capability-reference.md +212 -4
- package/agent-docs/references/kit-racing.md +4 -2
- package/agent-docs/references/performance-basics.md +2 -1
- package/agent-docs/references/terrain-authoring.md +21 -7
- package/agent-files/.agents/skills/prd-creator/SKILL.md +24 -0
- package/dist/index.js +255 -236
- package/dist/quality.d.ts +5 -1
- package/dist/quality.js +75 -6
- package/dist/terrain-kit.js +1 -1
- package/dist/threenative.js +6 -4
- package/dist/web-engine-post-effects.js +6 -0
- package/dist/web-engine-runtime.js +211 -36
- package/package.json +6 -6
- package/template-assets/assets/floor-fern-0.glb +0 -0
- package/template-assets/assets/floor-litter-0.glb +0 -0
- package/template-assets/assets/floor-log-0.glb +0 -0
- package/template-assets/assets/floor-log-1.glb +0 -0
- package/template-assets/assets/floor-stump-0.glb +0 -0
- package/template-assets/assets/floor-twig-0.glb +0 -0
- package/template-assets/quality/eslint.config.js +1 -1
- package/templates/action-rpg/package.json +7 -7
- package/templates/action-rpg/src/loot/drops.ts +3 -7
- package/templates/action-rpg/src/render/camera.ts +2 -2
- package/templates/action-rpg/src/render/clouds.ts +3 -1
- package/templates/action-rpg/src/render/materials.ts +3 -2
- package/templates/action-rpg/src/render/touch-controls.ts +7 -6
- package/templates/action-rpg/src/scenes/Play.ts +1 -15
- package/templates/adventure/AGENTS.md +3 -3
- package/templates/adventure/CLAUDE.md +3 -3
- package/templates/adventure/native-playtests/survives.playtest.json +12 -0
- package/templates/adventure/native-playtests/woodland-floor.playtest.json +61 -0
- package/templates/adventure/package.json +7 -7
- package/templates/adventure/playtests/grass.playtest.json +61 -0
- package/templates/adventure/playtests/performance.playtest.json +1 -1
- package/templates/adventure/playtests/survives.playtest.json +2 -2
- package/templates/adventure/playtests/woodland-floor.playtest.json +61 -0
- package/templates/adventure/src/entities/LockOn.ts +42 -4
- package/templates/adventure/src/entities/Warden.ts +4 -1
- package/templates/adventure/src/level/Vale.ts +241 -16
- package/templates/adventure/src/render/camera.ts +2 -2
- package/templates/adventure/src/render/foliage.ts +64 -20
- package/templates/adventure/src/render/grass.ts +325 -0
- package/templates/adventure/src/render/materials.ts +3 -2
- package/templates/adventure/src/render/palette.ts +3 -0
- package/templates/adventure/src/render/touch-controls.ts +4 -1
- package/templates/adventure/src/scenes/Play.ts +96 -1
- package/templates/collectathon/package.json +7 -7
- package/templates/collectathon/src/level/Course.ts +2 -7
- package/templates/collectathon/src/level/terrain.ts +2 -1
- package/templates/collectathon/src/render/camera.ts +2 -2
- package/templates/collectathon/src/render/ground.ts +4 -4
- package/templates/collectathon/src/render/hero.ts +1 -1
- package/templates/collectathon/src/render/materials.ts +0 -1
- package/templates/collectathon/src/render/sky.ts +4 -3
- package/templates/kart/package.json +6 -6
- package/templates/kart/src/entities/Kart.ts +2 -1
- package/templates/kart/src/render/course.ts +2 -1
- package/templates/kart/src/track/Course.ts +3 -1
- package/templates/minimal/package.json +6 -6
- package/templates/minimal/src/render/camera.ts +2 -2
- package/templates/minimal/src/render/clouds.ts +3 -1
- package/templates/minimal/src/render/materials.ts +3 -2
- package/templates/minimal/src/render/touch-controls.ts +7 -6
- package/templates/platformer/package.json +7 -7
- package/templates/platformer/playtests/collect.playtest.json +4 -1
- package/templates/platformer/src/level/Stage.ts +2 -6
- package/templates/platformer/src/scenes/Play.ts +2 -1
- package/templates/puzzle/package.json +7 -7
- package/templates/puzzle/src/entities/Warden.ts +3 -3
- package/templates/puzzle/src/render/camera.ts +2 -2
- package/templates/puzzle/src/render/touch-controls.ts +7 -6
- package/templates/racing/AGENTS.md +2 -2
- package/templates/racing/CLAUDE.md +2 -2
- package/templates/racing/CREDITS.md +29 -0
- package/templates/racing/assets/engine-loop.wav +0 -0
- package/templates/racing/assets/grass/Grass004_color.jpg +0 -0
- package/templates/racing/assets/grass/Grass004_normal.jpg +0 -0
- package/templates/racing/assets/grass/Grass004_roughness.jpg +0 -0
- package/templates/racing/assets/nitro-burst.wav +0 -0
- package/templates/racing/assets/tyre-squeal.wav +0 -0
- package/templates/racing/package.json +7 -7
- package/templates/racing/playtests/drift-natural.playtest.json +68 -0
- package/templates/racing/playtests/drift.playtest.json +100 -0
- package/templates/racing/playtests/hud.playtest.json +117 -0
- package/templates/racing/playtests/launch-pose.playtest.json +34 -0
- package/templates/racing/playtests/nitro.playtest.json +158 -0
- package/templates/racing/playtests/outcome.playtest.json +4 -4
- package/templates/racing/playtests/performance.playtest.json +1 -1
- package/templates/racing/playtests/steady-camera.playtest.json +88 -0
- package/templates/racing/src/audio/engine.ts +138 -0
- package/templates/racing/src/entities/CarBody.ts +83 -10
- package/templates/racing/src/entities/Drift.ts +243 -0
- package/templates/racing/src/entities/LineDriver.ts +2 -2
- package/templates/racing/src/entities/Nitro.ts +72 -0
- package/templates/racing/src/entities/RacingCar.ts +86 -21
- package/templates/racing/src/entities/Rival.ts +35 -21
- package/templates/racing/src/game.ts +6 -0
- package/templates/racing/src/gauges.ts +74 -0
- package/templates/racing/src/render/camera.ts +29 -4
- package/templates/racing/src/render/clouds.ts +3 -1
- package/templates/racing/src/render/effects.ts +244 -0
- package/templates/racing/src/render/materials.ts +43 -8
- package/templates/racing/src/render/shapes.ts +37 -0
- package/templates/racing/src/render/skids.ts +84 -0
- package/templates/racing/src/render/touch-controls.ts +10 -10
- package/templates/racing/src/scenes/Race.ts +277 -25
- package/templates/racing/src/state.ts +35 -0
- package/templates/racing/src/style.css +3 -0
- package/templates/racing/src/track/Track.ts +132 -58
- package/templates/racing/src/track/TrackSector.ts +19 -1
- package/templates/racing/src/track/circuit.ts +21 -15
- package/templates/racing/src/ui/GameUi.tsx +0 -2
- package/templates/racing/src/ui/Hud.tsx +417 -50
- package/templates/racing/threenative.config.ts +15 -0
- package/templates/racing/tools/make-racing-audio.mjs +388 -0
- package/templates/rain/package.json +6 -6
- package/templates/rain/src/render/noise-volume.ts +2 -1
- package/templates/rain/src/state.ts +3 -1
- package/templates/rain/src/ui/GameUi.tsx +1 -1
- package/templates/rain/src/ui/automation.ts +10 -8
- package/templates/rain/src/ui/tempest.ts +3 -4
- package/templates/rts/package.json +6 -6
- package/templates/rts/src/sim/terrain.ts +1 -0
- package/templates/rts/src/sim/types.ts +1 -0
- package/templates/runner/package.json +7 -7
- package/templates/runner/src/render/clouds.ts +3 -1
- package/templates/runner/src/render/materials.ts +3 -2
- package/templates/runner/src/render/touch-controls.ts +7 -6
- package/templates/runner/src/scenes/Run.ts +4 -9
- package/templates/sailing/package.json +7 -7
- package/templates/sailing/src/render/touch-controls.ts +7 -6
- package/templates/shooter/package.json +7 -7
- package/templates/shooter/src/render/clouds.ts +3 -1
- package/templates/snow/package.json +7 -7
- package/templates/snow/src/entities/Explorer.ts +6 -12
- package/templates/snow/src/render/bootPrint.ts +3 -1
- package/templates/snow/src/render/camera.ts +3 -2
- package/templates/snow/src/render/scenery.ts +3 -3
- package/templates/snow/src/render/touch-controls.ts +7 -6
- package/templates/snow/src/render/weather.ts +3 -5
- package/templates/snow/src/terrain.ts +2 -1
- package/templates/starter/native-playtests/render-chain.playtest.json +9 -9
- package/templates/starter/package.json +7 -7
- package/templates/starter/src/entities/Player.ts +10 -2
- package/templates/starter/src/render/camera.ts +2 -2
- package/templates/starter/src/render/clouds.ts +3 -1
- package/templates/starter/src/render/materials.ts +3 -2
- package/templates/starter/src/render/touch-controls.ts +7 -6
- package/templates/starter/src/scenes/Play.ts +1 -14
- package/templates/tower-defense/package.json +7 -7
- package/templates/tower-defense/src/render/shapes.ts +1 -2
- package/templates/tower-defense/src/scenes/Battle.ts +3 -8
- package/template-assets/terrain/alpine/assets.json +0 -12
- package/template-assets/terrain/alpine/bake.mjs +0 -6
- package/template-assets/terrain/alpine/credits.json +0 -164
- package/template-assets/terrain/alpine/heightmap.r16 +0 -0
- package/template-assets/terrain/alpine/recipe.json +0 -119
- package/template-assets/terrain/alpine/surface.json +0 -53
- package/template-assets/terrain/coastal/assets.json +0 -11
- package/template-assets/terrain/coastal/bake.mjs +0 -6
- package/template-assets/terrain/coastal/credits.json +0 -117
- package/template-assets/terrain/coastal/heightmap.r16 +0 -0
- package/template-assets/terrain/coastal/recipe.json +0 -113
- package/template-assets/terrain/coastal/surface.json +0 -41
- package/template-assets/terrain/desert/assets.json +0 -12
- package/template-assets/terrain/desert/bake.mjs +0 -6
- package/template-assets/terrain/desert/credits.json +0 -164
- package/template-assets/terrain/desert/heightmap.r16 +0 -0
- package/template-assets/terrain/desert/recipe.json +0 -108
- package/template-assets/terrain/desert/surface.json +0 -54
- package/template-assets/terrain/forest/assets.json +0 -65
- package/template-assets/terrain/forest/bake.mjs +0 -8
- package/template-assets/terrain/forest/credits.json +0 -225
- package/template-assets/terrain/forest/heightmap.r16 +0 -0
- package/template-assets/terrain/forest/recipe.json +0 -350
- package/template-assets/terrain/forest/surface.json +0 -79
- package/template-assets/terrain/tundra/assets.json +0 -12
- package/template-assets/terrain/tundra/bake.mjs +0 -6
- package/template-assets/terrain/tundra/credits.json +0 -164
- package/template-assets/terrain/tundra/heightmap.r16 +0 -0
- package/template-assets/terrain/tundra/recipe.json +0 -277
- package/template-assets/terrain/tundra/surface.json +0 -54
- package/templates/racing/src/ui/Menu.tsx +0 -7
|
@@ -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/procedural-animals`, `@threenative/raw-unreal`, `@threenative/terrain`, `@threenative/ueformat`, `@threenative/ui`, `template:rain`, `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/procedural-animals`, `@threenative/procedural-vegetation`, `@threenative/raw-unreal`, `@threenative/terrain`, `@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.
|
|
@@ -1117,6 +1117,22 @@ import { debugFlag } from "@threenative/core";
|
|
|
1117
1117
|
if (debugFlag("freeCam")) camera.flyMode = true;
|
|
1118
1118
|
```
|
|
1119
1119
|
|
|
1120
|
+
### `debugValue`
|
|
1121
|
+
|
|
1122
|
+
`function` — Read the text a debug switch was given by the launch, on the same rule as `debugFlag`.
|
|
1123
|
+
|
|
1124
|
+
```ts
|
|
1125
|
+
export function debugValue(name: string): string | undefined { … }
|
|
1126
|
+
```
|
|
1127
|
+
|
|
1128
|
+
- **Use when:** read a debug override whose value is not a boolean · override a quality tier or a mode for one run without changing the code
|
|
1129
|
+
- **Constraints:** the same name rule as `debugFlag`: `?quality=` on the web, `TN_DEBUG_QUALITY` on a native launch · a name in camelCase becomes UPPER_SNAKE: `debugValue("quality")` reads `?quality=` or `TN_DEBUG_QUALITY`
|
|
1130
|
+
|
|
1131
|
+
```ts
|
|
1132
|
+
import { debugValue } from "@threenative/core";
|
|
1133
|
+
const tier = debugValue("quality");
|
|
1134
|
+
```
|
|
1135
|
+
|
|
1120
1136
|
### `defineGame`
|
|
1121
1137
|
|
|
1122
1138
|
`function` — Define the portable game entry shared by web and native.
|
|
@@ -1606,6 +1622,25 @@ export class GPUSceneBVH extends Group implements IComputeDriven { … }
|
|
|
1606
1622
|
const bvh = ctx.add(new GPUSceneBVH(ctx.scene, { include: (object) => object.userData.traceable === true }));
|
|
1607
1623
|
```
|
|
1608
1624
|
|
|
1625
|
+
### `GrassField3D`
|
|
1626
|
+
|
|
1627
|
+
`class` — Stream instanced grass in chunks around the camera; the game owns the blade and its TSL material.
|
|
1628
|
+
|
|
1629
|
+
```ts
|
|
1630
|
+
export class GrassField3D extends Group { … }
|
|
1631
|
+
```
|
|
1632
|
+
|
|
1633
|
+
- **Use when:** grass that sways and parts around the player · a meadow, lawn or grassy field over terrain that streams around the camera · ground cover grass blades with distance thinning and LOD that does not pop · grass flattened or pushed aside where the player, a creature or a vehicle walks · grow grass on a terrain biome's grass rows with grassFieldFromBiome · Grass that sways and parts around the player across a large terrain. · Stream instanced ground cover in chunks around the camera under a frame budget. · Meadow, lawn or field grass with distance thinning and LOD that does not pop.
|
|
1634
|
+
- **Constraints:** call `update(camera)` once per rendered frame from `ctx.beforeRender`; chunks build nearest first inside `buildBudgetMs` · the material reads `GRASS_FIELD_ATTRIBUTES` and the field's `nodes` uniforms, so its thinning matches the CPU trim · a chunk is built inside 1.3 × the draw distance and discarded past 1.4 ×, so a camera on the edge rebuilds nothing · Call `update(camera)` once per rendered frame, from `ctx.beforeRender`. · Rotating or scaling the field is not supported; translating it is.
|
|
1635
|
+
- **Overrides:** densityScale and cullDistanceScale scale every density and distance at once; prewarm() builds all in range on the next update
|
|
1636
|
+
|
|
1637
|
+
```ts
|
|
1638
|
+
// the look lives in the kit's src/render/grass.ts
|
|
1639
|
+
const grass = new GrassField3D({ blade: grassBlade(), material: grassMaterial, getHeight: height });
|
|
1640
|
+
ctx.add(grass);
|
|
1641
|
+
ctx.beforeRender(() => { grass.pushers[0]?.set(hero.x, hero.y, hero.z, 1.2); grass.update(ctx.camera); });
|
|
1642
|
+
```
|
|
1643
|
+
|
|
1609
1644
|
### `GroundSnap`
|
|
1610
1645
|
|
|
1611
1646
|
`class` — Keep a rendered model's feet on a surface while preserving an auditable override.
|
|
@@ -2562,6 +2597,24 @@ ripples.advance(dt);
|
|
|
2562
2597
|
const lift = ripples.heightAt(boat.x, boat.z);
|
|
2563
2598
|
```
|
|
2564
2599
|
|
|
2600
|
+
### `ScatterField3D`
|
|
2601
|
+
|
|
2602
|
+
`class` — Stream instanced copies of any baked mesh around a follow point, with distance thinning and levels of detail, from the game's own placement rule.
|
|
2603
|
+
|
|
2604
|
+
```ts
|
|
2605
|
+
export class ScatterField3D extends Group { … }
|
|
2606
|
+
```
|
|
2607
|
+
|
|
2608
|
+
- **Use when:** scatter fallen logs, twigs, leaf litter, stones and ferns over a forest floor · stream instanced props of any baked mesh round the player without one draw per prop · place rocks, debris or plants on a heightfield with distance thinning and level of detail
|
|
2609
|
+
- **Constraints:** call `update(follow)` once per rendered frame · `place` runs once per candidate per tile build: return false for paths and clearings · rotating or scaling the field is not supported; translating it is
|
|
2610
|
+
- **Requires:** npm i -D @threenative/procedural-vegetation for the bake these instances come from
|
|
2611
|
+
|
|
2612
|
+
```ts
|
|
2613
|
+
const floor = new ScatterField3D({ parts: [{ lods, material }], getHeight, density: 0.05, place });
|
|
2614
|
+
ctx.add(floor);
|
|
2615
|
+
ctx.beforeRender(() => floor.update(hero.position));
|
|
2616
|
+
```
|
|
2617
|
+
|
|
2565
2618
|
### `Scene`
|
|
2566
2619
|
|
|
2567
2620
|
`class` — Implement a portable Godot-shaped game scene lifecycle.
|
|
@@ -2624,6 +2677,24 @@ const door = { y: 0 };
|
|
|
2624
2677
|
await ctx.tween(door, { y: 2.4 }, 0.5, { ease: (t) => 1 - (1 - t) ** 3 });
|
|
2625
2678
|
```
|
|
2626
2679
|
|
|
2680
|
+
### `ScreenProbeGather`
|
|
2681
|
+
|
|
2682
|
+
`class` — Lumen's Screen Probe Gather: one probe per 16 x 16 pixels traces an 8 x 8 octahedron of rays, the probes are filtered into an irradiance octahedron each, and a pixel blends the four nearest probes it can see, instead of every pixel tracing its own rays. A ray that hits on screen returns the lit frame minus the cache along it; a ray that leaves the screen continues through the packed scene up to the radiance cache's cell and reads the cache where it ended, so the light that arrives from off screen is that direction's and not the pixel's mean.
|
|
2683
|
+
|
|
2684
|
+
```ts
|
|
2685
|
+
export class ScreenProbeGather { … }
|
|
2686
|
+
```
|
|
2687
|
+
|
|
2688
|
+
- **Use when:** bounce light that reads the room off screen instead of a flat ambient term · global illumination that costs a fraction of one ray per pixel · the light a corner sees from around the wall, which a per-pixel screen trace loses · lumen screen probe gather · lumen final gather
|
|
2689
|
+
- **Constraints:** the owned engine only: on engine: "threejs" the upstream node takes the camera as its fourth argument and has no probes, and gather() refuses · the gather is a delta in E / pi: multiply it by the receiver's diffuse colour (mrt({ diffuseColor })) and add it after the scene pass, and give the scene pass no other indirect diffuse or the light is counted twice · a viewport resize needs a new gather: the probe grid is fixed when it is built · the grid is the cost: downsampleFactor 16 and an 8 x 8 octahedron are Unreal's Epic, 32 and 8 its High · radiance answers in the frame's units (the cache read times the frame's gain), and a trace reads it only where the screen has nothing
|
|
2690
|
+
- **Overrides:** downsampleFactor, tracingOctahedronResolution, cacheCellSize, timedPass and the strength of the composite are game-owned choices
|
|
2691
|
+
|
|
2692
|
+
```ts
|
|
2693
|
+
const gather = new ScreenProbeGather({ camera, viewport, radiance, trace });
|
|
2694
|
+
const gi = gather.gather(convertToTexture(input), depth(), normalView());
|
|
2695
|
+
const bounce = gather.getGINode().rgb.mul(diffuseColor.rgb);
|
|
2696
|
+
```
|
|
2697
|
+
|
|
2627
2698
|
### `setAttitude`
|
|
2628
2699
|
|
|
2629
2700
|
`function` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
|
|
@@ -2672,6 +2743,24 @@ const filter = new ShadowFilterBudget({ tier: "high", framePeriodMs: 1000 / 60,
|
|
|
2672
2743
|
ctx.beforeRender(() => filter.observeRenderer(ctx.renderer.raw));
|
|
2673
2744
|
```
|
|
2674
2745
|
|
|
2746
|
+
### `ShortRangeAO`
|
|
2747
|
+
|
|
2748
|
+
`class` — Unreal's Short Range AO: a horizon search of 2 sweeps around the view normal, 3 samples each at the squared fraction of a 32 px screen reach, at full resolution, with a bent normal at Epic. It is the occlusion that runs *with* dynamic global illumination — the contact detail Lumen keeps after the screen probe gather has already answered the wide occlusion — so a gathered frame is not darkened twice by two wide treatments. The result is one texture: `rgb` the bent normal in view space, `a` the share of the hemisphere left open, which multiplies indirect light only.
|
|
2749
|
+
|
|
2750
|
+
```ts
|
|
2751
|
+
export class ShortRangeAO { … }
|
|
2752
|
+
```
|
|
2753
|
+
|
|
2754
|
+
- **Use when:** contact shadow at the foot of an object while dynamic GI runs · dark line where a wall meets the floor, without a second wide AO over the gathered light · lumen short range ao
|
|
2755
|
+
- **Constraints:** it replaces GTAO when dynamic GI runs; a tier without GI keeps ambientOcclusion · the occlusion multiplies indirect light only: direct light and emission keep their own occlusion · multi-bounce and its albedo cap belong to the game's composite; Unreal caps the albedo at 0.5 · an authored stage that carries its name must anchor itself (`before: "ssgi"`), because the chain's built-in order names no shortRangeAO
|
|
2756
|
+
- **Overrides:** horizonSearchSliceCount, horizonSearchStepCount, reachPx, bentNormal and intensity are game-owned choices
|
|
2757
|
+
|
|
2758
|
+
```ts
|
|
2759
|
+
const shortRange = new ShortRangeAO({ camera, viewport: renderer.drawingBufferSize });
|
|
2760
|
+
const contact = shortRange.occlusion(depth(), normalView());
|
|
2761
|
+
const indirect = input.rgb.mul(contact.a);
|
|
2762
|
+
```
|
|
2763
|
+
|
|
2675
2764
|
### `SkeletalMesh3D`
|
|
2676
2765
|
|
|
2677
2766
|
`class` — Shared preparation for an imported rigged character. Instances the rig with a skeleton-safe clone, normalises size with skin-aware measurement, validates requested clips against the file and rig at load time, and sets up AnimationPlayer with honest stride-root accounting. Animation evaluation inherits AnimationPlayer's automatic camera-based `updateRate: "auto"` default; `updateRate: 1` evaluates every frame, another positive safe integer requests that interval, and `updateRateReport` exposes the effective rate, override status and latest result. One-shots and fades stay full-rate; root-motion `AnimationComposer` advances every tick, and auto camera-ray targets and camera-parented rigs stay full-rate. A public `mixer` `"loop"` listener promotes effective evaluation to 1 and observes only loop events after registration, so skipped pre-registration cycles are not replayed.
|
|
@@ -4237,13 +4326,13 @@ const reach = lakeReach(field, { ...lake, margin: 1.12 });
|
|
|
4237
4326
|
|
|
4238
4327
|
### `lakeSurfaceGeometry`
|
|
4239
4328
|
|
|
4240
|
-
`function` — A lake's water surface: a level disc out to `lakeReach`, the footprint `WaterBodies` floods, with a `metres` attribute (water depth over the ground). Only cells with
|
|
4329
|
+
`function` — A lake's water surface: a level disc out to `lakeReach`, the footprint `WaterBodies` floods, with a `metres` attribute (water depth over the ground). Only cells with a corner the seed's water reaches get triangles, so the surface does not hover over dry hillside, a hollow past the basin's rim (a river valley beyond the dam) stays dry instead of standing under a sheet that stops where the reach does, and the shore follows the ground's contour. The rings pack towards the middle, so an irregular basin costs vertices where the camera sees them. Returns `undefined` when the basin holds no water at its level.
|
|
4241
4330
|
|
|
4242
4331
|
```ts
|
|
4243
4332
|
export function lakeSurfaceGeometry( lake: IWaterLake, field: Heightfield, options: ILakeSurfaceOptions = { … }
|
|
4244
4333
|
```
|
|
4245
4334
|
|
|
4246
|
-
- **Use when:** draw a lake's water surface from the baked level and seed · a lake's drawn water and the swimmer's water disagree
|
|
4335
|
+
- **Use when:** draw a lake's water surface from the baked level and seed · a lake's drawn water and the swimmer's water disagree · lake water ends in a straight edge over a valley past the basin's rim
|
|
4247
4336
|
- **Constraints:** the lake row and field come from the game's bake; the game's material shades the geometry
|
|
4248
4337
|
|
|
4249
4338
|
```ts
|
|
@@ -4543,7 +4632,7 @@ export class WorldCells extends Group implements IComputeDriven { … }
|
|
|
4543
4632
|
|
|
4544
4633
|
- **Use when:** stream a large Blender-authored world by cell instead of one huge GLB · keep scattered props and hand-placed chunks resident around a moving player · honour per-asset draw distances and hard streaming budgets without a mid-frame throw
|
|
4545
4634
|
- **Constraints:** surface is the game's; this class creates no material, colour or geometry · a cell's model loads at `soon` priority, so a file the running scene awaits through `ctx.assets` starts first · budgets are hard caps that report pressure instead of over-committing · `whenSpawnReady(position, radius, timeoutMs)` snapshots a fixed region and settles from existing updates or disposal; it does not drive streaming, and `prewarmed` remains the separate draw gate · model loads are bounded by `concurrency` (default 12) across every resident cell, not per cell · refilters are bounded by `rebuildsPerUpdate` (default 16) per update, nearest cell first · residency and `placementReach` follow `follow`; levels and `maxDistance` are graded from the render camera, as UE picks instance LODs per view; `lodFrom: "follow"`, `?tnLodFromCamera=0` or `TN_LOD_FROM_CAMERA=0` grade from `follow`, reported as `TN_WORLD_MAIN_CULL lodFrom=` · admission is bounded by `admissionBudgetMs` (default 2) per update across every path, plus at most one unit each for terrain and props; while props are queued terrain takes at most half, so neither starves the other, and a deferred cell keeps drawing what it has · SkinnedMesh parts are skipped; an instanced copy would draw one rest pose · a baked chain's switch distances are measured against `autoLod` (default 4 px of error over 60° and 1080 raster rows), because an instanced draw cannot select a level per instance; an asset with nonempty authored `lods` never consults it; explicit empty lists enroll only unchanged static geometry/material parts · eligible static sources can use cooked HLOD (chunk-only alongside GPU scatter, whole-cell on CPU) after compilation and an observed main-context backend submission; projected-error hysteresis requires actual source triangle reduction and no extra material draws, unsupported or shared source stays resident, and collision/shadow paths retain source representations; stats().hlod counts lifecycle and charged resources, not GPU timing or physical allocation · `prewarmed` resolves once every prewarmed shared batch has been drawn; a game with a loading screen waits on it, and `stats().pendingPrewarm` is the same gate as a number · every `asset:level:part` is one InstancedMesh for the main pass, plus one caster InstancedMesh per world-grid square of `clusterSize` on the shadow caster layer, so the main pass draws one mesh per key and a shadow level submits only the squares it covers · two definitions the asset loader resolves to one model — the same cooked `glb`, the same `lods` at the same distances, the same `maxDistance` and bounds — are one asset under the lexicographically smallest id: one model load, one set of `asset:level:part` keys, one prewarm and one refcount, released when the last cell holding any member of the group leaves the ring; `TN_WORLD_ASSET_ALIAS` reports how many of the package's assets are really distinct · the main pass mesh draws only the squares the render camera's frustum covers — on by default, narrowed once per frame for every main batch by the engine's render-cadence dispatch, never for an orthographic camera — a batch with nothing to draw is hidden rather than submitted at `count 0`, and `TN_WORLD_MAIN_CULL` reports both every five seconds · a loaded chunk is merged by material before it is added, so it submits one draw per material rather than one per node; a skinned, multi-material or morph-target mesh, one carrying a baked AutoLOD chain, and an instanced mesh past `chunkMergeMaxTriangles` (default 43,690 triangles) or with a shape over 2,048 triangles, all keep their own geometry; a material group crossing 131,072 vertices (4 MiB of position + normal + uv) is split into several meshes in traversal order instead of one giant upload, indexed parts keep their index, and `TN_WORLD_CHUNK_MERGE` reports what the merge did and the bytes it left · `shadows.castDistance` is accepted and ignored (clusters replaced it); `shadows.invalidate` is called at most once a second after streamed records changed
|
|
4546
|
-
- **Overrides:** `hlod: false` keeps source rendering; ring, budgets, terrain tile size/resolution, terrain stream and collider radius, `transparentScatter`, `clusterSize` and `shadows.invalidate`, load `concurrency`, `rebuildsPerUpdate`, `admissionBudgetMs` and the package's per-asset maxDistance; `impostorFar: "always"` keeps the far aggregate the near ring's guaranteed radius made unnecessary
|
|
4635
|
+
- **Overrides:** `hlod: false` keeps source rendering; `partMaterial` gives a part the game's own surface (a swaying tree); ring, budgets, terrain tile size/resolution, terrain stream and collider radius, `transparentScatter`, `clusterSize` and `shadows.invalidate`, load `concurrency`, `rebuildsPerUpdate`, `admissionBudgetMs` and the package's per-asset maxDistance; `impostorFar: "always"` keeps the far aggregate the near ring's guaranteed radius made unnecessary
|
|
4547
4636
|
|
|
4548
4637
|
```ts
|
|
4549
4638
|
const world = await WorldCells.load({ url: "/world/world.json", surface, follow, ring: 1, budgets: { residentCells: 25, instances: 20000, bytes: 8000000 } });
|
|
@@ -6733,6 +6822,41 @@ export async function bakeWolfToFile( options: IWolfBakeOptions, destination: st
|
|
|
6733
6822
|
await bakeWolfToFile({ seed: 7, tier: "crowd" }, "assets/wolf-crowd.animal");
|
|
6734
6823
|
```
|
|
6735
6824
|
|
|
6825
|
+
## `@threenative/procedural-vegetation`
|
|
6826
|
+
|
|
6827
|
+
### `bakeVegetation`
|
|
6828
|
+
|
|
6829
|
+
`function` — Bake a procedural tree (Arbor) to GLBs, one per level of detail, ready for ctx.assets.model. Each GLB carries the _WIND vertex attribute, COLOR_0 and TEXCOORD_0; the Arbor presets also embed their bark and leaf textures with alpha-masked leaves, while forest-kit debris and cover shade from COLOR_0 alone.
|
|
6830
|
+
|
|
6831
|
+
```ts
|
|
6832
|
+
export async function bakeVegetation(options: IBakeVegetationOptions): Promise<IVegetationBake[]> { … }
|
|
6833
|
+
```
|
|
6834
|
+
|
|
6835
|
+
- **Use when:** generate a procedural tree, an oak, pine, spruce, palm or any forest species as a GLB · procedural oak tree GLB with level of detail for a game forest · tree GLB for Unity, Unreal or Godot, with wind weights in a _WIND attribute · a fallen mossy log and leaf litter on the forest floor, with a stump, twigs and boulders · reeds and cattails at a pond edge, or sedge tussocks, clover and seeding grass as cover
|
|
6836
|
+
- **Constraints:** fails closed: an unknown preset throws naming the nearest ids, the seed must be an integer and each lod 0 to 2 · the same preset, seed and lods write identical bytes; files are written atomically (temporary file, then rename) · bake-time only, so keep it a dev dependency; the game owns the look and the sway (a TSL render/wind.ts reading _WIND), because Arbor.three is not shipped · _WIND is vec4 (trunk sway, branch sway, flutter, phase): forest-kit sway is flutter in z, and debris writes all four zero · form and leafImage patch an Arbor preset only; a forest-kit debris or cover preset throws when given either
|
|
6837
|
+
- **Requires:** npm i -D @threenative/procedural-vegetation
|
|
6838
|
+
|
|
6839
|
+
```ts
|
|
6840
|
+
await bakeVegetation({ preset: "oak", seed: 7, lods: [0, 1], out: "assets/trees" });
|
|
6841
|
+
await bakeVegetation({ preset: "log", seed: 3, out: "assets/debris" });
|
|
6842
|
+
```
|
|
6843
|
+
|
|
6844
|
+
### `vegetationPresets`
|
|
6845
|
+
|
|
6846
|
+
`function` — List every preset a bake can grow: id, name, latin name and kind. Trees and cover come from Arbor; the `debris` rows (log, stump, twig, branch, leaflitter, rock) and the extra cover rows (reeds, tussock, seedgrass, clover, dock, plume) come from forest-kit.
|
|
6847
|
+
|
|
6848
|
+
```ts
|
|
6849
|
+
export function vegetationPresets(): IVegetationPreset[] { … }
|
|
6850
|
+
```
|
|
6851
|
+
|
|
6852
|
+
- **Use when:** list the oak, pine, spruce, palm and other tree species a bake can grow · choose a tree species id for bakeVegetation or a terrain arbor: species · what deadwood, leaf litter, boulders, reeds and tussocks can I bake for a forest floor
|
|
6853
|
+
- **Constraints:** ids come from the vendored Arbor and forest-kit presets; trees are kind "tree", grass, ferns and flowers are kind "cover", deadwood, litter and stone are kind "debris"
|
|
6854
|
+
- **Requires:** npm i -D @threenative/procedural-vegetation
|
|
6855
|
+
|
|
6856
|
+
```ts
|
|
6857
|
+
vegetationPresets().filter((p) => p.kind === "debris").map((p) => p.id);
|
|
6858
|
+
```
|
|
6859
|
+
|
|
6736
6860
|
## `@threenative/raw-unreal`
|
|
6737
6861
|
|
|
6738
6862
|
### `createThreeGeometry`
|
|
@@ -7433,6 +7557,23 @@ export function gradientAt(grid: ISampledGrid, x: number, z: number): [number, n
|
|
|
7433
7557
|
const gradient = gradientAt(new Terrain({ resolution: 17 }).evaluate(), 0, 0);
|
|
7434
7558
|
```
|
|
7435
7559
|
|
|
7560
|
+
### `grassFieldFromBiome`
|
|
7561
|
+
|
|
7562
|
+
`function` — Turns a terrain biome's grass rows and its ground into `GrassField3D` placement options, so a generated or cooked world grows streamed grass with one call. Returns null when the biome has no grass rows: the game draws no field. Each row covers its own slope band (full to `slope[1]`, gone `slopeFalloff` degrees past it), its own height band above `ground.floor` (fading over `heightFalloff` below the ceiling) and stays `waterMargin` above `ground.waterLevel`; the field takes the strongest row at each spot.
|
|
7563
|
+
|
|
7564
|
+
```ts
|
|
7565
|
+
export function grassFieldFromBiome( biome: Pick<IBiomeSpec, "grass" | "seed">, ground: IGrassGround, ): IGrassFieldPlacement | null { … }
|
|
7566
|
+
```
|
|
7567
|
+
|
|
7568
|
+
- **Use when:** grow streamed grass on a terrain world's biome grass rows · a Strata or terrain_generate world with a meadow that sways round the player · feed a cooked biome to GrassField3D
|
|
7569
|
+
- **Constraints:** the look stays the game's: pass the result with the kit's `render/grass.ts` blade and material
|
|
7570
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7571
|
+
|
|
7572
|
+
```ts
|
|
7573
|
+
const placement = grassFieldFromBiome(biome, { heightAt: (x, z) => field.heightAt(x, z), waterLevel: 0 });
|
|
7574
|
+
if (placement) ctx.add(new GrassField3D({ ...placement, blade: grassBlade(), material: grassMaterial }));
|
|
7575
|
+
```
|
|
7576
|
+
|
|
7436
7577
|
### `landform`
|
|
7437
7578
|
|
|
7438
7579
|
`function` — One call, one landscape: a calibrated layer recipe for a kind of environment.
|
|
@@ -8593,6 +8734,24 @@ export function useUiStateDuringStartup<TState extends object>(options: { … }
|
|
|
8593
8734
|
const loading = useUiStateDuringStartup<GameState, number>({ reason: "staged loading overlay" }, (state) => state.loading.progress);
|
|
8594
8735
|
```
|
|
8595
8736
|
|
|
8737
|
+
## `src/assets.ts`
|
|
8738
|
+
|
|
8739
|
+
### `ctx.assets.memo`
|
|
8740
|
+
|
|
8741
|
+
`function` — Returns what `build` returned the last time this build of the game ran, read back from disk, and calls `build` only when nothing is stored. Use it for seeded work that is the same every run: placement lists, painted sky pixels, terrain heights, a generated stage.
|
|
8742
|
+
|
|
8743
|
+
```ts
|
|
8744
|
+
ctx.assets.memo<T>(key: string, build: () => T | Promise<T>): Promise<T>
|
|
8745
|
+
```
|
|
8746
|
+
|
|
8747
|
+
- **Use when:** cache generated geometry between page loads · stop rebuilding the same generated stage on every page load · cache painted sky pixels or baked terrain heights between runs · keep seeded placement work the same every run without recomputing it · make a slow boot fast without shipping a baked asset
|
|
8748
|
+
- **Constraints:** The value is named typed arrays; a map of names to typed arrays is what is stored. · On the dev server and on a native host `build` runs every time, and `TN_ASSET_MEMO` reports why: the cache is a build artifact, not a substitute for authoring. · A new build of the game regenerates: the key alone does not pin a value across a rebuild. · A game that drives a loader outside `defineGame` may call it whenever it likes; the reveal is not waited on.
|
|
8749
|
+
- **Overrides:** TN_ASSET_MEMO reports why a run rebuilt instead of reading the store
|
|
8750
|
+
|
|
8751
|
+
```ts
|
|
8752
|
+
const { pixels } = await ctx.assets.memo("sky", () => ({ pixels: paintSky() }));
|
|
8753
|
+
```
|
|
8754
|
+
|
|
8596
8755
|
## `src/audio/storm.ts`
|
|
8597
8756
|
|
|
8598
8757
|
### `createStormAudio`
|
|
@@ -8728,6 +8887,55 @@ createWeatherWorld(scene: Scene, camera: PerspectiveCamera): IWeatherWorld
|
|
|
8728
8887
|
src/render/world.ts — edit the shader there, or the weather it is fed from src/state.ts
|
|
8729
8888
|
```
|
|
8730
8889
|
|
|
8890
|
+
## `src/scene.ts`
|
|
8891
|
+
|
|
8892
|
+
### `ctx.after`
|
|
8893
|
+
|
|
8894
|
+
`function` — Runs `callback` once, `delay` seconds of game time later, and returns a handle that cancels it. Game time stops while the game is paused, so a delayed beat does not fire behind a paused frame.
|
|
8895
|
+
|
|
8896
|
+
```ts
|
|
8897
|
+
ctx.after(delay: number, callback: () => void): ScheduleHandle
|
|
8898
|
+
```
|
|
8899
|
+
|
|
8900
|
+
- **Use when:** run a callback after a delay · schedule a one-shot timer that pauses with the game · do something a moment later without setTimeout · cancel a pending delayed action when a scene exits
|
|
8901
|
+
- **Constraints:** The delay is game seconds: a paused game does not age it, and a slow frame does not skip it. · `setTimeout` keeps running while the game is paused and after the scene is gone; this does not. · Call the returned handle to cancel: a pending callback holds its scene's closure alive.
|
|
8902
|
+
|
|
8903
|
+
```ts
|
|
8904
|
+
const spawn = ctx.after(0.4, () => ctx.add(makeWave()));
|
|
8905
|
+
spawn(); // cancels
|
|
8906
|
+
```
|
|
8907
|
+
|
|
8908
|
+
### `ctx.beforeRender`
|
|
8909
|
+
|
|
8910
|
+
`function` — Registers work that runs once per actual world render, after the frame's last fixed update and before the projection reconciles and the renderer draws. The last place to change a transform, a uniform or a camera before the frame is presented.
|
|
8911
|
+
|
|
8912
|
+
```ts
|
|
8913
|
+
ctx.beforeRender(callback: () => void): () => void
|
|
8914
|
+
```
|
|
8915
|
+
|
|
8916
|
+
- **Use when:** run a callback just before the frame renders · update a camera or a uniform after physics and before the draw · change a transform in the same frame it is seen · run per-render work that must not run on a loader-only frame
|
|
8917
|
+
- **Constraints:** A held, loader-only frame has no world draw and dispatches nothing. · Runs after every fixed update in the frame, so a value it writes is the one drawn. · Returns an unregister function; call it when the object that needed it is gone.
|
|
8918
|
+
|
|
8919
|
+
```ts
|
|
8920
|
+
const stop = ctx.beforeRender(() => (material.uniforms.time.value = clock.elapsed));
|
|
8921
|
+
// later: stop();
|
|
8922
|
+
```
|
|
8923
|
+
|
|
8924
|
+
### `ctx.startup.progress`
|
|
8925
|
+
|
|
8926
|
+
`function` — How much of the start scene has loaded and presented, 0 to 1, for a loading cover's bar. It never falls: a loader whose pending work grows keeps the number it reached rather than jumping backwards.
|
|
8927
|
+
|
|
8928
|
+
```ts
|
|
8929
|
+
ctx.startup.progress: number
|
|
8930
|
+
```
|
|
8931
|
+
|
|
8932
|
+
- **Use when:** boot progress bar · show how much of the start scene has loaded · loading screen percentage · a progress bar that never goes backwards · report startup progress while assets stream in
|
|
8933
|
+
- **Constraints:** Never decreases, even when the loader is asked for more work mid-boot. · Reaches 1 only after the first world render has been presented, not when the last byte arrived. · A loading view the engine drew for you already reads it; this is for a cover the game draws itself.
|
|
8934
|
+
|
|
8935
|
+
```ts
|
|
8936
|
+
const width = `${Math.round(ctx.startup.progress * 100)}%`; // a cover the game draws on ctx.canvasLayer
|
|
8937
|
+
```
|
|
8938
|
+
|
|
8731
8939
|
## `three/addons/tsl/display/BloomNode.js`
|
|
8732
8940
|
|
|
8733
8941
|
### `bloom`
|
|
@@ -14,7 +14,7 @@ This repository owns the car feel, track, race rules, rescue, HUD, and look; `sr
|
|
|
14
14
|
|
|
15
15
|
## Commands and map
|
|
16
16
|
|
|
17
|
-
`src/track/Track.ts` owns the circuit, its collision layers and the grid; `Lap.ts` orders `Area3D` gates and counts a lap on the car's **measured** travel direction; `TrackSector.ts` ray-probes the road and rescues from it; `Ranking.ts` ranks route progress. `src/entities/CarBody.ts` builds the one chassis both cars drive — a `VehicleBody3D` whose wheels are read off the four **named** wheel groups in `shapes.ts`. `RacingCar.ts` turns input into `engineForce` / `brake` / `steering` and nothing else; `Rival.ts` is that same car under a pure-pursuit controller
|
|
17
|
+
`src/track/Track.ts` owns the circuit, its collision layers and the grid; `Lap.ts` orders `Area3D` gates and counts a lap on the car's **measured** travel direction; `TrackSector.ts` ray-probes the road and rescues from it; `Ranking.ts` ranks route progress. `src/entities/CarBody.ts` builds the one chassis both cars drive — a `VehicleBody3D` whose wheels are read off the four **named** wheel groups in `shapes.ts`. `RacingCar.ts` turns input into `engineForce` / `brake` / `steering` and nothing else; `Rival.ts` is that same car under a pure-pursuit controller, five of them on a staggered six-car grid (`GRID_SLOTS` in `circuit.ts`), each at its own constant pace from `RIVALS`, the player last. `Drift.ts` is the drift: Shift with the wheel turned at speed kicks the tail out, full lock above `DRIFT.looseSpeed` lets it go by itself, and both lower the rear grip through `VehicleBody3D.setWheelFrictionSlip`. `Nitro.ts` is the tank Space burns, filled by driving and about four times faster by drifting. `gauges.ts` is the gearbox readout — six bands, and Need for Speed: Most Wanted's capped needle fall with a 55/45 blend — and `audio/engine.ts` is the car's sound over one `AudioBus`: the bed pitched from that needle, the tyre squeal opened by the slip angle, a burst on the nitro button. Controls: WASD or arrows drive, Shift drifts and brakes, Space is nitro, P is the autopilot, R restarts. Keep `playtests/survives.playtest.json` as the smoke proof, and on a touch device `src/render/touch-controls.ts` adds the stick and buttons.
|
|
18
18
|
|
|
19
19
|
**Two things about the vehicle are invisible in the API.** `suspensionStiffness` is a frequency squared, so the strut sags `gravity / (4 * stiffness)` and Godot's default of 20 bottoms it out, and a positive steering angle turns the chassis toward its own `-z` — so the input is negated once and the visual front wheels take that same signed angle. `CarBody.ts` carries every other number.
|
|
20
20
|
|
|
@@ -23,4 +23,6 @@ This repository owns the car feel, track, race rules, rescue, HUD, and look; `sr
|
|
|
23
23
|
|
|
24
24
|
Generated conventions call `normaliseToMetres` for authored vehicle scale; the four `VehicleBody3D` wheels own floor contact, so no car gets `GroundSnap`. `input.vector("move").y` is +up and means throttle, and `+x` is right.
|
|
25
25
|
|
|
26
|
-
`src/render/sky.ts` draws Unreal's default sky (an atmosphere with clouds: `atmosphere.ts`, `clouds.ts`, `gpuSky.ts`) as background, environment light and height-fog colour, and `lighting.ts` tints the sun at `SUN_DIRECTION` by the air it crosses; `SKY_OPTIONS` takes `sky: "photo"` for `assets/sky.jpg` (Poly Haven, CC0) or `clouds: false`, and `ground: false` once the game has its own global illumination (the sunlit ground under the horizon stands in for the bounce). The shared look comes from core through `src/render/quality.ts`: the filmic curve and metered auto exposure are enabled by default. The bridge flushes about 100 ms; keep speed/lap in state and frame feedback in Three.js. Racing keeps its deliberate gather, SSR and sharpening overrides in `quality.ts`: reflected rough tarmac and sharpening produced unstable speckles/bands, and the game retains its 33 ms / 30 FPS budget. The curve and meter stay enabled. The HUD uses the existing opaque `bg-panel` behind race, position, speed/time/
|
|
26
|
+
`src/render/sky.ts` draws Unreal's default sky (an atmosphere with clouds: `atmosphere.ts`, `clouds.ts`, `gpuSky.ts`) as background, environment light and height-fog colour, and `lighting.ts` tints the sun at `SUN_DIRECTION` by the air it crosses; `SKY_OPTIONS` takes `sky: "photo"` for `assets/sky.jpg` (Poly Haven, CC0) or `clouds: false`, and `ground: false` once the game has its own global illumination (the sunlit ground under the horizon stands in for the bounce). The shared look comes from core through `src/render/quality.ts`: the filmic curve and metered auto exposure are enabled by default. The bridge flushes about 100 ms; keep speed/lap in state and frame feedback in Three.js. Racing keeps its deliberate gather, SSR and sharpening overrides in `quality.ts`: reflected rough tarmac and sharpening produced unstable speckles/bands, and the game retains its 33 ms / 30 FPS budget. The curve and meter stay enabled. The HUD uses the existing opaque `bg-panel` behind race, position, speed/time/gear and revs/nitro and outcome text so a brighter road or sky does not erase the readouts; a banked drift's score pops up under it for 1.6 s, keyed on `driftsBanked` so two identical scores in a row still count as two, and counted in **game** seconds by `DRIFT.popupSeconds` — the drift owns that clock and publishes it as `driftPopup`, so a pause freezes the popup instead of ageing it while the car stands still.
|
|
27
|
+
|
|
28
|
+
**Sound is authored, not licensed.** `tools/make-racing-audio.mjs` bakes `assets/engine-loop.wav`, `tyre-squeal.wav` and `nitro-burst.wav` from maths — an engine bed pitched live from 0.62× to 2.05× has to be tonal and exactly periodic, which a recording is not — and `CREDITS.md` records why no downloaded clip fits. Both beds are declared loops with `crossFadeMs: 0` in `threenative.config.ts`, so the asset pass measures their seams and fails the build on a click. One named native gap: the host binds a source's `playbackRate` as a passive parameter, so on native the bed plays at rate 1 with the same volume, squeal and burst. `node tools/make-racing-audio.mjs --check` re-bakes and compares against the committed bytes.
|
|
@@ -134,7 +134,8 @@ change a line.
|
|
|
134
134
|
`pnpm check` runs the strict typecheck, ESLint and a Biome format check, and `pnpm test` runs it
|
|
135
135
|
first. ESLint fails on a floating Promise and on an async callback given to a synchronous slot, and
|
|
136
136
|
it warns when a `new Vector3()`-style math constructor runs directly inside `Scene.update`,
|
|
137
|
-
`Scene.render` or a `ctx.beforeRender`
|
|
137
|
+
`Scene.render`, an entity's `update`/`fixedUpdate`/`tick`/`step` method or a `ctx.beforeRender`
|
|
138
|
+
callback. That warning is a prompt to measure, not a
|
|
138
139
|
finding: reuse an instance the scene owns only if `TN_FRAME_BUDGET` shows allocation pressure.
|
|
139
140
|
It does not follow helper calls, so a quiet result is not proof a frame allocates nothing. A
|
|
140
141
|
suppression needs a reason: `// eslint-disable-next-line <rule> -- <why>`. Lint does not prove a
|
|
@@ -18,13 +18,26 @@ sky, props and colliders. `@threenative/terrain` ships them under `starter/<worl
|
|
|
18
18
|
|
|
19
19
|
```sh
|
|
20
20
|
cp -r node_modules/@threenative/terrain/starter/forest src/terrain/forest
|
|
21
|
-
|
|
21
|
+
npm install --save-dev tsx
|
|
22
|
+
node src/terrain/forest/bake.mjs
|
|
22
23
|
```
|
|
23
24
|
|
|
24
|
-
Then
|
|
25
|
-
|
|
26
|
-
`
|
|
27
|
-
|
|
25
|
+
Then start the game on its scene: `defineGame({ ...FOREST_GAME, plugins: [rapier()], scenes:
|
|
26
|
+
{ forest: ForestScene }, start: "forest" })`, both from `./terrain/forest/scene.js`. The kit's
|
|
27
|
+
`README.md` says what each file decides: the landform in `bake.mjs`, what grows where in
|
|
28
|
+
`biome.data.json`, every art path in `world/terrainAssets.ts`, and the look in `render/biomes.ts`.
|
|
29
|
+
|
|
30
|
+
## Name a region, not just a biome
|
|
31
|
+
|
|
32
|
+
The terrain MCP's `terrain_generate` reads a region word and cooks that region's own world: its real
|
|
33
|
+
ground from a survey, and its plant community — several species, each baked at more than one seed —
|
|
34
|
+
on the starter's own surface, understorey, road and water. The words today are `european` and
|
|
35
|
+
`europe` (a Central European beech wood), `boreal`, `taiga`, `nordic` and `scandinavian`,
|
|
36
|
+
`mediterranean` and `tuscan`, and `pacific northwest` and `cascadia`. The reply's `decided.region`
|
|
37
|
+
names the row behind it, `decided.ground` the survey it stands on with the attribution its source
|
|
38
|
+
requires, and `unused` the words nothing answered to. A tree word in a region request moves that
|
|
39
|
+
species to the front of the canopy and leaves the rest; `kit`, `biome` and `ground` still win over
|
|
40
|
+
the row.
|
|
28
41
|
|
|
29
42
|
## Generate once, play the bake
|
|
30
43
|
|
|
@@ -127,8 +140,9 @@ patches. Editor imports, workers, watchers and the document stay out of the game
|
|
|
127
140
|
runtime. Bake committed data before handing it to the game. The editor's GLB action and
|
|
128
141
|
`prepareWorldGLTF` from `@threenative/terrain/export` prepares the resolved world for
|
|
129
142
|
Node `cookTerrainWorld({ preparedWorld: prepared.json })` from `@threenative/assets` (terrain,
|
|
130
|
-
props, final transforms, embedded PBR maps); the root `encodeGLB` stays terrain-only.
|
|
131
|
-
operation list, units and patch rules ship in
|
|
143
|
+
props, final transforms, embedded PBR maps); the root `encodeGLB` stays terrain-only. Start at
|
|
144
|
+
`node_modules/@threenative/terrain/README.md`; the full operation list, units and patch rules ship in
|
|
145
|
+
`node_modules/@threenative/terrain/docs/authoring/recipes.md`.
|
|
132
146
|
|
|
133
147
|
For individual props, save `placementOverrides` in the authoring document, keyed
|
|
134
148
|
by evaluated placement `id`. Each entry contains `position: [x,y,z]`, a unit
|
|
@@ -29,6 +29,19 @@ and **References**. Each needs a value or explicit `none` with a reason; a blank
|
|
|
29
29
|
section blocks approval. Required texture search/download is step 5, after plan approval;
|
|
30
30
|
record planned asset needs here without claiming assets have already been selected or downloaded.
|
|
31
31
|
|
|
32
|
+
List every asset under **Asset slots** in `.agent/prd/PRD.md`, one row each: name, route, status
|
|
33
|
+
(`placeholder` or `final`), and scale with bounding box. Pick the route per slot:
|
|
34
|
+
|
|
35
|
+
- `procedural` (default): terrain, vegetation, simple or repeated shapes, and every first version.
|
|
36
|
+
- `pre-made`: a generic prop that looks the same in any game, such as a wooden chair. Record its licence.
|
|
37
|
+
- `custom`: an identity asset the player remembers this game by, such as the hero or a signature
|
|
38
|
+
vehicle. It is generated, then cleaned up, rigged and baked before it is `final`.
|
|
39
|
+
|
|
40
|
+
The code loads each slot from one stable path, so a swap replaces the file and leaves gameplay code
|
|
41
|
+
alone. Phase 1 (first playable) uses `procedural` and `pre-made` slots only. Phase 2 (polish) replaces
|
|
42
|
+
identity slots with `custom` ones, one at a time, after the user approves the gameplay or when the
|
|
43
|
+
judge's top gap is a placeholder. The visual judge does not score a `placeholder` slot on its looks.
|
|
44
|
+
|
|
32
45
|
Write the concise plan to `.agent/prd/PRD.md`, its short player-facing summary to
|
|
33
46
|
`.agent/prd/SUMMARY.md`, and implementation tasks to `.agent/tasks.json`. Tasks must be ordered,
|
|
34
47
|
bounded to about 10 minutes each, carry a concrete pass check, and start with `"passes": false`.
|
|
@@ -50,3 +63,14 @@ Start implementation only after explicit approval and a clear execution instruct
|
|
|
50
63
|
"execute", "implement", "build it", or an equivalent phrase. One message may contain both. After
|
|
51
64
|
that handoff, execute the approved tasks without silently expanding the scope; repeat capability
|
|
52
65
|
discovery only when the requested mechanics or target platforms change.
|
|
66
|
+
|
|
67
|
+
## Execution goal
|
|
68
|
+
|
|
69
|
+
At the handoff, start a `/goal` (or the host's persistent-goal equivalent) so execution continues
|
|
70
|
+
across turns. The goal text always carries both conditions:
|
|
71
|
+
|
|
72
|
+
- **Done:** every task in `.agent/tasks.json` has `"passes": true`.
|
|
73
|
+
- **Stop:** the first of these ends the goal: the visual judge passes its bar, three judge rounds in a
|
|
74
|
+
row show no score gain, the cost cap is reached, or the user says stop or accepts the result.
|
|
75
|
+
|
|
76
|
+
Start a goal only with its Stop condition. A goal without one keeps working after the user is done.
|