create-threenative 0.2.18 → 0.2.21
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/agent-docs/references/assertion-reference.md +1 -1
- package/agent-docs/references/capability-reference.md +792 -5
- 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 +25 -7
- package/agent-files/.agents/skills/prd-creator/SKILL.md +24 -0
- package/dist/index.js +268 -237
- package/dist/quality.d.ts +5 -1
- package/dist/quality.js +75 -6
- package/dist/terrain-kit.js +1 -1
- package/dist/threenative.js +7 -5
- package/dist/web-engine-post-effects.js +6 -0
- package/dist/web-engine-runtime.js +407 -38
- 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/patches/three@0.187.0.patch +108 -21
- 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 +12 -3
- 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/Ranking.ts +8 -4
- 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-environment`, `@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-environment 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,110 @@ 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-environment`
|
|
6826
|
+
|
|
6827
|
+
### `bakeCity`
|
|
6828
|
+
|
|
6829
|
+
`function` — Bake an Apex City Kit module to one GLB: a road tile, a building, a street prop, a vehicle, a race kit piece, a block or lot, a sidewalk, transit, a public space, a utility or a decal. The page's own generator and GLTFExporter run headless, so the GLB carries its merged meshes, its materials and textures (Poly Haven CC0 PBR maps and the canvas-drawn signs, liveries and markings) and its road sockets in the root node's extras.
|
|
6830
|
+
|
|
6831
|
+
```ts
|
|
6832
|
+
export async function bakeCity(options: IBakeCityOptions): Promise<IEnvironmentBake[]> { … }
|
|
6833
|
+
```
|
|
6834
|
+
|
|
6835
|
+
- **Use when:** generate a modular city street, intersection, roundabout or highway tile as a GLB · a procedural building, storefront, office tower, apartment block, house or warehouse for a city level · street props for a city: traffic signal, streetlight, bus shelter, hydrant, bench, mailbox, dumpster · a race track kit: starting grid, timing gantry, barriers, tire wall, kerbs, pit lane; or a car, van, kart or formula car
|
|
6836
|
+
- **Constraints:** fails closed: an unknown module throws naming the nearest ids; seed is an integer 0 to 4294967295, detail 0 to 2, wet 0 to 100, floors an integer 2 to 12, text at most 24 characters, dressing a boolean · the same options write identical bytes on one Node major and machine (fonts draw the sign text); files are written atomically (temporary file, then rename) · units are metres, +Y up; stock roads fit a 24 m grid, and custom straights and bends export updated socket positions, directions, widths and lane centres in the root node's extras · roadWidth and markings apply to straight and curve; roadLength applies to straight; bendAngle, bendRadius and bendSide apply to curve; roadSurface applies to socketed road modules · bake-time only, so keep it a dev dependency; textures are capped at 1024 px like the page's export
|
|
6837
|
+
- **Requires:** npm i -D @threenative/procedural-environment
|
|
6838
|
+
|
|
6839
|
+
```ts
|
|
6840
|
+
await bakeCity({ module: "cross", out: "assets/city" });
|
|
6841
|
+
await bakeCity({ module: "curve", bendAngle: 55, bendRadius: 24, bendSide: "left", roadWidth: 12, sidewalk: false, curb: false, out: "assets/city" });
|
|
6842
|
+
await bakeCity({ module: "apartments", seed: 7, floors: 8, out: "assets/city" });
|
|
6843
|
+
```
|
|
6844
|
+
|
|
6845
|
+
### `bakeRock`
|
|
6846
|
+
|
|
6847
|
+
`function` — Bake a procedural rock (Outcrop) to GLBs, one per level of detail: a boulder, slab, spire, hoodoo, sea stack, mesa, arch, tileable cliff module or a mountain, weathered and coloured for its biome (moss in a forest, snow in the tundra, sand in the desert, algae below the tide line).
|
|
6848
|
+
|
|
6849
|
+
```ts
|
|
6850
|
+
export async function bakeRock(options: IBakeRockOptions): Promise<IEnvironmentBake[]> { … }
|
|
6851
|
+
```
|
|
6852
|
+
|
|
6853
|
+
- **Use when:** generate a procedural rock, boulder or cliff as a GLB for a game level · desert mesa, hoodoo or sandstone arch; coastal sea stack; alpine spire; volcanic basalt columns · a procedural mountain mesh for the horizon, with snow at altitude
|
|
6854
|
+
- **Constraints:** fails closed: an unknown form or biome throws naming the nearest ids, as do unknown traits or surface keys, a non-integer seed, a lod outside 0 to 2 and a detail outside 0 to 1 · the same options write identical bytes; files are written atomically (temporary file, then rename) · each GLB carries POSITION, NORMAL and COLOR_0 (linear RGB, rock and cover already blended) on one `rock` material; units are metres, +Y up, the rock rests on y = 0 · a `cliff` module shows a cut face at each end: bake a run with one seed and `offset: [n * width, 0, 0]`, stand the modules one width apart and bury the two ends of the run · bake-time only, so keep it a dev dependency; the game owns the material and can re-material by the glTF material name `rock`
|
|
6855
|
+
- **Requires:** npm i -D @threenative/procedural-environment
|
|
6856
|
+
|
|
6857
|
+
```ts
|
|
6858
|
+
await bakeRock({ form: "cliff", biome: "coastal", seed: 7, lods: [0, 1], out: "assets/rocks" });
|
|
6859
|
+
await bakeRock({ form: "boulder", biome: "forest", traits: { weathering: 0.8 }, out: "assets/rocks" });
|
|
6860
|
+
for (const n of [0, 1, 2]) await bakeRock({ form: "cliff", biome: "desert", seed: 7, offset: [n * 10, 0, 0], out: "assets/rocks" }); // three modules of one wall
|
|
6861
|
+
```
|
|
6862
|
+
|
|
6863
|
+
### `bakeVegetation`
|
|
6864
|
+
|
|
6865
|
+
`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 and embeds WebP textures: Arbor trees and cover wear a CC0 bark scan and alpha-masked leaves, blades, fronds and needles painted from CC0 leaf scans; forest-kit wood and stone wear a grey CC0 detail scan, and forest-kit cover and leaf litter a grey CC0 blade or leaf scan, each over the kit's COLOR_0 palette.
|
|
6866
|
+
|
|
6867
|
+
```ts
|
|
6868
|
+
export async function bakeVegetation(options: IBakeVegetationOptions): Promise<IEnvironmentBake[]> { … }
|
|
6869
|
+
```
|
|
6870
|
+
|
|
6871
|
+
- **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
|
|
6872
|
+
- **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 · textures default to "scans" (the bake's `scan` and `leafScan` name them); nine presets with no fitting CC0 leaf scan (ginkgo, palms, banana, joshua, flowers, elephantear) keep Arbor's drawn leaf card; textures: "generated" keeps every generator texture byte for byte · form, leafImage, barkImage and barkNormalImage patch an Arbor preset only; a forest-kit debris or cover preset throws when given any
|
|
6873
|
+
- **Requires:** npm i -D @threenative/procedural-environment
|
|
6874
|
+
|
|
6875
|
+
```ts
|
|
6876
|
+
await bakeVegetation({ preset: "oak", seed: 7, lods: [0, 1], out: "assets/trees" });
|
|
6877
|
+
await bakeVegetation({ preset: "log", seed: 3, out: "assets/debris" });
|
|
6878
|
+
```
|
|
6879
|
+
|
|
6880
|
+
### `environmentBiomes`
|
|
6881
|
+
|
|
6882
|
+
`function` — Every biome: its id, name, the request words that mean it, the rock surface its rocks wear and the element ids that belong there.
|
|
6883
|
+
|
|
6884
|
+
```ts
|
|
6885
|
+
export function environmentBiomes(): IEnvironmentBiome[] { … }
|
|
6886
|
+
```
|
|
6887
|
+
|
|
6888
|
+
- **Use when:** which biomes can I bake nature for: forest, desert, jungle, tundra, coast, volcano · what trees, plants, debris and rocks belong in a desert or an alpine biome
|
|
6889
|
+
- **Constraints:** ids match the Strata terrain kits where they overlap (forest, coastal, alpine, desert, tundra)
|
|
6890
|
+
- **Requires:** npm i -D @threenative/procedural-environment
|
|
6891
|
+
|
|
6892
|
+
```ts
|
|
6893
|
+
environmentBiomes().map((biome) => biome.id);
|
|
6894
|
+
```
|
|
6895
|
+
|
|
6896
|
+
### `environmentElements`
|
|
6897
|
+
|
|
6898
|
+
`function` — Find the nature elements to bake, by biome, kind or words: trees, ground cover, forest-floor debris and rock forms (boulders, cliffs, sea stacks, mesas, arches, mountains), each with the exact bake call.
|
|
6899
|
+
|
|
6900
|
+
```ts
|
|
6901
|
+
export function environmentElements(filter: IEnvironmentFilter = { … }
|
|
6902
|
+
```
|
|
6903
|
+
|
|
6904
|
+
- **Use when:** what can I bake for a desert, a jungle, a coast, a tundra or a volcanic island · list the rocks, cliffs and mountains for a biome, or every plant that grows there · find a tree or plant by name or latin name, such as pine, palm, cactus or fern
|
|
6905
|
+
- **Constraints:** fails closed: an unknown biome or kind throws naming the nearest ids · biome takes an id or one of its words, so "jungle" finds tropical and "swamp" finds wetland
|
|
6906
|
+
- **Requires:** npm i -D @threenative/procedural-environment
|
|
6907
|
+
|
|
6908
|
+
```ts
|
|
6909
|
+
environmentElements({ biome: "desert", kind: "rock" }).map((element) => element.bake);
|
|
6910
|
+
environmentElements({ search: "palm" });
|
|
6911
|
+
```
|
|
6912
|
+
|
|
6913
|
+
### `vegetationPresets`
|
|
6914
|
+
|
|
6915
|
+
`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.
|
|
6916
|
+
|
|
6917
|
+
```ts
|
|
6918
|
+
export function vegetationPresets(): IVegetationPreset[] { … }
|
|
6919
|
+
```
|
|
6920
|
+
|
|
6921
|
+
- **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
|
|
6922
|
+
- **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"
|
|
6923
|
+
- **Requires:** npm i -D @threenative/procedural-environment
|
|
6924
|
+
|
|
6925
|
+
```ts
|
|
6926
|
+
vegetationPresets().filter((p) => p.kind === "debris").map((p) => p.id);
|
|
6927
|
+
```
|
|
6928
|
+
|
|
6736
6929
|
## `@threenative/raw-unreal`
|
|
6737
6930
|
|
|
6738
6931
|
### `createThreeGeometry`
|
|
@@ -7433,6 +7626,23 @@ export function gradientAt(grid: ISampledGrid, x: number, z: number): [number, n
|
|
|
7433
7626
|
const gradient = gradientAt(new Terrain({ resolution: 17 }).evaluate(), 0, 0);
|
|
7434
7627
|
```
|
|
7435
7628
|
|
|
7629
|
+
### `grassFieldFromBiome`
|
|
7630
|
+
|
|
7631
|
+
`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.
|
|
7632
|
+
|
|
7633
|
+
```ts
|
|
7634
|
+
export function grassFieldFromBiome( biome: Pick<IBiomeSpec, "grass" | "seed">, ground: IGrassGround, ): IGrassFieldPlacement | null { … }
|
|
7635
|
+
```
|
|
7636
|
+
|
|
7637
|
+
- **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
|
|
7638
|
+
- **Constraints:** the look stays the game's: pass the result with the kit's `render/grass.ts` blade and material
|
|
7639
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7640
|
+
|
|
7641
|
+
```ts
|
|
7642
|
+
const placement = grassFieldFromBiome(biome, { heightAt: (x, z) => field.heightAt(x, z), waterLevel: 0 });
|
|
7643
|
+
if (placement) ctx.add(new GrassField3D({ ...placement, blade: grassBlade(), material: grassMaterial }));
|
|
7644
|
+
```
|
|
7645
|
+
|
|
7436
7646
|
### `landform`
|
|
7437
7647
|
|
|
7438
7648
|
`function` — One call, one landscape: a calibrated layer recipe for a kind of environment.
|
|
@@ -7531,6 +7741,22 @@ export function orderedScatterRules(spec: IBiomeSpec): IOrderedScatterRules {
|
|
|
7531
7741
|
const rules = orderedScatterRules(spec);
|
|
7532
7742
|
```
|
|
7533
7743
|
|
|
7744
|
+
### `paintCanopyCover`
|
|
7745
|
+
|
|
7746
|
+
`function` — Paint each placed tree's crown into a per-vertex canopy grid, so the ground under a stand reads as forest floor rather than open turf. `values` is row-major Z then X, centred on the origin, at the heightfield's own spacing; each vertex keeps the strongest crown that reaches it (0 to 1).
|
|
7747
|
+
|
|
7748
|
+
```ts
|
|
7749
|
+
export function paintCanopyCover( values: Float32Array, world: { … }
|
|
7750
|
+
```
|
|
7751
|
+
|
|
7752
|
+
- **Use when:** shade the ground under a baked stand, at bake time or after a placement edit
|
|
7753
|
+
- **Constraints:** `crowns` is metres of crown radius per unit of placement scale, keyed by asset; other assets paint nothing
|
|
7754
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7755
|
+
|
|
7756
|
+
```ts
|
|
7757
|
+
paintCanopyCover(values, { size: 512, resolution: 257 }, placements, { spruce: 7 });
|
|
7758
|
+
```
|
|
7759
|
+
|
|
7534
7760
|
### `placeMassif`
|
|
7535
7761
|
|
|
7536
7762
|
`function` — Stands one surveyed mountain behind a world, chosen and posed by a seed: the tile from a list, a point on a bearing and distance, a turn that faces its steepest wall to the centre within 20 degrees, a mirror and a summit height. It stands on the host's own foot (a smooth surface through the host under its border), replacing the host's hills inside its square, and leaves the centre square untouched. Appends one `heightmap` layer; the placement carries the tile-spacing heights a relief map reads.
|
|
@@ -7626,6 +7852,22 @@ export function scatterProps( data: IOrderedScatterField, focus: { … }
|
|
|
7626
7852
|
const { placements, counts } = scatterProps(data, focus, clearings);
|
|
7627
7853
|
```
|
|
7628
7854
|
|
|
7855
|
+
### `skyVisibility`
|
|
7856
|
+
|
|
7857
|
+
`function` — The share of the sky each heightfield vertex sees past the terrain around it: 1 on open ground, lower on a valley floor, at a cliff foot or in a crater. The logic follows TerraForge3D's horizon ambient pass (MIT, `heightfield/ambient/compute.glsl`): march outward along evenly spaced azimuths, keep the highest horizon each one meets, and integrate the cosine-weighted sky above it, which is `cos²` of the horizon angle per azimuth. Only ground that rises over both the vertex's tangent plane and the horizontal occludes, so a straight slope and a steep face over a flat floor stay open: the lighting already counts the slope's own tilt. Heights are row-major Z then X, centred on the origin, as the baked world stores them. Every node marches: a strided march filled bilinearly erred by 0.13 at p99 on the alpine survey's creases. About 0.4 s of CPU a world, so `bakeKit` runs it and the game loads `<world>.sky.bin`.
|
|
7858
|
+
|
|
7859
|
+
```ts
|
|
7860
|
+
export function skyVisibility( heights: ArrayLike<number>, resolution: number, size: number, { … }
|
|
7861
|
+
```
|
|
7862
|
+
|
|
7863
|
+
- **Use when:** bake a heightfield's sky occlusion for the ground's ambient light
|
|
7864
|
+
- **Constraints:** offline: about 0.4 s of CPU for a 257² field; bake it, do not run it per frame
|
|
7865
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7866
|
+
|
|
7867
|
+
```ts
|
|
7868
|
+
const sky = skyVisibility(heights, 257, 512);
|
|
7869
|
+
```
|
|
7870
|
+
|
|
7629
7871
|
### `slopeAtIndex`
|
|
7630
7872
|
|
|
7631
7873
|
`function` — Slope in degrees at a heightfield sample.
|
|
@@ -8285,7 +8527,7 @@ const prepared = await prepareWorldGLTF(input);
|
|
|
8285
8527
|
`function` — Bake a copied kit, optionally using the caller's installed world cook.
|
|
8286
8528
|
|
|
8287
8529
|
```ts
|
|
8288
|
-
export async function bakeKit( url: string, { … }
|
|
8530
|
+
export async function bakeKit( url: string, options: IBakeKitOptions | IBakeKitWorldOptions, ): Promise<void> { … }
|
|
8289
8531
|
```
|
|
8290
8532
|
|
|
8291
8533
|
- **Use when:** bake a copied terrain starter kit into its offline world package
|
|
@@ -8330,6 +8572,211 @@ export async function addStarterWorld<Extra extends { … }
|
|
|
8330
8572
|
await addStarterWorld(ctx, follow, spec);
|
|
8331
8573
|
```
|
|
8332
8574
|
|
|
8575
|
+
### `addStreamedGround`
|
|
8576
|
+
|
|
8577
|
+
`function` — PRD-790: the ground past the playable square, streamed around the player by `TerrainTiles` out to the collar's reach. Tiles sample the kit's own height function, the surface the square and the collar's vertices stand on, so a tile meets the square and its neighbours with no step. The tile material slides the outermost tile onto the collar's drawn height (`collarMorph`), so at the collar every tile vertex stands on it; `?tnTerrainValidate=1` reports `streamCollarGap`. The largest block of resident tiles around the player is written to the stream each frame: the tiles draw inside it, the collar everywhere else, so a tile that is still building leaves the collar showing, never a hole.
|
|
8578
|
+
|
|
8579
|
+
```ts
|
|
8580
|
+
export function addStreamedGround(options: IStreamedGroundOptions): { … }
|
|
8581
|
+
```
|
|
8582
|
+
|
|
8583
|
+
- **Use when:** stream an authored square's ground past its edge, out to a drawn collar
|
|
8584
|
+
- **Constraints:** the game supplies the height, the collar, its curve and the tile material
|
|
8585
|
+
- **Requires:** npm i -D @threenative/terrain @threenative/physics
|
|
8586
|
+
|
|
8587
|
+
```ts
|
|
8588
|
+
const ground = addStreamedGround({ ctx, name, size, resolution, height, collar, curve, reach, stream, surface, follow, report });
|
|
8589
|
+
```
|
|
8590
|
+
|
|
8591
|
+
### `authoredQuaternion`
|
|
8592
|
+
|
|
8593
|
+
`function` — The quaternion a placement's own scatter numbers describe: the normal tilt, then the yaw.
|
|
8594
|
+
|
|
8595
|
+
```ts
|
|
8596
|
+
export function authoredQuaternion( placement: IPlacement, ): readonly [number, number, number, number] { … }
|
|
8597
|
+
```
|
|
8598
|
+
|
|
8599
|
+
- **Use when:** compose a placement's authored rotation before grounding it
|
|
8600
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8601
|
+
|
|
8602
|
+
```ts
|
|
8603
|
+
const quaternion = authoredQuaternion(placement);
|
|
8604
|
+
```
|
|
8605
|
+
|
|
8606
|
+
### `beginScene`
|
|
8607
|
+
|
|
8608
|
+
`function` — Start a scene's view accounting: the player view it opens in, and nothing measured yet.
|
|
8609
|
+
|
|
8610
|
+
```ts
|
|
8611
|
+
export function beginScene(world: string): void { … }
|
|
8612
|
+
```
|
|
8613
|
+
|
|
8614
|
+
- **Use when:** start the run's view accounting when a scene enters
|
|
8615
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8616
|
+
|
|
8617
|
+
```ts
|
|
8618
|
+
beginScene("forest");
|
|
8619
|
+
```
|
|
8620
|
+
|
|
8621
|
+
### `collarArithmeticHeight`
|
|
8622
|
+
|
|
8623
|
+
`function` — The collar triangle under `(x, z)` found by arithmetic alone, as the tile shader finds it: the ring from the ring spacing, the perimeter step from the face the point projects onto, and the triangle from the point's place in the quad. On one face the world point is an affine map of `(scale, share * scale)`, so weights read there are the drawn triangle's own.
|
|
8624
|
+
|
|
8625
|
+
```ts
|
|
8626
|
+
export function collarArithmeticHeight( collar: HeightfieldCollar, curve: ICollarRingCurve, x: number, z: number, ): number { … }
|
|
8627
|
+
```
|
|
8628
|
+
|
|
8629
|
+
- **Use when:** answer a collar height on the CPU exactly as its tile shader computes it
|
|
8630
|
+
- **Constraints:** the curve must be the one the collar was built with
|
|
8631
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8632
|
+
|
|
8633
|
+
```ts
|
|
8634
|
+
const y = collarArithmeticHeight(collar, { power: 1.65, reach: 2100 }, x, z);
|
|
8635
|
+
```
|
|
8636
|
+
|
|
8637
|
+
### `collarDrawnHeight`
|
|
8638
|
+
|
|
8639
|
+
`function` — The collar's drawn height under `(x, z)`; null where there is no collar.
|
|
8640
|
+
|
|
8641
|
+
```ts
|
|
8642
|
+
export function collarDrawnHeight(collar: HeightfieldCollar, x: number, z: number): number | null { … }
|
|
8643
|
+
```
|
|
8644
|
+
|
|
8645
|
+
- **Use when:** measure or collide against the triangles a collar actually draws
|
|
8646
|
+
- **Constraints:** reads the collar it is given; never resamples the square or builds a surface
|
|
8647
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8648
|
+
|
|
8649
|
+
```ts
|
|
8650
|
+
const y = collarDrawnHeight(collar, x, z);
|
|
8651
|
+
```
|
|
8652
|
+
|
|
8653
|
+
### `collarMorph`
|
|
8654
|
+
|
|
8655
|
+
`function` — PRD-790 box 2: the streamed tiles' vertex shift. Only the outermost tile of the square the tiles draw slides onto the collar's drawn height, smoothly over that tile, so at the square's edge every tile vertex stands on the collar; the ground inside keeps the survey's smooth surface. The collar's heights go to the GPU once, as a float texture of rings by perimeter steps.
|
|
8656
|
+
|
|
8657
|
+
```ts
|
|
8658
|
+
export function collarMorph( collar: HeightfieldCollar, curve: ICollarRingCurve, stream: ICollarStream, band: number, ): Node<"vec3"> { … }
|
|
8659
|
+
```
|
|
8660
|
+
|
|
8661
|
+
- **Use when:** slide the streamed ground's outer tile onto a drawn collar without a seam
|
|
8662
|
+
- **Constraints:** the curve must be the one the collar was built with; the band is one tile wide
|
|
8663
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8664
|
+
|
|
8665
|
+
```ts
|
|
8666
|
+
tile.positionNode = collarMorph(collar, { power: 1.65, reach: 2100 }, stream, 64);
|
|
8667
|
+
```
|
|
8668
|
+
|
|
8669
|
+
### `collarSeamGap`
|
|
8670
|
+
|
|
8671
|
+
`function` — PRD-790: where streamed tiles meet the collar. The tiles draw inside the square `(centreX, centreZ, half)` and the collar outside it, so the seam is that square's edge, past the playable square. `gap` is the largest step at the tiles' edge vertices (`spacing` apart), as core measures a tile-to-tile seam; `fold` is the largest step between them, where a fold of the collar's coarser triangles crosses a tile's straight edge.
|
|
8672
|
+
|
|
8673
|
+
```ts
|
|
8674
|
+
export function collarSeamGap( collar: HeightfieldCollar, height: (x: number, z: number) => number, centreX: number, centreZ: number, half: number, spacing: number, step = 0.1, ): { … }
|
|
8675
|
+
```
|
|
8676
|
+
|
|
8677
|
+
- **Use when:** prove a streamed ground and its collar meet without a step
|
|
8678
|
+
- **Constraints:** the caller supplies the height the tiles draw; a coarser `step` samples faster
|
|
8679
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8680
|
+
|
|
8681
|
+
```ts
|
|
8682
|
+
const { gap, fold } = collarSeamGap(collar, tilesHeight, x, z, 288, 2);
|
|
8683
|
+
```
|
|
8684
|
+
|
|
8685
|
+
### `createDiagnosticsState`
|
|
8686
|
+
|
|
8687
|
+
`function` — The state one world's measurements are reported through, with its own name in it. The game spreads this into its own state and adds the look values it also reports; the counters live here. The window groups and the drawn-frame counts are module-level on purpose: `ctx.goto` builds a new scene for the next world, and the numbers a run reports are the run's, not one scene's.
|
|
8688
|
+
|
|
8689
|
+
```ts
|
|
8690
|
+
export function createDiagnosticsState(world: string) { … }
|
|
8691
|
+
```
|
|
8692
|
+
|
|
8693
|
+
- **Use when:** start a kit's game state with the measurements every streamed starter world reports
|
|
8694
|
+
- **Constraints:** the world name is the one this state measures; a blank name fails rather than reporting ""
|
|
8695
|
+
- **Requires:** npm i -D @threenative/terrain @threenative/physics
|
|
8696
|
+
|
|
8697
|
+
```ts
|
|
8698
|
+
const state = { ...createDiagnosticsState("forest"), showcase: false };
|
|
8699
|
+
```
|
|
8700
|
+
|
|
8701
|
+
### `createMeasure`
|
|
8702
|
+
|
|
8703
|
+
`function` — The per-world measurement: contacts, travel, edge overshoot, water and the frame facts a run reports.
|
|
8704
|
+
|
|
8705
|
+
```ts
|
|
8706
|
+
export function createMeasure(options: IMeasureOptions): IMeasure { … }
|
|
8707
|
+
```
|
|
8708
|
+
|
|
8709
|
+
- **Use when:** measure one played starter world every fixed step
|
|
8710
|
+
- **Constraints:** the game supplies the actor, the player body and the probe fixture; it owns no look
|
|
8711
|
+
- **Requires:** npm i -D @threenative/terrain @threenative/physics
|
|
8712
|
+
|
|
8713
|
+
```ts
|
|
8714
|
+
const measure = createMeasure({ world, physics: ctx.physics, raycast, actor, player, ...options });
|
|
8715
|
+
```
|
|
8716
|
+
|
|
8717
|
+
### `createMorphedHeight`
|
|
8718
|
+
|
|
8719
|
+
`function` — The height a tile vertex stands at once `collarMorph` moved it: the survey inside the band, the collar's arithmetic height at the drawn square's edge. The seam measure reads this.
|
|
8720
|
+
|
|
8721
|
+
```ts
|
|
8722
|
+
export function createMorphedHeight( collar: HeightfieldCollar, curve: ICollarRingCurve, height: (x: number, z: number) => number, centreX: number, centreZ: number, half: number, band: number, ): (x: number, z: number) => number { … }
|
|
8723
|
+
```
|
|
8724
|
+
|
|
8725
|
+
- **Use when:** check on the CPU the surface the tile shader draws after its morph
|
|
8726
|
+
- **Constraints:** mirrors `collarMorph`'s weight exactly; both read the same curve and band
|
|
8727
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8728
|
+
|
|
8729
|
+
```ts
|
|
8730
|
+
const height = createMorphedHeight(collar, curve, surveyHeight, x, z, 288, 64);
|
|
8731
|
+
```
|
|
8732
|
+
|
|
8733
|
+
### `createPlayerRig`
|
|
8734
|
+
|
|
8735
|
+
`function` — The player: the capsule the solver moves, the mannequin that rides it, and the third-person camera that follows with the terrain as its walls. The stepped world is the authority for both the ground the player stands on and the wall the orbit camera cannot pass, which is why both queries mask to the game's ground layer: what the player can walk on. Every appearance value — the mannequin, its clips, the gait speeds, the capsule and the camera framing — comes from the game.
|
|
8736
|
+
|
|
8737
|
+
```ts
|
|
8738
|
+
export function createPlayerRig(options: IPlayerRigOptions): IPlayerRig { … }
|
|
8739
|
+
```
|
|
8740
|
+
|
|
8741
|
+
- **Use when:** give a copied starter kit its player capsule, mannequin and follow camera
|
|
8742
|
+
- **Constraints:** the game builds the camera and the wall probe; the package owns only their wiring
|
|
8743
|
+
- **Requires:** npm i -D @threenative/terrain @threenative/physics
|
|
8744
|
+
|
|
8745
|
+
```ts
|
|
8746
|
+
const rig = createPlayerRig({ at, field, mannequin, clips, gait, camera, probe, ...options });
|
|
8747
|
+
```
|
|
8748
|
+
|
|
8749
|
+
### `createRevealProbe`
|
|
8750
|
+
|
|
8751
|
+
`function` — What the loading reveal showed once the curtain lifts: drawn batches, pipelines and impostor readiness, measured against the reveal's own baseline.
|
|
8752
|
+
|
|
8753
|
+
```ts
|
|
8754
|
+
export function createRevealProbe(options: IRevealProbeOptions): IRevealProbe { … }
|
|
8755
|
+
```
|
|
8756
|
+
|
|
8757
|
+
- **Use when:** measure whether the spawn drew before the curtain released it
|
|
8758
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8759
|
+
|
|
8760
|
+
```ts
|
|
8761
|
+
const reveal = createRevealProbe({ camera, covered, phase, released, ...options });
|
|
8762
|
+
```
|
|
8763
|
+
|
|
8764
|
+
### `createSpawnGate`
|
|
8765
|
+
|
|
8766
|
+
`function` — The spawn gate: one deadline, one settlement, one failure report. `WorldCells.whenSpawnReady` is the data authority and each streamed world's `prewarmed` is the draw gate; this gate turns their landing into the loading screen's release, and writes the one console line a failed spawn leaves behind.
|
|
8767
|
+
|
|
8768
|
+
```ts
|
|
8769
|
+
export function createSpawnGate(ctx: SpawnGateHost, options: ISpawnGateOptions): ISpawnGate { … }
|
|
8770
|
+
```
|
|
8771
|
+
|
|
8772
|
+
- **Use when:** hold a streamed starter world's loading screen until its spawn has landed
|
|
8773
|
+
- **Constraints:** Every value it reports is supplied by the game; a failure writes one `TN_` line
|
|
8774
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8775
|
+
|
|
8776
|
+
```ts
|
|
8777
|
+
const gate = createSpawnGate(ctx, { world, progress, witness, released });
|
|
8778
|
+
```
|
|
8779
|
+
|
|
8333
8780
|
### `editWorldPlacements`
|
|
8334
8781
|
|
|
8335
8782
|
`function` — Apply deterministic startup edits to the decoded placement data before a world is loaded.
|
|
@@ -8346,6 +8793,157 @@ export function editWorldPlacements( data: { … }
|
|
|
8346
8793
|
const edited = editWorldPlacements(data, { remove: ["scree:candidate:7:41"] }, (x, z) => field.heightAt(x, z));
|
|
8347
8794
|
```
|
|
8348
8795
|
|
|
8796
|
+
### `enterView`
|
|
8797
|
+
|
|
8798
|
+
`function` — The camera cycle moved to another view: a keyed group for it, and a fresh measurement.
|
|
8799
|
+
|
|
8800
|
+
```ts
|
|
8801
|
+
export function enterView(world: string, view: string): { … }
|
|
8802
|
+
```
|
|
8803
|
+
|
|
8804
|
+
- **Use when:** switch the measured view when the benchmark camera cycle moves
|
|
8805
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8806
|
+
|
|
8807
|
+
```ts
|
|
8808
|
+
const { windows } = enterView("forest", "overview");
|
|
8809
|
+
```
|
|
8810
|
+
|
|
8811
|
+
### `invalidatePropShadows`
|
|
8812
|
+
|
|
8813
|
+
`function` — Keep WorldCells' changed caster bounds when forwarding to the existing shadow renderer.
|
|
8814
|
+
|
|
8815
|
+
```ts
|
|
8816
|
+
export function invalidatePropShadows( shadow: { … }
|
|
8817
|
+
```
|
|
8818
|
+
|
|
8819
|
+
- **Use when:** forward a streamed world's changed caster bounds to the game's shadow renderer
|
|
8820
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8821
|
+
|
|
8822
|
+
```ts
|
|
8823
|
+
invalidatePropShadows(ctx.shadows, region);
|
|
8824
|
+
```
|
|
8825
|
+
|
|
8826
|
+
### `leaveScene`
|
|
8827
|
+
|
|
8828
|
+
`function` — The scene is gone: nothing is on screen, so no window can belong to a view.
|
|
8829
|
+
|
|
8830
|
+
```ts
|
|
8831
|
+
export function leaveScene(): void { … }
|
|
8832
|
+
```
|
|
8833
|
+
|
|
8834
|
+
- **Use when:** stop attributing windows to a view when its scene is left
|
|
8835
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8836
|
+
|
|
8837
|
+
```ts
|
|
8838
|
+
leaveScene();
|
|
8839
|
+
```
|
|
8840
|
+
|
|
8841
|
+
### `loadCanopy`
|
|
8842
|
+
|
|
8843
|
+
`function` — The canopy weight the ground shader reads, painted from the placements the bake drew.
|
|
8844
|
+
|
|
8845
|
+
```ts
|
|
8846
|
+
export async function loadCanopy( assets: Pick<IAssetLoader, "resolve">, world: string, ): Promise<Float32Array> { … }
|
|
8847
|
+
```
|
|
8848
|
+
|
|
8849
|
+
- **Use when:** load the canopy map a streamed world's ground shades with
|
|
8850
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8851
|
+
|
|
8852
|
+
```ts
|
|
8853
|
+
const canopy = await loadCanopy(assets, "forest");
|
|
8854
|
+
```
|
|
8855
|
+
|
|
8856
|
+
### `loadPropPackage`
|
|
8857
|
+
|
|
8858
|
+
`function` — The baked prop package of one world, fetched as the bake wrote it. The files are the bake's output, not the game's: the manifest names one container, one reach array and one placement-ID list per streamed world, and nothing here derives a placement.
|
|
8859
|
+
|
|
8860
|
+
```ts
|
|
8861
|
+
export async function loadPropPackage( assets: Pick<IAssetLoader, "resolve">, world: string, ): Promise<IPropPackage> { … }
|
|
8862
|
+
```
|
|
8863
|
+
|
|
8864
|
+
- **Use when:** load the prop containers a bake wrote for one world
|
|
8865
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8866
|
+
|
|
8867
|
+
```ts
|
|
8868
|
+
const props = await loadPropPackage(assets, "forest");
|
|
8869
|
+
```
|
|
8870
|
+
|
|
8871
|
+
### `loadSky`
|
|
8872
|
+
|
|
8873
|
+
`function` — The share of the sky each terrain vertex sees past the relief, as `skyVisibility` baked it.
|
|
8874
|
+
|
|
8875
|
+
```ts
|
|
8876
|
+
export async function loadSky( assets: Pick<IAssetLoader, "resolve">, world: string, ): Promise<Float32Array> { … }
|
|
8877
|
+
```
|
|
8878
|
+
|
|
8879
|
+
- **Use when:** load the sky-visibility map a streamed world's ground shades with
|
|
8880
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8881
|
+
|
|
8882
|
+
```ts
|
|
8883
|
+
const sky = await loadSky(assets, "forest");
|
|
8884
|
+
```
|
|
8885
|
+
|
|
8886
|
+
### `observeFrame`
|
|
8887
|
+
|
|
8888
|
+
`function` — One world frame was drawn: count it, and open a fresh GPU sample window if the view or the readiness changed. Called from the render hook, before the camera is placed.
|
|
8889
|
+
|
|
8890
|
+
```ts
|
|
8891
|
+
export function observeFrame(ctx: ICounterCtx): void { … }
|
|
8892
|
+
```
|
|
8893
|
+
|
|
8894
|
+
- **Use when:** count a drawn frame and open the next GPU sample window
|
|
8895
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8896
|
+
|
|
8897
|
+
```ts
|
|
8898
|
+
ctx.beforeRender(() => observeFrame(ctx));
|
|
8899
|
+
```
|
|
8900
|
+
|
|
8901
|
+
### `observeWindow`
|
|
8902
|
+
|
|
8903
|
+
`function` — The frame-budget window closed: latch it, and update the numbers the run reports.
|
|
8904
|
+
|
|
8905
|
+
```ts
|
|
8906
|
+
export function observeWindow(window: IFrameBudgetWindow): void { … }
|
|
8907
|
+
```
|
|
8908
|
+
|
|
8909
|
+
- **Use when:** read the engine's own closed frame window into the run's report
|
|
8910
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8911
|
+
|
|
8912
|
+
```ts
|
|
8913
|
+
frameBudget: { onWindow: observeWindow }
|
|
8914
|
+
```
|
|
8915
|
+
|
|
8916
|
+
### `preparePose`
|
|
8917
|
+
|
|
8918
|
+
`function` — The pose a prop draws at, grounded on the game's own height field. The record's quaternion, when present, replaces the rotation a live placement composes; every step below it — the ground snap, the boulder burial, the flat-footprint sink and the crag base ring — still runs, because the record is a pose and not an override of the pose. A placement with no ground under it fails closed by its own id, so a streamed world cannot silently float.
|
|
8919
|
+
|
|
8920
|
+
```ts
|
|
8921
|
+
export function preparePose( geometry: BufferGeometry, _material: Material, placement: IPlacement, transform: IPlacementOverride | undefined, groundAt: PropGroundQuery, rules: IPropGroundRules, pose?: IPropPoseOverride, ): IPropPose { … }
|
|
8922
|
+
```
|
|
8923
|
+
|
|
8924
|
+
- **Use when:** ground one baked prop record on the game's height field before streaming it
|
|
8925
|
+
- **Constraints:** the burial, footprint and base-ring assets are the game's; the package applies them
|
|
8926
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8927
|
+
|
|
8928
|
+
```ts
|
|
8929
|
+
const pose = preparePose(foot.geometry, material, record.placement, undefined, groundAt, rules);
|
|
8930
|
+
```
|
|
8931
|
+
|
|
8932
|
+
### `preparePropTransform`
|
|
8933
|
+
|
|
8934
|
+
`function` — The pose and the transform an editor edited, prepared together so one write reports both.
|
|
8935
|
+
|
|
8936
|
+
```ts
|
|
8937
|
+
export function preparePropTransform( instance: IPropInstance, transform: IPlacementOverride | undefined, groundAt: PropGroundQuery, rules: IPropGroundRules, ) { … }
|
|
8938
|
+
```
|
|
8939
|
+
|
|
8940
|
+
- **Use when:** re-pose one prop the editor edited and keep the transform it reported
|
|
8941
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8942
|
+
|
|
8943
|
+
```ts
|
|
8944
|
+
const prepared = preparePropTransform(instance, transform, groundAt, rules);
|
|
8945
|
+
```
|
|
8946
|
+
|
|
8349
8947
|
### `PropColliders`
|
|
8350
8948
|
|
|
8351
8949
|
`class` — Stream caller-specified fixed collision shapes around a moving follow object.
|
|
@@ -8362,6 +8960,128 @@ export class PropColliders extends Object3D implements IComputeDriven { … }
|
|
|
8362
8960
|
new PropColliders(ctx, follow, manifest, records, shapes, reach, name);
|
|
8363
8961
|
```
|
|
8364
8962
|
|
|
8963
|
+
### `propCounts`
|
|
8964
|
+
|
|
8965
|
+
`function` — Records per asset across the package's buckets: what the run report calls the scatter's counts.
|
|
8966
|
+
|
|
8967
|
+
```ts
|
|
8968
|
+
export function propCounts( pkg: IPropPackage, assetNames: readonly string[], ): Record<string, number> { … }
|
|
8969
|
+
```
|
|
8970
|
+
|
|
8971
|
+
- **Use when:** report how many records each asset drew, zero included
|
|
8972
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8973
|
+
|
|
8974
|
+
```ts
|
|
8975
|
+
const counts = propCounts(pkg, ["spruce", "boulder"]);
|
|
8976
|
+
```
|
|
8977
|
+
|
|
8978
|
+
### `propKey`
|
|
8979
|
+
|
|
8980
|
+
`function` — The model a record draws: its asset, its variant, and the shape a non-uniform edit gave it. `WorldCells` names the model through the run the record sits in, so this key is what the container stores. A placement with one uniform scale draws its variant as authored (`spruce:2`); a placement the editor scaled unevenly draws a model of that shape (`spruce:2@1,0.5,0.5`), so the record stays one uniform scale and the picture keeps the edit.
|
|
8981
|
+
|
|
8982
|
+
```ts
|
|
8983
|
+
export function propKey(placement: IPlacement, variant: number): string { … }
|
|
8984
|
+
```
|
|
8985
|
+
|
|
8986
|
+
- **Use when:** name the model a baked or live placement record draws
|
|
8987
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
8988
|
+
|
|
8989
|
+
```ts
|
|
8990
|
+
const key = propKey(placement, 2);
|
|
8991
|
+
```
|
|
8992
|
+
|
|
8993
|
+
### `propRatio`
|
|
8994
|
+
|
|
8995
|
+
`function` — The shape `propKey` wrote, so the loader scales the model the record's one scale cannot carry.
|
|
8996
|
+
|
|
8997
|
+
```ts
|
|
8998
|
+
export function propRatio(key: string): [number, number, number] { … }
|
|
8999
|
+
```
|
|
9000
|
+
|
|
9001
|
+
- **Use when:** scale a streamed model by the shape its record's single scale cannot carry
|
|
9002
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
9003
|
+
|
|
9004
|
+
```ts
|
|
9005
|
+
const ratio = propRatio("spruce:2@1,0.5,0.5");
|
|
9006
|
+
```
|
|
9007
|
+
|
|
9008
|
+
### `publish`
|
|
9009
|
+
|
|
9010
|
+
`function` — Publish the measurements and the scene's own facts into state, twice per second.
|
|
9011
|
+
|
|
9012
|
+
```ts
|
|
9013
|
+
export function publish( ctx: { … }
|
|
9014
|
+
```
|
|
9015
|
+
|
|
9016
|
+
- **Use when:** write the measured view and frame numbers into the game's state
|
|
9017
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
9018
|
+
|
|
9019
|
+
```ts
|
|
9020
|
+
publish(ctx, { world, worldReady, frames, ...facts });
|
|
9021
|
+
```
|
|
9022
|
+
|
|
9023
|
+
### `readPropTransform`
|
|
9024
|
+
|
|
9025
|
+
`function` — The transform an instance's current pose describes.
|
|
9026
|
+
|
|
9027
|
+
```ts
|
|
9028
|
+
export function readPropTransform(instance: IPropInstance): IPlacementOverride { … }
|
|
9029
|
+
```
|
|
9030
|
+
|
|
9031
|
+
- **Use when:** read an edited prop's current pose for the scene format
|
|
9032
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
9033
|
+
|
|
9034
|
+
```ts
|
|
9035
|
+
const transform = readPropTransform(instance);
|
|
9036
|
+
```
|
|
9037
|
+
|
|
9038
|
+
### `streamProps`
|
|
9039
|
+
|
|
9040
|
+
`function` — Load the prop worlds, pose every record on the ground, and hand each bucket to `WorldCells`. The passes are short and yield between slices, because the whole point of streaming is that the first frame does not wait for 200 000 records: the records are decoded and grounded in slices, and each bucket loads as its own world.
|
|
9041
|
+
|
|
9042
|
+
```ts
|
|
9043
|
+
export async function streamProps(options: IPropWorldOptions) { … }
|
|
9044
|
+
```
|
|
9045
|
+
|
|
9046
|
+
- **Use when:** stream a world's baked prop containers and its live placements through WorldCells
|
|
9047
|
+
- **Constraints:** the variant, reach, bucket, LOD and gate rows are the game's; the package only applies
|
|
9048
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
9049
|
+
|
|
9050
|
+
```ts
|
|
9051
|
+
const props = await streamProps({ package: propPackage, groundAt, parts, materials, surface,
|
|
9052
|
+
follow, size, whileCurrent, variantOf, reachOf, bucketOf, lodOf, ...options });
|
|
9053
|
+
```
|
|
9054
|
+
|
|
9055
|
+
### `withAuthoredPose`
|
|
9056
|
+
|
|
9057
|
+
`function` — A placement as a package record stores it: the authored pose becomes its transform, at one scale. A record holds position, quaternion and one uniform scale, so an edited placement's own transform is folded down to the scale its record carries. The shape that scale removed is `propKey`'s ratio, and the drawable model that ratio names carries it instead.
|
|
9058
|
+
|
|
9059
|
+
```ts
|
|
9060
|
+
export function withAuthoredPose(placement: IPlacement): IPlacement { … }
|
|
9061
|
+
```
|
|
9062
|
+
|
|
9063
|
+
- **Use when:** fold an authored placement into the record transform the bake stores
|
|
9064
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
9065
|
+
|
|
9066
|
+
```ts
|
|
9067
|
+
const record = withAuthoredPose(placement);
|
|
9068
|
+
```
|
|
9069
|
+
|
|
9070
|
+
### `writePropTransform`
|
|
9071
|
+
|
|
9072
|
+
`function` — Writes a prepared pose onto the instance, reporting the transform only when the pose changed.
|
|
9073
|
+
|
|
9074
|
+
```ts
|
|
9075
|
+
export function writePropTransform( instance: IPropInstance, prepared: ReturnType<typeof preparePropTransform>, ): void { … }
|
|
9076
|
+
```
|
|
9077
|
+
|
|
9078
|
+
- **Use when:** write an edited prop's prepared pose back onto its instance
|
|
9079
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
9080
|
+
|
|
9081
|
+
```ts
|
|
9082
|
+
writePropTransform(instance, prepared);
|
|
9083
|
+
```
|
|
9084
|
+
|
|
8365
9085
|
## `@threenative/terrain/three`
|
|
8366
9086
|
|
|
8367
9087
|
### `toGeometry`
|
|
@@ -8593,6 +9313,24 @@ export function useUiStateDuringStartup<TState extends object>(options: { … }
|
|
|
8593
9313
|
const loading = useUiStateDuringStartup<GameState, number>({ reason: "staged loading overlay" }, (state) => state.loading.progress);
|
|
8594
9314
|
```
|
|
8595
9315
|
|
|
9316
|
+
## `src/assets.ts`
|
|
9317
|
+
|
|
9318
|
+
### `ctx.assets.memo`
|
|
9319
|
+
|
|
9320
|
+
`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.
|
|
9321
|
+
|
|
9322
|
+
```ts
|
|
9323
|
+
ctx.assets.memo<T>(key: string, build: () => T | Promise<T>): Promise<T>
|
|
9324
|
+
```
|
|
9325
|
+
|
|
9326
|
+
- **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
|
|
9327
|
+
- **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.
|
|
9328
|
+
- **Overrides:** TN_ASSET_MEMO reports why a run rebuilt instead of reading the store
|
|
9329
|
+
|
|
9330
|
+
```ts
|
|
9331
|
+
const { pixels } = await ctx.assets.memo("sky", () => ({ pixels: paintSky() }));
|
|
9332
|
+
```
|
|
9333
|
+
|
|
8596
9334
|
## `src/audio/storm.ts`
|
|
8597
9335
|
|
|
8598
9336
|
### `createStormAudio`
|
|
@@ -8728,6 +9466,55 @@ createWeatherWorld(scene: Scene, camera: PerspectiveCamera): IWeatherWorld
|
|
|
8728
9466
|
src/render/world.ts — edit the shader there, or the weather it is fed from src/state.ts
|
|
8729
9467
|
```
|
|
8730
9468
|
|
|
9469
|
+
## `src/scene.ts`
|
|
9470
|
+
|
|
9471
|
+
### `ctx.after`
|
|
9472
|
+
|
|
9473
|
+
`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.
|
|
9474
|
+
|
|
9475
|
+
```ts
|
|
9476
|
+
ctx.after(delay: number, callback: () => void): ScheduleHandle
|
|
9477
|
+
```
|
|
9478
|
+
|
|
9479
|
+
- **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
|
|
9480
|
+
- **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.
|
|
9481
|
+
|
|
9482
|
+
```ts
|
|
9483
|
+
const spawn = ctx.after(0.4, () => ctx.add(makeWave()));
|
|
9484
|
+
spawn(); // cancels
|
|
9485
|
+
```
|
|
9486
|
+
|
|
9487
|
+
### `ctx.beforeRender`
|
|
9488
|
+
|
|
9489
|
+
`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.
|
|
9490
|
+
|
|
9491
|
+
```ts
|
|
9492
|
+
ctx.beforeRender(callback: () => void): () => void
|
|
9493
|
+
```
|
|
9494
|
+
|
|
9495
|
+
- **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
|
|
9496
|
+
- **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.
|
|
9497
|
+
|
|
9498
|
+
```ts
|
|
9499
|
+
const stop = ctx.beforeRender(() => (material.uniforms.time.value = clock.elapsed));
|
|
9500
|
+
// later: stop();
|
|
9501
|
+
```
|
|
9502
|
+
|
|
9503
|
+
### `ctx.startup.progress`
|
|
9504
|
+
|
|
9505
|
+
`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.
|
|
9506
|
+
|
|
9507
|
+
```ts
|
|
9508
|
+
ctx.startup.progress: number
|
|
9509
|
+
```
|
|
9510
|
+
|
|
9511
|
+
- **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
|
|
9512
|
+
- **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.
|
|
9513
|
+
|
|
9514
|
+
```ts
|
|
9515
|
+
const width = `${Math.round(ctx.startup.progress * 100)}%`; // a cover the game draws on ctx.canvasLayer
|
|
9516
|
+
```
|
|
9517
|
+
|
|
8731
9518
|
## `three/addons/tsl/display/BloomNode.js`
|
|
8732
9519
|
|
|
8733
9520
|
### `bloom`
|