create-threenative 0.2.14 → 0.2.17
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/kit-mcp.md +10 -0
- package/agent-docs/kit-router.md +14 -0
- package/agent-docs/kit-stuck.md +7 -0
- package/agent-docs/references/capability-reference.md +958 -30
- package/agent-docs/references/conventions.md +271 -0
- package/agent-docs/references/kit-action-rpg.md +40 -0
- package/agent-docs/references/kit-adventure.md +40 -0
- package/agent-docs/references/kit-collectathon.md +38 -0
- package/agent-docs/references/kit-kart.md +31 -0
- package/agent-docs/references/kit-minimal.md +29 -0
- package/agent-docs/references/kit-platformer.md +34 -0
- package/agent-docs/references/kit-puzzle.md +22 -0
- package/agent-docs/references/kit-racing.md +26 -0
- package/agent-docs/references/kit-rain.md +31 -0
- package/agent-docs/references/kit-rts.md +34 -0
- package/agent-docs/references/kit-runner.md +32 -0
- package/agent-docs/references/kit-sailing.md +41 -0
- package/agent-docs/references/kit-shooter.md +33 -0
- package/agent-docs/references/kit-snow.md +33 -0
- package/agent-docs/references/kit-starter.md +55 -0
- package/agent-docs/references/kit-tower-defense.md +27 -0
- package/agent-docs/references/terrain-authoring.md +2 -1
- package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
- package/agent-files/.agents/skills/prd-creator/SKILL.md +3 -2
- package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +81 -59
- package/agent-files/.claude/hooks/discovery-gate.mjs +125 -0
- package/agent-files/.claude/hooks/ponytail-context.mjs +1 -1
- package/agent-files/.claude/settings.json +25 -0
- package/agent-files/.codex/hooks.json +18 -1
- package/dist/index.js +256 -120
- package/dist/terrain-kit.d.ts +7 -0
- package/dist/terrain-kit.js +82 -0
- package/dist/threenative.js +23 -4
- package/dist/web-engine-gltf-loader.js +20 -7
- package/dist/web-engine-post-effects.js +34 -4
- package/dist/web-engine-runtime.js +6119 -3311
- package/package.json +13 -8
- package/template-assets/patches/three@0.187.0.patch +2004 -407
- package/templates/action-rpg/AGENTS.md +99 -84
- package/templates/action-rpg/CLAUDE.md +99 -84
- package/templates/action-rpg/kit.json +1 -0
- package/templates/action-rpg/package.json +7 -7
- package/templates/action-rpg/playtests/spells.playtest.json +20 -0
- package/templates/action-rpg/src/game.ts +1 -0
- package/templates/action-rpg/src/render/atmosphere.ts +5 -16
- package/templates/action-rpg/src/render/gpuSky.ts +4 -7
- package/templates/action-rpg/src/render/quality.ts +3 -1
- package/templates/action-rpg/src/scenes/Play.ts +26 -0
- package/templates/action-rpg/src/ui/AbilityBar.tsx +1 -1
- package/templates/action-rpg/threenative.config.ts +0 -3
- package/templates/adventure/AGENTS.md +87 -44
- package/templates/adventure/CLAUDE.md +87 -44
- package/templates/adventure/package.json +7 -7
- package/templates/collectathon/AGENTS.md +88 -42
- package/templates/collectathon/CLAUDE.md +88 -42
- package/templates/collectathon/package.json +7 -7
- package/templates/kart/AGENTS.md +82 -42
- package/templates/kart/CLAUDE.md +82 -42
- package/templates/kart/package.json +6 -6
- package/templates/minimal/AGENTS.md +100 -84
- package/templates/minimal/CLAUDE.md +100 -84
- package/templates/minimal/package.json +6 -6
- package/templates/minimal/src/render/atmosphere.ts +5 -16
- package/templates/minimal/src/render/gpuSky.ts +4 -7
- package/templates/platformer/AGENTS.md +90 -46
- package/templates/platformer/CLAUDE.md +90 -46
- package/templates/platformer/package.json +7 -7
- package/templates/puzzle/AGENTS.md +92 -80
- package/templates/puzzle/CLAUDE.md +92 -80
- package/templates/puzzle/package.json +7 -7
- package/templates/racing/AGENTS.md +95 -82
- package/templates/racing/CLAUDE.md +95 -82
- package/templates/racing/package.json +7 -7
- package/templates/racing/src/render/atmosphere.ts +5 -16
- package/templates/racing/src/render/gpuSky.ts +4 -7
- package/templates/rain/AGENTS.md +92 -84
- package/templates/rain/CLAUDE.md +92 -84
- package/templates/rain/native-playtests/lightning.playtest.json +85 -10
- package/templates/rain/package.json +6 -6
- package/templates/rain/playtests/reduced-motion.playtest.json +6 -0
- package/templates/rain/src/scenes/Boot.ts +1 -0
- package/templates/rain/src/state.ts +7 -0
- package/templates/rain/src/ui/GameUi.tsx +7 -1
- package/templates/rts/AGENTS.md +96 -85
- package/templates/rts/CLAUDE.md +96 -85
- package/templates/rts/package.json +6 -6
- package/templates/runner/AGENTS.md +92 -80
- package/templates/runner/CLAUDE.md +92 -80
- package/templates/runner/package.json +7 -7
- package/templates/runner/playtests/performance.playtest.json +1 -1
- package/templates/runner/src/render/atmosphere.ts +5 -16
- package/templates/runner/src/render/gpuSky.ts +4 -7
- package/templates/runner/src/render/lighting.ts +53 -11
- package/templates/runner/src/scenes/Run.ts +4 -3
- package/templates/runner/threenative.config.ts +0 -3
- package/templates/sailing/AGENTS.md +91 -79
- package/templates/sailing/CLAUDE.md +91 -79
- package/templates/sailing/package.json +7 -7
- package/templates/sailing/playtests/sails.playtest.json +1 -0
- package/templates/sailing/src/render/sky.ts +4 -0
- package/templates/sailing/threenative.config.ts +0 -3
- package/templates/shooter/AGENTS.md +93 -68
- package/templates/shooter/CLAUDE.md +93 -68
- package/templates/shooter/package.json +7 -7
- package/templates/shooter/src/render/atmosphere.ts +5 -16
- package/templates/shooter/src/render/gpuSky.ts +4 -7
- package/templates/shooter/src/render/quality.ts +3 -1
- package/templates/snow/AGENTS.md +90 -76
- package/templates/snow/CLAUDE.md +90 -76
- package/templates/snow/package.json +7 -7
- package/templates/snow/threenative.config.ts +0 -3
- package/templates/starter/AGENTS.md +104 -88
- package/templates/starter/CLAUDE.md +104 -88
- package/templates/starter/native-playtests/render-chain.playtest.json +24 -24
- package/templates/starter/native-playtests/smooth-motion.playtest.json +3 -3
- package/templates/starter/package.json +7 -7
- package/templates/starter/src/entities/Player.ts +10 -22
- package/templates/starter/src/render/atmosphere.ts +5 -16
- package/templates/starter/src/render/gpuSky.ts +4 -7
- package/templates/starter/src/render/lighting.ts +54 -4
- package/templates/starter/src/render/temporalAA.ts +8 -7
- package/templates/starter/src/render/temporalAAFrame.ts +30 -9
- package/templates/starter/src/render/temporalAAResolve.ts +15 -1
- package/templates/starter/src/render/temporalClampRelease.ts +183 -0
- package/templates/starter/src/render/temporalHistoryResolve.ts +90 -0
- package/templates/starter/src/render/temporalMoire.ts +190 -0
- package/templates/starter/src/render/temporalResolve.ts +75 -16
- package/templates/starter/src/render/temporalResolveDepth.ts +2 -0
- package/templates/starter/src/scenes/Play.ts +41 -29
- package/templates/tower-defense/AGENTS.md +92 -81
- package/templates/tower-defense/CLAUDE.md +92 -81
- package/templates/tower-defense/package.json +7 -7
- package/capabilities.json +0 -9197
- package/templates/AGENTS.md +0 -21
- package/templates/CLAUDE.md +0 -23
- package/templates/action-rpg/.codex/config.toml +0 -23
- package/templates/action-rpg/.cursor/mcp.json +0 -38
- package/templates/action-rpg/.gemini/settings.json +0 -38
- package/templates/action-rpg/.mcp.json +0 -38
- package/templates/action-rpg/.vscode/mcp.json +0 -43
- package/templates/action-rpg/.zed/settings.json +0 -43
- package/templates/action-rpg/opencode.json +0 -49
- package/templates/adventure/.codex/config.toml +0 -23
- package/templates/adventure/.cursor/mcp.json +0 -38
- package/templates/adventure/.gemini/settings.json +0 -38
- package/templates/adventure/.mcp.json +0 -38
- package/templates/adventure/.vscode/mcp.json +0 -43
- package/templates/adventure/.zed/settings.json +0 -43
- package/templates/adventure/opencode.json +0 -49
- package/templates/collectathon/.codex/config.toml +0 -23
- package/templates/collectathon/.cursor/mcp.json +0 -38
- package/templates/collectathon/.gemini/settings.json +0 -38
- package/templates/collectathon/.mcp.json +0 -38
- package/templates/collectathon/.vscode/mcp.json +0 -43
- package/templates/collectathon/.zed/settings.json +0 -43
- package/templates/collectathon/opencode.json +0 -49
- package/templates/kart/.codex/config.toml +0 -23
- package/templates/kart/.cursor/mcp.json +0 -38
- package/templates/kart/.gemini/settings.json +0 -38
- package/templates/kart/.mcp.json +0 -38
- package/templates/kart/.vscode/mcp.json +0 -43
- package/templates/kart/.zed/settings.json +0 -43
- package/templates/kart/opencode.json +0 -49
- package/templates/minimal/.codex/config.toml +0 -23
- package/templates/minimal/.cursor/mcp.json +0 -38
- package/templates/minimal/.gemini/settings.json +0 -38
- package/templates/minimal/.mcp.json +0 -38
- package/templates/minimal/.vscode/mcp.json +0 -43
- package/templates/minimal/.zed/settings.json +0 -43
- package/templates/minimal/opencode.json +0 -49
- package/templates/platformer/.codex/config.toml +0 -23
- package/templates/platformer/.cursor/mcp.json +0 -38
- package/templates/platformer/.gemini/settings.json +0 -38
- package/templates/platformer/.mcp.json +0 -38
- package/templates/platformer/.vscode/mcp.json +0 -43
- package/templates/platformer/.zed/settings.json +0 -43
- package/templates/platformer/opencode.json +0 -49
- package/templates/puzzle/.codex/config.toml +0 -23
- package/templates/puzzle/.cursor/mcp.json +0 -38
- package/templates/puzzle/.gemini/settings.json +0 -38
- package/templates/puzzle/.mcp.json +0 -38
- package/templates/puzzle/.vscode/mcp.json +0 -43
- package/templates/puzzle/.zed/settings.json +0 -43
- package/templates/puzzle/opencode.json +0 -49
- package/templates/racing/.codex/config.toml +0 -23
- package/templates/racing/.cursor/mcp.json +0 -38
- package/templates/racing/.gemini/settings.json +0 -38
- package/templates/racing/.mcp.json +0 -38
- package/templates/racing/.vscode/mcp.json +0 -43
- package/templates/racing/.zed/settings.json +0 -43
- package/templates/racing/opencode.json +0 -49
- package/templates/rain/.codex/config.toml +0 -23
- package/templates/rain/.cursor/mcp.json +0 -38
- package/templates/rain/.gemini/settings.json +0 -38
- package/templates/rain/.mcp.json +0 -38
- package/templates/rain/.vscode/mcp.json +0 -43
- package/templates/rain/.zed/settings.json +0 -43
- package/templates/rain/opencode.json +0 -49
- package/templates/rts/.codex/config.toml +0 -23
- package/templates/rts/.cursor/mcp.json +0 -38
- package/templates/rts/.gemini/settings.json +0 -38
- package/templates/rts/.mcp.json +0 -38
- package/templates/rts/.vscode/mcp.json +0 -43
- package/templates/rts/.zed/settings.json +0 -43
- package/templates/rts/opencode.json +0 -49
- package/templates/runner/.codex/config.toml +0 -23
- package/templates/runner/.cursor/mcp.json +0 -38
- package/templates/runner/.gemini/settings.json +0 -38
- package/templates/runner/.mcp.json +0 -38
- package/templates/runner/.vscode/mcp.json +0 -43
- package/templates/runner/.zed/settings.json +0 -43
- package/templates/runner/README.md +0 -43
- package/templates/runner/opencode.json +0 -49
- package/templates/sailing/.codex/config.toml +0 -23
- package/templates/sailing/.cursor/mcp.json +0 -38
- package/templates/sailing/.gemini/settings.json +0 -38
- package/templates/sailing/.mcp.json +0 -38
- package/templates/sailing/.vscode/mcp.json +0 -43
- package/templates/sailing/.zed/settings.json +0 -43
- package/templates/sailing/README.md +0 -28
- package/templates/sailing/opencode.json +0 -49
- package/templates/shooter/.codex/config.toml +0 -23
- package/templates/shooter/.cursor/mcp.json +0 -38
- package/templates/shooter/.gemini/settings.json +0 -38
- package/templates/shooter/.mcp.json +0 -38
- package/templates/shooter/.vscode/mcp.json +0 -43
- package/templates/shooter/.zed/settings.json +0 -43
- package/templates/shooter/opencode.json +0 -49
- package/templates/snow/.codex/config.toml +0 -23
- package/templates/snow/.cursor/mcp.json +0 -38
- package/templates/snow/.gemini/settings.json +0 -38
- package/templates/snow/.mcp.json +0 -38
- package/templates/snow/.vscode/mcp.json +0 -43
- package/templates/snow/.zed/settings.json +0 -43
- package/templates/snow/README.md +0 -26
- package/templates/snow/opencode.json +0 -49
- package/templates/starter/.codex/config.toml +0 -23
- package/templates/starter/.cursor/mcp.json +0 -38
- package/templates/starter/.gemini/settings.json +0 -38
- package/templates/starter/.mcp.json +0 -38
- package/templates/starter/.vscode/mcp.json +0 -43
- package/templates/starter/.zed/settings.json +0 -43
- package/templates/starter/opencode.json +0 -49
- package/templates/tower-defense/.codex/config.toml +0 -23
- package/templates/tower-defense/.cursor/mcp.json +0 -38
- package/templates/tower-defense/.gemini/settings.json +0 -38
- package/templates/tower-defense/.mcp.json +0 -38
- package/templates/tower-defense/.vscode/mcp.json +0 -43
- package/templates/tower-defense/.zed/settings.json +0 -43
- package/templates/tower-defense/README.md +0 -16
- package/templates/tower-defense/opencode.json +0 -49
|
@@ -70,6 +70,20 @@ export async function compileAssets( options: IAssetCompileOptions = { … }
|
|
|
70
70
|
const result = await compileAssets({ source: "assets", output: "public" });
|
|
71
71
|
```
|
|
72
72
|
|
|
73
|
+
### `cookTerrainWorld`
|
|
74
|
+
|
|
75
|
+
`function` — Bake evaluated terrain and static species into an instanced GLB and streaming world package.
|
|
76
|
+
|
|
77
|
+
```ts
|
|
78
|
+
export function cookTerrainWorld( options: IPreparedTerrainWorldOptions, ): Promise< { … }
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
- **Use when:** bake a terrain world headlessly into a GLB with instanced trees and rocks · generate a forest world for my game
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
await cookTerrainWorld({ state, species, out: "assets/world" });
|
|
85
|
+
```
|
|
86
|
+
|
|
73
87
|
### `dedupeMaterials`
|
|
74
88
|
|
|
75
89
|
`function` — Collapse materials that became identical once their textures shared an atlas page, and count the buckets a merge would find — before and after — so the promise can be checked rather than made.
|
|
@@ -340,6 +354,21 @@ export function texturePass(options: ITexturePassOptions = { … }
|
|
|
340
354
|
const pass = texturePass({ quality: 150 });
|
|
341
355
|
```
|
|
342
356
|
|
|
357
|
+
### `thinFoliageCards`
|
|
358
|
+
|
|
359
|
+
`function` — Build a standalone card-thinned foliage mesh, preserving opaque parts and vertex attributes.
|
|
360
|
+
|
|
361
|
+
```ts
|
|
362
|
+
export function thinFoliageCards(document: Document, keepRatio: number): number { … }
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
- **Use when:** prepare a far foliage mesh by thinning whole cards instead of triangles
|
|
366
|
+
- **Constraints:** mutates the supplied document; rejects unsupported MASK topology and invalid ratios
|
|
367
|
+
|
|
368
|
+
```ts
|
|
369
|
+
thinFoliageCards(document, 0.14);
|
|
370
|
+
```
|
|
371
|
+
|
|
343
372
|
### `totalCensus`
|
|
344
373
|
|
|
345
374
|
`function` — Census one glTF document, or a directory of them: the merge buckets a scene has now, and the buckets it would have once its atlasable textures shared pages.
|
|
@@ -434,7 +463,7 @@ addFoliageBackLight(leaf, backIrradiance);
|
|
|
434
463
|
|
|
435
464
|
### `addInSlices`
|
|
436
465
|
|
|
437
|
-
`function` — Attach hundreds of built objects to the scene in slices, presenting a frame between each.
|
|
466
|
+
`function` — Attach hundreds of built objects to the scene in slices with an 8 ms default budget, presenting a frame between each.
|
|
438
467
|
|
|
439
468
|
```ts
|
|
440
469
|
export async function addInSlices<T>( objects: Iterable<T>, add: (object: T, index: number) => void, options: IAddInSlicesOptions = { … }
|
|
@@ -1763,6 +1792,21 @@ export async function loadAll<TIn, TOut>( items: readonly TIn[], load: (item: TI
|
|
|
1763
1792
|
const species = await loadAll(names, (name) => ctx.assets.model(`flora/${name}.glb`));
|
|
1764
1793
|
```
|
|
1765
1794
|
|
|
1795
|
+
### `lodChainOf`
|
|
1796
|
+
|
|
1797
|
+
`function` — The cooked automatic LOD chain (`TN_discrete_lod`) a loaded geometry carries, or `undefined`. Its levels share the base's vertex attributes and differ only in index, and `errors` are each level's world-unit error in the base's own space. A caller that draws one geometry many times (an instanced batch, a streamed world level) reads the reduced shapes here instead of re-cooking.
|
|
1798
|
+
|
|
1799
|
+
```ts
|
|
1800
|
+
export function lodChainOf(geometry: BufferGeometry): ILodChain | undefined { … }
|
|
1801
|
+
```
|
|
1802
|
+
|
|
1803
|
+
- **Use when:** draw a cooked reduced level of a model in an instanced batch or streamed world level
|
|
1804
|
+
- **Constraints:** a geometry the loader built no chain for returns undefined
|
|
1805
|
+
|
|
1806
|
+
```ts
|
|
1807
|
+
const chain = lodChainOf(baseGeometryOf(mesh)); const far = chain?.levels.at(-1);
|
|
1808
|
+
```
|
|
1809
|
+
|
|
1766
1810
|
### `lodPixelScale`
|
|
1767
1811
|
|
|
1768
1812
|
`function` — The screen pixels one world unit covers at `depth` for this camera and viewport. Perspective divides the projected scale by the depth; orthographic has no depth term and uses the frustum height instead. This is the number a level of detail is chosen against: multiply a level's world-space error by it and you have the on-screen error a player can see, which is the comparison `updateModelLods` makes from the baked chain.
|
|
@@ -2837,6 +2881,21 @@ export class SurfaceLights { … }
|
|
|
2837
2881
|
const lamps = new SurfaceLights(lights); lamps.shade(point, normal, albedo, out, (i) => !occluded(i));
|
|
2838
2882
|
```
|
|
2839
2883
|
|
|
2884
|
+
### `thinCards`
|
|
2885
|
+
|
|
2886
|
+
`function` — A far level for a card mesh (needle or leaf quads): keep a share of its cards and grow each kept card about its own centre, so the crown holds its total surface area, as Unreal's Nanite "Preserve Area" foliage does. A simplifier cannot reduce disconnected cards, so the cooked chain leaves them at full count.
|
|
2887
|
+
|
|
2888
|
+
```ts
|
|
2889
|
+
export function thinCards(geometry: BufferGeometry, keep: number): BufferGeometry { … }
|
|
2890
|
+
```
|
|
2891
|
+
|
|
2892
|
+
- **Use when:** far trees draw too many alpha-tested needle or leaf card triangles
|
|
2893
|
+
- **Constraints:** the geometry must be indexed and carry no material groups, else it throws · keep is in (0, 1]; a share that drops nothing returns the same geometry · the choice is deterministic, and the source geometry is left untouched
|
|
2894
|
+
|
|
2895
|
+
```ts
|
|
2896
|
+
const far = thinCards(needles.geometry, 0.4); // 40% of the cards, same area
|
|
2897
|
+
```
|
|
2898
|
+
|
|
2840
2899
|
### `TracedReflections`
|
|
2841
2900
|
|
|
2842
2901
|
`class` — Reflection rays against the scene's triangles, in TSL. For a smooth surface, a ray finds what the screen cannot show (a room behind the camera, the far side of an object) and returns the hit's position, normal and material. The game lights the hit in its own stage. The kernel is plain TSL: float textures and a loop, no storage buffer.
|
|
@@ -3028,9 +3087,9 @@ tracker.commit(scene);
|
|
|
3028
3087
|
export class VirtualShadowNode extends ShadowBaseNode { … }
|
|
3029
3088
|
```
|
|
3030
3089
|
|
|
3031
|
-
- **Use when:** crisp shadows close to the player across a large outdoor level · shadow map too coarse over a big terrain · one directional light shadow for a whole open world · shadows shimmer when the camera moves
|
|
3090
|
+
- **Use when:** crisp shadows close to the player across a large outdoor level · shadow map too coarse over a big terrain · one directional light shadow for a whole open world · shadows shimmer when the camera moves · shadow edges, tree lighting or level sharpness change while a third-person camera turns around its hero
|
|
3032
3091
|
- **Constraints:** the light must be a DirectionalLight with `castShadow` and a target in the scene · clipExtents are half-widths in world units, finest first, strictly increasing · movers sort themselves: a layer-0 caster whose world matrix, instance matrix or deformation changed draws through the mover maps and leaves the cached levels, and returns to them after `staticAfterFrames` quiet frames; the cache redraws only the region it left · `trackCaster(object)` is the override that pins an object as a mover for good (it enables layer `VIRTUAL_SHADOW_MOVER_LAYER` on the object and its descendants), and `pinStatic(object)` opts an object out of detection; tracking or untracking refreshes only that object's region · call `object.layers.set(VIRTUAL_SHADOW_CASTER_LAYER)` for a mesh that exists only to cast; the level cameras already render that layer and the main camera never does
|
|
3033
|
-
- **Overrides:** bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults, and `marker: false` silences the TN_VIRTUAL_SHADOW line, not the measurement · bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults · followViewFocus: false keeps eye follow; receiverPlaneBias: false uses only authored bias · minWindowAspect: below 1, a level is as high as `sin(sun elevation)` times its width, never under this, so a low sun's floor shadows keep the texel density of a high sun's; the default 1 keeps square levels
|
|
3092
|
+
- **Overrides:** bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults, and `marker: false` silences the TN_VIRTUAL_SHADOW line, not the measurement · bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults · setFocus(point) centres every window on a subject (a third-person hero) instead of the eye, so an orbiting eye moves no shadow; setFocus(undefined) hands them back · followViewFocus: false keeps eye follow; receiverPlaneBias: false uses only authored bias · minWindowAspect: below 1, a level is as high as `sin(sun elevation)` times its width, never under this, so a low sun's floor shadows keep the texel density of a high sun's; the default 1 keeps square levels
|
|
3034
3093
|
|
|
3035
3094
|
```ts
|
|
3036
3095
|
const sun = new DirectionalLight(0xffffff, 3);
|
|
@@ -3310,6 +3369,270 @@ const root = createCssUiRoot();
|
|
|
3310
3369
|
root.render(createElement("section", { className: "fixed inset-0 bg-zinc-900/90" }, "READY"));
|
|
3311
3370
|
```
|
|
3312
3371
|
|
|
3372
|
+
## `@threenative/core/spells`
|
|
3373
|
+
|
|
3374
|
+
### `CastPool`
|
|
3375
|
+
|
|
3376
|
+
`class` — Step a spell's timeline: charge, release, travel, impact, linger, done.
|
|
3377
|
+
|
|
3378
|
+
```ts
|
|
3379
|
+
export class CastPool { … }
|
|
3380
|
+
```
|
|
3381
|
+
|
|
3382
|
+
- **Use when:** a fireball or a lightning bolt that charges, flies, lands and lingers · several spells mid-flight, with no allocation per cast
|
|
3383
|
+
- **Constraints:** the pool is fixed and recycles the cast alive longest; it never grows · a ball that has passed its target lands on the target, however late the frame notices
|
|
3384
|
+
- **Overrides:** timing, shape, speed and radius come from the spell; a cast may override shape and seed
|
|
3385
|
+
|
|
3386
|
+
```ts
|
|
3387
|
+
const casts = new CastPool(world);
|
|
3388
|
+
casts.cast(fireball, target, { from: hand });
|
|
3389
|
+
casts.update(dt);
|
|
3390
|
+
```
|
|
3391
|
+
|
|
3392
|
+
### `createAegis`
|
|
3393
|
+
|
|
3394
|
+
`function` — A ward around the caster: it forms, holds, and breaks outward when it expires.
|
|
3395
|
+
|
|
3396
|
+
```ts
|
|
3397
|
+
export function createAegis(world: SpellWorld, overrides: IFireSpellOverrides = { … }
|
|
3398
|
+
```
|
|
3399
|
+
|
|
3400
|
+
- **Use when:** a shield spell a player casts on themselves · a magic barrier that forms around the caster · make a protective bubble spell · a defensive bubble that flashes when it breaks
|
|
3401
|
+
- **Constraints:** every colour, size, count and timing is a named override on the call
|
|
3402
|
+
- **Overrides:** core, highlight, charge, impact, linger, radius, light · core, highlight, charge, impact, linger, radius, light, shake
|
|
3403
|
+
|
|
3404
|
+
```ts
|
|
3405
|
+
const aegis = createAegis(world);
|
|
3406
|
+
casts.cast(aegis, world.focus);
|
|
3407
|
+
```
|
|
3408
|
+
|
|
3409
|
+
### `createArcaneBarrage`
|
|
3410
|
+
|
|
3411
|
+
`function` — A volley of arcane missiles: fast, precise, and each one pops on arrival.
|
|
3412
|
+
|
|
3413
|
+
```ts
|
|
3414
|
+
export function createArcaneBarrage(world: SpellWorld, overrides: IFireSpellOverrides = { … }
|
|
3415
|
+
```
|
|
3416
|
+
|
|
3417
|
+
- **Use when:** an arcane missile spell that fires projectiles at a target · a magic barrage a mage class spams · a magic missile spell · make an arcane bolt spell · an arcane missile spell that fires several projectiles at a target · a pink energy bolt with a short charge
|
|
3418
|
+
- **Constraints:** every colour, size, count and timing is a named override on the call
|
|
3419
|
+
- **Overrides:** core, highlight, speed, charge, impact, linger, radius, burst, light
|
|
3420
|
+
|
|
3421
|
+
```ts
|
|
3422
|
+
const barrage = createArcaneBarrage(world);
|
|
3423
|
+
casts.cast(barrage, target);
|
|
3424
|
+
```
|
|
3425
|
+
|
|
3426
|
+
### `createFireball`
|
|
3427
|
+
|
|
3428
|
+
`function` — A ball of fire that charges, crosses the room and leaves the floor burning.
|
|
3429
|
+
|
|
3430
|
+
```ts
|
|
3431
|
+
export function createFireball(world: SpellWorld, overrides: IFireSpellOverrides = { … }
|
|
3432
|
+
```
|
|
3433
|
+
|
|
3434
|
+
- **Use when:** a fireball spell the player casts at an enemy · a burning projectile that explodes and scorches the ground · a wizard's fire attack with a wind-up, a flight and an aftermath · make a fireball · a fireball spell a player casts at an enemy
|
|
3435
|
+
- **Constraints:** every colour, size, count and timing is a named override on the call · the first cast costs what the hundredth does: nothing is built at cast time · the stock look ships as the default, and no override rebuilds a pipeline
|
|
3436
|
+
- **Overrides:** core, highlight, speed, charge, impact, linger, radius, burst, trail, lingerBurst, light, shake, scorch
|
|
3437
|
+
|
|
3438
|
+
```ts
|
|
3439
|
+
const fireball = createFireball(world);
|
|
3440
|
+
casts.cast(fireball, target);
|
|
3441
|
+
```
|
|
3442
|
+
|
|
3443
|
+
### `createGlacialSpike`
|
|
3444
|
+
|
|
3445
|
+
`function` — A shard of ice that flies flat and fast, and freezes the ground it breaks on.
|
|
3446
|
+
|
|
3447
|
+
```ts
|
|
3448
|
+
export function createGlacialSpike(world: SpellWorld, overrides: IFireSpellOverrides = { … }
|
|
3449
|
+
```
|
|
3450
|
+
|
|
3451
|
+
- **Use when:** an ice spike spell that flies at a target and shatters · a freezing projectile that leaves frost on the floor · make an ice spell · a cold spell with a charge, a flight and a lingering chill
|
|
3452
|
+
- **Constraints:** every colour, size, count and timing is a named override on the call
|
|
3453
|
+
- **Overrides:** core, highlight, speed, charge, impact, linger, radius, burst, trail, light
|
|
3454
|
+
|
|
3455
|
+
```ts
|
|
3456
|
+
const spike = createGlacialSpike(world);
|
|
3457
|
+
casts.cast(spike, target);
|
|
3458
|
+
```
|
|
3459
|
+
|
|
3460
|
+
### `createInferno`
|
|
3461
|
+
|
|
3462
|
+
`function` — A pillar of fire that erupts where it lands and keeps burning.
|
|
3463
|
+
|
|
3464
|
+
```ts
|
|
3465
|
+
export function createInferno(world: SpellWorld, overrides: IFireSpellOverrides = { … }
|
|
3466
|
+
```
|
|
3467
|
+
|
|
3468
|
+
- **Use when:** a fire area spell that erupts at a point and burns there · an inferno column a boss drops on the arena · make a sustained fire area spell · a sustained flame that scorches the ground for seconds
|
|
3469
|
+
- **Constraints:** every colour, size, count and timing is a named override on the call
|
|
3470
|
+
- **Overrides:** core, highlight, charge, impact, linger, radius, burst, trail, light, shake, scorch
|
|
3471
|
+
|
|
3472
|
+
```ts
|
|
3473
|
+
const inferno = createInferno(world);
|
|
3474
|
+
casts.cast(inferno, target);
|
|
3475
|
+
```
|
|
3476
|
+
|
|
3477
|
+
### `createSpell`
|
|
3478
|
+
|
|
3479
|
+
`function` — Build a spell from a recipe: four beats, a tint, and the numbers between them.
|
|
3480
|
+
|
|
3481
|
+
```ts
|
|
3482
|
+
export function createSpell(world: SpellWorld, recipe: ISpellRecipe): ISpell { … }
|
|
3483
|
+
```
|
|
3484
|
+
|
|
3485
|
+
- **Use when:** author a spell the catalog does not cover, out of the same beats
|
|
3486
|
+
- **Constraints:** read the world through SpellWorld only, so a game can swap the scene and the floor
|
|
3487
|
+
|
|
3488
|
+
```ts
|
|
3489
|
+
const spell = createSpell(world, recipe);
|
|
3490
|
+
```
|
|
3491
|
+
|
|
3492
|
+
### `createThunderstrike`
|
|
3493
|
+
|
|
3494
|
+
`function` — A bolt out of the sky: it charges, strikes the point instantly, and the ground remembers it.
|
|
3495
|
+
|
|
3496
|
+
```ts
|
|
3497
|
+
export function createThunderstrike(world: SpellWorld, overrides: IFireSpellOverrides = { … }
|
|
3498
|
+
```
|
|
3499
|
+
|
|
3500
|
+
- **Use when:** a lightning strike spell that hits a point immediately · a thunderbolt with a wind-up and a burnt mark where it lands · make a lightning spell · an electrical spell with a column of light from above
|
|
3501
|
+
- **Constraints:** every colour, size, count and timing is a named override on the call
|
|
3502
|
+
- **Overrides:** core, highlight, charge, impact, linger, radius, light, shake, scorch
|
|
3503
|
+
|
|
3504
|
+
```ts
|
|
3505
|
+
const bolt = createThunderstrike(world);
|
|
3506
|
+
casts.cast(bolt, target);
|
|
3507
|
+
```
|
|
3508
|
+
|
|
3509
|
+
### `ParticleKindTable`
|
|
3510
|
+
|
|
3511
|
+
`class` — Tune what a particle kind does, as data rather than a shader.
|
|
3512
|
+
|
|
3513
|
+
```ts
|
|
3514
|
+
export class ParticleKindTable { … }
|
|
3515
|
+
```
|
|
3516
|
+
|
|
3517
|
+
- **Use when:** retune a spell's particles at run time from a settings screen · change how long, how fast or how heavy a kind of particle is without a new pipeline
|
|
3518
|
+
- **Constraints:** set writes uniforms; no kernel, material or pipeline is rebuilt · a table knows only the kinds it was asked for, so an unused kind costs nothing
|
|
3519
|
+
- **Overrides:** lifetime, size, speed, cone, gravity, drag, buoyancy, alpha, colour and highlight
|
|
3520
|
+
|
|
3521
|
+
```ts
|
|
3522
|
+
const kinds = new ParticleKindTable(["flame", "smoke"]);
|
|
3523
|
+
kinds.set("flame", { lifetime: [0.3, 0.6], colour: [0.4, 0.8, 1] });
|
|
3524
|
+
```
|
|
3525
|
+
|
|
3526
|
+
### `ReactionField`
|
|
3527
|
+
|
|
3528
|
+
`class` — The marks a spell leaves on the floor: heat, char, wet, frost, crack and glow.
|
|
3529
|
+
|
|
3530
|
+
```ts
|
|
3531
|
+
export class ReactionField { … }
|
|
3532
|
+
```
|
|
3533
|
+
|
|
3534
|
+
- **Use when:** a fireball impact that leaves a scorch and fades over time · ice that melts where lightning spread, or a lava geyser's crack
|
|
3535
|
+
- **Constraints:** it draws nothing; the game decides what a mark looks like · the patch is finite and every channel decays on its own half-life
|
|
3536
|
+
- **Overrides:** halfLife, resolution and size tune the patch; pattern, radius, seed and angle set each mark
|
|
3537
|
+
|
|
3538
|
+
```ts
|
|
3539
|
+
field.splat({ heat: 1, char: 0.6, radius: 2.5, x: hit.x, z: hit.z });
|
|
3540
|
+
field.update(dt);
|
|
3541
|
+
```
|
|
3542
|
+
|
|
3543
|
+
### `SpellLights`
|
|
3544
|
+
|
|
3545
|
+
`class` — A fixed pool of spell lights, created once at zero intensity.
|
|
3546
|
+
|
|
3547
|
+
```ts
|
|
3548
|
+
export class SpellLights { … }
|
|
3549
|
+
```
|
|
3550
|
+
|
|
3551
|
+
- **Use when:** a spell impact that glows without changing the light count · a charge glow or a falling meteor lighting what it passes
|
|
3552
|
+
- **Constraints:** the whole pool exists before the first cast; a cast changes intensity, never the list · flash returns undefined when the pool is busy; a spell carries on without one
|
|
3553
|
+
- **Overrides:** count is the pool size; each flash supplies position, colour, intensity, range and seconds
|
|
3554
|
+
|
|
3555
|
+
```ts
|
|
3556
|
+
lights.flash({ x, y, z, color, intensity: 40, range: 12, seconds: 0.35 });
|
|
3557
|
+
```
|
|
3558
|
+
|
|
3559
|
+
### `SpellWorld`
|
|
3560
|
+
|
|
3561
|
+
`class` — Everything a spell may touch: the scene, the floor, the light pool, the surface field, one shake and one flash limiter.
|
|
3562
|
+
|
|
3563
|
+
```ts
|
|
3564
|
+
export class SpellWorld implements ICastEnvironment { … }
|
|
3565
|
+
```
|
|
3566
|
+
|
|
3567
|
+
- **Use when:** cast an engine spell without passing a scene into every call · honour an accessibility setting that limits flashing
|
|
3568
|
+
- **Constraints:** damage, mana, cooldowns and who the target is stay in the game · with reducedFlashes on, a fourth flash inside one second is refused, never dimmed
|
|
3569
|
+
- **Overrides:** groundAt, castSlots, lightCount, reaction, shake and reducedFlashes are named options
|
|
3570
|
+
|
|
3571
|
+
```ts
|
|
3572
|
+
const world = new SpellWorld({ scene, groundAt });
|
|
3573
|
+
const casts = new CastPool(world);
|
|
3574
|
+
```
|
|
3575
|
+
|
|
3576
|
+
## `@threenative/core/spells/ultra`
|
|
3577
|
+
|
|
3578
|
+
### `bakeNoise`
|
|
3579
|
+
|
|
3580
|
+
`function` — CPU bake of the Ultra Elements 3D noise, curl and blackbody textures that every spell volume samples.
|
|
3581
|
+
|
|
3582
|
+
```ts
|
|
3583
|
+
export function bakeNoise( { … }
|
|
3584
|
+
```
|
|
3585
|
+
|
|
3586
|
+
- **Use when:** the noise and blackbody textures an Ultra Elements spell needs before it first draws
|
|
3587
|
+
- **Constraints:** costs about 0.6 s at 64^3 and about 5 s at 128^3 on the main thread; bake once at load
|
|
3588
|
+
|
|
3589
|
+
```ts
|
|
3590
|
+
bakeNoise({ noiseSize: 64 }); // once at load, before createFx draws
|
|
3591
|
+
```
|
|
3592
|
+
|
|
3593
|
+
### `createFx`
|
|
3594
|
+
|
|
3595
|
+
`function` — The shared Ultra Elements spell world: casts, volumes, spell lights and the per-frame CPU tick. Add `fx.scenes.fx` to the scene, `addSpell` each ported spell, call `renderFrame(dt)` each frame.
|
|
3596
|
+
|
|
3597
|
+
```ts
|
|
3598
|
+
export function createFx(o: IFxOptions) { … }
|
|
3599
|
+
```
|
|
3600
|
+
|
|
3601
|
+
- **Use when:** an Ultra Elements spell such as the raymarched teardrop Fireball cast at a target · a volumetric fire spell drawn through the Three.js TSL node API on WebGPU
|
|
3602
|
+
- **Constraints:** call bakeNoise first: the volume shaders sample its noise, curl and blackbody textures
|
|
3603
|
+
|
|
3604
|
+
```ts
|
|
3605
|
+
const ultra = createFx({ camera, size: () => ({ width: innerWidth, height: innerHeight }), seed: 777 }); const fireball = ultra.addSpell(fire); scene.add(ultra.fx.scenes.fx);
|
|
3606
|
+
```
|
|
3607
|
+
|
|
3608
|
+
### `groundShade`
|
|
3609
|
+
|
|
3610
|
+
`function` — The Ultra Elements arena floor's response to the ground field and spell impacts (scorch, char, wet, glowing hot ground) as nodes for a game's own floor material: `color`, `roughness`, `metalness`, `emissive` from the floor's own surface at a world position.
|
|
3611
|
+
|
|
3612
|
+
```ts
|
|
3613
|
+
export function groundShade(wp: V3, surface: IGroundSurface) { … }
|
|
3614
|
+
```
|
|
3615
|
+
|
|
3616
|
+
- **Use when:** a floor that shows the Fireball's scorch and hot ground cooling over seconds
|
|
3617
|
+
|
|
3618
|
+
```ts
|
|
3619
|
+
const shade = groundShade(positionWorld, { albedo, rough: float(0.85), metal: float(0) }); floor.colorNode = vec4(shade.color, 1);
|
|
3620
|
+
```
|
|
3621
|
+
|
|
3622
|
+
### `Particles`
|
|
3623
|
+
|
|
3624
|
+
`class` — The Ultra Elements GPU particle system behind `fx.particles`: a spell's kinds, emitters and field emitters.
|
|
3625
|
+
|
|
3626
|
+
```ts
|
|
3627
|
+
export class Particles { … }
|
|
3628
|
+
```
|
|
3629
|
+
|
|
3630
|
+
- **Use when:** the flames, embers, sparks, smoke and debris an Ultra Elements spell emits as it charges, flies and hits
|
|
3631
|
+
|
|
3632
|
+
```ts
|
|
3633
|
+
const flames = ultra.fx.particles.emitter("fire.flame"); // ultra from createFx
|
|
3634
|
+
```
|
|
3635
|
+
|
|
3313
3636
|
## `@threenative/core/ui-layer`
|
|
3314
3637
|
|
|
3315
3638
|
### `connectUiBridge`
|
|
@@ -3434,6 +3757,53 @@ const handle = startWorkerGame(new Worker(new URL("./worker.ts", import.meta.url
|
|
|
3434
3757
|
|
|
3435
3758
|
## `@threenative/core/world`
|
|
3436
3759
|
|
|
3760
|
+
### `applyTerrainSurface`
|
|
3761
|
+
|
|
3762
|
+
`function` — Apply a cooked GLB's package-authored layered surface to its marked terrain meshes. `url` is the loaded GLB URL; extras pointers are relative to it. Uses the same asset/fetch path as loadTerrainSplat on web and native. The caller owns the assigned materials' lifetime.
|
|
3763
|
+
|
|
3764
|
+
```ts
|
|
3765
|
+
export async function applyTerrainSurface( root: Object3D, options: ILoadTerrainSplatOptions, ): Promise<void> { … }
|
|
3766
|
+
```
|
|
3767
|
+
|
|
3768
|
+
- **Use when:** apply the authored layered terrain surface after loading a cooked world GLB
|
|
3769
|
+
- **Constraints:** url names the loaded GLB; tnTerrainSurface extras name a relative world package JSON
|
|
3770
|
+
- **Overrides:** `table` may replace `base`, `breakup`, `macro` and `layers`; baked `splat` and `textures` stay package-owned
|
|
3771
|
+
|
|
3772
|
+
```ts
|
|
3773
|
+
await applyTerrainSurface(world.scene, { assets: ctx.assets, renderer: ctx.renderer, url: "world/world.glb" });
|
|
3774
|
+
```
|
|
3775
|
+
|
|
3776
|
+
### `bakedFractalNoise`
|
|
3777
|
+
|
|
3778
|
+
`function` — Drop-in for `mx_fractal_noise_float(p, octaves, lacunarity, diminish, amplitude)`: one read an octave.
|
|
3779
|
+
|
|
3780
|
+
```ts
|
|
3781
|
+
export function bakedFractalNoise( p: Node<"vec3">, octaves = 3, lacunarity = 2, diminish = 0.5, amplitude: Scalar = 1, ): Node<"float"> { … }
|
|
3782
|
+
```
|
|
3783
|
+
|
|
3784
|
+
- **Use when:** fractal or fbm noise in a material costs too much GPU time per pixel
|
|
3785
|
+
- **Constraints:** octaves is a build-time number; each octave is one filtered volume read
|
|
3786
|
+
|
|
3787
|
+
```ts
|
|
3788
|
+
const macro = bakedFractalNoise(vec3(positionWorld.x, 0, positionWorld.z).mul(0.014), 3);
|
|
3789
|
+
```
|
|
3790
|
+
|
|
3791
|
+
### `bakedNoise`
|
|
3792
|
+
|
|
3793
|
+
`function` — Drop-in for `mx_noise_float(p, amplitude, pivot)` on a vec3 `p`: one filtered read of the baked volume instead of the per-pixel Perlin. Only the 3D form: three's 2D Perlin is another function (0.66 scale), so a vec2 caller keeps `mx_noise_float`. `channel` 1 to 3 are independent fields.
|
|
3794
|
+
|
|
3795
|
+
```ts
|
|
3796
|
+
export function bakedNoise( p: Node<"vec3">, amplitude: Scalar = 1, pivot: Scalar = 0, channel: 0 | 1 | 2 | 3 = 0, ): Node<"float"> { … }
|
|
3797
|
+
```
|
|
3798
|
+
|
|
3799
|
+
- **Use when:** a terrain, foliage or water shader calls mx_noise_float per pixel and the frame is GPU bound · open world ground material with procedural variation that must hold 60 FPS
|
|
3800
|
+
- **Constraints:** the field tiles every NOISE_PERIOD units of p; at p = world metres x 2.6 that is a 3 m repeat · vec3 input only: three's 2D Perlin is another function
|
|
3801
|
+
- **Overrides:** keep mx_noise_float where exact analytic noise matters more than the frame
|
|
3802
|
+
|
|
3803
|
+
```ts
|
|
3804
|
+
const patch = smoothstep(-0.35, 0.35, bakedNoise(positionWorld.mul(0.025)));
|
|
3805
|
+
```
|
|
3806
|
+
|
|
3437
3807
|
### `cellPlacements`
|
|
3438
3808
|
|
|
3439
3809
|
`function` — Borrow the run's placement records as a live view over the placement buffer.
|
|
@@ -3481,6 +3851,21 @@ export class Heightfield extends Group implements IComputeDriven { … }
|
|
|
3481
3851
|
const field = Heightfield.fromSampler({ rows: 65, columns: 65, width: 64, depth: 64, origin: { x: 0, z: 0 }, sampleHeight: terrainHeight });
|
|
3482
3852
|
```
|
|
3483
3853
|
|
|
3854
|
+
### `HeightfieldCollar`
|
|
3855
|
+
|
|
3856
|
+
`class` — A heightfield's far ring: `rings` square rings past its playable square, one vertex per boundary sample, and the index grid that draws them.
|
|
3857
|
+
|
|
3858
|
+
```ts
|
|
3859
|
+
export class HeightfieldCollar { … }
|
|
3860
|
+
```
|
|
3861
|
+
|
|
3862
|
+
- **Use when:** draw the terrain past the playable square without hand-building a ring grid · ground a character past the square, out to the walk band, on drawn triangles
|
|
3863
|
+
- **Constraints:** every ring vertex asks the game's `height` callback; core owns no terrain look · the collar is a ring of triangles, not a field: `heightAt` answers on it and null off it
|
|
3864
|
+
|
|
3865
|
+
```ts
|
|
3866
|
+
const collar = new HeightfieldCollar({ resolution: 129, size: 512, rings: 384, ringDistance: (ring) => (ring / 384) ** 1.65 * 2100, walkBand: 200, height: ({ x, z }) => surveyed.heightAt(x, z) });
|
|
3867
|
+
```
|
|
3868
|
+
|
|
3484
3869
|
### `heightSamplerFromHeightmap`
|
|
3485
3870
|
|
|
3486
3871
|
`function` — Build a game-usable `sampleHeight` from a raw v1 heightmap. The returned function interpolates bilinearly in world units and clamps to the map edges, so it plugs straight into `Heightfield.fromSampler` and `TerrainTiles`. Height is `heightMin + v / 65535 * (heightMax - heightMin)` at vertex `(column, row)`.
|
|
@@ -3496,6 +3881,35 @@ export function heightSamplerFromHeightmap( terrain: IWorldTerrain, extent: IWor
|
|
|
3496
3881
|
const sampleHeight = heightSamplerFromHeightmap(terrain, extent, await loadWorldHeightmap(url));
|
|
3497
3882
|
```
|
|
3498
3883
|
|
|
3884
|
+
### `instanceRandom`
|
|
3885
|
+
|
|
3886
|
+
`function` — A random in [0, 1) that stays with its instance, as UE 5.8.3's PerInstanceRandom: hashed from the instance's world origin, never from its draw slot. WorldCells repacks instances on every refilter, main-pass cull and LOD switch, so `instanceIndex` names another tree from one frame to the next; a wind phase hashed from it re-rolled each crown about every 0.7 s of a walk and snapped its top by a median 0.37 m. Parts of one placement share its translation, so its bark and needles read one value.
|
|
3887
|
+
|
|
3888
|
+
```ts
|
|
3889
|
+
export function instanceRandom(): Node<"float"> { … }
|
|
3890
|
+
```
|
|
3891
|
+
|
|
3892
|
+
- **Use when:** a per-instance random number that stays with each streamed placement as WorldCells repacks · replace instanceIndex in a WorldCells part material, which WorldCells refuses
|
|
3893
|
+
|
|
3894
|
+
```ts
|
|
3895
|
+
const phase = instanceRandom().mul(6.2831);
|
|
3896
|
+
```
|
|
3897
|
+
|
|
3898
|
+
### `lakeReach`
|
|
3899
|
+
|
|
3900
|
+
`function` — How far a lake's water reaches: the waterline its basin measures, `margin` times out, capped. The drawn surface and the swim footprint both size themselves here, so the shore a player sees is the shore they stop at.
|
|
3901
|
+
|
|
3902
|
+
```ts
|
|
3903
|
+
export function lakeReach(field: Heightfield, lake: IWaterLake): number { … }
|
|
3904
|
+
```
|
|
3905
|
+
|
|
3906
|
+
- **Use when:** size a lake's footprint from its basin and the cap its biome row names
|
|
3907
|
+
- **Constraints:** reads the heightfield at every bearing, once per lake, never per frame
|
|
3908
|
+
|
|
3909
|
+
```ts
|
|
3910
|
+
const reach = lakeReach(field, { ...lake, margin: 1.12 });
|
|
3911
|
+
```
|
|
3912
|
+
|
|
3499
3913
|
### `loadTerrainSplat`
|
|
3500
3914
|
|
|
3501
3915
|
`function` — The splat terrain surface a world package describes, for `WorldCells.load({ surface })`. Layers blend over a base by mask channels read as linear data (the masks ship raw, beside the heightmap, so no cook moves a blend threshold), with noise-broken edges and macro brightness variation. Texture sets tile in world metres on the package's ground plane (x, -z: a Z-up authoring tool's x and y), cliffs can be triplanar, and the base plus any layer that asks carries a normal map. Each layer answers light from its own ORM map where the table ships one and from the table's own roughness and metalness where it does not; a layer that states neither is matte and dielectric, and named in a warning. Nothing here is a look choice: textures, tiles, tints, thresholds, surface response and noise scales all come from the package's table, which the game authors once and its DCC shares.
|
|
@@ -3506,7 +3920,7 @@ export async function loadTerrainSplat(options: ILoadTerrainSplatOptions): Promi
|
|
|
3506
3920
|
|
|
3507
3921
|
- **Use when:** terrain textured by splat masks exported from Blender with the world package · the game's terrain should match the DCC's terrain material without a second copy
|
|
3508
3922
|
- **Constraints:** the package's world.json must carry `terrain.layers.table` and `terrain.layers.splat`, written by `export_terrain_layers` in the `export_world.py` recipe · WebGPU allows 16 sampled textures per stage: same-size layers stack into one array texture per set, and `TN_TERRAIN_SPLAT samplers=<n>` reports what is left
|
|
3509
|
-
- **Overrides:**
|
|
3923
|
+
- **Overrides:** `table` may replace `base`, `breakup`, `macro` and `layers` from game source; baked `splat` and `textures` stay package-owned
|
|
3510
3924
|
|
|
3511
3925
|
```ts
|
|
3512
3926
|
const surface = await loadTerrainSplat({ assets: ctx.assets, renderer: ctx.renderer, url: "world/world.json" });
|
|
@@ -3528,6 +3942,21 @@ export async function loadWorldHeightmap(url: string): Promise<Uint16Array> {
|
|
|
3528
3942
|
const data = await loadWorldHeightmap("/world/terrain/heightmap.u16");
|
|
3529
3943
|
```
|
|
3530
3944
|
|
|
3945
|
+
### `noiseVolume`
|
|
3946
|
+
|
|
3947
|
+
`function` — The one volume every material shares: baked on first use, 1 MiB of RGBA8 (it stays in L2).
|
|
3948
|
+
|
|
3949
|
+
```ts
|
|
3950
|
+
export function noiseVolume(): Data3DTexture { … }
|
|
3951
|
+
```
|
|
3952
|
+
|
|
3953
|
+
- **Use when:** a material needs the raw baked noise texture to sample in its own TSL
|
|
3954
|
+
- **Constraints:** baked once per page on the main thread (about 0.15 s); every channel is an independent field
|
|
3955
|
+
|
|
3956
|
+
```ts
|
|
3957
|
+
const volume = noiseVolume();
|
|
3958
|
+
```
|
|
3959
|
+
|
|
3531
3960
|
### `snowDiscFootprint`
|
|
3532
3961
|
|
|
3533
3962
|
`function` — A circular contact footprint, sized from a radius the caller measures. The shape a sphere, a ball, a wheel or a probe presses into snow, and the default the physics binding derives from a sphere's contact geometry. Flat inside the radius, eased over the softness band, with a raised rim just outside it.
|
|
@@ -3614,29 +4043,59 @@ export function validateWorldPackage( manifest: unknown, options: IWorldPackageV
|
|
|
3614
4043
|
const { ok, errors } = validateWorldPackage(json, { placementsByteLength: buffer.byteLength });
|
|
3615
4044
|
```
|
|
3616
4045
|
|
|
3617
|
-
### `
|
|
4046
|
+
### `WaterBodies`
|
|
3618
4047
|
|
|
3619
|
-
`class` —
|
|
4048
|
+
`class` — One world's water, queried: surface height, current and footprint from the baked arrays. Rendering and physics read the same store, as they do for `Heightfield`, so the surface a player sees and the surface a swimmer rests on cannot disagree. Every station, level, extent and speed comes from the game, and the shading stays in the game's own `src/render/`. A river's segments sit in a uniform grid, so a query tests the few that can reach its cell instead of every station of every river.
|
|
3620
4049
|
|
|
3621
4050
|
```ts
|
|
3622
|
-
export class
|
|
4051
|
+
export class WaterBodies { … }
|
|
3623
4052
|
```
|
|
3624
4053
|
|
|
3625
|
-
- **Use when:**
|
|
3626
|
-
- **Constraints:**
|
|
3627
|
-
- **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
|
|
4054
|
+
- **Use when:** ask how high the water is where a player swims · ask which way a current carries a body · ask which water body covers a point, and how high its surface is · share one water store between rendering and physics
|
|
4055
|
+
- **Constraints:** every station, level, extent and speed comes from the game's own bake; a lake is measured on the field passed in
|
|
3628
4056
|
|
|
3629
4057
|
```ts
|
|
3630
|
-
const
|
|
3631
|
-
scene.add(world);
|
|
3632
|
-
world.update();
|
|
4058
|
+
const water = new WaterBodies({ ribbons, lakes, field }); const height = water.surfaceAt(x, z);
|
|
3633
4059
|
```
|
|
3634
4060
|
|
|
3635
|
-
|
|
3636
|
-
|
|
3637
|
-
### `assertAssetPath`
|
|
4061
|
+
### `waterlineRadius`
|
|
3638
4062
|
|
|
3639
|
-
`function` —
|
|
4063
|
+
`function` — The furthest a lake's basin reaches on a bearing: where the drawn ground crosses its level. Twenty-four bearings step outwards and stop at the first bank, because binary-searching the whole ray can jump a dry ridge into another pond. Eighteen halvings land inside two centimetres at this scale, well under the ground's own sample spacing.
|
|
4064
|
+
|
|
4065
|
+
```ts
|
|
4066
|
+
export function waterlineRadius( field: Heightfield, centre: readonly number[], level: number, ): number { … }
|
|
4067
|
+
```
|
|
4068
|
+
|
|
4069
|
+
- **Use when:** measure where a lake's water meets the ground it floods · size a lake's drawn surface or the footprint a swimmer may enter
|
|
4070
|
+
- **Constraints:** returns metres on the furthest bearing; the caller applies its own cap
|
|
4071
|
+
|
|
4072
|
+
```ts
|
|
4073
|
+
const reach = waterlineRadius(field, lake.at, lake.level) * 1.12;
|
|
4074
|
+
```
|
|
4075
|
+
|
|
4076
|
+
### `WorldCells`
|
|
4077
|
+
|
|
4078
|
+
`class` — Stream a Blender-authored world package by cell and keep it resident around a followed point. The class composes `TerrainTiles` for the package's heightmap, builds one `InstancedBatch` per resident cell asset run, distance level and mesh part, and loads hand-placed chunk GLBs through `loadAll` + `addInSlices`. Ring residency, CPU per-asset `maxDistance` filtering, GPU dispatch culling, the per-asset `lods` levels, hard budgets and generation-tokened cancellation all live here; every geometry, material and surface still comes from the package's GLBs and the game. An asset is drawn per part, not per model: a GLB with several primitives is one `InstancedBatch` each, and a scattered part whose own material is transparent draws as an alpha cutout unless the game asks for blending, because an `InstancedMesh` cannot sort its instances. An asset with no nonempty authored `lods` can draw its own model's baked AutoLOD chain at distances measured over the `autoLod` viewport. An explicit empty list enrolls only unchanged static parts; section ranges, custom attributes, alpha foliage and vertex deformation retain source geometry.
|
|
4079
|
+
|
|
4080
|
+
```ts
|
|
4081
|
+
export class WorldCells extends Group implements IComputeDriven { … }
|
|
4082
|
+
```
|
|
4083
|
+
|
|
4084
|
+
- **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
|
|
4085
|
+
- **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
|
|
4086
|
+
- **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
|
|
4087
|
+
|
|
4088
|
+
```ts
|
|
4089
|
+
const world = await WorldCells.load({ url: "/world/world.json", surface, follow, ring: 1, budgets: { residentCells: 25, instances: 20000, bytes: 8000000 } });
|
|
4090
|
+
scene.add(world);
|
|
4091
|
+
world.update();
|
|
4092
|
+
```
|
|
4093
|
+
|
|
4094
|
+
## `@threenative/metahuman`
|
|
4095
|
+
|
|
4096
|
+
### `assertAssetPath`
|
|
4097
|
+
|
|
4098
|
+
`function` — Keeps a caller-supplied asset path inside the asset directory.
|
|
3640
4099
|
|
|
3641
4100
|
```ts
|
|
3642
4101
|
export function assertAssetPath(path: string): string { … }
|
|
@@ -3828,9 +4287,10 @@ const footprint = capsuleFootprint(0.5, 0.2);
|
|
|
3828
4287
|
export class CharacterBody3D { … }
|
|
3829
4288
|
```
|
|
3830
4289
|
|
|
3831
|
-
- **Use when:** move an enemy or player through a level · keep a character from walking through walls
|
|
3832
|
-
- **Constraints:** use moveAndSlide inside the physics update
|
|
4290
|
+
- **Use when:** move an enemy or player through a level · keep a character from walking through walls · swim in a river, lake or sea; float at the surface and wade slower in shallow water · river current carries a swimmer downstream while it floats
|
|
4291
|
+
- **Constraints:** use moveAndSlide inside the physics update · pass `water: (x, z) => surfaceHeight | undefined`; the body reads `swimming`, `immersionDepth` and `waterSurface` each moveAndSlide · pass `waterCurrent: (x, z) => { x, z } | undefined` in m/s to have the water carry the body; it reads `currentVelocity` back
|
|
3833
4292
|
- **Requires:** npm i @threenative/physics
|
|
4293
|
+
- **Overrides:** buoyancy (1.6, floats; Unreal 1.0 sinks), maxSwimSpeed (3 m/s) and fluidFriction (12) tune the Unreal MOVE_Swimming defaults
|
|
3834
4294
|
- **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. CharacterBody3D itself is not deprecated.
|
|
3835
4295
|
|
|
3836
4296
|
```ts
|
|
@@ -3926,7 +4386,7 @@ const game = defineGame({ plugins: [rapier()] });
|
|
|
3926
4386
|
export class RigidBody3D { … }
|
|
3927
4387
|
```
|
|
3928
4388
|
|
|
3929
|
-
- **Use when:** give a crate or prop physical motion · create a body that collides with a character · fire physical cannonballs that collide with ships or scenery · fire a cannonball projectile with cannon smoke particles · a bullet passes through a wall
|
|
4389
|
+
- **Use when:** give a crate or prop physical motion · a ball rolls across the floor · create a body that collides with a character · fire physical cannonballs that collide with ships or scenery · fire a cannonball projectile with cannon smoke particles · a bullet passes through a wall
|
|
3930
4390
|
- **Constraints:** register rapier() in the game plugin list before using bodies
|
|
3931
4391
|
- **Requires:** npm i @threenative/physics
|
|
3932
4392
|
- **Overrides:** continuousCollision: false opts one body out while body.continuousCollision still reports the effective setting
|
|
@@ -3936,6 +4396,22 @@ export class RigidBody3D { … }
|
|
|
3936
4396
|
const crate = new RigidBody3D({ object, physics: ctx.physics, shape: CollisionShape3D.box(1, 1, 1), mass: 8 });
|
|
3937
4397
|
```
|
|
3938
4398
|
|
|
4399
|
+
### `ScatterColliders`
|
|
4400
|
+
|
|
4401
|
+
`class` — Make scattered props solid: fixed bodies for rocks and trunks near a followed point, streamed with it.
|
|
4402
|
+
|
|
4403
|
+
```ts
|
|
4404
|
+
export class ScatterColliders { … }
|
|
4405
|
+
```
|
|
4406
|
+
|
|
4407
|
+
- **Use when:** stop the player walking through scattered rocks and trees · give instanced or streamed foliage props collision in an open world
|
|
4408
|
+
- **Constraints:** pass each instance's solid part (stone, bark), not its leaves; shapes are measured: a slender base is a trunk capsule, the rest an 18-DOP hull, and pieces under 0.25 m get none · call update() every frame; it rescans only after the follow point moves a quarter of `radius` (default 40 m) · `collision: "hull" | "trunk" | "none"` on an instance overrides the measured shape
|
|
4409
|
+
- **Requires:** npm i @threenative/physics
|
|
4410
|
+
|
|
4411
|
+
```ts
|
|
4412
|
+
const solids = new ScatterColliders({ physics: ctx.physics, follow: player, collisionLayer: 4, instances: rocks.map((matrix) => ({ geometry: rockGeometry, matrix })) });
|
|
4413
|
+
```
|
|
4414
|
+
|
|
3939
4415
|
### `softBodyCollision`
|
|
3940
4416
|
|
|
3941
4417
|
`function` — Feed existing rigid-body boxes into `SoftBody3D` without inventing a second collider API.
|
|
@@ -6171,6 +6647,22 @@ export function applyPlacementOverrides(state: ITerrainState, value: unknown): I
|
|
|
6171
6647
|
const state = applyPlacementOverrides(terrain.evaluate(), document.placementOverrides ?? {});
|
|
6172
6648
|
```
|
|
6173
6649
|
|
|
6650
|
+
### `bakeBiome`
|
|
6651
|
+
|
|
6652
|
+
`function` — Bake one biome: the recipe's evaluated state and the world package it streams. This is the composition `terrain_generate` and a game's build script both call, so the file layout a player streams is decided in one place. The biome is validated first — an inline spec from a request is checked here, not trusted — and the package's own placement runs are checked against the state they came from, so a bake can never ship a cell list that lost instances.
|
|
6653
|
+
|
|
6654
|
+
```ts
|
|
6655
|
+
export function bakeBiome(options: IBakeBiomeOptions): IBakedBiome { … }
|
|
6656
|
+
```
|
|
6657
|
+
|
|
6658
|
+
- **Use when:** bake one biome's world package from an evaluated recipe and a biome file
|
|
6659
|
+
- **Constraints:** every instance's asset must be in `assets`; every instance must land in exactly one cell run
|
|
6660
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6661
|
+
|
|
6662
|
+
```ts
|
|
6663
|
+
const baked = bakeBiome({ state: terrain.evaluate(), spec: validateBiome(json, "savanna"), assets });
|
|
6664
|
+
```
|
|
6665
|
+
|
|
6174
6666
|
### `bakeMesh`
|
|
6175
6667
|
|
|
6176
6668
|
`function` — Bakes the recovered indexed top surface and optional vertical skirts into caller-owned arrays.
|
|
@@ -6207,7 +6699,7 @@ const baked = bakeTerrain(new Terrain({ resolution: 129 }).evaluate(), { chunkCe
|
|
|
6207
6699
|
|
|
6208
6700
|
### `bakeWorldPackage`
|
|
6209
6701
|
|
|
6210
|
-
`function` — Bake an evaluated terrain into the engine's world package: a `world.json` manifest, a uint16 heightmap, a splat mask array, a placement buffer of eight float32 per instance, and the square cells that stream them. The encodings and row orders are the ones the Blender recipe `export_world.py` writes, so one runtime streams both without a second reader.
|
|
6702
|
+
`function` — Bake an evaluated terrain into the engine's world package: a `world.json` manifest, a uint16 heightmap, a splat mask array, a placement buffer of eight float32 per instance, a placement ID sidecar and the square cells that stream them. The encodings and row orders are the ones the Blender recipe `export_world.py` writes, so one runtime streams both without a second reader.
|
|
6211
6703
|
|
|
6212
6704
|
```ts
|
|
6213
6705
|
export function bakeWorldPackage( state: ITerrainState, options: IBakeWorldPackageOptions, ): IBakedWorldPackage { … }
|
|
@@ -6222,6 +6714,39 @@ export function bakeWorldPackage( state: ITerrainState, options: IBakeWorldPacka
|
|
|
6222
6714
|
const { manifest, files } = bakeWorldPackage(state, { assets });
|
|
6223
6715
|
```
|
|
6224
6716
|
|
|
6717
|
+
### `collarSampler`
|
|
6718
|
+
|
|
6719
|
+
`function` — The collar's height at any (x, z), and a way to raise one of its per-vertex attributes at a placement: both read the collar's own quad grid, so a lane that reshapes the collar moves the trees with it.
|
|
6720
|
+
|
|
6721
|
+
```ts
|
|
6722
|
+
export function collarSampler(collar: HeightfieldCollar) { … }
|
|
6723
|
+
```
|
|
6724
|
+
|
|
6725
|
+
- **Use when:** plant a far field on a drawn collar and paint the canopy its crowns cover
|
|
6726
|
+
- **Constraints:** the collar decides where a tree stands; this sampler never resamples the square
|
|
6727
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6728
|
+
|
|
6729
|
+
```ts
|
|
6730
|
+
const sampler = collarSampler(collar); const height = sampler.at(x, z);
|
|
6731
|
+
```
|
|
6732
|
+
|
|
6733
|
+
### `compilePropBuckets`
|
|
6734
|
+
|
|
6735
|
+
`function` — Group placements into their streamed worlds and write each world's cells and records. The order is the streamed one: cells sorted by `x` then `z`, assets sorted by name inside a cell, and records in the order the entries arrived inside a run. Same-cell, same-asset placements keep their input order, so a re-run of a seeded bake reproduces the buffer byte for byte.
|
|
6736
|
+
|
|
6737
|
+
```ts
|
|
6738
|
+
export function compilePropBuckets( entries: readonly IPropBucketEntry[], options: ICompilePropBucketsOptions = { … }
|
|
6739
|
+
```
|
|
6740
|
+
|
|
6741
|
+
- **Use when:** bake the prop worlds a game streams, once, instead of compiling them at load
|
|
6742
|
+
- **Constraints:** headless; the caller decides every placement, its streamed world, its reach and its pose
|
|
6743
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6744
|
+
- **Overrides:** cellSize and the base extent; the bucket, reach and kind of every entry
|
|
6745
|
+
|
|
6746
|
+
```ts
|
|
6747
|
+
const pkg = compilePropBuckets(entries, { bounds });
|
|
6748
|
+
```
|
|
6749
|
+
|
|
6225
6750
|
### `createSegmentIndex`
|
|
6226
6751
|
|
|
6227
6752
|
`function` — Build the index once per world; ask `nearby` per scatter candidate or heightfield vertex.
|
|
@@ -6350,6 +6875,38 @@ export function encodeZIP(files: readonly IExportFile[]) { … }
|
|
|
6350
6875
|
const archive = encodeZIP([{ name: "height.raw", bytes: new Uint8Array(8) }]);
|
|
6351
6876
|
```
|
|
6352
6877
|
|
|
6878
|
+
### `farForestPlacements`
|
|
6879
|
+
|
|
6880
|
+
`function` — Far-field placements on the collar; also paints the collar's `canopy` attribute under each crown.
|
|
6881
|
+
|
|
6882
|
+
```ts
|
|
6883
|
+
export function farForestPlacements(options: IFarFieldOptions): IPlacement[] { … }
|
|
6884
|
+
```
|
|
6885
|
+
|
|
6886
|
+
- **Use when:** plant the stand past a game's playable square, out to the drawn collar
|
|
6887
|
+
- **Constraints:** the row's `far` block decides every density; the caller supplies the collar and layer
|
|
6888
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6889
|
+
|
|
6890
|
+
```ts
|
|
6891
|
+
const trees = farForestPlacements({ size, resolution, collar, treeline, rules, asset, layer });
|
|
6892
|
+
```
|
|
6893
|
+
|
|
6894
|
+
### `fieldWeight`
|
|
6895
|
+
|
|
6896
|
+
`function` — A field's weight at (x, z), clamped to 0..1.
|
|
6897
|
+
|
|
6898
|
+
```ts
|
|
6899
|
+
export function fieldWeight(field: ICoverField, x: number, z: number): number { … }
|
|
6900
|
+
```
|
|
6901
|
+
|
|
6902
|
+
- **Use when:** sample the stand field a biome's trees and cover thin on · measure the drift a biome's blades grow by, or the mat field its cover follows
|
|
6903
|
+
- **Constraints:** the field is a value, so two worlds sample the same formula with their own numbers
|
|
6904
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6905
|
+
|
|
6906
|
+
```ts
|
|
6907
|
+
const stand = fieldWeight(STAND_FIELD, x, z);
|
|
6908
|
+
```
|
|
6909
|
+
|
|
6353
6910
|
### `gradientAt`
|
|
6354
6911
|
|
|
6355
6912
|
`function` — World-space height gradient from the canonical samples.
|
|
@@ -6366,12 +6923,46 @@ export function gradientAt(grid: ISampledGrid, x: number, z: number): [number, n
|
|
|
6366
6923
|
const gradient = gradientAt(new Terrain({ resolution: 17 }).evaluate(), 0, 0);
|
|
6367
6924
|
```
|
|
6368
6925
|
|
|
6926
|
+
### `landform`
|
|
6927
|
+
|
|
6928
|
+
`function` — One call, one landscape: a calibrated layer recipe for a kind of environment.
|
|
6929
|
+
|
|
6930
|
+
```ts
|
|
6931
|
+
export function landform(kind: LandformKind, options: ILandformOptions = { … }
|
|
6932
|
+
```
|
|
6933
|
+
|
|
6934
|
+
- **Use when:** start an open world, a distant backdrop or a mountain level from a kind of place
|
|
6935
|
+
- **Constraints:** returns an ordinary `Terrain`: add roads, rivers, scatter or more layers, then `evaluate()` in a build script · shape only; materials, colours and textures belong to the game · calibrated at size 5000, resolution 513; other sizes keep the same slopes and scale the relief with `size`
|
|
6936
|
+
- **Requires:** npm i @threenative/terrain
|
|
6937
|
+
- **Overrides:** `relief` is the highest-minus-lowest height in metres before the finishing passes shave a few percent; `size`, `resolution` and `seed` as in `Terrain`
|
|
6938
|
+
|
|
6939
|
+
```ts
|
|
6940
|
+
const terrain = landform("alpine", { size: 5000, resolution: 513, seed: 4 }); const state = terrain.evaluate();
|
|
6941
|
+
```
|
|
6942
|
+
|
|
6943
|
+
### `landformBackdrop`
|
|
6944
|
+
|
|
6945
|
+
`function` — Distant mountains around a playable area: a landform window with a valley floor at its centre.
|
|
6946
|
+
|
|
6947
|
+
```ts
|
|
6948
|
+
export function landformBackdrop( kind: LandformKind, options: IBackdropOptions = { … }
|
|
6949
|
+
```
|
|
6950
|
+
|
|
6951
|
+
- **Use when:** add a mountain backdrop around a playable area that the game's detail terrain covers
|
|
6952
|
+
- **Constraints:** resolution up to 513: the window is cut from a world twice as wide at the same spacing; build script only · shape only; the game places, colours and fades it
|
|
6953
|
+
- **Requires:** npm i @threenative/terrain
|
|
6954
|
+
- **Overrides:** `relief` and `centerHeight` in metres; `size`, `resolution` and `seed` as in `landform`
|
|
6955
|
+
|
|
6956
|
+
```ts
|
|
6957
|
+
const { size, resolution, heights } = landformBackdrop("temperateMountains", { seed: 7, centerHeight: 13 });
|
|
6958
|
+
```
|
|
6959
|
+
|
|
6369
6960
|
### `makeExport`
|
|
6370
6961
|
|
|
6371
6962
|
`function` — Recovered numerical/project exports; GLB/runtime outputs contain terrain only.
|
|
6372
6963
|
|
|
6373
6964
|
```ts
|
|
6374
|
-
export
|
|
6965
|
+
export function makeExport( state: ITerrainState | null, recipe: ITerrainDocument, kind: "project", ): Promise<IExportArchive>;
|
|
6375
6966
|
```
|
|
6376
6967
|
|
|
6377
6968
|
- **Use when:** export a terrain recipe and its numerical runtime data
|
|
@@ -6382,6 +6973,84 @@ export async function makeExport( state: ITerrainState, recipe: ITerrainDocument
|
|
|
6382
6973
|
const terrain = new Terrain({ resolution: 17 }); const file = await makeExport(terrain.evaluate(), terrain.toJSON(), "project");
|
|
6383
6974
|
```
|
|
6384
6975
|
|
|
6976
|
+
### `measureBands`
|
|
6977
|
+
|
|
6978
|
+
`function` — Resolve a biome's fraction bands against this world's own height samples.
|
|
6979
|
+
|
|
6980
|
+
```ts
|
|
6981
|
+
export function measureBands( layers: readonly ILayerInfo[], heights: ArrayLike<number>, ): IMeasuredBands { … }
|
|
6982
|
+
```
|
|
6983
|
+
|
|
6984
|
+
- **Use when:** turn a biome file's height fractions into the metres a world actually measured
|
|
6985
|
+
- **Constraints:** samples are finite and at least one; a flat field resolves every band onto its one height
|
|
6986
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
6987
|
+
|
|
6988
|
+
```ts
|
|
6989
|
+
const bands = measureBands(spec.layers, state.height);
|
|
6990
|
+
```
|
|
6991
|
+
|
|
6992
|
+
### `orderedScatterRules`
|
|
6993
|
+
|
|
6994
|
+
`function` — A biome's rows as the ordered generators read them. The rule is short and shared; only these numbers differ between a wood, a barren shoulder, a dune field and a tundra, so the biome file names them rather than the code. A biome whose tree is not one this generator has art for fails here, naming the species, rather than planting nothing.
|
|
6995
|
+
|
|
6996
|
+
```ts
|
|
6997
|
+
export function orderedScatterRules(spec: IBiomeSpec): IOrderedScatterRules { … }
|
|
6998
|
+
```
|
|
6999
|
+
|
|
7000
|
+
- **Use when:** run a biome file's rows through the ordered scatter
|
|
7001
|
+
- **Constraints:** the file carries one foliage row, one grass row and a cover block
|
|
7002
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7003
|
+
|
|
7004
|
+
```ts
|
|
7005
|
+
const rules = orderedScatterRules(spec);
|
|
7006
|
+
```
|
|
7007
|
+
|
|
7008
|
+
### `propAssetOf`
|
|
7009
|
+
|
|
7010
|
+
`function` — The asset a package run names. A prop run names the model it draws, `asset:variant[@shape]`; a container written by `bakeWorldPackage` names the asset alone. Both reduce to the asset here, which is what a count, a material or a placement's own `asset` field holds.
|
|
7011
|
+
|
|
7012
|
+
```ts
|
|
7013
|
+
export function propAssetOf(modelKey: string): string { … }
|
|
7014
|
+
```
|
|
7015
|
+
|
|
7016
|
+
- **Use when:** count one species across a world's prop buckets, or name the asset a run draws
|
|
7017
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7018
|
+
|
|
7019
|
+
```ts
|
|
7020
|
+
const asset = propAssetOf("spruce:2"); // "spruce"
|
|
7021
|
+
```
|
|
7022
|
+
|
|
7023
|
+
### `propPackageFile`
|
|
7024
|
+
|
|
7025
|
+
`function` — A path under `world/` that no bucket name can break: `local:true` becomes `local-true`. The bucket's own name is kept in the manifest, so this rename is only a file-system concern.
|
|
7026
|
+
|
|
7027
|
+
```ts
|
|
7028
|
+
export function propPackageFile(world: string, bucket: string, suffix: string): string { … }
|
|
7029
|
+
```
|
|
7030
|
+
|
|
7031
|
+
- **Use when:** name one of a bucket's three files without a bucket key that breaks a path
|
|
7032
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7033
|
+
|
|
7034
|
+
```ts
|
|
7035
|
+
const file = propPackageFile("forest", "local:true", "props.bin"); // "forest.local-true.props.bin"
|
|
7036
|
+
```
|
|
7037
|
+
|
|
7038
|
+
### `propPackageFiles`
|
|
7039
|
+
|
|
7040
|
+
`function` — Write a compiled package as the manifest the game fetches and one set of files per bucket. The manifest names the files rather than embedding them, so a loader fetches only the buckets its query flags keep (`?farForest=on` keeps the far field, `?meadow=off` drops the vista cover).
|
|
7041
|
+
|
|
7042
|
+
```ts
|
|
7043
|
+
export function propPackageFiles(pkg: IPropPackage, world: string): IPropPackageFiles { … }
|
|
7044
|
+
```
|
|
7045
|
+
|
|
7046
|
+
- **Use when:** write a compiled package to disk: one manifest and three files per streamed world
|
|
7047
|
+
- **Constraints:** the manifest names the files; nothing here touches a file system
|
|
7048
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7049
|
+
|
|
7050
|
+
```ts
|
|
7051
|
+
const { manifest, files } = propPackageFiles(pkg, "forest");
|
|
7052
|
+
```
|
|
7053
|
+
|
|
6385
7054
|
### `sampleHeight`
|
|
6386
7055
|
|
|
6387
7056
|
`function` — Bilinear query of canonical height samples; triangle sampling is a separate contract.
|
|
@@ -6398,6 +7067,22 @@ sampleHeight = (grid: ISampledGrid, x: number, z: number): number => sampleGrid(
|
|
|
6398
7067
|
const height = sampleHeight(new Terrain({ resolution: 17 }).evaluate(), 0, 0);
|
|
6399
7068
|
```
|
|
6400
7069
|
|
|
7070
|
+
### `scatterProps`
|
|
7071
|
+
|
|
7072
|
+
`function` — Every placement, for one world, from one seed: the game's own rule set, in its own draw order.
|
|
7073
|
+
|
|
7074
|
+
```ts
|
|
7075
|
+
export function scatterProps( data: IOrderedScatterField, focus: { … }
|
|
7076
|
+
```
|
|
7077
|
+
|
|
7078
|
+
- **Use when:** bake a biome that says `"stream": "ordered"`
|
|
7079
|
+
- **Constraints:** `data.rules` is the biome's rows, and `data.field` the ground they were graded on
|
|
7080
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7081
|
+
|
|
7082
|
+
```ts
|
|
7083
|
+
const { placements, counts } = scatterProps(data, focus, clearings);
|
|
7084
|
+
```
|
|
7085
|
+
|
|
6401
7086
|
### `slopeAtIndex`
|
|
6402
7087
|
|
|
6403
7088
|
`function` — Slope in degrees at a heightfield sample.
|
|
@@ -6454,7 +7139,7 @@ const points = splinePoints([[0, 4, 0], [10, 2, 10]], 3, false);
|
|
|
6454
7139
|
export class Terrain { … }
|
|
6455
7140
|
```
|
|
6456
7141
|
|
|
6457
|
-
- **Use when:** author seeded terrain with noise, sculpting, erosion, roads, rivers and scatter · generate a procedural heightmap landscape or island for a game
|
|
7142
|
+
- **Use when:** author seeded terrain with noise, sculpting, erosion, roads, rivers and scatter · generate a procedural heightmap landscape or island for a game · make realistic mountains, hills, desert, coast, tundra or volcano terrain: start from `landform(kind)`, or add `erode({ method: "fluvial" })` for dendritic valleys
|
|
6458
7143
|
- **Constraints:** authoring stays outside the game's steady-play graph; no renderer or physics is created · units are metres with Y up; `size` is the world edge in metres (1 to 100000), centred on the origin · `resolution` counts vertices per edge and must be one of 17, 33, 65, 129, 257, 513 or 1025 · `seed` is an integer from 0 to 4294967295; one document and seed evaluate to the same arrays · `evaluate()` is synchronous on the calling thread: run it in a build script, never per frame · no art is chosen or shipped: materials, models and texture paths belong to the game
|
|
6459
7144
|
- **Requires:** npm i @threenative/terrain
|
|
6460
7145
|
- **Overrides:** size, resolution, seed and all layer parameters are caller choices
|
|
@@ -6480,6 +7165,38 @@ export class TerrainEvaluator { … }
|
|
|
6480
7165
|
const terrain = new Terrain({ resolution: 17 }); const evaluator = new TerrainEvaluator(); const state = evaluator.evaluate(terrain.toJSON());
|
|
6481
7166
|
```
|
|
6482
7167
|
|
|
7168
|
+
### `terrainStats`
|
|
7169
|
+
|
|
7170
|
+
`function` — Landform statistics used to calibrate generators against real DEMs.
|
|
7171
|
+
|
|
7172
|
+
```ts
|
|
7173
|
+
export function terrainStats(height: ArrayLike<number>, n: number, size: number): ITerrainStats { … }
|
|
7174
|
+
```
|
|
7175
|
+
|
|
7176
|
+
- **Use when:** compare generated terrain with a USGS or SRTM crop on the same footprint
|
|
7177
|
+
- **Constraints:** square grids only; compare crops of equal spacing, because slope and curvature depend on it
|
|
7178
|
+
- **Requires:** npm i @threenative/terrain
|
|
7179
|
+
|
|
7180
|
+
```ts
|
|
7181
|
+
const stats = terrainStats(state.height, state.resolution, state.size);
|
|
7182
|
+
```
|
|
7183
|
+
|
|
7184
|
+
### `validateBiome`
|
|
7185
|
+
|
|
7186
|
+
`function` — One biome file, checked field by field. The file is `biome.data.json`: `biome.json` is Biome's own configuration name, and a data file called that is parsed as a project config and fails the lint.
|
|
7187
|
+
|
|
7188
|
+
```ts
|
|
7189
|
+
export function validateBiome(spec: unknown, name: string): IBiomeSpec { … }
|
|
7190
|
+
```
|
|
7191
|
+
|
|
7192
|
+
- **Use when:** read a biome's rules from `starter/<biome>/biome.data.json` before a game or a cook uses them
|
|
7193
|
+
- **Constraints:** The file carries no appearance; colours, materials and shading stay game source
|
|
7194
|
+
- **Requires:** npm i @threenative/terrain
|
|
7195
|
+
|
|
7196
|
+
```ts
|
|
7197
|
+
const spec = validateBiome(JSON.parse(text), "forest");
|
|
7198
|
+
```
|
|
7199
|
+
|
|
6483
7200
|
### `validateDocument`
|
|
6484
7201
|
|
|
6485
7202
|
`function` — Validates the recovered recipe schema, operation allow-lists and numeric bounds.
|
|
@@ -6532,6 +7249,70 @@ export function checkEnvironmentAssets( environment: IEnvironment, assets: reado
|
|
|
6532
7249
|
checkEnvironmentAssets({ sky: { image: "dusk" } }, document.assets ?? []);
|
|
6533
7250
|
```
|
|
6534
7251
|
|
|
7252
|
+
### `createEditorSelection`
|
|
7253
|
+
|
|
7254
|
+
`function` — Gesture and transaction mechanics; the caller owns the controls, proxy and all rendering.
|
|
7255
|
+
|
|
7256
|
+
```ts
|
|
7257
|
+
export function createEditorSelection( { … }
|
|
7258
|
+
```
|
|
7259
|
+
|
|
7260
|
+
- **Use when:** drive terrain-editor selection, gizmo drags, undo and saved transactions
|
|
7261
|
+
- **Constraints:** the caller supplies the TransformControls, proxy, controller and every drawing callback
|
|
7262
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7263
|
+
|
|
7264
|
+
```ts
|
|
7265
|
+
const selection = createEditorSelection({ gizmo, proxy, controller, grounding, surface, defaultFootprintSize, refreshPose, drawFootprint, restorePlacement, previewPlacement, setSaving, selectedChanged, setNavigation, message });
|
|
7266
|
+
```
|
|
7267
|
+
|
|
7268
|
+
### `editorPlacementCenter`
|
|
7269
|
+
|
|
7270
|
+
`function` — Transform the caller's measured geometry centre into the evaluated placement's world space.
|
|
7271
|
+
|
|
7272
|
+
```ts
|
|
7273
|
+
export function editorPlacementCenter(point: Vector3, pose: IPlacementOverride): Vector3 { … }
|
|
7274
|
+
```
|
|
7275
|
+
|
|
7276
|
+
- **Use when:** find the world-space centre of a placed terrain-editor instance
|
|
7277
|
+
- **Constraints:** the point is multiplied in place; the pose needs finite position, quaternion and scale
|
|
7278
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7279
|
+
|
|
7280
|
+
```ts
|
|
7281
|
+
const centre = editorPlacementCenter(localCentre.clone(), placement);
|
|
7282
|
+
```
|
|
7283
|
+
|
|
7284
|
+
### `editorPointToClient`
|
|
7285
|
+
|
|
7286
|
+
`function` — Project an injected world point to client pixels in the caller's viewport.
|
|
7287
|
+
|
|
7288
|
+
```ts
|
|
7289
|
+
export function editorPointToClient( point: Vector3, camera: Camera, box: { … }
|
|
7290
|
+
```
|
|
7291
|
+
|
|
7292
|
+
- **Use when:** convert a terrain-editor world point to viewport client pixels
|
|
7293
|
+
- **Constraints:** the point is projected in place; pass a clone to keep the original
|
|
7294
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7295
|
+
|
|
7296
|
+
```ts
|
|
7297
|
+
const [x, y] = editorPointToClient(point.clone(), camera, canvas.getBoundingClientRect());
|
|
7298
|
+
```
|
|
7299
|
+
|
|
7300
|
+
### `editorSurfaceHeight`
|
|
7301
|
+
|
|
7302
|
+
`function` — Query the rendered heightfield, including its triangulation rather than an interpolated bake.
|
|
7303
|
+
|
|
7304
|
+
```ts
|
|
7305
|
+
export function editorSurfaceHeight( ctx: { … }
|
|
7306
|
+
```
|
|
7307
|
+
|
|
7308
|
+
- **Use when:** query terrain-editor surface elevation at world X/Z coordinates
|
|
7309
|
+
- **Constraints:** the supplied mesh and raycast determine the surface; missing intersections return undefined
|
|
7310
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7311
|
+
|
|
7312
|
+
```ts
|
|
7313
|
+
const height = editorSurfaceHeight(ctx, terrainMesh, x, z);
|
|
7314
|
+
```
|
|
7315
|
+
|
|
6535
7316
|
### `focusCamera`
|
|
6536
7317
|
|
|
6537
7318
|
`function` — Frame a point, prop, landmark or region for the live viewport and projection. @summary Frame a focus target with an editor observation camera
|
|
@@ -6583,6 +7364,22 @@ export function inspectSpatial( state: ITerrainState, revision: string, query: I
|
|
|
6583
7364
|
const observation = inspectSpatial(state, revision, { kind: "point", at: [0, 0] });
|
|
6584
7365
|
```
|
|
6585
7366
|
|
|
7367
|
+
### `landformPose`
|
|
7368
|
+
|
|
7369
|
+
`function` — Recipe footprints are heights over X/Z, never independently transformed solids.
|
|
7370
|
+
|
|
7371
|
+
```ts
|
|
7372
|
+
export function landformPose(layer: Layer, worldSize: number, defaultSize: number) { … }
|
|
7373
|
+
```
|
|
7374
|
+
|
|
7375
|
+
- **Use when:** derive a terrain-editor gizmo pose from a landform layer
|
|
7376
|
+
- **Constraints:** the caller supplies world and default footprint sizes; unsupported layers return undefined
|
|
7377
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7378
|
+
|
|
7379
|
+
```ts
|
|
7380
|
+
const pose = landformPose(layer, terrain.size, footprintSize);
|
|
7381
|
+
```
|
|
7382
|
+
|
|
6586
7383
|
### `mountTerrainEditor`
|
|
6587
7384
|
|
|
6588
7385
|
`function` — Mount recovered terrain controls around the project-owned ThreeNative view.
|
|
@@ -6600,6 +7397,38 @@ export async function mountTerrainEditor(options: { … }
|
|
|
6600
7397
|
await mountTerrainEditor({ createView: createEditorView, materialColours: terrainPalette });
|
|
6601
7398
|
```
|
|
6602
7399
|
|
|
7400
|
+
### `pickEditorPlacement`
|
|
7401
|
+
|
|
7402
|
+
`function` — A foreground terrain hit occludes placements; matching uses the evaluated world position.
|
|
7403
|
+
|
|
7404
|
+
```ts
|
|
7405
|
+
export function pickEditorPlacement( ctx: Parameters<typeof pickEditorSurface>[0], terrain: Mesh, meshes: readonly Object3D[], placements: Iterable< { … }
|
|
7406
|
+
```
|
|
7407
|
+
|
|
7408
|
+
- **Use when:** pick a placed instance in the terrain editor from viewport client coordinates
|
|
7409
|
+
- **Constraints:** the caller supplies the raycast context, terrain mesh, instanced meshes and evaluated placements
|
|
7410
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7411
|
+
|
|
7412
|
+
```ts
|
|
7413
|
+
const id = pickEditorPlacement(ctx, terrainMesh, meshes, placements, event.clientX, event.clientY);
|
|
7414
|
+
```
|
|
7415
|
+
|
|
7416
|
+
### `pickEditorSurface`
|
|
7417
|
+
|
|
7418
|
+
`function` — Convert viewport client coordinates once; the installed picker owns ray intersection.
|
|
7419
|
+
|
|
7420
|
+
```ts
|
|
7421
|
+
export function pickEditorSurface( ctx: { … }
|
|
7422
|
+
```
|
|
7423
|
+
|
|
7424
|
+
- **Use when:** pick a terrain-editor surface from viewport client coordinates
|
|
7425
|
+
- **Constraints:** the caller supplies the raycast implementation and ordered targets
|
|
7426
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7427
|
+
|
|
7428
|
+
```ts
|
|
7429
|
+
const hit = pickEditorSurface(ctx, [terrainMesh], event.clientX, event.clientY);
|
|
7430
|
+
```
|
|
7431
|
+
|
|
6603
7432
|
### `probeTerrain`
|
|
6604
7433
|
|
|
6605
7434
|
`function` — Probe the evaluated surface at one world point, separating bilinear from triangle values.
|
|
@@ -6702,6 +7531,22 @@ export class TerrainEditorController { … }
|
|
|
6702
7531
|
const controller = new TerrainEditorController(editorUrl); const snapshot = await controller.snapshot();
|
|
6703
7532
|
```
|
|
6704
7533
|
|
|
7534
|
+
### `transformedLandform`
|
|
7535
|
+
|
|
7536
|
+
`function` — Convert a terrain-editor gizmo pose into a heightfield landform footprint.
|
|
7537
|
+
|
|
7538
|
+
```ts
|
|
7539
|
+
export function transformedLandform( layer: Layer, position: Vector3, quaternion: Quaternion, scale: Vector3, anchor: number, ): Layer { … }
|
|
7540
|
+
```
|
|
7541
|
+
|
|
7542
|
+
- **Use when:** apply a terrain-editor gizmo transform to a landform layer
|
|
7543
|
+
- **Constraints:** finite coordinates and positive scales are required; X/Z rotations that overhang throw
|
|
7544
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7545
|
+
|
|
7546
|
+
```ts
|
|
7547
|
+
const next = transformedLandform(layer, position, quaternion, scale, surfaceHeight);
|
|
7548
|
+
```
|
|
7549
|
+
|
|
6705
7550
|
### `validateAsset`
|
|
6706
7551
|
|
|
6707
7552
|
`function` — Validate one saved asset registration exactly as a document commit stores it. @summary Validate a registered terrain-editor asset entry
|
|
@@ -6859,21 +7704,104 @@ const document = new TerrainEditorDocument("/project/terrain/world.json"); const
|
|
|
6859
7704
|
|
|
6860
7705
|
## `@threenative/terrain/export`
|
|
6861
7706
|
|
|
6862
|
-
### `
|
|
7707
|
+
### `prepareWorldGLTF`
|
|
7708
|
+
|
|
7709
|
+
`function` — Prepare the game's validated, frozen portable scene; the server cook owns GLB encoding.
|
|
7710
|
+
|
|
7711
|
+
```ts
|
|
7712
|
+
export async function prepareWorldGLTF(input: IWorldGLBInput): Promise< { … }
|
|
7713
|
+
```
|
|
7714
|
+
|
|
7715
|
+
- **Use when:** export the terrain as a glb for another three.js project via the headless cook · prepare the terrain editor's resolved world for headless portable GLB cooking
|
|
7716
|
+
- **Constraints:** browser authoring FileReader/canvas; all appearance and coherent water come from the game
|
|
7717
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7718
|
+
|
|
7719
|
+
```ts
|
|
7720
|
+
const prepared = await prepareWorldGLTF(input);
|
|
7721
|
+
```
|
|
7722
|
+
|
|
7723
|
+
## `@threenative/terrain/kit`
|
|
7724
|
+
|
|
7725
|
+
### `bakeKit`
|
|
7726
|
+
|
|
7727
|
+
`function` — Bake a copied kit, optionally using the caller's installed world cook.
|
|
7728
|
+
|
|
7729
|
+
```ts
|
|
7730
|
+
export async function bakeKit( url: string, { … }
|
|
7731
|
+
```
|
|
7732
|
+
|
|
7733
|
+
- **Use when:** bake a copied terrain starter kit into its offline world package
|
|
7734
|
+
- **Constraints:** Node authoring only; recipes, asset tables and sky paths stay in the game
|
|
7735
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7736
|
+
|
|
7737
|
+
```ts
|
|
7738
|
+
await bakeKit(import.meta.url, { sky: "hdri/game-sky.hdr" });
|
|
7739
|
+
```
|
|
7740
|
+
|
|
7741
|
+
### `starterAssetsDir`
|
|
7742
|
+
|
|
7743
|
+
`function` — Resolve shared starter assets locally, or download the package's pinned archive on demand.
|
|
7744
|
+
|
|
7745
|
+
```ts
|
|
7746
|
+
export async function starterAssetsDir(): Promise<string> { … }
|
|
7747
|
+
```
|
|
7748
|
+
|
|
7749
|
+
- **Use when:** resolve terrain kit models and textures for offline baking
|
|
7750
|
+
- **Constraints:** Node authoring only; verifies archive size and SHA256 before atomic extraction
|
|
7751
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7752
|
+
|
|
7753
|
+
```ts
|
|
7754
|
+
const assets = await starterAssetsDir();
|
|
7755
|
+
```
|
|
7756
|
+
|
|
7757
|
+
## `@threenative/terrain/starter`
|
|
7758
|
+
|
|
7759
|
+
### `addStarterWorld`
|
|
7760
|
+
|
|
7761
|
+
`function` — Load caller-authored starter data with one scene lifetime; all appearance comes from spec.
|
|
7762
|
+
|
|
7763
|
+
```ts
|
|
7764
|
+
export async function addStarterWorld<Extra extends { … }
|
|
7765
|
+
```
|
|
7766
|
+
|
|
7767
|
+
- **Use when:** attach a baked starter world with game-owned surfaces, prop dressing and water
|
|
7768
|
+
- **Constraints:** Runtime subpath; the game supplies every appearance and collision choice
|
|
7769
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7770
|
+
|
|
7771
|
+
```ts
|
|
7772
|
+
await addStarterWorld(ctx, follow, spec);
|
|
7773
|
+
```
|
|
7774
|
+
|
|
7775
|
+
### `editWorldPlacements`
|
|
7776
|
+
|
|
7777
|
+
`function` — Apply deterministic startup edits to the decoded placement data before a world is loaded.
|
|
7778
|
+
|
|
7779
|
+
```ts
|
|
7780
|
+
export function editWorldPlacements( data: { … }
|
|
7781
|
+
```
|
|
7782
|
+
|
|
7783
|
+
- **Use when:** change generated terrain composition from game source without rebaking the world
|
|
7784
|
+
- **Requires:** npm i -D @threenative/terrain
|
|
7785
|
+
- **Overrides:** grounding defaults on, while `grounding: false` preserves the authored Y coordinate
|
|
7786
|
+
|
|
7787
|
+
```ts
|
|
7788
|
+
const edited = editWorldPlacements(data, { remove: ["scree:candidate:7:41"] }, (x, z) => field.heightAt(x, z));
|
|
7789
|
+
```
|
|
7790
|
+
|
|
7791
|
+
### `PropColliders`
|
|
6863
7792
|
|
|
6864
|
-
`
|
|
7793
|
+
`class` — Stream caller-specified fixed collision shapes around a moving follow object.
|
|
6865
7794
|
|
|
6866
7795
|
```ts
|
|
6867
|
-
export
|
|
7796
|
+
export class PropColliders extends Object3D implements IComputeDriven { … }
|
|
6868
7797
|
```
|
|
6869
7798
|
|
|
6870
|
-
- **Use when:**
|
|
6871
|
-
- **Constraints:**
|
|
7799
|
+
- **Use when:** attach nearby prop collision bodies from baked placement records
|
|
7800
|
+
- **Constraints:** Shapes and reach are supplied by the game; detach releases every body
|
|
6872
7801
|
- **Requires:** npm i -D @threenative/terrain
|
|
6873
|
-
- **Overrides:** actual static models, final matrices and baked PBR maps are supplied by the game
|
|
6874
7802
|
|
|
6875
7803
|
```ts
|
|
6876
|
-
|
|
7804
|
+
new PropColliders(ctx, follow, manifest, records, shapes, reach, name);
|
|
6877
7805
|
```
|
|
6878
7806
|
|
|
6879
7807
|
## `@threenative/terrain/three`
|