create-threenative 0.2.20 → 0.2.22

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.
@@ -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/procedural-vegetation`, `@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.
@@ -2607,7 +2607,7 @@ export class ScatterField3D extends Group { … }
2607
2607
 
2608
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
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
2610
+ - **Requires:** npm i -D @threenative/procedural-environment for the bake these instances come from
2611
2611
 
2612
2612
  ```ts
2613
2613
  const floor = new ScatterField3D({ parts: [{ lods, material }], getHeight, density: 0.05, place });
@@ -6822,25 +6822,94 @@ export async function bakeWolfToFile( options: IWolfBakeOptions, destination: st
6822
6822
  await bakeWolfToFile({ seed: 7, tier: "crowd" }, "assets/wolf-crowd.animal");
6823
6823
  ```
6824
6824
 
6825
- ## `@threenative/procedural-vegetation`
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
+ ```
6826
6862
 
6827
6863
  ### `bakeVegetation`
6828
6864
 
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.
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.
6830
6866
 
6831
6867
  ```ts
6832
- export async function bakeVegetation(options: IBakeVegetationOptions): Promise<IVegetationBake[]> { … }
6868
+ export async function bakeVegetation(options: IBakeVegetationOptions): Promise<IEnvironmentBake[]> { … }
6833
6869
  ```
6834
6870
 
6835
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
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
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
6838
6874
 
6839
6875
  ```ts
6840
6876
  await bakeVegetation({ preset: "oak", seed: 7, lods: [0, 1], out: "assets/trees" });
6841
6877
  await bakeVegetation({ preset: "log", seed: 3, out: "assets/debris" });
6842
6878
  ```
6843
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
+
6844
6913
  ### `vegetationPresets`
6845
6914
 
6846
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.
@@ -6851,7 +6920,7 @@ export function vegetationPresets(): IVegetationPreset[] { … }
6851
6920
 
6852
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
6853
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"
6854
- - **Requires:** npm i -D @threenative/procedural-vegetation
6923
+ - **Requires:** npm i -D @threenative/procedural-environment
6855
6924
 
6856
6925
  ```ts
6857
6926
  vegetationPresets().filter((p) => p.kind === "debris").map((p) => p.id);
@@ -7672,6 +7741,22 @@ export function orderedScatterRules(spec: IBiomeSpec): IOrderedScatterRules {
7672
7741
  const rules = orderedScatterRules(spec);
7673
7742
  ```
7674
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
+
7675
7760
  ### `placeMassif`
7676
7761
 
7677
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.
@@ -7767,6 +7852,22 @@ export function scatterProps( data: IOrderedScatterField, focus: { … }
7767
7852
  const { placements, counts } = scatterProps(data, focus, clearings);
7768
7853
  ```
7769
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
+
7770
7871
  ### `slopeAtIndex`
7771
7872
 
7772
7873
  `function` — Slope in degrees at a heightfield sample.
@@ -8426,7 +8527,7 @@ const prepared = await prepareWorldGLTF(input);
8426
8527
  `function` — Bake a copied kit, optionally using the caller's installed world cook.
8427
8528
 
8428
8529
  ```ts
8429
- export async function bakeKit( url: string, { … }
8530
+ export async function bakeKit( url: string, options: IBakeKitOptions | IBakeKitWorldOptions, ): Promise<void> { … }
8430
8531
  ```
8431
8532
 
8432
8533
  - **Use when:** bake a copied terrain starter kit into its offline world package
@@ -8471,6 +8572,211 @@ export async function addStarterWorld<Extra extends { … }
8471
8572
  await addStarterWorld(ctx, follow, spec);
8472
8573
  ```
8473
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
+
8474
8780
  ### `editWorldPlacements`
8475
8781
 
8476
8782
  `function` — Apply deterministic startup edits to the decoded placement data before a world is loaded.
@@ -8487,6 +8793,157 @@ export function editWorldPlacements( data: { … }
8487
8793
  const edited = editWorldPlacements(data, { remove: ["scree:candidate:7:41"] }, (x, z) => field.heightAt(x, z));
8488
8794
  ```
8489
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
+
8490
8947
  ### `PropColliders`
8491
8948
 
8492
8949
  `class` — Stream caller-specified fixed collision shapes around a moving follow object.
@@ -8503,6 +8960,128 @@ export class PropColliders extends Object3D implements IComputeDriven { … }
8503
8960
  new PropColliders(ctx, follow, manifest, records, shapes, reach, name);
8504
8961
  ```
8505
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
+
8506
9085
  ## `@threenative/terrain/three`
8507
9086
 
8508
9087
  ### `toGeometry`