@threenative/core 0.3.12 → 0.3.15
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/README.md +1 -1
- package/capabilities.json +1047 -44
- package/dist/{assets-YUbXa3-Y.d.ts → assets-CfMKnOsK.d.ts} +78 -1
- package/dist/{canvas-layer-CWuFRT7G.d.ts → canvas-layer-G7ttVy7y.d.ts} +1 -1
- package/dist/{chunk-7UUT3TY5.js → chunk-2GPHICV6.js} +1 -1
- package/dist/{chunk-GMHATRPW.js → chunk-GEMQJBY4.js} +1650 -383
- package/dist/{chunk-VAZM36TV.js → chunk-H4J6IAJE.js} +17 -10
- package/dist/{chunk-5O73CDMR.js → chunk-QAMSM3Z5.js} +415 -27
- package/dist/{chunk-2Z44XSI2.js → chunk-QAQHYOWY.js} +3 -7
- package/dist/{chunk-DBELTTTM.js → chunk-U4YHUKKL.js} +1 -1
- package/dist/{chunk-OKXUCASC.js → chunk-VBBYWGAT.js} +3 -4
- package/dist/chunk-VP43GIWW.js +18 -0
- package/dist/{chunk-N5LRP4BR.js → chunk-VQRPEOKY.js} +66 -3
- package/dist/{chunk-6KLNISRJ.js → chunk-XDTZ4QMO.js} +11 -4
- package/dist/default-tone-mapping-GgKPTiBP.d.ts +4 -0
- package/dist/{game-D7pAzZUY.d.ts → game-k8K3hZai.d.ts} +72 -8
- package/dist/hot.d.ts +5 -4
- package/dist/hot.js +5 -8
- package/dist/index.d.ts +871 -1018
- package/dist/index.js +4786 -1631
- package/dist/{model-lod-B6BMqS1r.d.ts → model-lod-DPTzeCcD.d.ts} +4 -2
- package/dist/playtest.d.ts +5 -4
- package/dist/playtest.js +6 -5
- package/dist/quality-BADStsTn.d.ts +868 -0
- package/dist/react.d.ts +3 -2
- package/dist/render-environment.d.ts +170 -0
- package/dist/render-environment.js +352 -0
- package/dist/{renderer-DvFVoAgj.d.ts → renderer-BtOSseYf.d.ts} +29 -31
- package/dist/spells/index.js +1 -1
- package/dist/ui-layer.js +3 -2
- package/dist/worker.js +12 -5
- package/dist/world.d.ts +280 -16
- package/dist/world.js +1529 -642
- package/mcp/animation-server.mjs +1 -1
- package/mcp/engine-server.mjs +135 -11
- package/mcp/servers.mjs +4 -4
- package/package.json +10 -6
- package/scripts/ensure-mcp.mjs +6 -1
- package/src/animation-batch.ts +193 -0
- package/src/animation-layers.ts +7 -3
- package/src/animation.ts +209 -29
- package/src/asset-cache.ts +3 -3
- package/src/asset-memo.ts +202 -0
- package/src/assets.ts +436 -131
- package/src/auto-batch.ts +190 -44
- package/src/clustered-batch.ts +146 -3
- package/src/clustered-mesh.ts +548 -20
- package/src/compute-driven.ts +1 -1
- package/src/config.ts +8 -0
- package/src/debug.ts +119 -22
- package/src/dev-global.ts +54 -0
- package/src/displaced-surface.ts +428 -0
- package/src/engine-hooks.ts +37 -0
- package/src/frame-budget.ts +35 -3
- package/src/game-boot-phase.ts +269 -0
- package/src/game-dev-tools.ts +7 -14
- package/src/game-frame-loop.ts +45 -82
- package/src/game-startup.ts +145 -70
- package/src/game-ui.ts +84 -0
- package/src/game.ts +168 -552
- package/src/gamepad-mappings.ts +269 -0
- package/src/generated/console-markers.ts +14 -0
- package/src/geometry-capture.ts +28 -4
- package/src/gpu-readings.ts +98 -0
- package/src/gpu-scene-bvh.ts +149 -36
- package/src/grass-field.ts +628 -0
- package/src/hot.ts +4 -7
- package/src/index.ts +227 -8
- package/src/input.ts +237 -25
- package/src/instanced-batch-lod.ts +3 -8
- package/src/interpolation.ts +171 -40
- package/src/look/ao-admission.ts +4 -3
- package/src/look/auto-exposure.ts +5 -16
- package/src/look/default-tone-mapping.ts +41 -5
- package/src/look/local-exposure.ts +2 -7
- package/src/look/quad-pass.ts +21 -0
- package/src/look/quality.ts +4 -0
- package/src/look/unreal-bloom.ts +4 -13
- package/src/look/world-environment.ts +58 -115
- package/src/merge-parts.ts +20 -24
- package/src/model-lod.ts +97 -14
- package/src/particle-significance.ts +12 -0
- package/src/particles.ts +19 -10
- package/src/platform.ts +23 -4
- package/src/profiling/FrameStages.ts +5 -6
- package/src/profiling/Spans.ts +3 -17
- package/src/profiling/debug-telemetry.ts +2 -6
- package/src/profiling/render-list-validate.ts +6 -15
- package/src/projection-marker.ts +2 -1
- package/src/quiet-markers.ts +3 -10
- package/src/render/cpu-bvh.ts +100 -0
- package/src/render/depth-pyramid.ts +6 -14
- package/src/render/environment/environmentContribution.ts +202 -0
- package/src/render/environment/environmentRadiance.ts +44 -0
- package/src/render/environment/environmentSampleCache.ts +56 -0
- package/src/render/environment/environmentSampling.ts +201 -0
- package/src/render/environment/environmentSnapshot.ts +71 -0
- package/src/render/environment/gate.ts +57 -0
- package/src/render/material-key.ts +21 -1
- package/src/render/mesh-pool.ts +3 -19
- package/src/render/probe-trace.ts +872 -0
- package/src/render/probe-volume.ts +780 -34
- package/src/render/radiance-cache.ts +17 -0
- package/src/render/screen-probe-gather.ts +303 -0
- package/src/render/short-range-ao.ts +274 -0
- package/src/render/virtual-shadow-partial.ts +13 -0
- package/src/render/virtual-shadow.ts +18 -16
- package/src/render/world-impostor-surface.ts +207 -9
- package/src/render/world-impostor.ts +5 -2
- package/src/render-camera-cull.ts +105 -4
- package/src/render-environment.ts +41 -0
- package/src/renderer-config.ts +36 -0
- package/src/renderer-facts.ts +37 -0
- package/src/renderer.ts +78 -32
- package/src/resolution-scaler.ts +3 -2
- package/src/scatter-field.ts +496 -0
- package/src/scene-entry-inspectors.ts +61 -0
- package/src/snow-field.ts +1 -0
- package/src/startup-offscreen-bytes.ts +84 -0
- package/src/state.ts +16 -3
- package/src/static-transform.ts +100 -25
- package/src/streamed-textures.ts +112 -0
- package/src/streaming.ts +68 -4
- package/src/texture-streaming.ts +331 -0
- package/src/tile-ring.ts +294 -0
- package/src/version.ts +1 -1
- package/src/warmup.ts +15 -2
- package/src/worker.ts +12 -2
- package/src/world-bundle-safety.ts +55 -10
- package/src/world-cell-batches.ts +166 -200
- package/src/world-cell-chunks.ts +3 -7
- package/src/world-cell-data.ts +7 -0
- package/src/world-cell-impostors.ts +20 -8
- package/src/world-cell-models.ts +36 -8
- package/src/world-cell-options.ts +2 -14
- package/src/world-cell-placements.ts +194 -90
- package/src/world-cell-prewarm.ts +39 -4
- package/src/world-cell-records.ts +401 -0
- package/src/world-cell-render-bundles.ts +2 -2
- package/src/world-cell-render-gpu-dress.ts +17 -19
- package/src/world-cell-render-main-cull.ts +73 -17
- package/src/world-cell-render-util.ts +18 -5
- package/src/world-cell-render.ts +13 -5
- package/src/world-cell-residency.ts +15 -6
- package/src/world-cell-stale.ts +238 -0
- package/src/world-cells.ts +23 -6
- package/src/world-gpu-flags.ts +18 -50
- package/src/world-gpu-reference.ts +22 -8
- package/src/world-gpu-scene.ts +44 -24
- package/src/world-gpu-shadow.ts +21 -8
- package/src/world-gpu-types.ts +41 -13
- package/src/world-load-limiter.ts +5 -0
- package/src/world-model-sections.ts +80 -0
- package/src/world-river-ribbon.ts +273 -0
- package/src/world-root-frame.ts +39 -0
- package/src/world-shore-field.ts +91 -0
- package/src/world-static-pose.ts +163 -0
- package/src/world-surface-sampler.ts +48 -0
- package/src/world-terrain-splat.ts +10 -18
- package/src/world-tile-budget.ts +4 -11
- package/src/world-tiles.ts +79 -12
- package/src/world-validate.ts +6 -14
- package/src/world-warm.ts +51 -0
- package/src/world-water-bodies.ts +113 -3
- package/src/world.ts +13 -0
package/capabilities.json
CHANGED
|
@@ -271,17 +271,27 @@
|
|
|
271
271
|
{
|
|
272
272
|
"aliases": [],
|
|
273
273
|
"constraints": [
|
|
274
|
-
"the pass self-verifies reachable geometry, animation, bounds, and embedded texture bindings before returning output"
|
|
274
|
+
"the pass self-verifies reachable geometry, animation, bounds, and embedded texture bindings before returning output",
|
|
275
|
+
"each colour texture climbs a codec ladder (ETC1S, then UASTC with RDO, then plain UASTC) and keeps the smallest rung that meets the quality floor (SSIM 0.95, ΔE00 3); a data slot such as a normal or metallic-roughness map takes UASTC only, as ETC1S is forbidden there (`TN_ASSETS_TEXTURE_SLOT_CODEC`); a result is kept only when it is smaller than the source, else the source stays and the report says `not-smaller`",
|
|
276
|
+
"a PNG or JPEG source can always be kept; a WebP source can be kept only on a web target, whose runtimes all decode WebP, so on desktop and mobile it always becomes KTX2"
|
|
275
277
|
],
|
|
276
278
|
"example": "const pass = modelPass({ simplify: { ratio: 0.5 } });",
|
|
277
279
|
"importPath": "@threenative/assets",
|
|
278
280
|
"kind": "function",
|
|
279
|
-
"overrides": [
|
|
281
|
+
"overrides": [
|
|
282
|
+
"`textures: { overrides: [{ slot: \"baseColorTexture\", codec: \"uastc\" }] }` forces one glTF slot's codec (`etc1s`, `uastc` or `none`); `textures: { floor }` moves the quality floor; `textures: \"none\"` keeps every embedded texture as authored"
|
|
283
|
+
],
|
|
280
284
|
"package": "@threenative/assets",
|
|
281
285
|
"signature": "export function modelPass(options: IModelPassOptions = { … }",
|
|
282
286
|
"situations": [
|
|
283
287
|
"reduce a model's download and GPU footprint",
|
|
284
|
-
"optimize a GLB before shipping it with a game"
|
|
288
|
+
"optimize a GLB before shipping it with a game",
|
|
289
|
+
"texture bytes too big after the model cook",
|
|
290
|
+
"a KTX2 model texture came out larger than its WebP or JPEG source",
|
|
291
|
+
"choose ETC1S or UASTC for a model's embedded textures",
|
|
292
|
+
"model texture codec ladder",
|
|
293
|
+
"keep smaller source texture",
|
|
294
|
+
"TN_ASSETS_COMPRESSION_SKIPPED"
|
|
285
295
|
],
|
|
286
296
|
"summary": "Optimizes self-contained GLB models through the configured geometry and embedded-texture passes.",
|
|
287
297
|
"supersedes": [],
|
|
@@ -1324,13 +1334,24 @@
|
|
|
1324
1334
|
"constraints": [
|
|
1325
1335
|
"reuse the loader handed to scenes as `ctx.assets` instead of building parallel caches",
|
|
1326
1336
|
"await everything the spawn camera sees before the reveal; `ctx.assets.prefetch` and the background fill are for content out of view, or the player spawns into a half-built world",
|
|
1327
|
-
"
|
|
1337
|
+
"a whole-file load requested after the reveal that the game had not `prefetch`ed logs one `TN_ASSET_LATE` line with its bytes, so a pop-in is countable from a playtest",
|
|
1338
|
+
"web only: a native host reads installed files, so `ctx.assets.cache` reports `enabled: false` with the reason and `prefetch` resolves at once",
|
|
1339
|
+
"streaming is engine-owned and on by default: a cooked LOD-chained model loads its `.coarse.<digest>.glb` companion first, then the full file at \"soon\" priority, and the full geometry replaces the coarse in place (clones and the projection mirror included); a failed coarse load falls back to the whole file and logs `TN_ASSETS_STREAM_FAILED`",
|
|
1340
|
+
"texture streaming rides on the coarse parse: each shared `.ktx2` of that model is read by `Range` as its resident mips (the header and the tail), and the whole files replace them when the full model lands; a host without `Range` sends the whole file and keeps it whole. `TN_STREAMING_POOL` reports `files`, `residentBytes`, `fullBytes`, `deferredBytes` and `upgraded` once, two seconds after the last change",
|
|
1341
|
+
"the whole texture keeps what the game set on the resident one (`anisotropy`, wrap, filters, offset, repeat, `userData`), so the swap changes the mips and nothing else",
|
|
1342
|
+
"every web build cooks meshopt geometry and KTX2 textures for both engines (`webRuntimeDecoders` in create-threenative answers `{ ktx2: true, meshopt: true }`); the owned engine's glTF loader decodes both itself, with no JS decoder",
|
|
1343
|
+
"the owned engine transcodes a KTX2 image to BC7 on a device with `texture-compression-bc`, else ETC2, else RGBA8 with an engine mip chain, and prints `TN_TEXTURE_TRANSCODE_TARGET <target>` once; a block format needs a width and height that are multiples of 4, so any other size stays RGBA8 and the same line names it",
|
|
1344
|
+
"a three `CompressedTexture` (format plus `mipmaps`) uploads one GPU write per level; a block format the device lacks throws `TN_NATIVE_TEXTURE_UNSUPPORTED` by name instead of drawing garbage",
|
|
1345
|
+
"levels are coarse-first: a level whose `mipmaps[i].data` is null is not resident and the texture samples its finest resident level; set `mipmaps[i].data` and `needsUpdate = true` to write that one finer level in place, without re-creating the texture or rewriting the other levels"
|
|
1328
1346
|
],
|
|
1329
1347
|
"example": "const assets = createAssetLoader({ basePath: \"/assets\" });\nconst rock = await assets.texture(\"rock.png\");",
|
|
1330
1348
|
"importPath": "@threenative/core",
|
|
1331
1349
|
"kind": "function",
|
|
1332
1350
|
"overrides": [
|
|
1333
|
-
"`assets.cache: false` turns the disk cache off and `assets.backgroundFill: false` turns the post-reveal fill off; both are reported on `ctx.assets.cache`"
|
|
1351
|
+
"`assets.cache: false` turns the disk cache off and `assets.backgroundFill: false` turns the post-reveal fill off; both are reported on `ctx.assets.cache`",
|
|
1352
|
+
"`ctx.assets.model(path, { whole: true })` resolves only once the full file has replaced the coarse companion, for a collider or navmesh that copies vertices once",
|
|
1353
|
+
"`assets.streamMeshes: false` loads every model whole (reported once as `TN_ASSETS_STREAM_MESHES_OFF`); `assets.streamTextures: false` loads every model texture whole (`TN_ASSETS_STREAM_TEXTURES_OFF`)",
|
|
1354
|
+
"`engine: \"threejs\"` runs three's own `KTX2Loader` and `MeshoptDecoder` in JS instead of the owned engine's decoders"
|
|
1334
1355
|
],
|
|
1335
1356
|
"package": "@threenative/core",
|
|
1336
1357
|
"signature": "export function createAssetLoader(options: IAssetLoaderOptions = { … }",
|
|
@@ -1340,7 +1361,27 @@
|
|
|
1340
1361
|
"download the next scene before the player gets there",
|
|
1341
1362
|
"free the disk cache from a settings menu",
|
|
1342
1363
|
"prefetch assets into the Cache Storage disk cache of a large web game",
|
|
1343
|
-
"load assets from a nonstandard base path or a compiled asset manifest"
|
|
1364
|
+
"load assets from a nonstandard base path or a compiled asset manifest",
|
|
1365
|
+
"stream a large game: boot on the spawn bytes and prefetch the rest",
|
|
1366
|
+
"make the first scene play before the whole game finishes downloading",
|
|
1367
|
+
"draw a heavy model's coarsest level first and its full detail when the file lands",
|
|
1368
|
+
"draw a model's textures at their resident mips first and the whole files later",
|
|
1369
|
+
"coarse first model streaming",
|
|
1370
|
+
"streamMeshes and streamTextures: stream the meshes and textures of a model",
|
|
1371
|
+
"mip streaming textures",
|
|
1372
|
+
"TN_STREAMING_POOL",
|
|
1373
|
+
"TN_ASSET_LATE",
|
|
1374
|
+
"an asset pops in after the reveal and the game needs to count it",
|
|
1375
|
+
"a model texture looks blurry or low resolution right after load, then sharpens",
|
|
1376
|
+
"build a collider or navmesh from a streamed model only once its full file landed",
|
|
1377
|
+
"compressed texture upload on the owned engine (KTX2 to BC7 or ETC2 on the GPU)",
|
|
1378
|
+
"load a model with KHR_texture_basisu or EXT_meshopt_compression on the owned engine",
|
|
1379
|
+
"stream a finer mip level into a CompressedTexture that already draws",
|
|
1380
|
+
"KTX2Loader on the owned engine",
|
|
1381
|
+
"CompressedTexture upload",
|
|
1382
|
+
"TN_TEXTURE_TRANSCODE_TARGET",
|
|
1383
|
+
"TN_NATIVE_TEXTURE_UNSUPPORTED",
|
|
1384
|
+
"webRuntimeDecoders meshopt ktx2"
|
|
1344
1385
|
],
|
|
1345
1386
|
"summary": "Create the portable asset loader a scene also receives as `ctx.assets`.",
|
|
1346
1387
|
"supersedes": [],
|
|
@@ -1438,11 +1479,33 @@
|
|
|
1438
1479
|
"overrides": [],
|
|
1439
1480
|
"package": "@threenative/core",
|
|
1440
1481
|
"signature": "export function debugFlag(name: string): boolean { … }",
|
|
1441
|
-
"situations": [
|
|
1482
|
+
"situations": [
|
|
1483
|
+
"read a debug toggle from the URL, an environment variable or a harness global"
|
|
1484
|
+
],
|
|
1442
1485
|
"summary": "Read a debug switch from the URL, or from `TN_DEBUG_*` in the environment on a native launch.",
|
|
1443
1486
|
"supersedes": [],
|
|
1444
1487
|
"symbol": "debugFlag"
|
|
1445
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
|
+
},
|
|
1446
1509
|
{
|
|
1447
1510
|
"aliases": [
|
|
1448
1511
|
"nearest target crosshair spawns",
|
|
@@ -1513,6 +1576,22 @@
|
|
|
1513
1576
|
"supersedes": [],
|
|
1514
1577
|
"symbol": "describeSceneWarning"
|
|
1515
1578
|
},
|
|
1579
|
+
{
|
|
1580
|
+
"aliases": [],
|
|
1581
|
+
"constraints": [
|
|
1582
|
+
"every dev surface publishes under this key; the worker's typed mirror tuple names it too"
|
|
1583
|
+
],
|
|
1584
|
+
"example": "import { DEV_GLOBAL_KEY, devGlobal } from \"@threenative/core\";\nconst tools = devGlobal(globalThis);",
|
|
1585
|
+
"importPath": "@threenative/core",
|
|
1586
|
+
"kind": "function",
|
|
1587
|
+
"overrides": [],
|
|
1588
|
+
"package": "@threenative/core",
|
|
1589
|
+
"signature": "export function devGlobal(scope: unknown): DevGlobal | undefined { … }",
|
|
1590
|
+
"situations": ["read or extend the `__THREENATIVE__` object a dev launch publishes"],
|
|
1591
|
+
"summary": "The one name every dev surface publishes under, and the reader/writer for it.",
|
|
1592
|
+
"supersedes": [],
|
|
1593
|
+
"symbol": "devGlobal"
|
|
1594
|
+
},
|
|
1516
1595
|
{
|
|
1517
1596
|
"aliases": [],
|
|
1518
1597
|
"constraints": ["pass a non-zero direction; coefficients and radii come from the game"],
|
|
@@ -1697,6 +1776,23 @@
|
|
|
1697
1776
|
"supersedes": [],
|
|
1698
1777
|
"symbol": "exposureFromEv100"
|
|
1699
1778
|
},
|
|
1779
|
+
{
|
|
1780
|
+
"aliases": [],
|
|
1781
|
+
"constraints": ["reads the response once; call `.json()` or `.arrayBuffer()` on the result"],
|
|
1782
|
+
"example": "const heights = new Float32Array(await (await fetchAsset(ctx.assets, \"world/forest.bin\")).arrayBuffer());",
|
|
1783
|
+
"importPath": "@threenative/core",
|
|
1784
|
+
"kind": "function",
|
|
1785
|
+
"overrides": [],
|
|
1786
|
+
"package": "@threenative/core",
|
|
1787
|
+
"signature": "export async function fetchAsset( assets: Pick<IAssetLoader, \"resolve\">, path: string, ): Promise<Response> { … }",
|
|
1788
|
+
"situations": [
|
|
1789
|
+
"load a baked JSON or binary file (a heightmap, a placement buffer, a data table) that the loader has no typed method for",
|
|
1790
|
+
"a data file loads in dev but 404s in the built game"
|
|
1791
|
+
],
|
|
1792
|
+
"summary": "Fetch a data file the asset loader serves: each url `assets.resolve(path)` names, in order, until one answers ok. A built game serves the hashed output and a dev server the source path, so taking only the first url 404s on one of them. When none answers it throws `TN_ASSET_NOT_SERVED` naming every url tried and why, so a missing file is never a half-drawn world.",
|
|
1793
|
+
"supersedes": [],
|
|
1794
|
+
"symbol": "fetchAsset"
|
|
1795
|
+
},
|
|
1700
1796
|
{
|
|
1701
1797
|
"aliases": [],
|
|
1702
1798
|
"constraints": [
|
|
@@ -1936,7 +2032,7 @@
|
|
|
1936
2032
|
"a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host",
|
|
1937
2033
|
"when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size"
|
|
1938
2034
|
],
|
|
1939
|
-
"example": "if (isMobile()) showTouchControls();",
|
|
2035
|
+
"example": "if (isMobile()) showTouchControls();\nif (isConsole()) showPadPrompts(isPs4() ? \"dualshock\" : \"generic\");",
|
|
1940
2036
|
"importPath": "@threenative/core",
|
|
1941
2037
|
"kind": "function",
|
|
1942
2038
|
"overrides": [],
|
|
@@ -1945,7 +2041,8 @@
|
|
|
1945
2041
|
"situations": [
|
|
1946
2042
|
"branch a portable game on web or native",
|
|
1947
2043
|
"choose touch controls for a mobile device",
|
|
1948
|
-
"can I raytrace on native"
|
|
2044
|
+
"can I raytrace on native",
|
|
2045
|
+
"show gamepad prompts and bind pad buttons on a games console such as the PS4"
|
|
1949
2046
|
],
|
|
1950
2047
|
"summary": "Read the host platform without reaching for browser globals.",
|
|
1951
2048
|
"supersedes": [],
|
|
@@ -2076,6 +2173,37 @@
|
|
|
2076
2173
|
"supersedes": [],
|
|
2077
2174
|
"symbol": "GPUSceneBVH"
|
|
2078
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
|
+
},
|
|
2079
2207
|
{
|
|
2080
2208
|
"aliases": [],
|
|
2081
2209
|
"constraints": [
|
|
@@ -2098,21 +2226,28 @@
|
|
|
2098
2226
|
"symbol": "GroundSnap"
|
|
2099
2227
|
},
|
|
2100
2228
|
{
|
|
2101
|
-
"aliases": [],
|
|
2229
|
+
"aliases": ["gamepad", "controller", "joypad", "xbox", "8bitdo", "steam deck"],
|
|
2102
2230
|
"constraints": [
|
|
2103
2231
|
"`buttons` is the gamepad and `mouseButtons` the mouse; `up`/`down`/`left`/`right` are the directions of `vector(name)`, not the keys that press it",
|
|
2104
|
-
"scroll, pinch and pointer-relative sources are declared on the binding and read through `axis(name)`; a game adds no window listener of its own"
|
|
2232
|
+
"scroll, pinch and pointer-relative sources are declared on the binding and read through `axis(name)`; a game adds no window listener of its own",
|
|
2233
|
+
"gamepad buttons are W3C standard indices on every pad: 0 south (A/Cross), 1 east, 2 west, 3 north, 4/5 shoulders, 6/7 triggers, 8 select, 9 start, 10/11 stick clicks; axes 0..3 are the sticks",
|
|
2234
|
+
"both sticks carry a radial dead zone, `0.2` by default, reported per connected pad as `TN_GAMEPAD`; a pad the browser reports unmapped and the table does not know is ignored, never read with raw indices",
|
|
2235
|
+
"a pad claims the input when a button goes down or a stick travels past half tilt, and keeps it while idle so its releases read; a stick resting past the dead zone or jittering across it claims nothing, so an idle pad in the first slot cannot steal input"
|
|
2105
2236
|
],
|
|
2106
2237
|
"example": "const game = defineGame({ input: { move: { up: [\"KeyW\"], down: [\"KeyS\"], left: [\"KeyA\"], right: [\"KeyD\"] } }, scenes: { Play } });\n// inside the scene, per frame: ctx.input.axis(\"move\") is 0 at rest and 1 at full tilt",
|
|
2107
2238
|
"importPath": "@threenative/core",
|
|
2108
2239
|
"kind": "class",
|
|
2109
|
-
"overrides": [],
|
|
2240
|
+
"overrides": ["defineGame({ gamepadDeadZone: 0 }) publishes raw axes"],
|
|
2110
2241
|
"package": "@threenative/core",
|
|
2111
2242
|
"signature": "export class InputMap { … }",
|
|
2112
2243
|
"situations": [
|
|
2113
2244
|
"map WASD keys to a movement axis instead of reading the held key set in the update loop",
|
|
2114
2245
|
"read a jump, a fire or a reload as one named action bound to key, gamepad button and mouse button together",
|
|
2115
|
-
"read mouse look, wheel zoom or a two-finger pinch as an axis the frame loop already ticks"
|
|
2246
|
+
"read mouse look, wheel zoom or a two-finger pinch as an axis the frame loop already ticks",
|
|
2247
|
+
"support an Xbox pad, a generic XInput clone, an 8BitDo or a Steam Deck controller",
|
|
2248
|
+
"the character drifts while the controller stick is idle",
|
|
2249
|
+
"the controller does nothing in Firefox on Linux",
|
|
2250
|
+
"a second controller or a wheel steals the input from the pad the player holds"
|
|
2116
2251
|
],
|
|
2117
2252
|
"summary": "The map a game reads input through: named actions, 2D vectors and scalar axes resolved from keyboard, gamepad, mouse, wheel, pinch and touch. `defineGame({ input })` builds one and hands it to the running game as `ctx.input`, so the usual route is a binding in the config and `ctx.input.axis(\"move\")` in the update. Construct one directly to drive a menu, a replay or a test outside a running game.",
|
|
2118
2253
|
"supersedes": [],
|
|
@@ -2215,7 +2350,31 @@
|
|
|
2215
2350
|
"a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host",
|
|
2216
2351
|
"when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size"
|
|
2217
2352
|
],
|
|
2218
|
-
"example": "if (isMobile()) showTouchControls();",
|
|
2353
|
+
"example": "if (isMobile()) showTouchControls();\nif (isConsole()) showPadPrompts(isPs4() ? \"dualshock\" : \"generic\");",
|
|
2354
|
+
"importPath": "@threenative/core",
|
|
2355
|
+
"kind": "function",
|
|
2356
|
+
"overrides": [],
|
|
2357
|
+
"package": "@threenative/core",
|
|
2358
|
+
"signature": "export function isConsole(): boolean { … }",
|
|
2359
|
+
"situations": [
|
|
2360
|
+
"branch a portable game on web or native",
|
|
2361
|
+
"choose touch controls for a mobile device",
|
|
2362
|
+
"can I raytrace on native",
|
|
2363
|
+
"show gamepad prompts and bind pad buttons on a games console such as the PS4"
|
|
2364
|
+
],
|
|
2365
|
+
"summary": "Read the host platform without reaching for browser globals.",
|
|
2366
|
+
"supersedes": [],
|
|
2367
|
+
"symbol": "isConsole"
|
|
2368
|
+
},
|
|
2369
|
+
{
|
|
2370
|
+
"aliases": [],
|
|
2371
|
+
"constraints": [
|
|
2372
|
+
"only use the returned platform facts; native globals are host-owned",
|
|
2373
|
+
"image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result",
|
|
2374
|
+
"a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host",
|
|
2375
|
+
"when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size"
|
|
2376
|
+
],
|
|
2377
|
+
"example": "if (isMobile()) showTouchControls();\nif (isConsole()) showPadPrompts(isPs4() ? \"dualshock\" : \"generic\");",
|
|
2219
2378
|
"importPath": "@threenative/core",
|
|
2220
2379
|
"kind": "function",
|
|
2221
2380
|
"overrides": [],
|
|
@@ -2224,7 +2383,8 @@
|
|
|
2224
2383
|
"situations": [
|
|
2225
2384
|
"branch a portable game on web or native",
|
|
2226
2385
|
"choose touch controls for a mobile device",
|
|
2227
|
-
"can I raytrace on native"
|
|
2386
|
+
"can I raytrace on native",
|
|
2387
|
+
"show gamepad prompts and bind pad buttons on a games console such as the PS4"
|
|
2228
2388
|
],
|
|
2229
2389
|
"summary": "Read the host platform without reaching for browser globals.",
|
|
2230
2390
|
"supersedes": [],
|
|
@@ -2238,7 +2398,7 @@
|
|
|
2238
2398
|
"a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host",
|
|
2239
2399
|
"when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size"
|
|
2240
2400
|
],
|
|
2241
|
-
"example": "if (isMobile()) showTouchControls();",
|
|
2401
|
+
"example": "if (isMobile()) showTouchControls();\nif (isConsole()) showPadPrompts(isPs4() ? \"dualshock\" : \"generic\");",
|
|
2242
2402
|
"importPath": "@threenative/core",
|
|
2243
2403
|
"kind": "function",
|
|
2244
2404
|
"overrides": [],
|
|
@@ -2247,12 +2407,37 @@
|
|
|
2247
2407
|
"situations": [
|
|
2248
2408
|
"branch a portable game on web or native",
|
|
2249
2409
|
"choose touch controls for a mobile device",
|
|
2250
|
-
"can I raytrace on native"
|
|
2410
|
+
"can I raytrace on native",
|
|
2411
|
+
"show gamepad prompts and bind pad buttons on a games console such as the PS4"
|
|
2251
2412
|
],
|
|
2252
2413
|
"summary": "Read the host platform without reaching for browser globals.",
|
|
2253
2414
|
"supersedes": [],
|
|
2254
2415
|
"symbol": "isNative"
|
|
2255
2416
|
},
|
|
2417
|
+
{
|
|
2418
|
+
"aliases": [],
|
|
2419
|
+
"constraints": [
|
|
2420
|
+
"only use the returned platform facts; native globals are host-owned",
|
|
2421
|
+
"image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result",
|
|
2422
|
+
"a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host",
|
|
2423
|
+
"when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size"
|
|
2424
|
+
],
|
|
2425
|
+
"example": "if (isMobile()) showTouchControls();\nif (isConsole()) showPadPrompts(isPs4() ? \"dualshock\" : \"generic\");",
|
|
2426
|
+
"importPath": "@threenative/core",
|
|
2427
|
+
"kind": "function",
|
|
2428
|
+
"overrides": [],
|
|
2429
|
+
"package": "@threenative/core",
|
|
2430
|
+
"signature": "export function isPs4(): boolean { … }",
|
|
2431
|
+
"situations": [
|
|
2432
|
+
"branch a portable game on web or native",
|
|
2433
|
+
"choose touch controls for a mobile device",
|
|
2434
|
+
"can I raytrace on native",
|
|
2435
|
+
"show gamepad prompts and bind pad buttons on a games console such as the PS4"
|
|
2436
|
+
],
|
|
2437
|
+
"summary": "Read the host platform without reaching for browser globals.",
|
|
2438
|
+
"supersedes": [],
|
|
2439
|
+
"symbol": "isPs4"
|
|
2440
|
+
},
|
|
2256
2441
|
{
|
|
2257
2442
|
"aliases": [],
|
|
2258
2443
|
"constraints": [
|
|
@@ -2274,6 +2459,27 @@
|
|
|
2274
2459
|
"supersedes": [],
|
|
2275
2460
|
"symbol": "isStatic"
|
|
2276
2461
|
},
|
|
2462
|
+
{
|
|
2463
|
+
"aliases": [],
|
|
2464
|
+
"constraints": [
|
|
2465
|
+
"`CollisionShape3D.fromMesh` with \"trimesh\" or \"convexHull\" on a streamed geometry warns `TN_COLLIDER_COARSE` naming the mesh and the `{ whole: true }` override, and still builds"
|
|
2466
|
+
],
|
|
2467
|
+
"example": "const coarse = isStreamedGeometry(mesh.geometry);",
|
|
2468
|
+
"importPath": "@threenative/core",
|
|
2469
|
+
"kind": "function",
|
|
2470
|
+
"overrides": [],
|
|
2471
|
+
"package": "@threenative/core",
|
|
2472
|
+
"signature": "export function isStreamedGeometry(geometry: BufferGeometry): boolean { … }",
|
|
2473
|
+
"situations": [
|
|
2474
|
+
"collider or navmesh built from a model is coarser than what is drawn",
|
|
2475
|
+
"wait for the full model before copying its vertices",
|
|
2476
|
+
"whole model before collision",
|
|
2477
|
+
"TN_COLLIDER_COARSE"
|
|
2478
|
+
],
|
|
2479
|
+
"summary": "True while a geometry is the coarse companion a streamed model draws first (PRD-860), before its full file replaces it in place. A caller that copies vertices (a trimesh collider, a navmesh bake, a merge) waits with `ctx.assets.model(path, { whole: true })` instead of copying the coarse ones.",
|
|
2480
|
+
"supersedes": [],
|
|
2481
|
+
"symbol": "isStreamedGeometry"
|
|
2482
|
+
},
|
|
2277
2483
|
{
|
|
2278
2484
|
"aliases": [],
|
|
2279
2485
|
"constraints": [
|
|
@@ -2282,7 +2488,7 @@
|
|
|
2282
2488
|
"a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host",
|
|
2283
2489
|
"when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size"
|
|
2284
2490
|
],
|
|
2285
|
-
"example": "if (isMobile()) showTouchControls();",
|
|
2491
|
+
"example": "if (isMobile()) showTouchControls();\nif (isConsole()) showPadPrompts(isPs4() ? \"dualshock\" : \"generic\");",
|
|
2286
2492
|
"importPath": "@threenative/core",
|
|
2287
2493
|
"kind": "function",
|
|
2288
2494
|
"overrides": [],
|
|
@@ -2291,7 +2497,8 @@
|
|
|
2291
2497
|
"situations": [
|
|
2292
2498
|
"branch a portable game on web or native",
|
|
2293
2499
|
"choose touch controls for a mobile device",
|
|
2294
|
-
"can I raytrace on native"
|
|
2500
|
+
"can I raytrace on native",
|
|
2501
|
+
"show gamepad prompts and bind pad buttons on a games console such as the PS4"
|
|
2295
2502
|
],
|
|
2296
2503
|
"summary": "Read the host platform without reaching for browser globals.",
|
|
2297
2504
|
"supersedes": [],
|
|
@@ -2305,7 +2512,7 @@
|
|
|
2305
2512
|
"a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host",
|
|
2306
2513
|
"when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size"
|
|
2307
2514
|
],
|
|
2308
|
-
"example": "if (isMobile()) showTouchControls();",
|
|
2515
|
+
"example": "if (isMobile()) showTouchControls();\nif (isConsole()) showPadPrompts(isPs4() ? \"dualshock\" : \"generic\");",
|
|
2309
2516
|
"importPath": "@threenative/core",
|
|
2310
2517
|
"kind": "function",
|
|
2311
2518
|
"overrides": [],
|
|
@@ -2314,7 +2521,8 @@
|
|
|
2314
2521
|
"situations": [
|
|
2315
2522
|
"branch a portable game on web or native",
|
|
2316
2523
|
"choose touch controls for a mobile device",
|
|
2317
|
-
"can I raytrace on native"
|
|
2524
|
+
"can I raytrace on native",
|
|
2525
|
+
"show gamepad prompts and bind pad buttons on a games console such as the PS4"
|
|
2318
2526
|
],
|
|
2319
2527
|
"summary": "Read the host platform without reaching for browser globals.",
|
|
2320
2528
|
"supersedes": [],
|
|
@@ -2702,6 +2910,22 @@
|
|
|
2702
2910
|
"supersedes": [],
|
|
2703
2911
|
"symbol": "ProbeVolume"
|
|
2704
2912
|
},
|
|
2913
|
+
{
|
|
2914
|
+
"aliases": [],
|
|
2915
|
+
"constraints": [
|
|
2916
|
+
"every dev surface publishes under this key; the worker's typed mirror tuple names it too"
|
|
2917
|
+
],
|
|
2918
|
+
"example": "import { DEV_GLOBAL_KEY, devGlobal } from \"@threenative/core\";\nconst tools = devGlobal(globalThis);",
|
|
2919
|
+
"importPath": "@threenative/core",
|
|
2920
|
+
"kind": "function",
|
|
2921
|
+
"overrides": [],
|
|
2922
|
+
"package": "@threenative/core",
|
|
2923
|
+
"signature": "export function publishDevGlobal(name: string, value: unknown, scope: unknown): void { … }",
|
|
2924
|
+
"situations": ["read or extend the `__THREENATIVE__` object a dev launch publishes"],
|
|
2925
|
+
"summary": "The one name every dev surface publishes under, and the reader/writer for it.",
|
|
2926
|
+
"supersedes": [],
|
|
2927
|
+
"symbol": "publishDevGlobal"
|
|
2928
|
+
},
|
|
2705
2929
|
{
|
|
2706
2930
|
"aliases": [],
|
|
2707
2931
|
"constraints": ["an unknown tier name throws with the names it expected"],
|
|
@@ -2721,6 +2945,30 @@
|
|
|
2721
2945
|
"supersedes": [],
|
|
2722
2946
|
"symbol": "qualityPreset"
|
|
2723
2947
|
},
|
|
2948
|
+
{
|
|
2949
|
+
"aliases": ["lumen radiance cache", "radiance cache", "irradiance field", "dynamic probe gi"],
|
|
2950
|
+
"constraints": [
|
|
2951
|
+
"build a GPUSceneBVH of the static meshes first and pass it as trace.bvh; the cache reads colour and emissive from each material, a texture or a node is counted as ignored",
|
|
2952
|
+
"add the cache with ctx.add() so its refresh is measured in the render phase, and read it with sampleNode(position, normal) from a game-owned material",
|
|
2953
|
+
"a one-sided material is not seen from behind, as a cube capture would not draw it"
|
|
2954
|
+
],
|
|
2955
|
+
"example": "const bvh = new GPUSceneBVH(ctx.scene); ctx.add(bvh); const cache = new RadianceCache({ bounds, density: 0.5, trace: { bvh, sun, sky, camera: ctx.camera } }); ctx.add(cache);",
|
|
2956
|
+
"importPath": "@threenative/core",
|
|
2957
|
+
"kind": "class",
|
|
2958
|
+
"overrides": [
|
|
2959
|
+
"numProbesToTraceBudget (100), probeResolution (8, so 64 rays a probe; 32 for a small emitter), bounds, density, bounces and the sun and sky values are game-owned"
|
|
2960
|
+
],
|
|
2961
|
+
"package": "@threenative/core",
|
|
2962
|
+
"signature": "export class RadianceCache extends ProbeVolume { … }",
|
|
2963
|
+
"situations": [
|
|
2964
|
+
"light follows a lamp that switches on and off in a room",
|
|
2965
|
+
"bounce light that updates when the sun moves, with no baked lightmap",
|
|
2966
|
+
"global illumination that refreshes fast enough to read as dynamic"
|
|
2967
|
+
],
|
|
2968
|
+
"summary": "A probe field of diffuse irradiance that refreshes by tracing the packed scene, with no scene draw: the radiance cache of a dynamic global-illumination pass. Probes in view refresh first, oldest first, within `numProbesToTraceBudget` a frame; a lamp toggled in game code or a sun that steps more than one degree re-traces them while the old values keep lighting the frame.",
|
|
2969
|
+
"supersedes": [],
|
|
2970
|
+
"symbol": "RadianceCache"
|
|
2971
|
+
},
|
|
2724
2972
|
{
|
|
2725
2973
|
"aliases": [],
|
|
2726
2974
|
"constraints": ["non-marker lines and malformed markers return `undefined`"],
|
|
@@ -3163,6 +3411,31 @@
|
|
|
3163
3411
|
"supersedes": [],
|
|
3164
3412
|
"symbol": "RippleField"
|
|
3165
3413
|
},
|
|
3414
|
+
{
|
|
3415
|
+
"aliases": [],
|
|
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-vegetation 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
|
+
},
|
|
3166
3439
|
{
|
|
3167
3440
|
"aliases": [],
|
|
3168
3441
|
"constraints": ["scene code must stay portable across web and native"],
|
|
@@ -3241,6 +3514,34 @@
|
|
|
3241
3514
|
"supersedes": [],
|
|
3242
3515
|
"symbol": "Scheduler"
|
|
3243
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
|
+
},
|
|
3244
3545
|
{
|
|
3245
3546
|
"aliases": [],
|
|
3246
3547
|
"constraints": [
|
|
@@ -3308,6 +3609,31 @@
|
|
|
3308
3609
|
"supersedes": [],
|
|
3309
3610
|
"symbol": "ShadowFilterBudget"
|
|
3310
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
|
+
},
|
|
3311
3637
|
{
|
|
3312
3638
|
"aliases": [],
|
|
3313
3639
|
"constraints": [
|
|
@@ -4323,6 +4649,185 @@
|
|
|
4323
4649
|
"supersedes": [],
|
|
4324
4650
|
"symbol": "View"
|
|
4325
4651
|
},
|
|
4652
|
+
{
|
|
4653
|
+
"aliases": [],
|
|
4654
|
+
"constraints": [
|
|
4655
|
+
"a sample whose source texture or intensity moved is dropped, so a stale one never reaches a material"
|
|
4656
|
+
],
|
|
4657
|
+
"example": "const hit = cachedEnvironmentSample(renderer, scene);",
|
|
4658
|
+
"importPath": "@threenative/core/render/environment",
|
|
4659
|
+
"kind": "function",
|
|
4660
|
+
"overrides": [],
|
|
4661
|
+
"package": "@threenative/core",
|
|
4662
|
+
"signature": "export function cachedEnvironmentSample( renderer: object, scene: Scene, ): IEnvironmentSample | undefined { … }",
|
|
4663
|
+
"situations": ["skip a second environment readback in the same frame"],
|
|
4664
|
+
"summary": "The sample this renderer took of `scene`'s environment, if it is still current.",
|
|
4665
|
+
"supersedes": [],
|
|
4666
|
+
"symbol": "cachedEnvironmentSample"
|
|
4667
|
+
},
|
|
4668
|
+
{
|
|
4669
|
+
"aliases": [],
|
|
4670
|
+
"constraints": [],
|
|
4671
|
+
"example": "cacheEnvironmentSample(renderer, scene, sample);",
|
|
4672
|
+
"importPath": "@threenative/core/render/environment",
|
|
4673
|
+
"kind": "function",
|
|
4674
|
+
"overrides": [],
|
|
4675
|
+
"package": "@threenative/core",
|
|
4676
|
+
"signature": "export function cacheEnvironmentSample( renderer: object, scene: Scene, sample: IEnvironmentSample, ): void { … }",
|
|
4677
|
+
"situations": ["reuse one environment readback across the materials of a scene"],
|
|
4678
|
+
"summary": "Remembers `sample` as this renderer's reading of `scene`'s environment.",
|
|
4679
|
+
"supersedes": [],
|
|
4680
|
+
"symbol": "cacheEnvironmentSample"
|
|
4681
|
+
},
|
|
4682
|
+
{
|
|
4683
|
+
"aliases": [],
|
|
4684
|
+
"constraints": [],
|
|
4685
|
+
"example": "const snapshot = captureEnvironmentSnapshot(scene);",
|
|
4686
|
+
"importPath": "@threenative/core/render/environment",
|
|
4687
|
+
"kind": "function",
|
|
4688
|
+
"overrides": [],
|
|
4689
|
+
"package": "@threenative/core",
|
|
4690
|
+
"signature": "export function captureEnvironmentSnapshot(scene: Scene): IEnvironmentSourceSnapshot { … }",
|
|
4691
|
+
"situations": ["reject an environment readback that belongs to a different sky"],
|
|
4692
|
+
"summary": "The provenance of a scene's environment: which texture, at which intensity, in which colour space.",
|
|
4693
|
+
"supersedes": [],
|
|
4694
|
+
"symbol": "captureEnvironmentSnapshot"
|
|
4695
|
+
},
|
|
4696
|
+
{
|
|
4697
|
+
"aliases": [],
|
|
4698
|
+
"constraints": [],
|
|
4699
|
+
"example": "if (environmentSnapshotCurrent(scene, snapshot)) draw(snapshot);",
|
|
4700
|
+
"importPath": "@threenative/core/render/environment",
|
|
4701
|
+
"kind": "function",
|
|
4702
|
+
"overrides": [],
|
|
4703
|
+
"package": "@threenative/core",
|
|
4704
|
+
"signature": "export function environmentSnapshotCurrent( scene: Scene, snapshot: IEnvironmentSourceSnapshot, ): boolean { … }",
|
|
4705
|
+
"situations": ["hold a material's fill light to the sky that is on screen now"],
|
|
4706
|
+
"summary": "Whether the scene's environment still matches the snapshot a sample was taken from.",
|
|
4707
|
+
"supersedes": [],
|
|
4708
|
+
"symbol": "environmentSnapshotCurrent"
|
|
4709
|
+
},
|
|
4710
|
+
{
|
|
4711
|
+
"aliases": [],
|
|
4712
|
+
"constraints": [],
|
|
4713
|
+
"example": "if (isWebGLFallbackRenderer(renderer)) skipMaterialLane();",
|
|
4714
|
+
"importPath": "@threenative/core/render/environment",
|
|
4715
|
+
"kind": "function",
|
|
4716
|
+
"overrides": [],
|
|
4717
|
+
"package": "@threenative/core",
|
|
4718
|
+
"signature": "export function isWebGLFallbackRenderer(renderer: unknown): boolean { … }",
|
|
4719
|
+
"situations": [
|
|
4720
|
+
"refuse a GPU-only lane on a WebGL fallback instead of drawing something wrong"
|
|
4721
|
+
],
|
|
4722
|
+
"summary": "Whether a `WebGPURenderer` wrapper is running three's WebGL backend behind it.",
|
|
4723
|
+
"supersedes": [],
|
|
4724
|
+
"symbol": "isWebGLFallbackRenderer"
|
|
4725
|
+
},
|
|
4726
|
+
{
|
|
4727
|
+
"aliases": [],
|
|
4728
|
+
"constraints": [
|
|
4729
|
+
"high tier, browser, hardware WebGPU, not mobile, not software, not a WebGL fallback"
|
|
4730
|
+
],
|
|
4731
|
+
"example": "if (materialLightingEnabled(\"high\", env)) lightMaterials();",
|
|
4732
|
+
"importPath": "@threenative/core/render/environment",
|
|
4733
|
+
"kind": "function",
|
|
4734
|
+
"overrides": [],
|
|
4735
|
+
"package": "@threenative/core",
|
|
4736
|
+
"signature": "export function materialLightingEnabled( tier: QualityTier, environment: IMaterialLightingEnvironment, ): boolean { … }",
|
|
4737
|
+
"situations": ["decide whether this renderer is the admitted material lane"],
|
|
4738
|
+
"summary": "Whether `tier` may run the material-lighting lane in `environment`.",
|
|
4739
|
+
"supersedes": [],
|
|
4740
|
+
"symbol": "materialLightingEnabled"
|
|
4741
|
+
},
|
|
4742
|
+
{
|
|
4743
|
+
"aliases": [],
|
|
4744
|
+
"constraints": [],
|
|
4745
|
+
"example": "const m = measureEnvironment(scene, 2048);",
|
|
4746
|
+
"importPath": "@threenative/core/render/environment",
|
|
4747
|
+
"kind": "function",
|
|
4748
|
+
"overrides": [],
|
|
4749
|
+
"package": "@threenative/core",
|
|
4750
|
+
"signature": "export function measureEnvironment(scene: Scene, maxSourceTexels: number): IEnvironmentMeasurement { … }",
|
|
4751
|
+
"situations": [
|
|
4752
|
+
"measure what a scene's environment actually contributes",
|
|
4753
|
+
"sample the environment on the GPU without stalling the frame",
|
|
4754
|
+
"keep an environment readback from reaching a frame it does not belong to"
|
|
4755
|
+
],
|
|
4756
|
+
"summary": "The environment measure-and-sample mechanism every kit repeats: what the scene's environment actually contributes, a bounded GPU sample of it with a cache and a readback deadline, the provenance a stale readback is rejected by, and the gate that decides which renderer may run the material lane. The backlight itself is a shader with fixed constants, so it stays in each kit's `src/render/` (stamped from one source there) where the game can change how it looks. This is machinery, not a look: every colour, gain and threshold arrives as an argument, and a kit that wants a different bound passes a different one. It lives here because twelve kits held byte-identical copies — 9 084 lines — so a fix to one left eleven wrong with every gate green (`c93b427d0` touched 552 files for one look change).",
|
|
4757
|
+
"supersedes": [],
|
|
4758
|
+
"symbol": "measureEnvironment"
|
|
4759
|
+
},
|
|
4760
|
+
{
|
|
4761
|
+
"aliases": [],
|
|
4762
|
+
"constraints": [],
|
|
4763
|
+
"example": "reportEnvironmentContribution(scene, {\n darkThreshold: 0.02, fillAdmitted: true, fillColor: new Color(1, 1, 1), fillGain: 0.4,\n maxSourceTexels: 2048, rimGain: 0.6,\n});",
|
|
4764
|
+
"importPath": "@threenative/core/render/environment",
|
|
4765
|
+
"kind": "function",
|
|
4766
|
+
"overrides": [],
|
|
4767
|
+
"package": "@threenative/core",
|
|
4768
|
+
"signature": "export function reportEnvironmentContribution( scene: Scene, options: IContributionControls, measurement?: IEnvironmentMeasurement, ) { … }",
|
|
4769
|
+
"situations": [
|
|
4770
|
+
"measure what a scene's environment actually contributes",
|
|
4771
|
+
"sample the environment on the GPU without stalling the frame",
|
|
4772
|
+
"keep an environment readback from reaching a frame it does not belong to"
|
|
4773
|
+
],
|
|
4774
|
+
"summary": "The environment measure-and-sample mechanism every kit repeats: what the scene's environment actually contributes, a bounded GPU sample of it with a cache and a readback deadline, the provenance a stale readback is rejected by, and the gate that decides which renderer may run the material lane. The backlight itself is a shader with fixed constants, so it stays in each kit's `src/render/` (stamped from one source there) where the game can change how it looks. This is machinery, not a look: every colour, gain and threshold arrives as an argument, and a kit that wants a different bound passes a different one. It lives here because twelve kits held byte-identical copies — 9 084 lines — so a fix to one left eleven wrong with every gate green (`c93b427d0` touched 552 files for one look change).",
|
|
4775
|
+
"supersedes": [],
|
|
4776
|
+
"symbol": "reportEnvironmentContribution"
|
|
4777
|
+
},
|
|
4778
|
+
{
|
|
4779
|
+
"aliases": [],
|
|
4780
|
+
"constraints": [
|
|
4781
|
+
"the sample must be the qualified 64x32 float RGBA readback; anything else is refused by name"
|
|
4782
|
+
],
|
|
4783
|
+
"example": "const m = sampledRadiance(readback, 1);",
|
|
4784
|
+
"importPath": "@threenative/core/render/environment",
|
|
4785
|
+
"kind": "function",
|
|
4786
|
+
"overrides": [],
|
|
4787
|
+
"package": "@threenative/core",
|
|
4788
|
+
"signature": "export function sampledRadiance(samples: unknown, intensity: number): IEnvironmentMeasurement { … }",
|
|
4789
|
+
"situations": [
|
|
4790
|
+
"turn an environment readback into the radiance a material's fill light needs",
|
|
4791
|
+
"know why an environment sample could not be measured"
|
|
4792
|
+
],
|
|
4793
|
+
"summary": "The mean radiance and colour of a bounded linear sample, or `unknown` with the reason.",
|
|
4794
|
+
"supersedes": [],
|
|
4795
|
+
"symbol": "sampledRadiance"
|
|
4796
|
+
},
|
|
4797
|
+
{
|
|
4798
|
+
"aliases": [],
|
|
4799
|
+
"constraints": [
|
|
4800
|
+
"off unless the renderer is the admitted high-tier WebGPU lane; every refusal is reported by name",
|
|
4801
|
+
"the readback is abandoned after the deadline and the frame keeps the previous answer"
|
|
4802
|
+
],
|
|
4803
|
+
"example": "const sample = await sampleEnvironment(renderer, scene, env);",
|
|
4804
|
+
"importPath": "@threenative/core/render/environment",
|
|
4805
|
+
"kind": "function",
|
|
4806
|
+
"overrides": [],
|
|
4807
|
+
"package": "@threenative/core",
|
|
4808
|
+
"signature": "export async function sampleEnvironment( renderer: unknown, scene: Scene, environment: IMaterialLightingEnvironment, ): Promise<IEnvironmentSample> { … }",
|
|
4809
|
+
"situations": [
|
|
4810
|
+
"measure what a scene's environment actually contributes without stalling the frame",
|
|
4811
|
+
"give a material's fill light the environment's own radiance"
|
|
4812
|
+
],
|
|
4813
|
+
"summary": "Measures and samples the scene's real environment on the GPU, bounded by a readback deadline.",
|
|
4814
|
+
"supersedes": [],
|
|
4815
|
+
"symbol": "sampleEnvironment"
|
|
4816
|
+
},
|
|
4817
|
+
{
|
|
4818
|
+
"aliases": [],
|
|
4819
|
+
"constraints": [],
|
|
4820
|
+
"example": "if (samplingSourceSupported(source)) sample(source);",
|
|
4821
|
+
"importPath": "@threenative/core/render/environment",
|
|
4822
|
+
"kind": "function",
|
|
4823
|
+
"overrides": [],
|
|
4824
|
+
"package": "@threenative/core",
|
|
4825
|
+
"signature": "export function samplingSourceSupported(source: NonNullable<Scene[\"environment\"]>): boolean { … }",
|
|
4826
|
+
"situations": ["know why an environment was not sampled on the GPU"],
|
|
4827
|
+
"summary": "Whether an environment texture's mapping and colour space are qualified for the bounded GPU sample.",
|
|
4828
|
+
"supersedes": [],
|
|
4829
|
+
"symbol": "samplingSourceSupported"
|
|
4830
|
+
},
|
|
4326
4831
|
{
|
|
4327
4832
|
"aliases": [],
|
|
4328
4833
|
"constraints": [
|
|
@@ -4790,6 +5295,25 @@
|
|
|
4790
5295
|
"supersedes": [],
|
|
4791
5296
|
"symbol": "startWorkerGame"
|
|
4792
5297
|
},
|
|
5298
|
+
{
|
|
5299
|
+
"aliases": [],
|
|
5300
|
+
"constraints": [
|
|
5301
|
+
"open a new budget each frame; a unit always finishes, so one unit can cross the limit"
|
|
5302
|
+
],
|
|
5303
|
+
"example": "tiles.follow(player.position, new AdmissionBudget(2, () => performance.now()));",
|
|
5304
|
+
"importPath": "@threenative/core/world",
|
|
5305
|
+
"kind": "class",
|
|
5306
|
+
"overrides": [],
|
|
5307
|
+
"package": "@threenative/core",
|
|
5308
|
+
"signature": "export class AdmissionBudget implements IAdmissionBudget { … }",
|
|
5309
|
+
"situations": [
|
|
5310
|
+
"streamed terrain tiles or cells hitch the frame that admits them",
|
|
5311
|
+
"cap how many milliseconds a frame spends building streamed content"
|
|
5312
|
+
],
|
|
5313
|
+
"summary": "One frame's admission allowance, shared by every path that puts streamed content on screen. A streaming world has no frame-time ceiling anywhere else: a cell row arriving builds a batch per asset run over every placement in it, a terrain tile builds every LOD level, and the game's `createCollider` runs for every resident tile — all in the one frame that discovers them. That is the 100-330 ms hitch a 60 m/s camera feels every time the ring moves, and it is admission cost, not streaming: the loads never fail. The budget is opened once per `update` and drawn down by the units it admits. A unit always finishes, so a frame spends at most the limit plus the unit that crossed it, and the rest of the backlog waits for the next frame rather than being dropped.",
|
|
5314
|
+
"supersedes": [],
|
|
5315
|
+
"symbol": "AdmissionBudget"
|
|
5316
|
+
},
|
|
4793
5317
|
{
|
|
4794
5318
|
"aliases": [],
|
|
4795
5319
|
"constraints": [
|
|
@@ -4842,6 +5366,24 @@
|
|
|
4842
5366
|
"supersedes": [],
|
|
4843
5367
|
"symbol": "bakedNoise"
|
|
4844
5368
|
},
|
|
5369
|
+
{
|
|
5370
|
+
"aliases": [],
|
|
5371
|
+
"constraints": [
|
|
5372
|
+
"throws `TN_STATIC_POSE_GROUND` where the ground does not answer; check `samples` before trusting `gap`"
|
|
5373
|
+
],
|
|
5374
|
+
"example": "const ring = baseRingGap(geometry, matrix, ground); if (ring.samples >= 4) matrix.elements[13] -= ring.gap + 0.5;",
|
|
5375
|
+
"importPath": "@threenative/core/world",
|
|
5376
|
+
"kind": "function",
|
|
5377
|
+
"overrides": [],
|
|
5378
|
+
"package": "@threenative/core",
|
|
5379
|
+
"signature": "export function baseRingGap( geometry: BufferGeometry, matrix: Matrix4, ground: StaticGroundQuery, options: { … }",
|
|
5380
|
+
"situations": [
|
|
5381
|
+
"a cliff or crag model rests on a buried stem while its wide base hangs over the downhill ground"
|
|
5382
|
+
],
|
|
5383
|
+
"summary": "The highest gap between a wide model's rim and the ground, one sample per angular sector: in each sector, the lowest vertex beyond `rim` of that sector's reach. A narrow buried stem then cannot hold a wide base up in the air on the downhill side. Sink the pose by `gap` (plus any burial the game wants) to close it.",
|
|
5384
|
+
"supersedes": [],
|
|
5385
|
+
"symbol": "baseRingGap"
|
|
5386
|
+
},
|
|
4845
5387
|
{
|
|
4846
5388
|
"aliases": [],
|
|
4847
5389
|
"constraints": [
|
|
@@ -4858,6 +5400,22 @@
|
|
|
4858
5400
|
"supersedes": [],
|
|
4859
5401
|
"symbol": "cellPlacements"
|
|
4860
5402
|
},
|
|
5403
|
+
{
|
|
5404
|
+
"aliases": [],
|
|
5405
|
+
"constraints": [
|
|
5406
|
+
"the footprint is every vertex at the geometry's lowest local y; throws `TN_STATIC_POSE_GROUND` where the ground does not answer"
|
|
5407
|
+
],
|
|
5408
|
+
"example": "matrix.elements[13] -= footprintGap(geometry, matrix, ground, 0.08);",
|
|
5409
|
+
"importPath": "@threenative/core/world",
|
|
5410
|
+
"kind": "function",
|
|
5411
|
+
"overrides": [],
|
|
5412
|
+
"package": "@threenative/core",
|
|
5413
|
+
"signature": "export function footprintGap( geometry: BufferGeometry, matrix: Matrix4, ground: StaticGroundQuery, margin = 0, ): number { … }",
|
|
5414
|
+
"situations": ["a rock snapped to a slope shows a lip or a gap under its downhill side"],
|
|
5415
|
+
"summary": "How far the flat underside of a static geometry rises above the ground at its highest point. Snapping the lowest point leaves the downhill side of a flat-bottomed rock hanging; sinking the pose by this much buries the whole footprint. Returns 0 when the footprint is already buried.",
|
|
5416
|
+
"supersedes": [],
|
|
5417
|
+
"symbol": "footprintGap"
|
|
5418
|
+
},
|
|
4861
5419
|
{
|
|
4862
5420
|
"aliases": [],
|
|
4863
5421
|
"constraints": [
|
|
@@ -4969,11 +5527,31 @@
|
|
|
4969
5527
|
"kind": "function",
|
|
4970
5528
|
"overrides": [],
|
|
4971
5529
|
"package": "@threenative/core",
|
|
4972
|
-
"signature": "export function lakeReach(field: Heightfield, lake: IWaterLake): number { … }",
|
|
4973
|
-
"situations": ["size a lake's footprint from its basin and the cap its biome row names"],
|
|
4974
|
-
"summary": "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.",
|
|
5530
|
+
"signature": "export function lakeReach(field: Heightfield, lake: IWaterLake): number { … }",
|
|
5531
|
+
"situations": ["size a lake's footprint from its basin and the cap its biome row names"],
|
|
5532
|
+
"summary": "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.",
|
|
5533
|
+
"supersedes": [],
|
|
5534
|
+
"symbol": "lakeReach"
|
|
5535
|
+
},
|
|
5536
|
+
{
|
|
5537
|
+
"aliases": [],
|
|
5538
|
+
"constraints": [
|
|
5539
|
+
"the lake row and field come from the game's bake; the game's material shades the geometry"
|
|
5540
|
+
],
|
|
5541
|
+
"example": "const geometry = lakeSurfaceGeometry({ ...lake, margin: 1.12 }, field, { maxDepth: 1.6 });",
|
|
5542
|
+
"importPath": "@threenative/core/world",
|
|
5543
|
+
"kind": "function",
|
|
5544
|
+
"overrides": [],
|
|
5545
|
+
"package": "@threenative/core",
|
|
5546
|
+
"signature": "export function lakeSurfaceGeometry( lake: IWaterLake, field: Heightfield, options: ILakeSurfaceOptions = { … }",
|
|
5547
|
+
"situations": [
|
|
5548
|
+
"draw a lake's water surface from the baked level and seed",
|
|
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"
|
|
5551
|
+
],
|
|
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.",
|
|
4975
5553
|
"supersedes": [],
|
|
4976
|
-
"symbol": "
|
|
5554
|
+
"symbol": "lakeSurfaceGeometry"
|
|
4977
5555
|
},
|
|
4978
5556
|
{
|
|
4979
5557
|
"aliases": [],
|
|
@@ -5011,6 +5589,22 @@
|
|
|
5011
5589
|
"supersedes": [],
|
|
5012
5590
|
"symbol": "loadWorldHeightmap"
|
|
5013
5591
|
},
|
|
5592
|
+
{
|
|
5593
|
+
"aliases": [],
|
|
5594
|
+
"constraints": [
|
|
5595
|
+
"a section's `material` can be `undefined` for a group naming a missing material slot; skip it"
|
|
5596
|
+
],
|
|
5597
|
+
"example": "for (const section of meshSections(mesh)) parts.push(sectionGeometry(mesh, box, section));",
|
|
5598
|
+
"importPath": "@threenative/core/world",
|
|
5599
|
+
"kind": "function",
|
|
5600
|
+
"overrides": [],
|
|
5601
|
+
"package": "@threenative/core",
|
|
5602
|
+
"signature": "export function meshSections(mesh: Mesh): IMeshSection[] { … }",
|
|
5603
|
+
"situations": ["scatter or instance an imported glTF model that has several materials"],
|
|
5604
|
+
"summary": "A mesh's material sections: one per geometry group for a material array, else the whole mesh. Instanced props draw one batch per material, so an imported model splits here first.",
|
|
5605
|
+
"supersedes": [],
|
|
5606
|
+
"symbol": "meshSections"
|
|
5607
|
+
},
|
|
5014
5608
|
{
|
|
5015
5609
|
"aliases": [],
|
|
5016
5610
|
"constraints": [
|
|
@@ -5027,6 +5621,81 @@
|
|
|
5027
5621
|
"supersedes": [],
|
|
5028
5622
|
"symbol": "noiseVolume"
|
|
5029
5623
|
},
|
|
5624
|
+
{
|
|
5625
|
+
"aliases": [],
|
|
5626
|
+
"constraints": [
|
|
5627
|
+
"one bad normal recomputes them all; an intentionally hard-edged model loses its authored split normals only if one is bad"
|
|
5628
|
+
],
|
|
5629
|
+
"example": "geometry.scale(1.1, 1, 1.1); repairZeroNormals(geometry);",
|
|
5630
|
+
"importPath": "@threenative/core/world",
|
|
5631
|
+
"kind": "function",
|
|
5632
|
+
"overrides": [],
|
|
5633
|
+
"package": "@threenative/core",
|
|
5634
|
+
"signature": "export function repairZeroNormals(geometry: BufferGeometry): boolean { … }",
|
|
5635
|
+
"situations": ["an imported model draws black or unlit because it ships zero normals"],
|
|
5636
|
+
"summary": "Recompute the normals of a geometry whose normals are missing, zero or not finite, and leave authored normals alone. Some exported art ships zero normals and draws black under any light. Run it after any reshape, so the recomputed normals fit the final shape.",
|
|
5637
|
+
"supersedes": [],
|
|
5638
|
+
"symbol": "repairZeroNormals"
|
|
5639
|
+
},
|
|
5640
|
+
{
|
|
5641
|
+
"aliases": [],
|
|
5642
|
+
"constraints": [
|
|
5643
|
+
"stations, width and reach come from the game's bake; the game's material shades the geometry"
|
|
5644
|
+
],
|
|
5645
|
+
"example": "const geometry = riverRibbonGeometry(rivers, field, { maxDepth: 1.6 });",
|
|
5646
|
+
"importPath": "@threenative/core/world",
|
|
5647
|
+
"kind": "function",
|
|
5648
|
+
"overrides": [],
|
|
5649
|
+
"package": "@threenative/core",
|
|
5650
|
+
"signature": "export function riverRibbonGeometry( rivers: readonly { … }",
|
|
5651
|
+
"situations": [
|
|
5652
|
+
"draw a river's water surface from the baked stations",
|
|
5653
|
+
"a river's water stops in a straight edge, or a swimmer floats where no water is drawn",
|
|
5654
|
+
"share one river shape between the drawn water and the swimmer",
|
|
5655
|
+
"river water hangs over dry ground past the river's head or tail"
|
|
5656
|
+
],
|
|
5657
|
+
"summary": "The water surface of every river, as one geometry with one group per river. Each station is a row across the river at its own surface height, out to `reach` widths either side of the centreline, the reach `WaterBodies` floods; one more row a reach past each end stands where `WaterBodies` clamps a segment, so the water a swimmer finds past a river's end is drawn there too (cut at the end station, the surface stopped in a straight edge with its carved bed dry beyond). Quads dry on both rows against `field` are dropped, so the surface ends at the shore. Past an end where the ground falls below the end's bed, the water would run off: that cap is not drawn, and the end stays cut at its last station. Attributes for the game's water material: `flow` (the unit downstream heading), `flowUv` (metres down the centreline, metres across it) and `metres` (water depth over the ground). It decides no colour, ripple or opacity: the game shades it.",
|
|
5658
|
+
"supersedes": [],
|
|
5659
|
+
"symbol": "riverRibbonGeometry"
|
|
5660
|
+
},
|
|
5661
|
+
{
|
|
5662
|
+
"aliases": [],
|
|
5663
|
+
"constraints": [
|
|
5664
|
+
"`box` is the whole model's world bounds after any unit normalisation; call `mesh.updateWorldMatrix` first"
|
|
5665
|
+
],
|
|
5666
|
+
"example": "const box = new Box3().setFromObject(root); const geometry = sectionGeometry(mesh, box, section);",
|
|
5667
|
+
"importPath": "@threenative/core/world",
|
|
5668
|
+
"kind": "function",
|
|
5669
|
+
"overrides": [],
|
|
5670
|
+
"package": "@threenative/core",
|
|
5671
|
+
"signature": "export function sectionGeometry( mesh: Mesh, box: Box3, section: IMeshSection, options: { … }",
|
|
5672
|
+
"situations": [
|
|
5673
|
+
"the crown of an instanced tree floats off its trunk, or the parts of a model separate",
|
|
5674
|
+
"turn each part of an imported model into a geometry for an instanced prop batch"
|
|
5675
|
+
],
|
|
5676
|
+
"summary": "One section's geometry in model space, standing on y = 0. Every section of a model takes the same base from the whole model's `box`, so a crown keeps its place on its trunk: basing each section on its own bounds detaches them. The mesh's LOD0 geometry is cloned under its world matrix, and a group becomes the clone's draw range.",
|
|
5677
|
+
"supersedes": [],
|
|
5678
|
+
"symbol": "sectionGeometry"
|
|
5679
|
+
},
|
|
5680
|
+
{
|
|
5681
|
+
"aliases": [],
|
|
5682
|
+
"constraints": [
|
|
5683
|
+
"heights are row-major, `resolution` by `resolution`, across `size` metres; measured once, never per frame"
|
|
5684
|
+
],
|
|
5685
|
+
"example": "const { distance, exposed } = shoreField(world.heights, world.resolution, world.size, world.waterLevel);",
|
|
5686
|
+
"importPath": "@threenative/core/world",
|
|
5687
|
+
"kind": "function",
|
|
5688
|
+
"overrides": [],
|
|
5689
|
+
"package": "@threenative/core",
|
|
5690
|
+
"signature": "export function shoreField( heights: ArrayLike<number>, resolution: number, size: number, level: number, options: IShoreFieldOptions = { … }",
|
|
5691
|
+
"situations": [
|
|
5692
|
+
"surf breaks only on water open to the sea, not in a sheltered lagoon",
|
|
5693
|
+
"distance from each water cell to the shore, for a foam or depth mask"
|
|
5694
|
+
],
|
|
5695
|
+
"summary": "Distance to the shore and open-sea exposure for every node of a square height grid, measured once from the bake. `distance` is a two-pass chamfer distance to the nearest node at or above `level` (0 on dry ground). `exposed` floods from the grid's edge through water deeper than `openDepth`, then `carry` metres further into shallow water, so a sheltered lagoon behind a sand bar stays out of it. Both feed the game's surf and shore masks; neither decides a colour.",
|
|
5696
|
+
"supersedes": [],
|
|
5697
|
+
"symbol": "shoreField"
|
|
5698
|
+
},
|
|
5030
5699
|
{
|
|
5031
5700
|
"aliases": [],
|
|
5032
5701
|
"constraints": ["radius is metres; the footprint never grows with load, only deeper"],
|
|
@@ -5062,6 +5731,7 @@
|
|
|
5062
5731
|
"signature": "export class SnowField { … }",
|
|
5063
5732
|
"situations": [
|
|
5064
5733
|
"leave footprints, tracks and tyre ruts in snow that persist and fill in over time",
|
|
5734
|
+
"let a fresh snowfall slowly fill older tracks back in as the field recovers",
|
|
5065
5735
|
"let a pushed sphere carve a connected track and a dropped one settle into a crater",
|
|
5066
5736
|
"store snow deformation that rendered geometry and collision both read",
|
|
5067
5737
|
"reset a snowfield between rounds or change its depth at runtime",
|
|
@@ -5071,6 +5741,44 @@
|
|
|
5071
5741
|
"supersedes": [],
|
|
5072
5742
|
"symbol": "SnowField"
|
|
5073
5743
|
},
|
|
5744
|
+
{
|
|
5745
|
+
"aliases": [],
|
|
5746
|
+
"constraints": [
|
|
5747
|
+
"static geometry only; a skinned model uses `GroundSnap`; the sort is cached per geometry, so do not mutate its positions"
|
|
5748
|
+
],
|
|
5749
|
+
"example": "placed.position.y += ground - staticLowestY(geometry, matrix);",
|
|
5750
|
+
"importPath": "@threenative/core/world",
|
|
5751
|
+
"kind": "function",
|
|
5752
|
+
"overrides": [],
|
|
5753
|
+
"package": "@threenative/core",
|
|
5754
|
+
"signature": "export function staticLowestY(geometry: BufferGeometry, matrix: Matrix4): number { … }",
|
|
5755
|
+
"situations": [
|
|
5756
|
+
"stand a scattered rock, tree or crate on the ground by its lowest point, not its origin",
|
|
5757
|
+
"props hover or sink because their pivot is not at their base"
|
|
5758
|
+
],
|
|
5759
|
+
"summary": "Exact lowest world Y of a static geometry under `matrix`, the precise measurement `GroundSnap` audits against, cheap enough for a load that poses hundreds of thousands of props. An upright pose reads the bounding box. A tilted pose scans the vertices bottom first (sorted once per geometry) and stops once no later vertex can be lower: `|x e1 + z e9| <= reach * hypot(e1, e9)`.",
|
|
5760
|
+
"supersedes": [],
|
|
5761
|
+
"symbol": "staticLowestY"
|
|
5762
|
+
},
|
|
5763
|
+
{
|
|
5764
|
+
"aliases": [],
|
|
5765
|
+
"constraints": [
|
|
5766
|
+
"the mesh is `field.toGeometry()` drawn upright under a uniform scale; read `matrixWorld` after it settles"
|
|
5767
|
+
],
|
|
5768
|
+
"example": "const ground = surfaceSampler(field, mesh.matrixWorld); const y = ground(x, z) ?? fallback;",
|
|
5769
|
+
"importPath": "@threenative/core/world",
|
|
5770
|
+
"kind": "function",
|
|
5771
|
+
"overrides": [],
|
|
5772
|
+
"package": "@threenative/core",
|
|
5773
|
+
"signature": "export function surfaceSampler(field: Heightfield, matrixWorld: Matrix4): SurfaceSampler { … }",
|
|
5774
|
+
"situations": [
|
|
5775
|
+
"stand props or a player on the drawn terrain triangles under a moved or scaled mesh",
|
|
5776
|
+
"props float or sink where the terrain mesh is drawn under a transform"
|
|
5777
|
+
],
|
|
5778
|
+
"summary": "`Heightfield.surfaceAt` under the transform the game draws the field's mesh with, so a prop or a player stands on the triangles the eye sees rather than on the bilinear field between them. Answers `null` outside the field and for a transform it does not model (any rotation, or an unequal scale), so the caller keeps its own fallback there.",
|
|
5779
|
+
"supersedes": [],
|
|
5780
|
+
"symbol": "surfaceSampler"
|
|
5781
|
+
},
|
|
5074
5782
|
{
|
|
5075
5783
|
"aliases": ["stream terrain across chunks"],
|
|
5076
5784
|
"constraints": [
|
|
@@ -5089,7 +5797,9 @@
|
|
|
5089
5797
|
"situations": [
|
|
5090
5798
|
"stream terrain without cracks",
|
|
5091
5799
|
"keep generated terrain resident around a moving player",
|
|
5092
|
-
"put a generated terrain tile into a game-owned physics world"
|
|
5800
|
+
"put a generated terrain tile into a game-owned physics world",
|
|
5801
|
+
"a hole or a flicker where streamed terrain tiles are still building (`settledHalf`)",
|
|
5802
|
+
"split the ground between streamed tiles and a far mesh around the player (`settledHalf`)"
|
|
5093
5803
|
],
|
|
5094
5804
|
"summary": "Stream a bounded square of game-authored heightfields and keep their render and physics units together. The class composes ordinary THREE.LOD objects and leaves frustum/projection culling to the renderer's existing scene path.",
|
|
5095
5805
|
"supersedes": [],
|
|
@@ -5131,6 +5841,25 @@
|
|
|
5131
5841
|
"supersedes": [],
|
|
5132
5842
|
"symbol": "validateWorldPackage"
|
|
5133
5843
|
},
|
|
5844
|
+
{
|
|
5845
|
+
"aliases": [],
|
|
5846
|
+
"constraints": [
|
|
5847
|
+
"`ctx.beforeRender` runs on every world draw, also behind the curtain; join the promise to the curtain's hold"
|
|
5848
|
+
],
|
|
5849
|
+
"example": "const warm = warmUnculled(ctx, lake.mesh); ctx.startup.hold(\"lake\", () => warm);",
|
|
5850
|
+
"importPath": "@threenative/core/world",
|
|
5851
|
+
"kind": "function",
|
|
5852
|
+
"overrides": [],
|
|
5853
|
+
"package": "@threenative/core",
|
|
5854
|
+
"signature": "export function warmUnculled( ctx: { … }",
|
|
5855
|
+
"situations": [
|
|
5856
|
+
"the first frames after the loading curtain hitch on pipeline builds for content behind the camera",
|
|
5857
|
+
"streamed terrain or a lake compiles its pipelines after the reveal"
|
|
5858
|
+
],
|
|
5859
|
+
"summary": "Draw `root` with frustum culling off until it has drawn `draws` times, then cull it again and resolve. A pipeline is built by its first real draw (a startup warm-up compiles a different pass), so content the spawn view does not see — streamed tiles behind the player, a mirror that draws only when its water does — builds its pipelines after the reveal and hitches the first frames that see it. Join the promise to the loading curtain to build them behind it. Objects that join `root` while it warms draw unculled too.",
|
|
5860
|
+
"supersedes": [],
|
|
5861
|
+
"symbol": "warmUnculled"
|
|
5862
|
+
},
|
|
5134
5863
|
{
|
|
5135
5864
|
"aliases": [],
|
|
5136
5865
|
"constraints": [
|
|
@@ -5194,7 +5923,7 @@
|
|
|
5194
5923
|
"importPath": "@threenative/core/world",
|
|
5195
5924
|
"kind": "class",
|
|
5196
5925
|
"overrides": [
|
|
5197
|
-
"`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"
|
|
5198
5927
|
],
|
|
5199
5928
|
"package": "@threenative/core",
|
|
5200
5929
|
"signature": "export class WorldCells extends Group implements IComputeDriven { … }",
|
|
@@ -5542,7 +6271,10 @@
|
|
|
5542
6271
|
},
|
|
5543
6272
|
{
|
|
5544
6273
|
"aliases": [],
|
|
5545
|
-
"constraints": [
|
|
6274
|
+
"constraints": [
|
|
6275
|
+
"place rapier() before recast() in the plugin list",
|
|
6276
|
+
"ctx.physics is set before Scene.enter(), not during load(): Rapier initializes while the scene loads, so create bodies in enter() or later (TN_PHYSICS_NOT_READY)"
|
|
6277
|
+
],
|
|
5546
6278
|
"example": "const game = defineGame({ plugins: [rapier()] });",
|
|
5547
6279
|
"importPath": "@threenative/physics",
|
|
5548
6280
|
"kind": "function",
|
|
@@ -6249,6 +6981,22 @@
|
|
|
6249
6981
|
"supersedes": [],
|
|
6250
6982
|
"symbol": "requestedPlaytestClockMode"
|
|
6251
6983
|
},
|
|
6984
|
+
{
|
|
6985
|
+
"aliases": [],
|
|
6986
|
+
"constraints": [
|
|
6987
|
+
"an unreadable load is a refusal, not a silence: an unmeasured machine cannot vouch"
|
|
6988
|
+
],
|
|
6989
|
+
"example": "import { absolutesVerdict, readHostLoad } from \"@threenative/playtest/runner\";\nconst load = readHostLoad();\nif (absolutesVerdict(load) === \"invalid-absolute\") ignoreAbsoluteMilliseconds();",
|
|
6990
|
+
"importPath": "@threenative/playtest/runner",
|
|
6991
|
+
"kind": "function",
|
|
6992
|
+
"overrides": [],
|
|
6993
|
+
"package": "@threenative/playtest",
|
|
6994
|
+
"signature": "export function absolutesVerdict(reading: IPerfHostLoadReading): IPerfHostLoad[\"absolutes\"] { … }",
|
|
6995
|
+
"situations": ["mark a benchmark run invalid because the machine was busy"],
|
|
6996
|
+
"summary": "The host-load reading and the rule that decides whether absolute milliseconds are trustworthy: absolutes are invalid once the one-minute load passes half the cores.",
|
|
6997
|
+
"supersedes": [],
|
|
6998
|
+
"symbol": "absolutesVerdict"
|
|
6999
|
+
},
|
|
6252
7000
|
{
|
|
6253
7001
|
"aliases": [],
|
|
6254
7002
|
"constraints": ["Android evidence must name its target and transport"],
|
|
@@ -6957,6 +7705,22 @@
|
|
|
6957
7705
|
"supersedes": [],
|
|
6958
7706
|
"symbol": "preflightDisplay"
|
|
6959
7707
|
},
|
|
7708
|
+
{
|
|
7709
|
+
"aliases": [],
|
|
7710
|
+
"constraints": [
|
|
7711
|
+
"an unreadable load is a refusal, not a silence: an unmeasured machine cannot vouch"
|
|
7712
|
+
],
|
|
7713
|
+
"example": "import { absolutesVerdict, readHostLoad } from \"@threenative/playtest/runner\";\nconst load = readHostLoad();\nif (absolutesVerdict(load) === \"invalid-absolute\") ignoreAbsoluteMilliseconds();",
|
|
7714
|
+
"importPath": "@threenative/playtest/runner",
|
|
7715
|
+
"kind": "function",
|
|
7716
|
+
"overrides": [],
|
|
7717
|
+
"package": "@threenative/playtest",
|
|
7718
|
+
"signature": "export function readHostLoad( source: IPerfHostLoadSource = { … }",
|
|
7719
|
+
"situations": ["mark a benchmark run invalid because the machine was busy"],
|
|
7720
|
+
"summary": "The host-load reading and the rule that decides whether absolute milliseconds are trustworthy: absolutes are invalid once the one-minute load passes half the cores.",
|
|
7721
|
+
"supersedes": [],
|
|
7722
|
+
"symbol": "readHostLoad"
|
|
7723
|
+
},
|
|
6960
7724
|
{
|
|
6961
7725
|
"aliases": [],
|
|
6962
7726
|
"constraints": [
|
|
@@ -7111,18 +7875,17 @@
|
|
|
7111
7875
|
},
|
|
7112
7876
|
{
|
|
7113
7877
|
"aliases": [],
|
|
7114
|
-
"constraints": [
|
|
7115
|
-
|
|
7878
|
+
"constraints": [
|
|
7879
|
+
"the driver must prepare the app bundle and the transport must answer the handshake"
|
|
7880
|
+
],
|
|
7881
|
+
"example": "await runDevicePlaytest(config, { name: \"android\", driver, transport, processName, mailboxPaths });",
|
|
7116
7882
|
"importPath": "@threenative/playtest/runner",
|
|
7117
7883
|
"kind": "function",
|
|
7118
7884
|
"overrides": [],
|
|
7119
7885
|
"package": "@threenative/playtest",
|
|
7120
7886
|
"signature": "export async function runDevicePlaytest( config: IStandalonePlaytestConfig, target: IDevicePlaytestTarget, ): Promise<IStandalonePlaytestReport> { … }",
|
|
7121
|
-
"situations": [
|
|
7122
|
-
|
|
7123
|
-
"collect Android playtest artifacts"
|
|
7124
|
-
],
|
|
7125
|
-
"summary": "Run a playtest on Android through the configured device transport.",
|
|
7887
|
+
"situations": ["execute a scenario on a device target with a custom driver"],
|
|
7888
|
+
"summary": "Run a playtest on any device lane (Android, desktop or iOS) through its driver and transport.",
|
|
7126
7889
|
"supersedes": [],
|
|
7127
7890
|
"symbol": "runDevicePlaytest"
|
|
7128
7891
|
},
|
|
@@ -7657,6 +8420,54 @@
|
|
|
7657
8420
|
"supersedes": [],
|
|
7658
8421
|
"symbol": "bakeWolfToFile"
|
|
7659
8422
|
},
|
|
8423
|
+
{
|
|
8424
|
+
"aliases": [],
|
|
8425
|
+
"constraints": [
|
|
8426
|
+
"fails closed: an unknown preset throws naming the nearest ids, the seed must be an integer and each lod 0 to 2",
|
|
8427
|
+
"the same preset, seed and lods write identical bytes; files are written atomically (temporary file, then rename)",
|
|
8428
|
+
"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",
|
|
8429
|
+
"_WIND is vec4 (trunk sway, branch sway, flutter, phase): forest-kit sway is flutter in z, and debris writes all four zero",
|
|
8430
|
+
"form and leafImage patch an Arbor preset only; a forest-kit debris or cover preset throws when given either"
|
|
8431
|
+
],
|
|
8432
|
+
"example": "await bakeVegetation({ preset: \"oak\", seed: 7, lods: [0, 1], out: \"assets/trees\" });\nawait bakeVegetation({ preset: \"log\", seed: 3, out: \"assets/debris\" });",
|
|
8433
|
+
"importPath": "@threenative/procedural-vegetation",
|
|
8434
|
+
"kind": "function",
|
|
8435
|
+
"overrides": [],
|
|
8436
|
+
"package": "@threenative/procedural-vegetation",
|
|
8437
|
+
"requires": ["npm i -D @threenative/procedural-vegetation"],
|
|
8438
|
+
"signature": "export async function bakeVegetation(options: IBakeVegetationOptions): Promise<IVegetationBake[]> { … }",
|
|
8439
|
+
"situations": [
|
|
8440
|
+
"generate a procedural tree, an oak, pine, spruce, palm or any forest species as a GLB",
|
|
8441
|
+
"procedural oak tree GLB with level of detail for a game forest",
|
|
8442
|
+
"tree GLB for Unity, Unreal or Godot, with wind weights in a _WIND attribute",
|
|
8443
|
+
"a fallen mossy log and leaf litter on the forest floor, with a stump, twigs and boulders",
|
|
8444
|
+
"reeds and cattails at a pond edge, or sedge tussocks, clover and seeding grass as cover"
|
|
8445
|
+
],
|
|
8446
|
+
"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; the Arbor presets also embed their bark and leaf textures with alpha-masked leaves, while forest-kit debris and cover shade from COLOR_0 alone.",
|
|
8447
|
+
"supersedes": [],
|
|
8448
|
+
"symbol": "bakeVegetation"
|
|
8449
|
+
},
|
|
8450
|
+
{
|
|
8451
|
+
"aliases": [],
|
|
8452
|
+
"constraints": [
|
|
8453
|
+
"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\""
|
|
8454
|
+
],
|
|
8455
|
+
"example": "vegetationPresets().filter((p) => p.kind === \"debris\").map((p) => p.id);",
|
|
8456
|
+
"importPath": "@threenative/procedural-vegetation",
|
|
8457
|
+
"kind": "function",
|
|
8458
|
+
"overrides": [],
|
|
8459
|
+
"package": "@threenative/procedural-vegetation",
|
|
8460
|
+
"requires": ["npm i -D @threenative/procedural-vegetation"],
|
|
8461
|
+
"signature": "export function vegetationPresets(): IVegetationPreset[] { … }",
|
|
8462
|
+
"situations": [
|
|
8463
|
+
"list the oak, pine, spruce, palm and other tree species a bake can grow",
|
|
8464
|
+
"choose a tree species id for bakeVegetation or a terrain arbor: species",
|
|
8465
|
+
"what deadwood, leaf litter, boulders, reeds and tussocks can I bake for a forest floor"
|
|
8466
|
+
],
|
|
8467
|
+
"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.",
|
|
8468
|
+
"supersedes": [],
|
|
8469
|
+
"symbol": "vegetationPresets"
|
|
8470
|
+
},
|
|
7660
8471
|
{
|
|
7661
8472
|
"aliases": [],
|
|
7662
8473
|
"constraints": [
|
|
@@ -8138,8 +8949,15 @@
|
|
|
8138
8949
|
"package": "@threenative/terrain",
|
|
8139
8950
|
"requires": ["npm i -D @threenative/terrain"],
|
|
8140
8951
|
"signature": "export function bakeBiome(options: IBakeBiomeOptions): IBakedBiome { … }",
|
|
8141
|
-
"situations": [
|
|
8142
|
-
|
|
8952
|
+
"situations": [
|
|
8953
|
+
"bake one biome's world package from an evaluated recipe and a biome file",
|
|
8954
|
+
"generate terrain with mountains, hills, a river, a lake or an island from a request in words",
|
|
8955
|
+
"generate a landscape or open world map for a game",
|
|
8956
|
+
"procedural terrain for a level: a volcanic island, a mountain valley or a coast",
|
|
8957
|
+
"make a canyon, a volcano, a fjord, a desert, a tundra or a forest world",
|
|
8958
|
+
"cook the real terrain of a place on Earth from its latitude and longitude"
|
|
8959
|
+
],
|
|
8960
|
+
"summary": "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. An agent does not write this call to get a world: the `threenative-terrain` MCP tool `terrain_generate` takes the request in words (\"a pine forest under snowy mountains with a river\", \"a volcanic island\", or `ground: { location }` for a real place) and cooks the world.glb, recipe.json and world.json a game loads with `ctx.assets.model`.",
|
|
8143
8961
|
"supersedes": [],
|
|
8144
8962
|
"symbol": "bakeBiome"
|
|
8145
8963
|
},
|
|
@@ -8267,6 +9085,25 @@
|
|
|
8267
9085
|
"supersedes": [],
|
|
8268
9086
|
"symbol": "decodeHeightPNG"
|
|
8269
9087
|
},
|
|
9088
|
+
{
|
|
9089
|
+
"aliases": [],
|
|
9090
|
+
"constraints": [
|
|
9091
|
+
"throws `TN_PROP_BUCKET_INVALID` when the record buffer, the IDs and the runs disagree"
|
|
9092
|
+
],
|
|
9093
|
+
"example": "for (const record of decodePropBucket(bucket)) pose(record.key, record.position, record.quaternion);",
|
|
9094
|
+
"importPath": "@threenative/terrain",
|
|
9095
|
+
"kind": "function",
|
|
9096
|
+
"overrides": [],
|
|
9097
|
+
"package": "@threenative/terrain",
|
|
9098
|
+
"requires": ["npm i -D @threenative/terrain"],
|
|
9099
|
+
"signature": "export function decodePropBucket(bucket: IPropBucketPackage): IPropBucketRecord[] { … }",
|
|
9100
|
+
"situations": [
|
|
9101
|
+
"read a baked prop bucket back into placements to ground them on this machine's terrain"
|
|
9102
|
+
],
|
|
9103
|
+
"summary": "The records of one compiled prop bucket, read back in record order: the inverse of `compilePropBuckets`, so a loader that fetched a bake's files gets each record's ID, model, pose and reach without re-deriving the container layout.",
|
|
9104
|
+
"supersedes": [],
|
|
9105
|
+
"symbol": "decodePropBucket"
|
|
9106
|
+
},
|
|
8270
9107
|
{
|
|
8271
9108
|
"aliases": [],
|
|
8272
9109
|
"constraints": ["authoring data only; the game owns appearance, physics and rendering"],
|
|
@@ -8409,6 +9246,27 @@
|
|
|
8409
9246
|
"supersedes": [],
|
|
8410
9247
|
"symbol": "gradientAt"
|
|
8411
9248
|
},
|
|
9249
|
+
{
|
|
9250
|
+
"aliases": [],
|
|
9251
|
+
"constraints": [
|
|
9252
|
+
"the look stays the game's: pass the result with the kit's `render/grass.ts` blade and material"
|
|
9253
|
+
],
|
|
9254
|
+
"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 }));",
|
|
9255
|
+
"importPath": "@threenative/terrain",
|
|
9256
|
+
"kind": "function",
|
|
9257
|
+
"overrides": [],
|
|
9258
|
+
"package": "@threenative/terrain",
|
|
9259
|
+
"requires": ["npm i -D @threenative/terrain"],
|
|
9260
|
+
"signature": "export function grassFieldFromBiome( biome: Pick<IBiomeSpec, \"grass\" | \"seed\">, ground: IGrassGround, ): IGrassFieldPlacement | null { … }",
|
|
9261
|
+
"situations": [
|
|
9262
|
+
"grow streamed grass on a terrain world's biome grass rows",
|
|
9263
|
+
"a Strata or terrain_generate world with a meadow that sways round the player",
|
|
9264
|
+
"feed a cooked biome to GrassField3D"
|
|
9265
|
+
],
|
|
9266
|
+
"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.",
|
|
9267
|
+
"supersedes": [],
|
|
9268
|
+
"symbol": "grassFieldFromBiome"
|
|
9269
|
+
},
|
|
8412
9270
|
{
|
|
8413
9271
|
"aliases": [],
|
|
8414
9272
|
"constraints": [
|
|
@@ -8454,6 +9312,23 @@
|
|
|
8454
9312
|
"supersedes": [],
|
|
8455
9313
|
"symbol": "landformBackdrop"
|
|
8456
9314
|
},
|
|
9315
|
+
{
|
|
9316
|
+
"aliases": [],
|
|
9317
|
+
"constraints": ["the tile must cover the whole mountain; a summit crop lifts as a cone"],
|
|
9318
|
+
"example": "const lifted = liftMassif({ id: \"hill\", size: 400, resolution: 3, heights: [0, 0, 0, 0, 90, 0, 0, 0, 0] });",
|
|
9319
|
+
"importPath": "@threenative/terrain",
|
|
9320
|
+
"kind": "function",
|
|
9321
|
+
"overrides": [],
|
|
9322
|
+
"package": "@threenative/terrain",
|
|
9323
|
+
"requires": ["npm i -D @threenative/terrain"],
|
|
9324
|
+
"signature": "export function liftMassif(tile: IMassifTile): Float32Array { … }",
|
|
9325
|
+
"situations": [
|
|
9326
|
+
"measure how tall a surveyed mountain stands above the valley floor around it"
|
|
9327
|
+
],
|
|
9328
|
+
"summary": "A tile's mountain above its own foot: the heights minus a smooth surface through its border, so its edge is exactly zero and stands on any ground with no wall or ramp. Signed: a valley inside the mountain cuts below the foot, as it does in the survey.",
|
|
9329
|
+
"supersedes": [],
|
|
9330
|
+
"symbol": "liftMassif"
|
|
9331
|
+
},
|
|
8457
9332
|
{
|
|
8458
9333
|
"aliases": [],
|
|
8459
9334
|
"constraints": ["authoring data only; the game owns appearance, physics and rendering"],
|
|
@@ -8503,6 +9378,27 @@
|
|
|
8503
9378
|
"supersedes": [],
|
|
8504
9379
|
"symbol": "orderedScatterRules"
|
|
8505
9380
|
},
|
|
9381
|
+
{
|
|
9382
|
+
"aliases": [],
|
|
9383
|
+
"constraints": [
|
|
9384
|
+
"the tile must be a whole mountain whose border is valley floor; erosion after it carves the survey"
|
|
9385
|
+
],
|
|
9386
|
+
"example": "const { terrain, placement } = placeMassif(new Terrain({ size: 5000, resolution: 129 }), { seed: 3, tile: { id: \"cone\", size: 2000, resolution: 3, heights: [0, 0, 0, 0, 900, 0, 0, 0, 0] } });",
|
|
9387
|
+
"importPath": "@threenative/terrain",
|
|
9388
|
+
"kind": "function",
|
|
9389
|
+
"overrides": [
|
|
9390
|
+
"`at`, `bearing`, `distance`, `height`, `top`, `face` and `keepOut` on the same call"
|
|
9391
|
+
],
|
|
9392
|
+
"package": "@threenative/terrain",
|
|
9393
|
+
"requires": ["npm i -D @threenative/terrain"],
|
|
9394
|
+
"signature": "export function placeMassif( terrain: Terrain, options: IPlaceMassifOptions, ): { … }",
|
|
9395
|
+
"situations": [
|
|
9396
|
+
"put a real-shaped mountain behind a generated world, a different one per seed"
|
|
9397
|
+
],
|
|
9398
|
+
"summary": "Stands one surveyed mountain behind a world, chosen and posed by a seed: the tile from a list, a point on a bearing and distance, a turn that faces its steepest wall to the centre within 20 degrees, a mirror and a summit height. It stands on the host's own foot (a smooth surface through the host under its border), replacing the host's hills inside its square, and leaves the centre square untouched. Appends one `heightmap` layer; the placement carries the tile-spacing heights a relief map reads.",
|
|
9399
|
+
"supersedes": [],
|
|
9400
|
+
"symbol": "placeMassif"
|
|
9401
|
+
},
|
|
8506
9402
|
{
|
|
8507
9403
|
"aliases": [],
|
|
8508
9404
|
"constraints": [],
|
|
@@ -8780,6 +9676,23 @@
|
|
|
8780
9676
|
"supersedes": [],
|
|
8781
9677
|
"symbol": "createEditorSelection"
|
|
8782
9678
|
},
|
|
9679
|
+
{
|
|
9680
|
+
"aliases": [],
|
|
9681
|
+
"constraints": [],
|
|
9682
|
+
"example": "const box = createTweakBox({ title: \"Fog\", knobs: { density: { min: 0, max: 0.1, value: 0.02 } }, onChange: (name, value) => console.info(name, value) });",
|
|
9683
|
+
"importPath": "@threenative/terrain/editor",
|
|
9684
|
+
"kind": "function",
|
|
9685
|
+
"overrides": [],
|
|
9686
|
+
"package": "@threenative/terrain",
|
|
9687
|
+
"requires": ["npm i -D @threenative/terrain"],
|
|
9688
|
+
"signature": "export function createTweakBox<K extends string>(options: ITweakBoxOptions<K>): ITweakBox<K> { … }",
|
|
9689
|
+
"situations": [
|
|
9690
|
+
"tune look numbers by eye with live range bars and colour pickers while the game runs"
|
|
9691
|
+
],
|
|
9692
|
+
"summary": "A box of range bars and colour pickers over the running game, for tuning numbers by eye. The game names its knobs and applies each change itself; the box owns the page elements, the stored values and the Copy button, whose JSON is what gets pasted back and written into the game's own source. With no `document` (a native launch, a test) it draws nothing and still holds the values, so the game code that reads them is the same on every target.",
|
|
9693
|
+
"supersedes": [],
|
|
9694
|
+
"symbol": "createTweakBox"
|
|
9695
|
+
},
|
|
8783
9696
|
{
|
|
8784
9697
|
"aliases": [],
|
|
8785
9698
|
"constraints": [
|
|
@@ -9618,6 +10531,31 @@
|
|
|
9618
10531
|
"supersedes": [],
|
|
9619
10532
|
"symbol": "useUiStateDuringStartup"
|
|
9620
10533
|
},
|
|
10534
|
+
{
|
|
10535
|
+
"symbol": "ctx.assets.memo",
|
|
10536
|
+
"package": "@threenative/core",
|
|
10537
|
+
"importPath": "src/assets.ts",
|
|
10538
|
+
"kind": "function",
|
|
10539
|
+
"signature": "ctx.assets.memo<T>(key: string, build: () => T | Promise<T>): Promise<T>",
|
|
10540
|
+
"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.",
|
|
10541
|
+
"situations": [
|
|
10542
|
+
"cache generated geometry between page loads",
|
|
10543
|
+
"stop rebuilding the same generated stage on every page load",
|
|
10544
|
+
"cache painted sky pixels or baked terrain heights between runs",
|
|
10545
|
+
"keep seeded placement work the same every run without recomputing it",
|
|
10546
|
+
"make a slow boot fast without shipping a baked asset"
|
|
10547
|
+
],
|
|
10548
|
+
"aliases": [],
|
|
10549
|
+
"example": "const { pixels } = await ctx.assets.memo(\"sky\", () => ({ pixels: paintSky() }));",
|
|
10550
|
+
"constraints": [
|
|
10551
|
+
"The value is named typed arrays; a map of names to typed arrays is what is stored.",
|
|
10552
|
+
"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.",
|
|
10553
|
+
"A new build of the game regenerates: the key alone does not pin a value across a rebuild.",
|
|
10554
|
+
"A game that drives a loader outside `defineGame` may call it whenever it likes; the reveal is not waited on."
|
|
10555
|
+
],
|
|
10556
|
+
"overrides": ["TN_ASSET_MEMO reports why a run rebuilt instead of reading the store"],
|
|
10557
|
+
"supersedes": []
|
|
10558
|
+
},
|
|
9621
10559
|
{
|
|
9622
10560
|
"symbol": "createStormAudio",
|
|
9623
10561
|
"package": "template:rain",
|
|
@@ -9843,6 +10781,76 @@
|
|
|
9843
10781
|
"supersedes": [],
|
|
9844
10782
|
"aliases": []
|
|
9845
10783
|
},
|
|
10784
|
+
{
|
|
10785
|
+
"symbol": "ctx.after",
|
|
10786
|
+
"package": "@threenative/core",
|
|
10787
|
+
"importPath": "src/scene.ts",
|
|
10788
|
+
"kind": "function",
|
|
10789
|
+
"signature": "ctx.after(delay: number, callback: () => void): ScheduleHandle",
|
|
10790
|
+
"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.",
|
|
10791
|
+
"situations": [
|
|
10792
|
+
"run a callback after a delay",
|
|
10793
|
+
"schedule a one-shot timer that pauses with the game",
|
|
10794
|
+
"do something a moment later without setTimeout",
|
|
10795
|
+
"cancel a pending delayed action when a scene exits"
|
|
10796
|
+
],
|
|
10797
|
+
"aliases": [],
|
|
10798
|
+
"example": "const spawn = ctx.after(0.4, () => ctx.add(makeWave()));\nspawn(); // cancels",
|
|
10799
|
+
"constraints": [
|
|
10800
|
+
"The delay is game seconds: a paused game does not age it, and a slow frame does not skip it.",
|
|
10801
|
+
"`setTimeout` keeps running while the game is paused and after the scene is gone; this does not.",
|
|
10802
|
+
"Call the returned handle to cancel: a pending callback holds its scene's closure alive."
|
|
10803
|
+
],
|
|
10804
|
+
"overrides": [],
|
|
10805
|
+
"supersedes": []
|
|
10806
|
+
},
|
|
10807
|
+
{
|
|
10808
|
+
"symbol": "ctx.beforeRender",
|
|
10809
|
+
"package": "@threenative/core",
|
|
10810
|
+
"importPath": "src/scene.ts",
|
|
10811
|
+
"kind": "function",
|
|
10812
|
+
"signature": "ctx.beforeRender(callback: () => void): () => void",
|
|
10813
|
+
"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.",
|
|
10814
|
+
"situations": [
|
|
10815
|
+
"run a callback just before the frame renders",
|
|
10816
|
+
"update a camera or a uniform after physics and before the draw",
|
|
10817
|
+
"change a transform in the same frame it is seen",
|
|
10818
|
+
"run per-render work that must not run on a loader-only frame"
|
|
10819
|
+
],
|
|
10820
|
+
"aliases": [],
|
|
10821
|
+
"example": "const stop = ctx.beforeRender(() => (material.uniforms.time.value = clock.elapsed));\n// later: stop();",
|
|
10822
|
+
"constraints": [
|
|
10823
|
+
"A held, loader-only frame has no world draw and dispatches nothing.",
|
|
10824
|
+
"Runs after every fixed update in the frame, so a value it writes is the one drawn.",
|
|
10825
|
+
"Returns an unregister function; call it when the object that needed it is gone."
|
|
10826
|
+
],
|
|
10827
|
+
"overrides": [],
|
|
10828
|
+
"supersedes": []
|
|
10829
|
+
},
|
|
10830
|
+
{
|
|
10831
|
+
"symbol": "ctx.startup.progress",
|
|
10832
|
+
"package": "@threenative/core",
|
|
10833
|
+
"importPath": "src/scene.ts",
|
|
10834
|
+
"kind": "function",
|
|
10835
|
+
"signature": "ctx.startup.progress: number",
|
|
10836
|
+
"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.",
|
|
10837
|
+
"situations": [
|
|
10838
|
+
"boot progress bar",
|
|
10839
|
+
"show how much of the start scene has loaded",
|
|
10840
|
+
"loading screen percentage",
|
|
10841
|
+
"a progress bar that never goes backwards",
|
|
10842
|
+
"report startup progress while assets stream in"
|
|
10843
|
+
],
|
|
10844
|
+
"aliases": [],
|
|
10845
|
+
"example": "const width = `${Math.round(ctx.startup.progress * 100)}%`; // a cover the game draws on ctx.canvasLayer",
|
|
10846
|
+
"constraints": [
|
|
10847
|
+
"Never decreases, even when the loader is asked for more work mid-boot.",
|
|
10848
|
+
"Reaches 1 only after the first world render has been presented, not when the last byte arrived.",
|
|
10849
|
+
"A loading view the engine drew for you already reads it; this is for a cover the game draws itself."
|
|
10850
|
+
],
|
|
10851
|
+
"overrides": [],
|
|
10852
|
+
"supersedes": []
|
|
10853
|
+
},
|
|
9846
10854
|
{
|
|
9847
10855
|
"symbol": "bloom",
|
|
9848
10856
|
"package": "three",
|
|
@@ -10155,14 +11163,9 @@
|
|
|
10155
11163
|
"situations": ["authoritative replication", "client prediction"]
|
|
10156
11164
|
},
|
|
10157
11165
|
{
|
|
10158
|
-
"guidance": "The framework owns no vegetation system
|
|
11166
|
+
"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-vegetation, 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].",
|
|
10159
11167
|
"id": "procedural-vegetation",
|
|
10160
|
-
"situations": [
|
|
10161
|
-
"procedural trees",
|
|
10162
|
-
"swaying trees",
|
|
10163
|
-
"tree foliage wind sway",
|
|
10164
|
-
"grow procedural tree meshes"
|
|
10165
|
-
]
|
|
11168
|
+
"situations": ["swaying trees", "tree foliage wind sway"]
|
|
10166
11169
|
},
|
|
10167
11170
|
{
|
|
10168
11171
|
"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.",
|