@threenative/core 0.3.13 → 0.3.16

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.
Files changed (60) hide show
  1. package/capabilities.json +1008 -83
  2. package/dist/{chunk-4SRAQFTU.js → chunk-2GPHICV6.js} +1 -1
  3. package/dist/{chunk-EEABDLUC.js → chunk-5C4TCWI3.js} +2 -2
  4. package/dist/{chunk-DIPIJICH.js → chunk-FQURMC2F.js} +122 -18
  5. package/dist/{chunk-EFWZWLPY.js → chunk-OMGIYWW7.js} +400 -13
  6. package/dist/{chunk-SV4QVUTQ.js → chunk-QAQHYOWY.js} +1 -1
  7. package/dist/{chunk-GYUZJQ7U.js → chunk-VQRPEOKY.js} +4 -1
  8. package/dist/hot.js +10 -2
  9. package/dist/index.d.ts +608 -16
  10. package/dist/index.js +2037 -633
  11. package/dist/{model-lod-DPTzeCcD.d.ts → model-lod-B921F6kQ.d.ts} +0 -10
  12. package/dist/playtest.js +3 -3
  13. package/dist/{quality-BYqKGAwo.d.ts → quality-BADStsTn.d.ts} +2 -2
  14. package/dist/render-environment.d.ts +1 -1
  15. package/dist/ui-layer.js +2 -2
  16. package/dist/worker.js +2 -2
  17. package/dist/world.d.ts +14 -4
  18. package/dist/world.js +179 -36
  19. package/mcp/animation-server.mjs +1 -1
  20. package/mcp/engine-server.mjs +44 -17
  21. package/mcp/servers.mjs +4 -4
  22. package/package.json +6 -6
  23. package/patches/three@0.187.0-prd269-upgrade.patch +126 -2
  24. package/patches/three@0.187.0.patch +108 -21
  25. package/scripts/ensure-mcp.mjs +6 -1
  26. package/src/clustered-batch.ts +146 -3
  27. package/src/clustered-mesh.ts +548 -20
  28. package/src/debug.ts +16 -0
  29. package/src/displaced-surface.ts +428 -0
  30. package/src/engine-hooks.ts +29 -0
  31. package/src/frame-budget.ts +16 -0
  32. package/src/generated/console-markers.ts +1 -0
  33. package/src/grass-field.ts +628 -0
  34. package/src/grounding.ts +19 -10
  35. package/src/hot.ts +18 -2
  36. package/src/index.ts +112 -0
  37. package/src/instanced-batch-lod.ts +54 -0
  38. package/src/model-lod.ts +77 -1
  39. package/src/pose-measure.ts +27 -2
  40. package/src/render/material-key.ts +21 -1
  41. package/src/render/screen-probe-gather.ts +303 -0
  42. package/src/render/short-range-ao.ts +274 -0
  43. package/src/render/world-impostor-surface.ts +98 -3
  44. package/src/render-camera-cull.ts +9 -3
  45. package/src/renderer.ts +26 -4
  46. package/src/scatter-field.ts +497 -0
  47. package/src/startup-offscreen-bytes.ts +11 -5
  48. package/src/state.ts +16 -3
  49. package/src/static-transform.ts +109 -6
  50. package/src/tile-ring.ts +294 -0
  51. package/src/version.ts +1 -1
  52. package/src/warmup.ts +15 -2
  53. package/src/world-cell-batches.ts +4 -0
  54. package/src/world-cell-data.ts +7 -0
  55. package/src/world-cell-models.ts +36 -8
  56. package/src/world-cell-render-gpu-dress.ts +4 -2
  57. package/src/world-cell-render-util.ts +2 -2
  58. package/src/world-cells.ts +1 -1
  59. package/src/world-river-ribbon.ts +13 -22
  60. package/src/world-water-bodies.ts +113 -3
package/capabilities.json CHANGED
@@ -1486,6 +1486,26 @@
1486
1486
  "supersedes": [],
1487
1487
  "symbol": "debugFlag"
1488
1488
  },
1489
+ {
1490
+ "aliases": [],
1491
+ "constraints": [
1492
+ "the same name rule as `debugFlag`: `?quality=` on the web, `TN_DEBUG_QUALITY` on a native launch",
1493
+ "a name in camelCase becomes UPPER_SNAKE: `debugValue(\"quality\")` reads `?quality=` or `TN_DEBUG_QUALITY`"
1494
+ ],
1495
+ "example": "import { debugValue } from \"@threenative/core\";\nconst tier = debugValue(\"quality\");",
1496
+ "importPath": "@threenative/core",
1497
+ "kind": "function",
1498
+ "overrides": [],
1499
+ "package": "@threenative/core",
1500
+ "signature": "export function debugValue(name: string): string | undefined { … }",
1501
+ "situations": [
1502
+ "read a debug override whose value is not a boolean",
1503
+ "override a quality tier or a mode for one run without changing the code"
1504
+ ],
1505
+ "summary": "Read the text a debug switch was given by the launch, on the same rule as `debugFlag`.",
1506
+ "supersedes": [],
1507
+ "symbol": "debugValue"
1508
+ },
1489
1509
  {
1490
1510
  "aliases": [
1491
1511
  "nearest target crosshair spawns",
@@ -2153,6 +2173,37 @@
2153
2173
  "supersedes": [],
2154
2174
  "symbol": "GPUSceneBVH"
2155
2175
  },
2176
+ {
2177
+ "aliases": [],
2178
+ "constraints": [
2179
+ "call `update(camera)` once per rendered frame from `ctx.beforeRender`; chunks build nearest first inside `buildBudgetMs`",
2180
+ "the material reads `GRASS_FIELD_ATTRIBUTES` and the field's `nodes` uniforms, so its thinning matches the CPU trim",
2181
+ "a chunk is built inside 1.3 × the draw distance and discarded past 1.4 ×, so a camera on the edge rebuilds nothing",
2182
+ "Call `update(camera)` once per rendered frame, from `ctx.beforeRender`.",
2183
+ "Rotating or scaling the field is not supported; translating it is."
2184
+ ],
2185
+ "example": "// the look lives in the kit's src/render/grass.ts\nconst grass = new GrassField3D({ blade: grassBlade(), material: grassMaterial, getHeight: height });\nctx.add(grass);\nctx.beforeRender(() => { grass.pushers[0]?.set(hero.x, hero.y, hero.z, 1.2); grass.update(ctx.camera); });",
2186
+ "importPath": "@threenative/core",
2187
+ "kind": "class",
2188
+ "overrides": [
2189
+ "densityScale and cullDistanceScale scale every density and distance at once; prewarm() builds all in range on the next update"
2190
+ ],
2191
+ "package": "@threenative/core",
2192
+ "signature": "export class GrassField3D extends Group { … }",
2193
+ "situations": [
2194
+ "grass that sways and parts around the player",
2195
+ "a meadow, lawn or grassy field over terrain that streams around the camera",
2196
+ "ground cover grass blades with distance thinning and LOD that does not pop",
2197
+ "grass flattened or pushed aside where the player, a creature or a vehicle walks",
2198
+ "grow grass on a terrain biome's grass rows with grassFieldFromBiome",
2199
+ "Grass that sways and parts around the player across a large terrain.",
2200
+ "Stream instanced ground cover in chunks around the camera under a frame budget.",
2201
+ "Meadow, lawn or field grass with distance thinning and LOD that does not pop."
2202
+ ],
2203
+ "summary": "Stream instanced grass in chunks around the camera; the game owns the blade and its TSL material.",
2204
+ "supersedes": [],
2205
+ "symbol": "GrassField3D"
2206
+ },
2156
2207
  {
2157
2208
  "aliases": [],
2158
2209
  "constraints": [
@@ -3360,6 +3411,31 @@
3360
3411
  "supersedes": [],
3361
3412
  "symbol": "RippleField"
3362
3413
  },
3414
+ {
3415
+ "aliases": ["scatter rocks, debris and plants over terrain"],
3416
+ "constraints": [
3417
+ "call `update(follow)` once per rendered frame",
3418
+ "`place` runs once per candidate per tile build: return false for paths and clearings",
3419
+ "rotating or scaling the field is not supported; translating it is"
3420
+ ],
3421
+ "example": "const floor = new ScatterField3D({ parts: [{ lods, material }], getHeight, density: 0.05, place });\nctx.add(floor);\nctx.beforeRender(() => floor.update(hero.position));",
3422
+ "importPath": "@threenative/core",
3423
+ "kind": "class",
3424
+ "overrides": [],
3425
+ "package": "@threenative/core",
3426
+ "requires": [
3427
+ "npm i -D @threenative/procedural-environment for the bake these instances come from"
3428
+ ],
3429
+ "signature": "export class ScatterField3D extends Group { … }",
3430
+ "situations": [
3431
+ "scatter fallen logs, twigs, leaf litter, stones and ferns over a forest floor",
3432
+ "stream instanced props of any baked mesh round the player without one draw per prop",
3433
+ "place rocks, debris or plants on a heightfield with distance thinning and level of detail"
3434
+ ],
3435
+ "summary": "Stream instanced copies of any baked mesh around a follow point, with distance thinning and levels of detail, from the game's own placement rule.",
3436
+ "supersedes": [],
3437
+ "symbol": "ScatterField3D"
3438
+ },
3363
3439
  {
3364
3440
  "aliases": [],
3365
3441
  "constraints": ["scene code must stay portable across web and native"],
@@ -3438,6 +3514,34 @@
3438
3514
  "supersedes": [],
3439
3515
  "symbol": "Scheduler"
3440
3516
  },
3517
+ {
3518
+ "aliases": [],
3519
+ "constraints": [
3520
+ "the owned engine only: on engine: \"threejs\" the upstream node takes the camera as its fourth argument and has no probes, and gather() refuses",
3521
+ "the gather is a delta in E / pi: multiply it by the receiver's diffuse colour (mrt({ diffuseColor })) and add it after the scene pass, and give the scene pass no other indirect diffuse or the light is counted twice",
3522
+ "a viewport resize needs a new gather: the probe grid is fixed when it is built",
3523
+ "the grid is the cost: downsampleFactor 16 and an 8 x 8 octahedron are Unreal's Epic, 32 and 8 its High",
3524
+ "radiance answers in the frame's units (the cache read times the frame's gain), and a trace reads it only where the screen has nothing"
3525
+ ],
3526
+ "example": "const gather = new ScreenProbeGather({ camera, viewport, radiance, trace });\nconst gi = gather.gather(convertToTexture(input), depth(), normalView());\nconst bounce = gather.getGINode().rgb.mul(diffuseColor.rgb);",
3527
+ "importPath": "@threenative/core",
3528
+ "kind": "class",
3529
+ "overrides": [
3530
+ "downsampleFactor, tracingOctahedronResolution, cacheCellSize, timedPass and the strength of the composite are game-owned choices"
3531
+ ],
3532
+ "package": "@threenative/core",
3533
+ "signature": "export class ScreenProbeGather { … }",
3534
+ "situations": [
3535
+ "bounce light that reads the room off screen instead of a flat ambient term",
3536
+ "global illumination that costs a fraction of one ray per pixel",
3537
+ "the light a corner sees from around the wall, which a per-pixel screen trace loses",
3538
+ "lumen screen probe gather",
3539
+ "lumen final gather"
3540
+ ],
3541
+ "summary": "Lumen's Screen Probe Gather: one probe per 16 x 16 pixels traces an 8 x 8 octahedron of rays, the probes are filtered into an irradiance octahedron each, and a pixel blends the four nearest probes it can see, instead of every pixel tracing its own rays. A ray that hits on screen returns the lit frame minus the cache along it; a ray that leaves the screen continues through the packed scene up to the radiance cache's cell and reads the cache where it ended, so the light that arrives from off screen is that direction's and not the pixel's mean.",
3542
+ "supersedes": [],
3543
+ "symbol": "ScreenProbeGather"
3544
+ },
3441
3545
  {
3442
3546
  "aliases": [],
3443
3547
  "constraints": [
@@ -3505,6 +3609,31 @@
3505
3609
  "supersedes": [],
3506
3610
  "symbol": "ShadowFilterBudget"
3507
3611
  },
3612
+ {
3613
+ "aliases": [],
3614
+ "constraints": [
3615
+ "it replaces GTAO when dynamic GI runs; a tier without GI keeps ambientOcclusion",
3616
+ "the occlusion multiplies indirect light only: direct light and emission keep their own occlusion",
3617
+ "multi-bounce and its albedo cap belong to the game's composite; Unreal caps the albedo at 0.5",
3618
+ "an authored stage that carries its name must anchor itself (`before: \"ssgi\"`), because the chain's built-in order names no shortRangeAO"
3619
+ ],
3620
+ "example": "const shortRange = new ShortRangeAO({ camera, viewport: renderer.drawingBufferSize });\nconst contact = shortRange.occlusion(depth(), normalView());\nconst indirect = input.rgb.mul(contact.a);",
3621
+ "importPath": "@threenative/core",
3622
+ "kind": "class",
3623
+ "overrides": [
3624
+ "horizonSearchSliceCount, horizonSearchStepCount, reachPx, bentNormal and intensity are game-owned choices"
3625
+ ],
3626
+ "package": "@threenative/core",
3627
+ "signature": "export class ShortRangeAO { … }",
3628
+ "situations": [
3629
+ "contact shadow at the foot of an object while dynamic GI runs",
3630
+ "dark line where a wall meets the floor, without a second wide AO over the gathered light",
3631
+ "lumen short range ao"
3632
+ ],
3633
+ "summary": "Unreal's Short Range AO: a horizon search of 2 sweeps around the view normal, 3 samples each at the squared fraction of a 32 px screen reach, at full resolution, with a bent normal at Epic. It is the occlusion that runs *with* dynamic global illumination — the contact detail Lumen keeps after the screen probe gather has already answered the wide occlusion — so a gathered frame is not darkened twice by two wide treatments. The result is one texture: `rgb` the bent normal in view space, `a` the share of the hemisphere left open, which multiplies indirect light only.",
3634
+ "supersedes": [],
3635
+ "symbol": "ShortRangeAO"
3636
+ },
3508
3637
  {
3509
3638
  "aliases": [],
3510
3639
  "constraints": [
@@ -5417,9 +5546,10 @@
5417
5546
  "signature": "export function lakeSurfaceGeometry( lake: IWaterLake, field: Heightfield, options: ILakeSurfaceOptions = { … }",
5418
5547
  "situations": [
5419
5548
  "draw a lake's water surface from the baked level and seed",
5420
- "a lake's drawn water and the swimmer's water disagree"
5549
+ "a lake's drawn water and the swimmer's water disagree",
5550
+ "lake water ends in a straight edge over a valley past the basin's rim"
5421
5551
  ],
5422
- "summary": "A lake's water surface: a level disc out to `lakeReach`, the footprint `WaterBodies` floods, with a `metres` attribute (water depth over the ground). Only cells with water at a corner get triangles, so the surface does not hover over dry hillside and the shore follows the ground's contour. The rings pack towards the middle, so an irregular basin costs vertices where the camera sees them. Returns `undefined` when the basin holds no water at its level.",
5552
+ "summary": "A lake's water surface: a level disc out to `lakeReach`, the footprint `WaterBodies` floods, with a `metres` attribute (water depth over the ground). Only cells with a corner the seed's water reaches get triangles, so the surface does not hover over dry hillside, a hollow past the basin's rim (a river valley beyond the dam) stays dry instead of standing under a sheet that stops where the reach does, and the shore follows the ground's contour. The rings pack towards the middle, so an irregular basin costs vertices where the camera sees them. Returns `undefined` when the basin holds no water at its level.",
5423
5553
  "supersedes": [],
5424
5554
  "symbol": "lakeSurfaceGeometry"
5425
5555
  },
@@ -5793,7 +5923,7 @@
5793
5923
  "importPath": "@threenative/core/world",
5794
5924
  "kind": "class",
5795
5925
  "overrides": [
5796
- "`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"
5926
+ "`hlod: false` keeps source rendering; `partMaterial` gives a part the game's own surface (a swaying tree); ring, budgets, terrain tile size/resolution, terrain stream and collider radius, `transparentScatter`, `clusterSize` and `shadows.invalidate`, load `concurrency`, `rebuildsPerUpdate`, `admissionBudgetMs` and the package's per-asset maxDistance; `impostorFar: \"always\"` keeps the far aggregate the near ring's guaranteed radius made unnecessary"
5797
5927
  ],
5798
5928
  "package": "@threenative/core",
5799
5929
  "signature": "export class WorldCells extends Group implements IComputeDriven { … }",
@@ -8290,6 +8420,165 @@
8290
8420
  "supersedes": [],
8291
8421
  "symbol": "bakeWolfToFile"
8292
8422
  },
8423
+ {
8424
+ "aliases": ["city kit", "modular road tiles", "low poly city buildings", "cars and vehicles"],
8425
+ "constraints": [
8426
+ "fails closed: an unknown module throws naming the nearest ids; seed is an integer 0 to 4294967295, detail 0 to 2, wet 0 to 100, floors an integer 2 to 12, text at most 24 characters, dressing a boolean",
8427
+ "the same options write identical bytes on one Node major and machine (fonts draw the sign text); files are written atomically (temporary file, then rename)",
8428
+ "units are metres, +Y up; stock roads fit a 24 m grid, and custom straights and bends export updated socket positions, directions, widths and lane centres in the root node's extras",
8429
+ "roadWidth and markings apply to straight and curve; roadLength applies to straight; bendAngle, bendRadius and bendSide apply to curve; roadSurface applies to socketed road modules",
8430
+ "bake-time only, so keep it a dev dependency; textures are capped at 1024 px like the page's export"
8431
+ ],
8432
+ "example": "await bakeCity({ module: \"cross\", out: \"assets/city\" });\nawait bakeCity({ module: \"curve\", bendAngle: 55, bendRadius: 24, bendSide: \"left\", roadWidth: 12, sidewalk: false, curb: false, out: \"assets/city\" });\nawait bakeCity({ module: \"apartments\", seed: 7, floors: 8, out: \"assets/city\" });",
8433
+ "importPath": "@threenative/procedural-environment",
8434
+ "kind": "function",
8435
+ "overrides": [],
8436
+ "package": "@threenative/procedural-environment",
8437
+ "requires": ["npm i -D @threenative/procedural-environment"],
8438
+ "signature": "export async function bakeCity(options: IBakeCityOptions): Promise<IEnvironmentBake[]> { … }",
8439
+ "situations": [
8440
+ "generate a modular city street, intersection, roundabout or highway tile as a GLB",
8441
+ "a procedural building, storefront, office tower, apartment block, house or warehouse for a city level",
8442
+ "street props for a city: traffic signal, streetlight, bus shelter, hydrant, bench, mailbox, dumpster",
8443
+ "a race track kit: starting grid, timing gantry, barriers, tire wall, kerbs, pit lane; or a car, van, kart or formula car"
8444
+ ],
8445
+ "summary": "Bake an Apex City Kit module to one GLB: a road tile, a building, a street prop, a vehicle, a race kit piece, a block or lot, a sidewalk, transit, a public space, a utility or a decal. The page's own generator and GLTFExporter run headless, so the GLB carries its merged meshes, its materials and textures (Poly Haven CC0 PBR maps and the canvas-drawn signs, liveries and markings) and its road sockets in the root node's extras.",
8446
+ "supersedes": [],
8447
+ "symbol": "bakeCity"
8448
+ },
8449
+ {
8450
+ "aliases": ["rocks and boulders", "cliffs and mountains"],
8451
+ "constraints": [
8452
+ "fails closed: an unknown form or biome throws naming the nearest ids, as do unknown traits or surface keys, a non-integer seed, a lod outside 0 to 2 and a detail outside 0 to 1",
8453
+ "the same options write identical bytes; files are written atomically (temporary file, then rename)",
8454
+ "each GLB carries POSITION, NORMAL and COLOR_0 (linear RGB, rock and cover already blended) on one `rock` material; units are metres, +Y up, the rock rests on y = 0",
8455
+ "a `cliff` module shows a cut face at each end: bake a run with one seed and `offset: [n * width, 0, 0]`, stand the modules one width apart and bury the two ends of the run",
8456
+ "bake-time only, so keep it a dev dependency; the game owns the material and can re-material by the glTF material name `rock`"
8457
+ ],
8458
+ "example": "await bakeRock({ form: \"cliff\", biome: \"coastal\", seed: 7, lods: [0, 1], out: \"assets/rocks\" });\nawait bakeRock({ form: \"boulder\", biome: \"forest\", traits: { weathering: 0.8 }, out: \"assets/rocks\" });\nfor (const n of [0, 1, 2]) await bakeRock({ form: \"cliff\", biome: \"desert\", seed: 7, offset: [n * 10, 0, 0], out: \"assets/rocks\" }); // three modules of one wall",
8459
+ "importPath": "@threenative/procedural-environment",
8460
+ "kind": "function",
8461
+ "overrides": [],
8462
+ "package": "@threenative/procedural-environment",
8463
+ "requires": ["npm i -D @threenative/procedural-environment"],
8464
+ "signature": "export async function bakeRock(options: IBakeRockOptions): Promise<IEnvironmentBake[]> { … }",
8465
+ "situations": [
8466
+ "generate a procedural rock, boulder or cliff as a GLB for a game level",
8467
+ "desert mesa, hoodoo or sandstone arch; coastal sea stack; alpine spire; volcanic basalt columns",
8468
+ "a procedural mountain mesh for the horizon, with snow at altitude"
8469
+ ],
8470
+ "summary": "Bake a procedural rock (Outcrop) to GLBs, one per level of detail: a boulder, slab, spire, hoodoo, sea stack, mesa, arch, tileable cliff module or a mountain, weathered and coloured for its biome (moss in a forest, snow in the tundra, sand in the desert, algae below the tide line).",
8471
+ "supersedes": [],
8472
+ "symbol": "bakeRock"
8473
+ },
8474
+ {
8475
+ "aliases": [
8476
+ "trees",
8477
+ "palm trees",
8478
+ "street trees along a road",
8479
+ "bushes and shrubs",
8480
+ "grass, flowers and ferns as ground cover",
8481
+ "dead trees, fallen logs and stumps",
8482
+ "low poly tree with level of detail",
8483
+ "realistic textured tree model",
8484
+ "foliage and vegetation models",
8485
+ "pine, oak or spruce forest trees",
8486
+ "grass tufts and clumps"
8487
+ ],
8488
+ "constraints": [
8489
+ "fails closed: an unknown preset throws naming the nearest ids, the seed must be an integer and each lod 0 to 2",
8490
+ "the same preset, seed and lods write identical bytes; files are written atomically (temporary file, then rename)",
8491
+ "bake-time only, so keep it a dev dependency; the game owns the look and the sway (a TSL render/wind.ts reading _WIND), because Arbor.three is not shipped",
8492
+ "_WIND is vec4 (trunk sway, branch sway, flutter, phase): forest-kit sway is flutter in z, and debris writes all four zero",
8493
+ "textures default to \"scans\" (the bake's `scan` and `leafScan` name them); nine presets with no fitting CC0 leaf scan (ginkgo, palms, banana, joshua, flowers, elephantear) keep Arbor's drawn leaf card; textures: \"generated\" keeps every generator texture byte for byte",
8494
+ "form, leafImage, barkImage and barkNormalImage patch an Arbor preset only; a forest-kit debris or cover preset throws when given any"
8495
+ ],
8496
+ "example": "await bakeVegetation({ preset: \"oak\", seed: 7, lods: [0, 1], out: \"assets/trees\" });\nawait bakeVegetation({ preset: \"log\", seed: 3, out: \"assets/debris\" });",
8497
+ "importPath": "@threenative/procedural-environment",
8498
+ "kind": "function",
8499
+ "overrides": [],
8500
+ "package": "@threenative/procedural-environment",
8501
+ "requires": ["npm i -D @threenative/procedural-environment"],
8502
+ "signature": "export async function bakeVegetation(options: IBakeVegetationOptions): Promise<IEnvironmentBake[]> { … }",
8503
+ "situations": [
8504
+ "generate a procedural tree, an oak, pine, spruce, palm or any forest species as a GLB",
8505
+ "procedural oak tree GLB with level of detail for a game forest",
8506
+ "tree GLB for Unity, Unreal or Godot, with wind weights in a _WIND attribute",
8507
+ "a fallen mossy log and leaf litter on the forest floor, with a stump, twigs and boulders",
8508
+ "reeds and cattails at a pond edge, or sedge tussocks, clover and seeding grass as cover"
8509
+ ],
8510
+ "summary": "Bake a procedural tree (Arbor) to GLBs, one per level of detail, ready for ctx.assets.model. Each GLB carries the _WIND vertex attribute, COLOR_0 and TEXCOORD_0 and embeds WebP textures: Arbor trees and cover wear a CC0 bark scan and alpha-masked leaves, blades, fronds and needles painted from CC0 leaf scans; forest-kit wood and stone wear a grey CC0 detail scan, and forest-kit cover and leaf litter a grey CC0 blade or leaf scan, each over the kit's COLOR_0 palette.",
8511
+ "supersedes": [],
8512
+ "symbol": "bakeVegetation"
8513
+ },
8514
+ {
8515
+ "aliases": [],
8516
+ "constraints": [
8517
+ "ids match the Strata terrain kits where they overlap (forest, coastal, alpine, desert, tundra)"
8518
+ ],
8519
+ "example": "environmentBiomes().map((biome) => biome.id);",
8520
+ "importPath": "@threenative/procedural-environment",
8521
+ "kind": "function",
8522
+ "overrides": [],
8523
+ "package": "@threenative/procedural-environment",
8524
+ "requires": ["npm i -D @threenative/procedural-environment"],
8525
+ "signature": "export function environmentBiomes(): IEnvironmentBiome[] { … }",
8526
+ "situations": [
8527
+ "which biomes can I bake nature for: forest, desert, jungle, tundra, coast, volcano",
8528
+ "what trees, plants, debris and rocks belong in a desert or an alpine biome"
8529
+ ],
8530
+ "summary": "Every biome: its id, name, the request words that mean it, the rock surface its rocks wear and the element ids that belong there.",
8531
+ "supersedes": [],
8532
+ "symbol": "environmentBiomes"
8533
+ },
8534
+ {
8535
+ "aliases": [
8536
+ "nature props for a level",
8537
+ "jungle and tropical plants",
8538
+ "desert cactus",
8539
+ "vegetation for a biome"
8540
+ ],
8541
+ "constraints": [
8542
+ "fails closed: an unknown biome or kind throws naming the nearest ids",
8543
+ "biome takes an id or one of its words, so \"jungle\" finds tropical and \"swamp\" finds wetland"
8544
+ ],
8545
+ "example": "environmentElements({ biome: \"desert\", kind: \"rock\" }).map((element) => element.bake);\nenvironmentElements({ search: \"palm\" });",
8546
+ "importPath": "@threenative/procedural-environment",
8547
+ "kind": "function",
8548
+ "overrides": [],
8549
+ "package": "@threenative/procedural-environment",
8550
+ "requires": ["npm i -D @threenative/procedural-environment"],
8551
+ "signature": "export function environmentElements(filter: IEnvironmentFilter = { … }",
8552
+ "situations": [
8553
+ "what can I bake for a desert, a jungle, a coast, a tundra or a volcanic island",
8554
+ "list the rocks, cliffs and mountains for a biome, or every plant that grows there",
8555
+ "find a tree or plant by name or latin name, such as pine, palm, cactus or fern"
8556
+ ],
8557
+ "summary": "Find the nature elements to bake, by biome, kind or words: trees, ground cover, forest-floor debris and rock forms (boulders, cliffs, sea stacks, mesas, arches, mountains), each with the exact bake call.",
8558
+ "supersedes": [],
8559
+ "symbol": "environmentElements"
8560
+ },
8561
+ {
8562
+ "aliases": [],
8563
+ "constraints": [
8564
+ "ids come from the vendored Arbor and forest-kit presets; trees are kind \"tree\", grass, ferns and flowers are kind \"cover\", deadwood, litter and stone are kind \"debris\""
8565
+ ],
8566
+ "example": "vegetationPresets().filter((p) => p.kind === \"debris\").map((p) => p.id);",
8567
+ "importPath": "@threenative/procedural-environment",
8568
+ "kind": "function",
8569
+ "overrides": [],
8570
+ "package": "@threenative/procedural-environment",
8571
+ "requires": ["npm i -D @threenative/procedural-environment"],
8572
+ "signature": "export function vegetationPresets(): IVegetationPreset[] { … }",
8573
+ "situations": [
8574
+ "list the oak, pine, spruce, palm and other tree species a bake can grow",
8575
+ "choose a tree species id for bakeVegetation or a terrain arbor: species",
8576
+ "what deadwood, leaf litter, boulders, reeds and tussocks can I bake for a forest floor"
8577
+ ],
8578
+ "summary": "List every preset a bake can grow: id, name, latin name and kind. Trees and cover come from Arbor; the `debris` rows (log, stump, twig, branch, leaflitter, rock) and the extra cover rows (reeds, tussock, seedgrass, clover, dock, plume) come from forest-kit.",
8579
+ "supersedes": [],
8580
+ "symbol": "vegetationPresets"
8581
+ },
8293
8582
  {
8294
8583
  "aliases": [],
8295
8584
  "constraints": [
@@ -9068,6 +9357,27 @@
9068
9357
  "supersedes": [],
9069
9358
  "symbol": "gradientAt"
9070
9359
  },
9360
+ {
9361
+ "aliases": [],
9362
+ "constraints": [
9363
+ "the look stays the game's: pass the result with the kit's `render/grass.ts` blade and material"
9364
+ ],
9365
+ "example": "const placement = grassFieldFromBiome(biome, { heightAt: (x, z) => field.heightAt(x, z), waterLevel: 0 });\nif (placement) ctx.add(new GrassField3D({ ...placement, blade: grassBlade(), material: grassMaterial }));",
9366
+ "importPath": "@threenative/terrain",
9367
+ "kind": "function",
9368
+ "overrides": [],
9369
+ "package": "@threenative/terrain",
9370
+ "requires": ["npm i -D @threenative/terrain"],
9371
+ "signature": "export function grassFieldFromBiome( biome: Pick<IBiomeSpec, \"grass\" | \"seed\">, ground: IGrassGround, ): IGrassFieldPlacement | null { … }",
9372
+ "situations": [
9373
+ "grow streamed grass on a terrain world's biome grass rows",
9374
+ "a Strata or terrain_generate world with a meadow that sways round the player",
9375
+ "feed a cooked biome to GrassField3D"
9376
+ ],
9377
+ "summary": "Turns a terrain biome's grass rows and its ground into `GrassField3D` placement options, so a generated or cooked world grows streamed grass with one call. Returns null when the biome has no grass rows: the game draws no field. Each row covers its own slope band (full to `slope[1]`, gone `slopeFalloff` degrees past it), its own height band above `ground.floor` (fading over `heightFalloff` below the ceiling) and stays `waterMargin` above `ground.waterLevel`; the field takes the strongest row at each spot.",
9378
+ "supersedes": [],
9379
+ "symbol": "grassFieldFromBiome"
9380
+ },
9071
9381
  {
9072
9382
  "aliases": [],
9073
9383
  "constraints": [
@@ -9179,6 +9489,25 @@
9179
9489
  "supersedes": [],
9180
9490
  "symbol": "orderedScatterRules"
9181
9491
  },
9492
+ {
9493
+ "aliases": [],
9494
+ "constraints": [
9495
+ "`crowns` is metres of crown radius per unit of placement scale, keyed by asset; other assets paint nothing"
9496
+ ],
9497
+ "example": "paintCanopyCover(values, { size: 512, resolution: 257 }, placements, { spruce: 7 });",
9498
+ "importPath": "@threenative/terrain",
9499
+ "kind": "function",
9500
+ "overrides": [],
9501
+ "package": "@threenative/terrain",
9502
+ "requires": ["npm i -D @threenative/terrain"],
9503
+ "signature": "export function paintCanopyCover( values: Float32Array, world: { … }",
9504
+ "situations": [
9505
+ "shade the ground under a baked stand, at bake time or after a placement edit"
9506
+ ],
9507
+ "summary": "Paint each placed tree's crown into a per-vertex canopy grid, so the ground under a stand reads as forest floor rather than open turf. `values` is row-major Z then X, centred on the origin, at the heightfield's own spacing; each vertex keeps the strongest crown that reaches it (0 to 1).",
9508
+ "supersedes": [],
9509
+ "symbol": "paintCanopyCover"
9510
+ },
9182
9511
  {
9183
9512
  "aliases": [],
9184
9513
  "constraints": [
@@ -9281,6 +9610,23 @@
9281
9610
  "supersedes": [],
9282
9611
  "symbol": "scatterProps"
9283
9612
  },
9613
+ {
9614
+ "aliases": [],
9615
+ "constraints": [
9616
+ "offline: about 0.4 s of CPU for a 257² field; bake it, do not run it per frame"
9617
+ ],
9618
+ "example": "const sky = skyVisibility(heights, 257, 512);",
9619
+ "importPath": "@threenative/terrain",
9620
+ "kind": "function",
9621
+ "overrides": [],
9622
+ "package": "@threenative/terrain",
9623
+ "requires": ["npm i -D @threenative/terrain"],
9624
+ "signature": "export function skyVisibility( heights: ArrayLike<number>, resolution: number, size: number, { … }",
9625
+ "situations": ["bake a heightfield's sky occlusion for the ground's ambient light"],
9626
+ "summary": "The share of the sky each heightfield vertex sees past the terrain around it: 1 on open ground, lower on a valley floor, at a cliff foot or in a crater. The logic follows TerraForge3D's horizon ambient pass (MIT, `heightfield/ambient/compute.glsl`): march outward along evenly spaced azimuths, keep the highest horizon each one meets, and integrate the cosine-weighted sky above it, which is `cos²` of the horizon angle per azimuth. Only ground that rises over both the vertex's tangent plane and the horizontal occludes, so a straight slope and a steep face over a flat floor stay open: the lighting already counts the slope's own tilt. Heights are row-major Z then X, centred on the origin, as the baked world stores them. Every node marches: a strided march filled bilinearly erred by 0.13 at p99 on the alpine survey's creases. About 0.4 s of CPU a world, so `bakeKit` runs it and the game loads `<world>.sky.bin`.",
9627
+ "supersedes": [],
9628
+ "symbol": "skyVisibility"
9629
+ },
9284
9630
  {
9285
9631
  "aliases": [],
9286
9632
  "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
@@ -9989,7 +10335,7 @@
9989
10335
  "overrides": [],
9990
10336
  "package": "@threenative/terrain",
9991
10337
  "requires": ["npm i -D @threenative/terrain"],
9992
- "signature": "export async function bakeKit( url: string, { … }",
10338
+ "signature": "export async function bakeKit( url: string, options: IBakeKitOptions | IBakeKitWorldOptions, ): Promise<void> { … }",
9993
10339
  "situations": ["bake a copied terrain starter kit into its offline world package"],
9994
10340
  "summary": "Bake a copied kit, optionally using the caller's installed world cook.",
9995
10341
  "supersedes": [],
@@ -10029,131 +10375,620 @@
10029
10375
  "supersedes": [],
10030
10376
  "symbol": "addStarterWorld"
10031
10377
  },
10378
+ {
10379
+ "aliases": [],
10380
+ "constraints": ["the game supplies the height, the collar, its curve and the tile material"],
10381
+ "example": "const ground = addStreamedGround({ ctx, name, size, resolution, height, collar, curve, reach, stream, surface, follow, report });",
10382
+ "importPath": "@threenative/terrain/starter",
10383
+ "kind": "function",
10384
+ "overrides": [],
10385
+ "package": "@threenative/terrain",
10386
+ "requires": ["npm i -D @threenative/terrain @threenative/physics"],
10387
+ "signature": "export function addStreamedGround(options: IStreamedGroundOptions): { … }",
10388
+ "situations": ["stream an authored square's ground past its edge, out to a drawn collar"],
10389
+ "summary": "PRD-790: the ground past the playable square, streamed around the player by `TerrainTiles` out to the collar's reach. Tiles sample the kit's own height function, the surface the square and the collar's vertices stand on, so a tile meets the square and its neighbours with no step. The tile material slides the outermost tile onto the collar's drawn height (`collarMorph`), so at the collar every tile vertex stands on it; `?tnTerrainValidate=1` reports `streamCollarGap`. The largest block of resident tiles around the player is written to the stream each frame: the tiles draw inside it, the collar everywhere else, so a tile that is still building leaves the collar showing, never a hole.",
10390
+ "supersedes": [],
10391
+ "symbol": "addStreamedGround"
10392
+ },
10032
10393
  {
10033
10394
  "aliases": [],
10034
10395
  "constraints": [],
10035
- "example": "const edited = editWorldPlacements(data, { remove: [\"scree:candidate:7:41\"] }, (x, z) => field.heightAt(x, z));",
10396
+ "example": "const quaternion = authoredQuaternion(placement);",
10036
10397
  "importPath": "@threenative/terrain/starter",
10037
10398
  "kind": "function",
10038
- "overrides": [
10039
- "grounding defaults on, while `grounding: false` preserves the authored Y coordinate"
10040
- ],
10399
+ "overrides": [],
10041
10400
  "package": "@threenative/terrain",
10042
10401
  "requires": ["npm i -D @threenative/terrain"],
10043
- "signature": "export function editWorldPlacements( data: { … }",
10044
- "situations": [
10045
- "change generated terrain composition from game source without rebaking the world"
10046
- ],
10047
- "summary": "Apply deterministic startup edits to the decoded placement data before a world is loaded.",
10402
+ "signature": "export function authoredQuaternion( placement: IPlacement, ): readonly [number, number, number, number] { … }",
10403
+ "situations": ["compose a placement's authored rotation before grounding it"],
10404
+ "summary": "The quaternion a placement's own scatter numbers describe: the normal tilt, then the yaw.",
10048
10405
  "supersedes": [],
10049
- "symbol": "editWorldPlacements"
10406
+ "symbol": "authoredQuaternion"
10050
10407
  },
10051
10408
  {
10052
10409
  "aliases": [],
10053
- "constraints": ["Shapes and reach are supplied by the game; detach releases every body"],
10054
- "example": "new PropColliders(ctx, follow, manifest, records, shapes, reach, name);",
10410
+ "constraints": [],
10411
+ "example": "beginScene(\"forest\");",
10055
10412
  "importPath": "@threenative/terrain/starter",
10056
- "kind": "class",
10413
+ "kind": "function",
10057
10414
  "overrides": [],
10058
10415
  "package": "@threenative/terrain",
10059
10416
  "requires": ["npm i -D @threenative/terrain"],
10060
- "signature": "export class PropColliders extends Object3D implements IComputeDriven { … }",
10061
- "situations": ["attach nearby prop collision bodies from baked placement records"],
10062
- "summary": "Stream caller-specified fixed collision shapes around a moving follow object.",
10417
+ "signature": "export function beginScene(world: string): void { … }",
10418
+ "situations": ["start the run's view accounting when a scene enters"],
10419
+ "summary": "Start a scene's view accounting: the player view it opens in, and nothing measured yet.",
10063
10420
  "supersedes": [],
10064
- "symbol": "PropColliders"
10421
+ "symbol": "beginScene"
10065
10422
  },
10066
10423
  {
10067
10424
  "aliases": [],
10068
- "constraints": ["creates only geometry; the caller owns its material, scene and disposal"],
10069
- "example": "const geometry = toGeometry(bakeMesh(new Terrain({ resolution: 17 }).evaluate()));",
10070
- "importPath": "@threenative/terrain/three",
10425
+ "constraints": ["the curve must be the one the collar was built with"],
10426
+ "example": "const y = collarArithmeticHeight(collar, { power: 1.65, reach: 2100 }, x, z);",
10427
+ "importPath": "@threenative/terrain/starter",
10071
10428
  "kind": "function",
10072
- "overrides": ["every surface choice remains in game source"],
10429
+ "overrides": [],
10073
10430
  "package": "@threenative/terrain",
10074
- "requires": ["npm i @threenative/terrain"],
10075
- "signature": "export function toGeometry(mesh: IBakedMesh): BufferGeometry { … }",
10076
- "situations": ["put an authored terrain mesh in a game-owned Three.js scene"],
10077
- "summary": "Converts baked arrays to ordinary geometry using the consumer's installed Three.js.",
10431
+ "requires": ["npm i -D @threenative/terrain"],
10432
+ "signature": "export function collarArithmeticHeight( collar: HeightfieldCollar, curve: ICollarRingCurve, x: number, z: number, ): number { … }",
10433
+ "situations": ["answer a collar height on the CPU exactly as its tile shader computes it"],
10434
+ "summary": "The collar triangle under `(x, z)` found by arithmetic alone, as the tile shader finds it: the ring from the ring spacing, the perimeter step from the face the point projects onto, and the triangle from the point's place in the quad. On one face the world point is an affine map of `(scale, share * scale)`, so weights read there are the drawn triangle's own.",
10078
10435
  "supersedes": [],
10079
- "symbol": "toGeometry"
10436
+ "symbol": "collarArithmeticHeight"
10080
10437
  },
10081
10438
  {
10082
10439
  "aliases": [],
10083
10440
  "constraints": [
10084
- "rejects indices, channels, or material sections that disagree with the vertex count before any geometry is constructed"
10441
+ "reads the collar it is given; never resamples the square or builds a surface"
10085
10442
  ],
10086
- "example": "const geometry = createThreeGeometry(model.lods[0]);",
10087
- "importPath": "@threenative/ueformat",
10443
+ "example": "const y = collarDrawnHeight(collar, x, z);",
10444
+ "importPath": "@threenative/terrain/starter",
10088
10445
  "kind": "function",
10089
10446
  "overrides": [],
10090
- "package": "@threenative/ueformat",
10091
- "requires": ["npm i @threenative/ueformat"],
10092
- "signature": "export function createThreeGeometry( lod: IUEModelLOD, adapterOptions: IThreeAdapterOptions = { … }",
10093
- "situations": [
10094
- "convert one Unreal mesh LOD into a three.js BufferGeometry by hand",
10095
- "build custom scene objects from Unreal mesh data instead of a whole model"
10096
- ],
10097
- "summary": "Converts one parsed Unreal mesh LOD into a `THREE.BufferGeometry` — coordinates, scale, winding, normals, tangents, UVs, vertex colours, morphs, skin weights, and material groups.",
10447
+ "package": "@threenative/terrain",
10448
+ "requires": ["npm i -D @threenative/terrain"],
10449
+ "signature": "export function collarDrawnHeight(collar: HeightfieldCollar, x: number, z: number): number | null { … }",
10450
+ "situations": ["measure or collide against the triangles a collar actually draws"],
10451
+ "summary": "The collar's drawn height under `(x, z)`; null where there is no collar.",
10098
10452
  "supersedes": [],
10099
- "symbol": "createThreeGeometry"
10453
+ "symbol": "collarDrawnHeight"
10100
10454
  },
10101
10455
  {
10102
10456
  "aliases": [],
10103
10457
  "constraints": [
10104
- "every material comes from the game through `materialFactory`; the fallback is three.js's own GLTFLoader default, a plain MeshStandardMaterial",
10105
- "parsed bones are exposed on `userData` but never bound into a THREE.SkinnedMesh — skeletal rendering is the game's job"
10458
+ "the curve must be the one the collar was built with; the band is one tile wide"
10106
10459
  ],
10107
- "example": "const hero = createThreeObject(parseUEModel(buffer), { lodDistances: [0, 25, 50] });",
10108
- "importPath": "@threenative/ueformat",
10460
+ "example": "tile.positionNode = collarMorph(collar, { power: 1.65, reach: 2100 }, stream, 64);",
10461
+ "importPath": "@threenative/terrain/starter",
10109
10462
  "kind": "function",
10110
10463
  "overrides": [],
10111
- "package": "@threenative/ueformat",
10112
- "requires": ["npm i @threenative/ueformat"],
10113
- "signature": "export function createThreeObject( model: IUEModelData, adapterOptions: IThreeAdapterOptions = { … }",
10114
- "situations": [
10115
- "put a mesh exported from an Unreal package on screen",
10116
- "load an Unreal static or skeletal mesh with LODs, sockets, and collision geometry"
10117
- ],
10118
- "summary": "Builds a renderable Three.js object — a `Group` for single-LOD models, a `THREE.LOD` for multi-LOD ones — from parsed `.uemodel` data, with collision geometry on `userData`.",
10464
+ "package": "@threenative/terrain",
10465
+ "requires": ["npm i -D @threenative/terrain"],
10466
+ "signature": "export function collarMorph( collar: HeightfieldCollar, curve: ICollarRingCurve, stream: ICollarStream, band: number, ): Node<\"vec3\"> { … }",
10467
+ "situations": ["slide the streamed ground's outer tile onto a drawn collar without a seam"],
10468
+ "summary": "PRD-790 box 2: the streamed tiles' vertex shift. Only the outermost tile of the square the tiles draw slides onto the collar's drawn height, smoothly over that tile, so at the square's edge every tile vertex stands on the collar; the ground inside keeps the survey's smooth surface. The collar's heights go to the GPU once, as a float texture of rings by perimeter steps.",
10119
10469
  "supersedes": [],
10120
- "symbol": "createThreeObject"
10470
+ "symbol": "collarMorph"
10121
10471
  },
10122
10472
  {
10123
10473
  "aliases": [],
10124
10474
  "constraints": [
10125
- "only UEFormat v10 UEMODEL files are accepted; anything else throws UEFormatError with the byte offset",
10126
- "ZSTD-compressed bodies require an injected `zstdDecoder`; the package never bundles a ZSTD implementation"
10475
+ "the caller supplies the height the tiles draw; a coarser `step` samples faster"
10127
10476
  ],
10128
- "example": "const model = parseUEModel(await file.arrayBuffer());",
10129
- "importPath": "@threenative/ueformat",
10477
+ "example": "const { gap, fold } = collarSeamGap(collar, tilesHeight, x, z, 288, 2);",
10478
+ "importPath": "@threenative/terrain/starter",
10130
10479
  "kind": "function",
10131
10480
  "overrides": [],
10132
- "package": "@threenative/ueformat",
10133
- "requires": ["npm i @threenative/ueformat"],
10134
- "signature": "export function parseUEModel( input: ArrayBuffer | ArrayBufferView, options: IParseUEModelOptions = { … }",
10135
- "situations": [
10136
- "parse a mesh exported from an Unreal package without Unreal installed",
10137
- "inspect the LODs, skeleton, sockets, and collision inside a .uemodel file"
10138
- ],
10139
- "summary": "Parses a UEFormat v10 `.uemodel` body — the interchange format CUE4Parse and FModel export from Unreal packages — into validated, plain mesh data without building any Three.js objects.",
10481
+ "package": "@threenative/terrain",
10482
+ "requires": ["npm i -D @threenative/terrain"],
10483
+ "signature": "export function collarSeamGap( collar: HeightfieldCollar, height: (x: number, z: number) => number, centreX: number, centreZ: number, half: number, spacing: number, step = 0.1, ): { … }",
10484
+ "situations": ["prove a streamed ground and its collar meet without a step"],
10485
+ "summary": "PRD-790: where streamed tiles meet the collar. The tiles draw inside the square `(centreX, centreZ, half)` and the collar outside it, so the seam is that square's edge, past the playable square. `gap` is the largest step at the tiles' edge vertices (`spacing` apart), as core measures a tile-to-tile seam; `fold` is the largest step between them, where a fold of the collar's coarser triangles crosses a tile's straight edge.",
10140
10486
  "supersedes": [],
10141
- "symbol": "parseUEModel"
10487
+ "symbol": "collarSeamGap"
10142
10488
  },
10143
10489
  {
10144
10490
  "aliases": [],
10145
10491
  "constraints": [
10146
- "the summary reflects one already-parsed model; it does not read files itself"
10492
+ "the world name is the one this state measures; a blank name fails rather than reporting \"\""
10147
10493
  ],
10148
- "example": "const summary = summarizeUEModel(parseUEModel(buffer));",
10149
- "importPath": "@threenative/ueformat",
10494
+ "example": "const state = { ...createDiagnosticsState(\"forest\"), showcase: false };",
10495
+ "importPath": "@threenative/terrain/starter",
10150
10496
  "kind": "function",
10151
10497
  "overrides": [],
10152
- "package": "@threenative/ueformat",
10153
- "requires": ["npm i @threenative/ueformat"],
10154
- "signature": "export function summarizeUEModel(model: IUEModelData): IUEModelSummary { … }",
10498
+ "package": "@threenative/terrain",
10499
+ "requires": ["npm i -D @threenative/terrain @threenative/physics"],
10500
+ "signature": "export function createDiagnosticsState(world: string) { … }",
10155
10501
  "situations": [
10156
- "report what a UEFormat model contains without dumping its vertex data",
10502
+ "start a kit's game state with the measurements every streamed starter world reports"
10503
+ ],
10504
+ "summary": "The state one world's measurements are reported through, with its own name in it. The game spreads this into its own state and adds the look values it also reports; the counters live here. The window groups and the drawn-frame counts are module-level on purpose: `ctx.goto` builds a new scene for the next world, and the numbers a run reports are the run's, not one scene's.",
10505
+ "supersedes": [],
10506
+ "symbol": "createDiagnosticsState"
10507
+ },
10508
+ {
10509
+ "aliases": [],
10510
+ "constraints": [
10511
+ "the game supplies the actor, the player body and the probe fixture; it owns no look"
10512
+ ],
10513
+ "example": "const measure = createMeasure({ world, physics: ctx.physics, raycast, actor, player, ...options });",
10514
+ "importPath": "@threenative/terrain/starter",
10515
+ "kind": "function",
10516
+ "overrides": [],
10517
+ "package": "@threenative/terrain",
10518
+ "requires": ["npm i -D @threenative/terrain @threenative/physics"],
10519
+ "signature": "export function createMeasure(options: IMeasureOptions): IMeasure { … }",
10520
+ "situations": ["measure one played starter world every fixed step"],
10521
+ "summary": "The per-world measurement: contacts, travel, edge overshoot, water and the frame facts a run reports.",
10522
+ "supersedes": [],
10523
+ "symbol": "createMeasure"
10524
+ },
10525
+ {
10526
+ "aliases": [],
10527
+ "constraints": ["mirrors `collarMorph`'s weight exactly; both read the same curve and band"],
10528
+ "example": "const height = createMorphedHeight(collar, curve, surveyHeight, x, z, 288, 64);",
10529
+ "importPath": "@threenative/terrain/starter",
10530
+ "kind": "function",
10531
+ "overrides": [],
10532
+ "package": "@threenative/terrain",
10533
+ "requires": ["npm i -D @threenative/terrain"],
10534
+ "signature": "export function createMorphedHeight( collar: HeightfieldCollar, curve: ICollarRingCurve, height: (x: number, z: number) => number, centreX: number, centreZ: number, half: number, band: number, ): (x: number, z: number) => number { … }",
10535
+ "situations": ["check on the CPU the surface the tile shader draws after its morph"],
10536
+ "summary": "The height a tile vertex stands at once `collarMorph` moved it: the survey inside the band, the collar's arithmetic height at the drawn square's edge. The seam measure reads this.",
10537
+ "supersedes": [],
10538
+ "symbol": "createMorphedHeight"
10539
+ },
10540
+ {
10541
+ "aliases": [],
10542
+ "constraints": [
10543
+ "the game builds the camera and the wall probe; the package owns only their wiring"
10544
+ ],
10545
+ "example": "const rig = createPlayerRig({ at, field, mannequin, clips, gait, camera, probe, ...options });",
10546
+ "importPath": "@threenative/terrain/starter",
10547
+ "kind": "function",
10548
+ "overrides": [],
10549
+ "package": "@threenative/terrain",
10550
+ "requires": ["npm i -D @threenative/terrain @threenative/physics"],
10551
+ "signature": "export function createPlayerRig(options: IPlayerRigOptions): IPlayerRig { … }",
10552
+ "situations": ["give a copied starter kit its player capsule, mannequin and follow camera"],
10553
+ "summary": "The player: the capsule the solver moves, the mannequin that rides it, and the third-person camera that follows with the terrain as its walls. The stepped world is the authority for both the ground the player stands on and the wall the orbit camera cannot pass, which is why both queries mask to the game's ground layer: what the player can walk on. Every appearance value — the mannequin, its clips, the gait speeds, the capsule and the camera framing — comes from the game.",
10554
+ "supersedes": [],
10555
+ "symbol": "createPlayerRig"
10556
+ },
10557
+ {
10558
+ "aliases": [],
10559
+ "constraints": [],
10560
+ "example": "const reveal = createRevealProbe({ camera, covered, phase, released, ...options });",
10561
+ "importPath": "@threenative/terrain/starter",
10562
+ "kind": "function",
10563
+ "overrides": [],
10564
+ "package": "@threenative/terrain",
10565
+ "requires": ["npm i -D @threenative/terrain"],
10566
+ "signature": "export function createRevealProbe(options: IRevealProbeOptions): IRevealProbe { … }",
10567
+ "situations": ["measure whether the spawn drew before the curtain released it"],
10568
+ "summary": "What the loading reveal showed once the curtain lifts: drawn batches, pipelines and impostor readiness, measured against the reveal's own baseline.",
10569
+ "supersedes": [],
10570
+ "symbol": "createRevealProbe"
10571
+ },
10572
+ {
10573
+ "aliases": [],
10574
+ "constraints": [
10575
+ "Every value it reports is supplied by the game; a failure writes one `TN_` line"
10576
+ ],
10577
+ "example": "const gate = createSpawnGate(ctx, { world, progress, witness, released });",
10578
+ "importPath": "@threenative/terrain/starter",
10579
+ "kind": "function",
10580
+ "overrides": [],
10581
+ "package": "@threenative/terrain",
10582
+ "requires": ["npm i -D @threenative/terrain"],
10583
+ "signature": "export function createSpawnGate(ctx: SpawnGateHost, options: ISpawnGateOptions): ISpawnGate { … }",
10584
+ "situations": ["hold a streamed starter world's loading screen until its spawn has landed"],
10585
+ "summary": "The spawn gate: one deadline, one settlement, one failure report. `WorldCells.whenSpawnReady` is the data authority and each streamed world's `prewarmed` is the draw gate; this gate turns their landing into the loading screen's release, and writes the one console line a failed spawn leaves behind.",
10586
+ "supersedes": [],
10587
+ "symbol": "createSpawnGate"
10588
+ },
10589
+ {
10590
+ "aliases": [],
10591
+ "constraints": [],
10592
+ "example": "const edited = editWorldPlacements(data, { remove: [\"scree:candidate:7:41\"] }, (x, z) => field.heightAt(x, z));",
10593
+ "importPath": "@threenative/terrain/starter",
10594
+ "kind": "function",
10595
+ "overrides": [
10596
+ "grounding defaults on, while `grounding: false` preserves the authored Y coordinate"
10597
+ ],
10598
+ "package": "@threenative/terrain",
10599
+ "requires": ["npm i -D @threenative/terrain"],
10600
+ "signature": "export function editWorldPlacements( data: { … }",
10601
+ "situations": [
10602
+ "change generated terrain composition from game source without rebaking the world"
10603
+ ],
10604
+ "summary": "Apply deterministic startup edits to the decoded placement data before a world is loaded.",
10605
+ "supersedes": [],
10606
+ "symbol": "editWorldPlacements"
10607
+ },
10608
+ {
10609
+ "aliases": [],
10610
+ "constraints": [],
10611
+ "example": "const { windows } = enterView(\"forest\", \"overview\");",
10612
+ "importPath": "@threenative/terrain/starter",
10613
+ "kind": "function",
10614
+ "overrides": [],
10615
+ "package": "@threenative/terrain",
10616
+ "requires": ["npm i -D @threenative/terrain"],
10617
+ "signature": "export function enterView(world: string, view: string): { … }",
10618
+ "situations": ["switch the measured view when the benchmark camera cycle moves"],
10619
+ "summary": "The camera cycle moved to another view: a keyed group for it, and a fresh measurement.",
10620
+ "supersedes": [],
10621
+ "symbol": "enterView"
10622
+ },
10623
+ {
10624
+ "aliases": [],
10625
+ "constraints": [],
10626
+ "example": "invalidatePropShadows(ctx.shadows, region);",
10627
+ "importPath": "@threenative/terrain/starter",
10628
+ "kind": "function",
10629
+ "overrides": [],
10630
+ "package": "@threenative/terrain",
10631
+ "requires": ["npm i -D @threenative/terrain"],
10632
+ "signature": "export function invalidatePropShadows( shadow: { … }",
10633
+ "situations": [
10634
+ "forward a streamed world's changed caster bounds to the game's shadow renderer"
10635
+ ],
10636
+ "summary": "Keep WorldCells' changed caster bounds when forwarding to the existing shadow renderer.",
10637
+ "supersedes": [],
10638
+ "symbol": "invalidatePropShadows"
10639
+ },
10640
+ {
10641
+ "aliases": [],
10642
+ "constraints": [],
10643
+ "example": "leaveScene();",
10644
+ "importPath": "@threenative/terrain/starter",
10645
+ "kind": "function",
10646
+ "overrides": [],
10647
+ "package": "@threenative/terrain",
10648
+ "requires": ["npm i -D @threenative/terrain"],
10649
+ "signature": "export function leaveScene(): void { … }",
10650
+ "situations": ["stop attributing windows to a view when its scene is left"],
10651
+ "summary": "The scene is gone: nothing is on screen, so no window can belong to a view.",
10652
+ "supersedes": [],
10653
+ "symbol": "leaveScene"
10654
+ },
10655
+ {
10656
+ "aliases": [],
10657
+ "constraints": [],
10658
+ "example": "const canopy = await loadCanopy(assets, \"forest\");",
10659
+ "importPath": "@threenative/terrain/starter",
10660
+ "kind": "function",
10661
+ "overrides": [],
10662
+ "package": "@threenative/terrain",
10663
+ "requires": ["npm i -D @threenative/terrain"],
10664
+ "signature": "export async function loadCanopy( assets: Pick<IAssetLoader, \"resolve\">, world: string, ): Promise<Float32Array> { … }",
10665
+ "situations": ["load the canopy map a streamed world's ground shades with"],
10666
+ "summary": "The canopy weight the ground shader reads, painted from the placements the bake drew.",
10667
+ "supersedes": [],
10668
+ "symbol": "loadCanopy"
10669
+ },
10670
+ {
10671
+ "aliases": [],
10672
+ "constraints": [],
10673
+ "example": "const props = await loadPropPackage(assets, \"forest\");",
10674
+ "importPath": "@threenative/terrain/starter",
10675
+ "kind": "function",
10676
+ "overrides": [],
10677
+ "package": "@threenative/terrain",
10678
+ "requires": ["npm i -D @threenative/terrain"],
10679
+ "signature": "export async function loadPropPackage( assets: Pick<IAssetLoader, \"resolve\">, world: string, ): Promise<IPropPackage> { … }",
10680
+ "situations": ["load the prop containers a bake wrote for one world"],
10681
+ "summary": "The baked prop package of one world, fetched as the bake wrote it. The files are the bake's output, not the game's: the manifest names one container, one reach array and one placement-ID list per streamed world, and nothing here derives a placement.",
10682
+ "supersedes": [],
10683
+ "symbol": "loadPropPackage"
10684
+ },
10685
+ {
10686
+ "aliases": [],
10687
+ "constraints": [],
10688
+ "example": "const sky = await loadSky(assets, \"forest\");",
10689
+ "importPath": "@threenative/terrain/starter",
10690
+ "kind": "function",
10691
+ "overrides": [],
10692
+ "package": "@threenative/terrain",
10693
+ "requires": ["npm i -D @threenative/terrain"],
10694
+ "signature": "export async function loadSky( assets: Pick<IAssetLoader, \"resolve\">, world: string, ): Promise<Float32Array> { … }",
10695
+ "situations": ["load the sky-visibility map a streamed world's ground shades with"],
10696
+ "summary": "The share of the sky each terrain vertex sees past the relief, as `skyVisibility` baked it.",
10697
+ "supersedes": [],
10698
+ "symbol": "loadSky"
10699
+ },
10700
+ {
10701
+ "aliases": [],
10702
+ "constraints": [],
10703
+ "example": "ctx.beforeRender(() => observeFrame(ctx));",
10704
+ "importPath": "@threenative/terrain/starter",
10705
+ "kind": "function",
10706
+ "overrides": [],
10707
+ "package": "@threenative/terrain",
10708
+ "requires": ["npm i -D @threenative/terrain"],
10709
+ "signature": "export function observeFrame(ctx: ICounterCtx): void { … }",
10710
+ "situations": ["count a drawn frame and open the next GPU sample window"],
10711
+ "summary": "One world frame was drawn: count it, and open a fresh GPU sample window if the view or the readiness changed. Called from the render hook, before the camera is placed.",
10712
+ "supersedes": [],
10713
+ "symbol": "observeFrame"
10714
+ },
10715
+ {
10716
+ "aliases": [],
10717
+ "constraints": [],
10718
+ "example": "frameBudget: { onWindow: observeWindow }",
10719
+ "importPath": "@threenative/terrain/starter",
10720
+ "kind": "function",
10721
+ "overrides": [],
10722
+ "package": "@threenative/terrain",
10723
+ "requires": ["npm i -D @threenative/terrain"],
10724
+ "signature": "export function observeWindow(window: IFrameBudgetWindow): void { … }",
10725
+ "situations": ["read the engine's own closed frame window into the run's report"],
10726
+ "summary": "The frame-budget window closed: latch it, and update the numbers the run reports.",
10727
+ "supersedes": [],
10728
+ "symbol": "observeWindow"
10729
+ },
10730
+ {
10731
+ "aliases": [],
10732
+ "constraints": [
10733
+ "the burial, footprint and base-ring assets are the game's; the package applies them"
10734
+ ],
10735
+ "example": "const pose = preparePose(foot.geometry, material, record.placement, undefined, groundAt, rules);",
10736
+ "importPath": "@threenative/terrain/starter",
10737
+ "kind": "function",
10738
+ "overrides": [],
10739
+ "package": "@threenative/terrain",
10740
+ "requires": ["npm i -D @threenative/terrain"],
10741
+ "signature": "export function preparePose( geometry: BufferGeometry, _material: Material, placement: IPlacement, transform: IPlacementOverride | undefined, groundAt: PropGroundQuery, rules: IPropGroundRules, pose?: IPropPoseOverride, ): IPropPose { … }",
10742
+ "situations": ["ground one baked prop record on the game's height field before streaming it"],
10743
+ "summary": "The pose a prop draws at, grounded on the game's own height field. The record's quaternion, when present, replaces the rotation a live placement composes; every step below it — the ground snap, the boulder burial, the flat-footprint sink and the crag base ring — still runs, because the record is a pose and not an override of the pose. A placement with no ground under it fails closed by its own id, so a streamed world cannot silently float.",
10744
+ "supersedes": [],
10745
+ "symbol": "preparePose"
10746
+ },
10747
+ {
10748
+ "aliases": [],
10749
+ "constraints": [],
10750
+ "example": "const prepared = preparePropTransform(instance, transform, groundAt, rules);",
10751
+ "importPath": "@threenative/terrain/starter",
10752
+ "kind": "function",
10753
+ "overrides": [],
10754
+ "package": "@threenative/terrain",
10755
+ "requires": ["npm i -D @threenative/terrain"],
10756
+ "signature": "export function preparePropTransform( instance: IPropInstance, transform: IPlacementOverride | undefined, groundAt: PropGroundQuery, rules: IPropGroundRules, ) { … }",
10757
+ "situations": ["re-pose one prop the editor edited and keep the transform it reported"],
10758
+ "summary": "The pose and the transform an editor edited, prepared together so one write reports both.",
10759
+ "supersedes": [],
10760
+ "symbol": "preparePropTransform"
10761
+ },
10762
+ {
10763
+ "aliases": [],
10764
+ "constraints": ["Shapes and reach are supplied by the game; detach releases every body"],
10765
+ "example": "new PropColliders(ctx, follow, manifest, records, shapes, reach, name);",
10766
+ "importPath": "@threenative/terrain/starter",
10767
+ "kind": "class",
10768
+ "overrides": [],
10769
+ "package": "@threenative/terrain",
10770
+ "requires": ["npm i -D @threenative/terrain"],
10771
+ "signature": "export class PropColliders extends Object3D implements IComputeDriven { … }",
10772
+ "situations": ["attach nearby prop collision bodies from baked placement records"],
10773
+ "summary": "Stream caller-specified fixed collision shapes around a moving follow object.",
10774
+ "supersedes": [],
10775
+ "symbol": "PropColliders"
10776
+ },
10777
+ {
10778
+ "aliases": [],
10779
+ "constraints": [],
10780
+ "example": "const counts = propCounts(pkg, [\"spruce\", \"boulder\"]);",
10781
+ "importPath": "@threenative/terrain/starter",
10782
+ "kind": "function",
10783
+ "overrides": [],
10784
+ "package": "@threenative/terrain",
10785
+ "requires": ["npm i -D @threenative/terrain"],
10786
+ "signature": "export function propCounts( pkg: IPropPackage, assetNames: readonly string[], ): Record<string, number> { … }",
10787
+ "situations": ["report how many records each asset drew, zero included"],
10788
+ "summary": "Records per asset across the package's buckets: what the run report calls the scatter's counts.",
10789
+ "supersedes": [],
10790
+ "symbol": "propCounts"
10791
+ },
10792
+ {
10793
+ "aliases": [],
10794
+ "constraints": [],
10795
+ "example": "const key = propKey(placement, 2);",
10796
+ "importPath": "@threenative/terrain/starter",
10797
+ "kind": "function",
10798
+ "overrides": [],
10799
+ "package": "@threenative/terrain",
10800
+ "requires": ["npm i -D @threenative/terrain"],
10801
+ "signature": "export function propKey(placement: IPlacement, variant: number): string { … }",
10802
+ "situations": ["name the model a baked or live placement record draws"],
10803
+ "summary": "The model a record draws: its asset, its variant, and the shape a non-uniform edit gave it. `WorldCells` names the model through the run the record sits in, so this key is what the container stores. A placement with one uniform scale draws its variant as authored (`spruce:2`); a placement the editor scaled unevenly draws a model of that shape (`spruce:2@1,0.5,0.5`), so the record stays one uniform scale and the picture keeps the edit.",
10804
+ "supersedes": [],
10805
+ "symbol": "propKey"
10806
+ },
10807
+ {
10808
+ "aliases": [],
10809
+ "constraints": [],
10810
+ "example": "const ratio = propRatio(\"spruce:2@1,0.5,0.5\");",
10811
+ "importPath": "@threenative/terrain/starter",
10812
+ "kind": "function",
10813
+ "overrides": [],
10814
+ "package": "@threenative/terrain",
10815
+ "requires": ["npm i -D @threenative/terrain"],
10816
+ "signature": "export function propRatio(key: string): [number, number, number] { … }",
10817
+ "situations": ["scale a streamed model by the shape its record's single scale cannot carry"],
10818
+ "summary": "The shape `propKey` wrote, so the loader scales the model the record's one scale cannot carry.",
10819
+ "supersedes": [],
10820
+ "symbol": "propRatio"
10821
+ },
10822
+ {
10823
+ "aliases": [],
10824
+ "constraints": [],
10825
+ "example": "publish(ctx, { world, worldReady, frames, ...facts });",
10826
+ "importPath": "@threenative/terrain/starter",
10827
+ "kind": "function",
10828
+ "overrides": [],
10829
+ "package": "@threenative/terrain",
10830
+ "requires": ["npm i -D @threenative/terrain"],
10831
+ "signature": "export function publish( ctx: { … }",
10832
+ "situations": ["write the measured view and frame numbers into the game's state"],
10833
+ "summary": "Publish the measurements and the scene's own facts into state, twice per second.",
10834
+ "supersedes": [],
10835
+ "symbol": "publish"
10836
+ },
10837
+ {
10838
+ "aliases": [],
10839
+ "constraints": [],
10840
+ "example": "const transform = readPropTransform(instance);",
10841
+ "importPath": "@threenative/terrain/starter",
10842
+ "kind": "function",
10843
+ "overrides": [],
10844
+ "package": "@threenative/terrain",
10845
+ "requires": ["npm i -D @threenative/terrain"],
10846
+ "signature": "export function readPropTransform(instance: IPropInstance): IPlacementOverride { … }",
10847
+ "situations": ["read an edited prop's current pose for the scene format"],
10848
+ "summary": "The transform an instance's current pose describes.",
10849
+ "supersedes": [],
10850
+ "symbol": "readPropTransform"
10851
+ },
10852
+ {
10853
+ "aliases": [],
10854
+ "constraints": [
10855
+ "the variant, reach, bucket, LOD and gate rows are the game's; the package only applies"
10856
+ ],
10857
+ "example": "const props = await streamProps({ package: propPackage, groundAt, parts, materials, surface,\n follow, size, whileCurrent, variantOf, reachOf, bucketOf, lodOf, ...options });",
10858
+ "importPath": "@threenative/terrain/starter",
10859
+ "kind": "function",
10860
+ "overrides": [],
10861
+ "package": "@threenative/terrain",
10862
+ "requires": ["npm i -D @threenative/terrain"],
10863
+ "signature": "export async function streamProps(options: IPropWorldOptions) { … }",
10864
+ "situations": [
10865
+ "stream a world's baked prop containers and its live placements through WorldCells"
10866
+ ],
10867
+ "summary": "Load the prop worlds, pose every record on the ground, and hand each bucket to `WorldCells`. The passes are short and yield between slices, because the whole point of streaming is that the first frame does not wait for 200 000 records: the records are decoded and grounded in slices, and each bucket loads as its own world.",
10868
+ "supersedes": [],
10869
+ "symbol": "streamProps"
10870
+ },
10871
+ {
10872
+ "aliases": [],
10873
+ "constraints": [],
10874
+ "example": "const record = withAuthoredPose(placement);",
10875
+ "importPath": "@threenative/terrain/starter",
10876
+ "kind": "function",
10877
+ "overrides": [],
10878
+ "package": "@threenative/terrain",
10879
+ "requires": ["npm i -D @threenative/terrain"],
10880
+ "signature": "export function withAuthoredPose(placement: IPlacement): IPlacement { … }",
10881
+ "situations": ["fold an authored placement into the record transform the bake stores"],
10882
+ "summary": "A placement as a package record stores it: the authored pose becomes its transform, at one scale. A record holds position, quaternion and one uniform scale, so an edited placement's own transform is folded down to the scale its record carries. The shape that scale removed is `propKey`'s ratio, and the drawable model that ratio names carries it instead.",
10883
+ "supersedes": [],
10884
+ "symbol": "withAuthoredPose"
10885
+ },
10886
+ {
10887
+ "aliases": [],
10888
+ "constraints": [],
10889
+ "example": "writePropTransform(instance, prepared);",
10890
+ "importPath": "@threenative/terrain/starter",
10891
+ "kind": "function",
10892
+ "overrides": [],
10893
+ "package": "@threenative/terrain",
10894
+ "requires": ["npm i -D @threenative/terrain"],
10895
+ "signature": "export function writePropTransform( instance: IPropInstance, prepared: ReturnType<typeof preparePropTransform>, ): void { … }",
10896
+ "situations": ["write an edited prop's prepared pose back onto its instance"],
10897
+ "summary": "Writes a prepared pose onto the instance, reporting the transform only when the pose changed.",
10898
+ "supersedes": [],
10899
+ "symbol": "writePropTransform"
10900
+ },
10901
+ {
10902
+ "aliases": [],
10903
+ "constraints": ["creates only geometry; the caller owns its material, scene and disposal"],
10904
+ "example": "const geometry = toGeometry(bakeMesh(new Terrain({ resolution: 17 }).evaluate()));",
10905
+ "importPath": "@threenative/terrain/three",
10906
+ "kind": "function",
10907
+ "overrides": ["every surface choice remains in game source"],
10908
+ "package": "@threenative/terrain",
10909
+ "requires": ["npm i @threenative/terrain"],
10910
+ "signature": "export function toGeometry(mesh: IBakedMesh): BufferGeometry { … }",
10911
+ "situations": ["put an authored terrain mesh in a game-owned Three.js scene"],
10912
+ "summary": "Converts baked arrays to ordinary geometry using the consumer's installed Three.js.",
10913
+ "supersedes": [],
10914
+ "symbol": "toGeometry"
10915
+ },
10916
+ {
10917
+ "aliases": [],
10918
+ "constraints": [
10919
+ "rejects indices, channels, or material sections that disagree with the vertex count before any geometry is constructed"
10920
+ ],
10921
+ "example": "const geometry = createThreeGeometry(model.lods[0]);",
10922
+ "importPath": "@threenative/ueformat",
10923
+ "kind": "function",
10924
+ "overrides": [],
10925
+ "package": "@threenative/ueformat",
10926
+ "requires": ["npm i @threenative/ueformat"],
10927
+ "signature": "export function createThreeGeometry( lod: IUEModelLOD, adapterOptions: IThreeAdapterOptions = { … }",
10928
+ "situations": [
10929
+ "convert one Unreal mesh LOD into a three.js BufferGeometry by hand",
10930
+ "build custom scene objects from Unreal mesh data instead of a whole model"
10931
+ ],
10932
+ "summary": "Converts one parsed Unreal mesh LOD into a `THREE.BufferGeometry` — coordinates, scale, winding, normals, tangents, UVs, vertex colours, morphs, skin weights, and material groups.",
10933
+ "supersedes": [],
10934
+ "symbol": "createThreeGeometry"
10935
+ },
10936
+ {
10937
+ "aliases": [],
10938
+ "constraints": [
10939
+ "every material comes from the game through `materialFactory`; the fallback is three.js's own GLTFLoader default, a plain MeshStandardMaterial",
10940
+ "parsed bones are exposed on `userData` but never bound into a THREE.SkinnedMesh — skeletal rendering is the game's job"
10941
+ ],
10942
+ "example": "const hero = createThreeObject(parseUEModel(buffer), { lodDistances: [0, 25, 50] });",
10943
+ "importPath": "@threenative/ueformat",
10944
+ "kind": "function",
10945
+ "overrides": [],
10946
+ "package": "@threenative/ueformat",
10947
+ "requires": ["npm i @threenative/ueformat"],
10948
+ "signature": "export function createThreeObject( model: IUEModelData, adapterOptions: IThreeAdapterOptions = { … }",
10949
+ "situations": [
10950
+ "put a mesh exported from an Unreal package on screen",
10951
+ "load an Unreal static or skeletal mesh with LODs, sockets, and collision geometry"
10952
+ ],
10953
+ "summary": "Builds a renderable Three.js object — a `Group` for single-LOD models, a `THREE.LOD` for multi-LOD ones — from parsed `.uemodel` data, with collision geometry on `userData`.",
10954
+ "supersedes": [],
10955
+ "symbol": "createThreeObject"
10956
+ },
10957
+ {
10958
+ "aliases": [],
10959
+ "constraints": [
10960
+ "only UEFormat v10 UEMODEL files are accepted; anything else throws UEFormatError with the byte offset",
10961
+ "ZSTD-compressed bodies require an injected `zstdDecoder`; the package never bundles a ZSTD implementation"
10962
+ ],
10963
+ "example": "const model = parseUEModel(await file.arrayBuffer());",
10964
+ "importPath": "@threenative/ueformat",
10965
+ "kind": "function",
10966
+ "overrides": [],
10967
+ "package": "@threenative/ueformat",
10968
+ "requires": ["npm i @threenative/ueformat"],
10969
+ "signature": "export function parseUEModel( input: ArrayBuffer | ArrayBufferView, options: IParseUEModelOptions = { … }",
10970
+ "situations": [
10971
+ "parse a mesh exported from an Unreal package without Unreal installed",
10972
+ "inspect the LODs, skeleton, sockets, and collision inside a .uemodel file"
10973
+ ],
10974
+ "summary": "Parses a UEFormat v10 `.uemodel` body — the interchange format CUE4Parse and FModel export from Unreal packages — into validated, plain mesh data without building any Three.js objects.",
10975
+ "supersedes": [],
10976
+ "symbol": "parseUEModel"
10977
+ },
10978
+ {
10979
+ "aliases": [],
10980
+ "constraints": [
10981
+ "the summary reflects one already-parsed model; it does not read files itself"
10982
+ ],
10983
+ "example": "const summary = summarizeUEModel(parseUEModel(buffer));",
10984
+ "importPath": "@threenative/ueformat",
10985
+ "kind": "function",
10986
+ "overrides": [],
10987
+ "package": "@threenative/ueformat",
10988
+ "requires": ["npm i @threenative/ueformat"],
10989
+ "signature": "export function summarizeUEModel(model: IUEModelData): IUEModelSummary { … }",
10990
+ "situations": [
10991
+ "report what a UEFormat model contains without dumping its vertex data",
10157
10992
  "validate a .uemodel file before building geometry from it"
10158
10993
  ],
10159
10994
  "summary": "Summarizes a parsed `.uemodel` — LOD, material, skeleton, collision, and unknown-attribute counts — without dumping vertex arrays, for logs, validation, and build reports.",
@@ -10332,6 +11167,31 @@
10332
11167
  "supersedes": [],
10333
11168
  "symbol": "useUiStateDuringStartup"
10334
11169
  },
11170
+ {
11171
+ "symbol": "ctx.assets.memo",
11172
+ "package": "@threenative/core",
11173
+ "importPath": "src/assets.ts",
11174
+ "kind": "function",
11175
+ "signature": "ctx.assets.memo<T>(key: string, build: () => T | Promise<T>): Promise<T>",
11176
+ "summary": "Returns what `build` returned the last time this build of the game ran, read back from disk, and calls `build` only when nothing is stored. Use it for seeded work that is the same every run: placement lists, painted sky pixels, terrain heights, a generated stage.",
11177
+ "situations": [
11178
+ "cache generated geometry between page loads",
11179
+ "stop rebuilding the same generated stage on every page load",
11180
+ "cache painted sky pixels or baked terrain heights between runs",
11181
+ "keep seeded placement work the same every run without recomputing it",
11182
+ "make a slow boot fast without shipping a baked asset"
11183
+ ],
11184
+ "aliases": [],
11185
+ "example": "const { pixels } = await ctx.assets.memo(\"sky\", () => ({ pixels: paintSky() }));",
11186
+ "constraints": [
11187
+ "The value is named typed arrays; a map of names to typed arrays is what is stored.",
11188
+ "On the dev server and on a native host `build` runs every time, and `TN_ASSET_MEMO` reports why: the cache is a build artifact, not a substitute for authoring.",
11189
+ "A new build of the game regenerates: the key alone does not pin a value across a rebuild.",
11190
+ "A game that drives a loader outside `defineGame` may call it whenever it likes; the reveal is not waited on."
11191
+ ],
11192
+ "overrides": ["TN_ASSET_MEMO reports why a run rebuilt instead of reading the store"],
11193
+ "supersedes": []
11194
+ },
10335
11195
  {
10336
11196
  "symbol": "createStormAudio",
10337
11197
  "package": "template:rain",
@@ -10557,6 +11417,76 @@
10557
11417
  "supersedes": [],
10558
11418
  "aliases": []
10559
11419
  },
11420
+ {
11421
+ "symbol": "ctx.after",
11422
+ "package": "@threenative/core",
11423
+ "importPath": "src/scene.ts",
11424
+ "kind": "function",
11425
+ "signature": "ctx.after(delay: number, callback: () => void): ScheduleHandle",
11426
+ "summary": "Runs `callback` once, `delay` seconds of game time later, and returns a handle that cancels it. Game time stops while the game is paused, so a delayed beat does not fire behind a paused frame.",
11427
+ "situations": [
11428
+ "run a callback after a delay",
11429
+ "schedule a one-shot timer that pauses with the game",
11430
+ "do something a moment later without setTimeout",
11431
+ "cancel a pending delayed action when a scene exits"
11432
+ ],
11433
+ "aliases": [],
11434
+ "example": "const spawn = ctx.after(0.4, () => ctx.add(makeWave()));\nspawn(); // cancels",
11435
+ "constraints": [
11436
+ "The delay is game seconds: a paused game does not age it, and a slow frame does not skip it.",
11437
+ "`setTimeout` keeps running while the game is paused and after the scene is gone; this does not.",
11438
+ "Call the returned handle to cancel: a pending callback holds its scene's closure alive."
11439
+ ],
11440
+ "overrides": [],
11441
+ "supersedes": []
11442
+ },
11443
+ {
11444
+ "symbol": "ctx.beforeRender",
11445
+ "package": "@threenative/core",
11446
+ "importPath": "src/scene.ts",
11447
+ "kind": "function",
11448
+ "signature": "ctx.beforeRender(callback: () => void): () => void",
11449
+ "summary": "Registers work that runs once per actual world render, after the frame's last fixed update and before the projection reconciles and the renderer draws. The last place to change a transform, a uniform or a camera before the frame is presented.",
11450
+ "situations": [
11451
+ "run a callback just before the frame renders",
11452
+ "update a camera or a uniform after physics and before the draw",
11453
+ "change a transform in the same frame it is seen",
11454
+ "run per-render work that must not run on a loader-only frame"
11455
+ ],
11456
+ "aliases": [],
11457
+ "example": "const stop = ctx.beforeRender(() => (material.uniforms.time.value = clock.elapsed));\n// later: stop();",
11458
+ "constraints": [
11459
+ "A held, loader-only frame has no world draw and dispatches nothing.",
11460
+ "Runs after every fixed update in the frame, so a value it writes is the one drawn.",
11461
+ "Returns an unregister function; call it when the object that needed it is gone."
11462
+ ],
11463
+ "overrides": [],
11464
+ "supersedes": []
11465
+ },
11466
+ {
11467
+ "symbol": "ctx.startup.progress",
11468
+ "package": "@threenative/core",
11469
+ "importPath": "src/scene.ts",
11470
+ "kind": "function",
11471
+ "signature": "ctx.startup.progress: number",
11472
+ "summary": "How much of the start scene has loaded and presented, 0 to 1, for a loading cover's bar. It never falls: a loader whose pending work grows keeps the number it reached rather than jumping backwards.",
11473
+ "situations": [
11474
+ "boot progress bar",
11475
+ "show how much of the start scene has loaded",
11476
+ "loading screen percentage",
11477
+ "a progress bar that never goes backwards",
11478
+ "report startup progress while assets stream in"
11479
+ ],
11480
+ "aliases": [],
11481
+ "example": "const width = `${Math.round(ctx.startup.progress * 100)}%`; // a cover the game draws on ctx.canvasLayer",
11482
+ "constraints": [
11483
+ "Never decreases, even when the loader is asked for more work mid-boot.",
11484
+ "Reaches 1 only after the first world render has been presented, not when the last byte arrived.",
11485
+ "A loading view the engine drew for you already reads it; this is for a cover the game draws itself."
11486
+ ],
11487
+ "overrides": [],
11488
+ "supersedes": []
11489
+ },
10560
11490
  {
10561
11491
  "symbol": "bloom",
10562
11492
  "package": "three",
@@ -10869,14 +11799,9 @@
10869
11799
  "situations": ["authoritative replication", "client prediction"]
10870
11800
  },
10871
11801
  {
10872
- "guidance": "The framework owns no vegetation system. Copy the MIT source in examples/integrations/vegetation/src/ (https://github.com/ThreeNativeHQ/threenative/tree/develop/examples/integrations/vegetation) into your src/ and follow its README: generate seeded, vertex-budgeted EZ Tree variants offline (tree.ts, from the pinned ez-tree source, not the npm 1.1.0 bundle), write them with treeToGlb into assets/, cook them with assets.models.passes.prune: false (prune strips the uv and _WIND weight your materials read), load with ctx.assets.model and re-material by glTF material name. render/wind.ts is editable TSL wind in world metres; call expandBounds(geometry, minWorldScale) per variant geometry. assets.lod bakes bark levels and keeps alpha-masked leaves at LOD0. Worked sample: the grove game in github.com/ThreeNativeHQ/examples.",
10873
- "id": "procedural-vegetation",
10874
- "situations": [
10875
- "procedural trees",
10876
- "swaying trees",
10877
- "tree foliage wind sway",
10878
- "grow procedural tree meshes"
10879
- ]
11802
+ "guidance": "The framework owns no vegetation render system: wind and materials are your look, in your project's src/render/. Trees come from the optional bake package: npm i -D @threenative/procedural-environment, then await bakeVegetation({ preset: \"oak\", seed: 7, lods: [0, 1], out: \"assets/trees\" }) writes one GLB per LOD (vegetationPresets() lists the 28 species). Each GLB carries COLOR_0, TEXCOORD_0, embedded bark and leaf textures, alpha-masked leaves and a per-vertex _WIND vec4 (x trunk sway m, y branch sway m, z leaf flutter m, w phase). Cook them with assets.models.passes.prune: false (prune strips the uv and _WIND your materials read), load with ctx.assets.model and re-material by glTF material name (bark, foliage). Write the sway as TSL in render/wind.ts: attribute(\"_wind\", \"vec4\") scaled by a time uniform and a world wind direction, pushed through modelWorldMatrixInverse so it stays in world metres. A terrain world takes the same trees through the species prefix arbor:<preset>[@seed].",
11803
+ "id": "procedural-environment",
11804
+ "situations": ["foliage wind sway shader", "wind animation render system for leaves"]
10880
11805
  },
10881
11806
  {
10882
11807
  "guidance": "The framework owns no IK system. Copy the MIT source in examples/integrations/ik/src/ (https://github.com/ThreeNativeHQ/threenative/tree/develop/examples/integrations/ik) into your src/ and follow its README: it needs the closed-chain-ik/core dependency its own package.json pins, three keeps the only rendered pose, and new ConstrainedIK({root, joints: [{bone, axes, min, max}], effectors: [{bone, orientation?}], iterations, positionTolerance, rotationTolerance}) admits direct Bone hierarchies under rigid or positive-uniform-scale parents (shear, reflection, non-uniform or singular scale throws before the pose is touched). Call ik.update(targets) once per frame after AnimationPlayer/mixer and before render, with one world-space metre position per effector in order plus an optional quaternion only where the effector declared orientation: true; it never starts a loop, never moves the root and installs no bone translation or root-motion controller. Joint limits are X/Y/Z offsets relative to the animation pose supplied that call, so reapply the animation pose before solving to avoid accumulation, and the solver only rotates: bone lengths hold to under 1e-15 m. Iterations are 1-128; an unreachable goal returns converged false with finite residuals and never throws, a solver failure restores the original pose, and dispose() at scene teardown. Worked demo: the rifle grip game in examples/constrained-ik/, which plays on web, desktop native and Android.",