@threenative/core 0.3.12 → 0.3.13
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 +746 -32
- 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-4SRAQFTU.js} +1 -1
- package/dist/{chunk-GMHATRPW.js → chunk-DIPIJICH.js} +1590 -375
- package/dist/{chunk-OKXUCASC.js → chunk-EEABDLUC.js} +3 -4
- package/dist/{chunk-5O73CDMR.js → chunk-EFWZWLPY.js} +62 -16
- package/dist/{chunk-N5LRP4BR.js → chunk-GYUZJQ7U.js} +63 -3
- package/dist/{chunk-VAZM36TV.js → chunk-H4J6IAJE.js} +17 -10
- package/dist/{chunk-2Z44XSI2.js → chunk-SV4QVUTQ.js} +3 -7
- package/dist/{chunk-DBELTTTM.js → chunk-U4YHUKKL.js} +1 -1
- package/dist/chunk-VP43GIWW.js +18 -0
- 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 +289 -1034
- package/dist/index.js +3096 -1305
- 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-BYqKGAwo.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 +269 -15
- package/dist/world.js +1372 -628
- package/mcp/animation-server.mjs +1 -1
- package/mcp/engine-server.mjs +105 -7
- package/mcp/servers.mjs +4 -4
- package/package.json +10 -6
- 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/compute-driven.ts +1 -1
- package/src/config.ts +8 -0
- package/src/debug.ts +103 -22
- package/src/dev-global.ts +54 -0
- package/src/engine-hooks.ts +37 -0
- package/src/frame-budget.ts +19 -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 +13 -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/hot.ts +4 -7
- package/src/index.ts +115 -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/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/virtual-shadow-partial.ts +13 -0
- package/src/render/virtual-shadow.ts +18 -16
- package/src/render/world-impostor-surface.ts +109 -6
- package/src/render/world-impostor.ts +5 -2
- package/src/render-camera-cull.ts +98 -3
- 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 +52 -28
- package/src/resolution-scaler.ts +3 -2
- package/src/scene-entry-inspectors.ts +61 -0
- package/src/snow-field.ts +1 -0
- package/src/startup-offscreen-bytes.ts +78 -0
- package/src/static-transform.ts +25 -19
- package/src/streamed-textures.ts +112 -0
- package/src/streaming.ts +68 -4
- package/src/texture-streaming.ts +331 -0
- package/src/version.ts +1 -1
- package/src/worker.ts +12 -2
- package/src/world-bundle-safety.ts +55 -10
- package/src/world-cell-batches.ts +162 -200
- package/src/world-cell-chunks.ts +3 -7
- package/src/world-cell-impostors.ts +20 -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 +13 -17
- package/src/world-cell-render-main-cull.ts +73 -17
- package/src/world-cell-render-util.ts +17 -4
- 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 +22 -5
- 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 +282 -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.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,7 +1479,9 @@
|
|
|
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"
|
|
@@ -1513,6 +1556,22 @@
|
|
|
1513
1556
|
"supersedes": [],
|
|
1514
1557
|
"symbol": "describeSceneWarning"
|
|
1515
1558
|
},
|
|
1559
|
+
{
|
|
1560
|
+
"aliases": [],
|
|
1561
|
+
"constraints": [
|
|
1562
|
+
"every dev surface publishes under this key; the worker's typed mirror tuple names it too"
|
|
1563
|
+
],
|
|
1564
|
+
"example": "import { DEV_GLOBAL_KEY, devGlobal } from \"@threenative/core\";\nconst tools = devGlobal(globalThis);",
|
|
1565
|
+
"importPath": "@threenative/core",
|
|
1566
|
+
"kind": "function",
|
|
1567
|
+
"overrides": [],
|
|
1568
|
+
"package": "@threenative/core",
|
|
1569
|
+
"signature": "export function devGlobal(scope: unknown): DevGlobal | undefined { … }",
|
|
1570
|
+
"situations": ["read or extend the `__THREENATIVE__` object a dev launch publishes"],
|
|
1571
|
+
"summary": "The one name every dev surface publishes under, and the reader/writer for it.",
|
|
1572
|
+
"supersedes": [],
|
|
1573
|
+
"symbol": "devGlobal"
|
|
1574
|
+
},
|
|
1516
1575
|
{
|
|
1517
1576
|
"aliases": [],
|
|
1518
1577
|
"constraints": ["pass a non-zero direction; coefficients and radii come from the game"],
|
|
@@ -1697,6 +1756,23 @@
|
|
|
1697
1756
|
"supersedes": [],
|
|
1698
1757
|
"symbol": "exposureFromEv100"
|
|
1699
1758
|
},
|
|
1759
|
+
{
|
|
1760
|
+
"aliases": [],
|
|
1761
|
+
"constraints": ["reads the response once; call `.json()` or `.arrayBuffer()` on the result"],
|
|
1762
|
+
"example": "const heights = new Float32Array(await (await fetchAsset(ctx.assets, \"world/forest.bin\")).arrayBuffer());",
|
|
1763
|
+
"importPath": "@threenative/core",
|
|
1764
|
+
"kind": "function",
|
|
1765
|
+
"overrides": [],
|
|
1766
|
+
"package": "@threenative/core",
|
|
1767
|
+
"signature": "export async function fetchAsset( assets: Pick<IAssetLoader, \"resolve\">, path: string, ): Promise<Response> { … }",
|
|
1768
|
+
"situations": [
|
|
1769
|
+
"load a baked JSON or binary file (a heightmap, a placement buffer, a data table) that the loader has no typed method for",
|
|
1770
|
+
"a data file loads in dev but 404s in the built game"
|
|
1771
|
+
],
|
|
1772
|
+
"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.",
|
|
1773
|
+
"supersedes": [],
|
|
1774
|
+
"symbol": "fetchAsset"
|
|
1775
|
+
},
|
|
1700
1776
|
{
|
|
1701
1777
|
"aliases": [],
|
|
1702
1778
|
"constraints": [
|
|
@@ -1936,7 +2012,7 @@
|
|
|
1936
2012
|
"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
2013
|
"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
2014
|
],
|
|
1939
|
-
"example": "if (isMobile()) showTouchControls();",
|
|
2015
|
+
"example": "if (isMobile()) showTouchControls();\nif (isConsole()) showPadPrompts(isPs4() ? \"dualshock\" : \"generic\");",
|
|
1940
2016
|
"importPath": "@threenative/core",
|
|
1941
2017
|
"kind": "function",
|
|
1942
2018
|
"overrides": [],
|
|
@@ -1945,7 +2021,8 @@
|
|
|
1945
2021
|
"situations": [
|
|
1946
2022
|
"branch a portable game on web or native",
|
|
1947
2023
|
"choose touch controls for a mobile device",
|
|
1948
|
-
"can I raytrace on native"
|
|
2024
|
+
"can I raytrace on native",
|
|
2025
|
+
"show gamepad prompts and bind pad buttons on a games console such as the PS4"
|
|
1949
2026
|
],
|
|
1950
2027
|
"summary": "Read the host platform without reaching for browser globals.",
|
|
1951
2028
|
"supersedes": [],
|
|
@@ -2098,21 +2175,28 @@
|
|
|
2098
2175
|
"symbol": "GroundSnap"
|
|
2099
2176
|
},
|
|
2100
2177
|
{
|
|
2101
|
-
"aliases": [],
|
|
2178
|
+
"aliases": ["gamepad", "controller", "joypad", "xbox", "8bitdo", "steam deck"],
|
|
2102
2179
|
"constraints": [
|
|
2103
2180
|
"`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"
|
|
2181
|
+
"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",
|
|
2182
|
+
"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",
|
|
2183
|
+
"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",
|
|
2184
|
+
"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
2185
|
],
|
|
2106
2186
|
"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
2187
|
"importPath": "@threenative/core",
|
|
2108
2188
|
"kind": "class",
|
|
2109
|
-
"overrides": [],
|
|
2189
|
+
"overrides": ["defineGame({ gamepadDeadZone: 0 }) publishes raw axes"],
|
|
2110
2190
|
"package": "@threenative/core",
|
|
2111
2191
|
"signature": "export class InputMap { … }",
|
|
2112
2192
|
"situations": [
|
|
2113
2193
|
"map WASD keys to a movement axis instead of reading the held key set in the update loop",
|
|
2114
2194
|
"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"
|
|
2195
|
+
"read mouse look, wheel zoom or a two-finger pinch as an axis the frame loop already ticks",
|
|
2196
|
+
"support an Xbox pad, a generic XInput clone, an 8BitDo or a Steam Deck controller",
|
|
2197
|
+
"the character drifts while the controller stick is idle",
|
|
2198
|
+
"the controller does nothing in Firefox on Linux",
|
|
2199
|
+
"a second controller or a wheel steals the input from the pad the player holds"
|
|
2116
2200
|
],
|
|
2117
2201
|
"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
2202
|
"supersedes": [],
|
|
@@ -2215,7 +2299,31 @@
|
|
|
2215
2299
|
"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
2300
|
"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
2301
|
],
|
|
2218
|
-
"example": "if (isMobile()) showTouchControls();",
|
|
2302
|
+
"example": "if (isMobile()) showTouchControls();\nif (isConsole()) showPadPrompts(isPs4() ? \"dualshock\" : \"generic\");",
|
|
2303
|
+
"importPath": "@threenative/core",
|
|
2304
|
+
"kind": "function",
|
|
2305
|
+
"overrides": [],
|
|
2306
|
+
"package": "@threenative/core",
|
|
2307
|
+
"signature": "export function isConsole(): boolean { … }",
|
|
2308
|
+
"situations": [
|
|
2309
|
+
"branch a portable game on web or native",
|
|
2310
|
+
"choose touch controls for a mobile device",
|
|
2311
|
+
"can I raytrace on native",
|
|
2312
|
+
"show gamepad prompts and bind pad buttons on a games console such as the PS4"
|
|
2313
|
+
],
|
|
2314
|
+
"summary": "Read the host platform without reaching for browser globals.",
|
|
2315
|
+
"supersedes": [],
|
|
2316
|
+
"symbol": "isConsole"
|
|
2317
|
+
},
|
|
2318
|
+
{
|
|
2319
|
+
"aliases": [],
|
|
2320
|
+
"constraints": [
|
|
2321
|
+
"only use the returned platform facts; native globals are host-owned",
|
|
2322
|
+
"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",
|
|
2323
|
+
"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",
|
|
2324
|
+
"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"
|
|
2325
|
+
],
|
|
2326
|
+
"example": "if (isMobile()) showTouchControls();\nif (isConsole()) showPadPrompts(isPs4() ? \"dualshock\" : \"generic\");",
|
|
2219
2327
|
"importPath": "@threenative/core",
|
|
2220
2328
|
"kind": "function",
|
|
2221
2329
|
"overrides": [],
|
|
@@ -2224,7 +2332,8 @@
|
|
|
2224
2332
|
"situations": [
|
|
2225
2333
|
"branch a portable game on web or native",
|
|
2226
2334
|
"choose touch controls for a mobile device",
|
|
2227
|
-
"can I raytrace on native"
|
|
2335
|
+
"can I raytrace on native",
|
|
2336
|
+
"show gamepad prompts and bind pad buttons on a games console such as the PS4"
|
|
2228
2337
|
],
|
|
2229
2338
|
"summary": "Read the host platform without reaching for browser globals.",
|
|
2230
2339
|
"supersedes": [],
|
|
@@ -2238,7 +2347,7 @@
|
|
|
2238
2347
|
"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
2348
|
"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
2349
|
],
|
|
2241
|
-
"example": "if (isMobile()) showTouchControls();",
|
|
2350
|
+
"example": "if (isMobile()) showTouchControls();\nif (isConsole()) showPadPrompts(isPs4() ? \"dualshock\" : \"generic\");",
|
|
2242
2351
|
"importPath": "@threenative/core",
|
|
2243
2352
|
"kind": "function",
|
|
2244
2353
|
"overrides": [],
|
|
@@ -2247,12 +2356,37 @@
|
|
|
2247
2356
|
"situations": [
|
|
2248
2357
|
"branch a portable game on web or native",
|
|
2249
2358
|
"choose touch controls for a mobile device",
|
|
2250
|
-
"can I raytrace on native"
|
|
2359
|
+
"can I raytrace on native",
|
|
2360
|
+
"show gamepad prompts and bind pad buttons on a games console such as the PS4"
|
|
2251
2361
|
],
|
|
2252
2362
|
"summary": "Read the host platform without reaching for browser globals.",
|
|
2253
2363
|
"supersedes": [],
|
|
2254
2364
|
"symbol": "isNative"
|
|
2255
2365
|
},
|
|
2366
|
+
{
|
|
2367
|
+
"aliases": [],
|
|
2368
|
+
"constraints": [
|
|
2369
|
+
"only use the returned platform facts; native globals are host-owned",
|
|
2370
|
+
"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",
|
|
2371
|
+
"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",
|
|
2372
|
+
"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"
|
|
2373
|
+
],
|
|
2374
|
+
"example": "if (isMobile()) showTouchControls();\nif (isConsole()) showPadPrompts(isPs4() ? \"dualshock\" : \"generic\");",
|
|
2375
|
+
"importPath": "@threenative/core",
|
|
2376
|
+
"kind": "function",
|
|
2377
|
+
"overrides": [],
|
|
2378
|
+
"package": "@threenative/core",
|
|
2379
|
+
"signature": "export function isPs4(): boolean { … }",
|
|
2380
|
+
"situations": [
|
|
2381
|
+
"branch a portable game on web or native",
|
|
2382
|
+
"choose touch controls for a mobile device",
|
|
2383
|
+
"can I raytrace on native",
|
|
2384
|
+
"show gamepad prompts and bind pad buttons on a games console such as the PS4"
|
|
2385
|
+
],
|
|
2386
|
+
"summary": "Read the host platform without reaching for browser globals.",
|
|
2387
|
+
"supersedes": [],
|
|
2388
|
+
"symbol": "isPs4"
|
|
2389
|
+
},
|
|
2256
2390
|
{
|
|
2257
2391
|
"aliases": [],
|
|
2258
2392
|
"constraints": [
|
|
@@ -2274,6 +2408,27 @@
|
|
|
2274
2408
|
"supersedes": [],
|
|
2275
2409
|
"symbol": "isStatic"
|
|
2276
2410
|
},
|
|
2411
|
+
{
|
|
2412
|
+
"aliases": [],
|
|
2413
|
+
"constraints": [
|
|
2414
|
+
"`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"
|
|
2415
|
+
],
|
|
2416
|
+
"example": "const coarse = isStreamedGeometry(mesh.geometry);",
|
|
2417
|
+
"importPath": "@threenative/core",
|
|
2418
|
+
"kind": "function",
|
|
2419
|
+
"overrides": [],
|
|
2420
|
+
"package": "@threenative/core",
|
|
2421
|
+
"signature": "export function isStreamedGeometry(geometry: BufferGeometry): boolean { … }",
|
|
2422
|
+
"situations": [
|
|
2423
|
+
"collider or navmesh built from a model is coarser than what is drawn",
|
|
2424
|
+
"wait for the full model before copying its vertices",
|
|
2425
|
+
"whole model before collision",
|
|
2426
|
+
"TN_COLLIDER_COARSE"
|
|
2427
|
+
],
|
|
2428
|
+
"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.",
|
|
2429
|
+
"supersedes": [],
|
|
2430
|
+
"symbol": "isStreamedGeometry"
|
|
2431
|
+
},
|
|
2277
2432
|
{
|
|
2278
2433
|
"aliases": [],
|
|
2279
2434
|
"constraints": [
|
|
@@ -2282,7 +2437,7 @@
|
|
|
2282
2437
|
"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
2438
|
"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
2439
|
],
|
|
2285
|
-
"example": "if (isMobile()) showTouchControls();",
|
|
2440
|
+
"example": "if (isMobile()) showTouchControls();\nif (isConsole()) showPadPrompts(isPs4() ? \"dualshock\" : \"generic\");",
|
|
2286
2441
|
"importPath": "@threenative/core",
|
|
2287
2442
|
"kind": "function",
|
|
2288
2443
|
"overrides": [],
|
|
@@ -2291,7 +2446,8 @@
|
|
|
2291
2446
|
"situations": [
|
|
2292
2447
|
"branch a portable game on web or native",
|
|
2293
2448
|
"choose touch controls for a mobile device",
|
|
2294
|
-
"can I raytrace on native"
|
|
2449
|
+
"can I raytrace on native",
|
|
2450
|
+
"show gamepad prompts and bind pad buttons on a games console such as the PS4"
|
|
2295
2451
|
],
|
|
2296
2452
|
"summary": "Read the host platform without reaching for browser globals.",
|
|
2297
2453
|
"supersedes": [],
|
|
@@ -2305,7 +2461,7 @@
|
|
|
2305
2461
|
"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
2462
|
"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
2463
|
],
|
|
2308
|
-
"example": "if (isMobile()) showTouchControls();",
|
|
2464
|
+
"example": "if (isMobile()) showTouchControls();\nif (isConsole()) showPadPrompts(isPs4() ? \"dualshock\" : \"generic\");",
|
|
2309
2465
|
"importPath": "@threenative/core",
|
|
2310
2466
|
"kind": "function",
|
|
2311
2467
|
"overrides": [],
|
|
@@ -2314,7 +2470,8 @@
|
|
|
2314
2470
|
"situations": [
|
|
2315
2471
|
"branch a portable game on web or native",
|
|
2316
2472
|
"choose touch controls for a mobile device",
|
|
2317
|
-
"can I raytrace on native"
|
|
2473
|
+
"can I raytrace on native",
|
|
2474
|
+
"show gamepad prompts and bind pad buttons on a games console such as the PS4"
|
|
2318
2475
|
],
|
|
2319
2476
|
"summary": "Read the host platform without reaching for browser globals.",
|
|
2320
2477
|
"supersedes": [],
|
|
@@ -2702,6 +2859,22 @@
|
|
|
2702
2859
|
"supersedes": [],
|
|
2703
2860
|
"symbol": "ProbeVolume"
|
|
2704
2861
|
},
|
|
2862
|
+
{
|
|
2863
|
+
"aliases": [],
|
|
2864
|
+
"constraints": [
|
|
2865
|
+
"every dev surface publishes under this key; the worker's typed mirror tuple names it too"
|
|
2866
|
+
],
|
|
2867
|
+
"example": "import { DEV_GLOBAL_KEY, devGlobal } from \"@threenative/core\";\nconst tools = devGlobal(globalThis);",
|
|
2868
|
+
"importPath": "@threenative/core",
|
|
2869
|
+
"kind": "function",
|
|
2870
|
+
"overrides": [],
|
|
2871
|
+
"package": "@threenative/core",
|
|
2872
|
+
"signature": "export function publishDevGlobal(name: string, value: unknown, scope: unknown): void { … }",
|
|
2873
|
+
"situations": ["read or extend the `__THREENATIVE__` object a dev launch publishes"],
|
|
2874
|
+
"summary": "The one name every dev surface publishes under, and the reader/writer for it.",
|
|
2875
|
+
"supersedes": [],
|
|
2876
|
+
"symbol": "publishDevGlobal"
|
|
2877
|
+
},
|
|
2705
2878
|
{
|
|
2706
2879
|
"aliases": [],
|
|
2707
2880
|
"constraints": ["an unknown tier name throws with the names it expected"],
|
|
@@ -2721,6 +2894,30 @@
|
|
|
2721
2894
|
"supersedes": [],
|
|
2722
2895
|
"symbol": "qualityPreset"
|
|
2723
2896
|
},
|
|
2897
|
+
{
|
|
2898
|
+
"aliases": ["lumen radiance cache", "radiance cache", "irradiance field", "dynamic probe gi"],
|
|
2899
|
+
"constraints": [
|
|
2900
|
+
"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",
|
|
2901
|
+
"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",
|
|
2902
|
+
"a one-sided material is not seen from behind, as a cube capture would not draw it"
|
|
2903
|
+
],
|
|
2904
|
+
"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);",
|
|
2905
|
+
"importPath": "@threenative/core",
|
|
2906
|
+
"kind": "class",
|
|
2907
|
+
"overrides": [
|
|
2908
|
+
"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"
|
|
2909
|
+
],
|
|
2910
|
+
"package": "@threenative/core",
|
|
2911
|
+
"signature": "export class RadianceCache extends ProbeVolume { … }",
|
|
2912
|
+
"situations": [
|
|
2913
|
+
"light follows a lamp that switches on and off in a room",
|
|
2914
|
+
"bounce light that updates when the sun moves, with no baked lightmap",
|
|
2915
|
+
"global illumination that refreshes fast enough to read as dynamic"
|
|
2916
|
+
],
|
|
2917
|
+
"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.",
|
|
2918
|
+
"supersedes": [],
|
|
2919
|
+
"symbol": "RadianceCache"
|
|
2920
|
+
},
|
|
2724
2921
|
{
|
|
2725
2922
|
"aliases": [],
|
|
2726
2923
|
"constraints": ["non-marker lines and malformed markers return `undefined`"],
|
|
@@ -4323,6 +4520,185 @@
|
|
|
4323
4520
|
"supersedes": [],
|
|
4324
4521
|
"symbol": "View"
|
|
4325
4522
|
},
|
|
4523
|
+
{
|
|
4524
|
+
"aliases": [],
|
|
4525
|
+
"constraints": [
|
|
4526
|
+
"a sample whose source texture or intensity moved is dropped, so a stale one never reaches a material"
|
|
4527
|
+
],
|
|
4528
|
+
"example": "const hit = cachedEnvironmentSample(renderer, scene);",
|
|
4529
|
+
"importPath": "@threenative/core/render/environment",
|
|
4530
|
+
"kind": "function",
|
|
4531
|
+
"overrides": [],
|
|
4532
|
+
"package": "@threenative/core",
|
|
4533
|
+
"signature": "export function cachedEnvironmentSample( renderer: object, scene: Scene, ): IEnvironmentSample | undefined { … }",
|
|
4534
|
+
"situations": ["skip a second environment readback in the same frame"],
|
|
4535
|
+
"summary": "The sample this renderer took of `scene`'s environment, if it is still current.",
|
|
4536
|
+
"supersedes": [],
|
|
4537
|
+
"symbol": "cachedEnvironmentSample"
|
|
4538
|
+
},
|
|
4539
|
+
{
|
|
4540
|
+
"aliases": [],
|
|
4541
|
+
"constraints": [],
|
|
4542
|
+
"example": "cacheEnvironmentSample(renderer, scene, sample);",
|
|
4543
|
+
"importPath": "@threenative/core/render/environment",
|
|
4544
|
+
"kind": "function",
|
|
4545
|
+
"overrides": [],
|
|
4546
|
+
"package": "@threenative/core",
|
|
4547
|
+
"signature": "export function cacheEnvironmentSample( renderer: object, scene: Scene, sample: IEnvironmentSample, ): void { … }",
|
|
4548
|
+
"situations": ["reuse one environment readback across the materials of a scene"],
|
|
4549
|
+
"summary": "Remembers `sample` as this renderer's reading of `scene`'s environment.",
|
|
4550
|
+
"supersedes": [],
|
|
4551
|
+
"symbol": "cacheEnvironmentSample"
|
|
4552
|
+
},
|
|
4553
|
+
{
|
|
4554
|
+
"aliases": [],
|
|
4555
|
+
"constraints": [],
|
|
4556
|
+
"example": "const snapshot = captureEnvironmentSnapshot(scene);",
|
|
4557
|
+
"importPath": "@threenative/core/render/environment",
|
|
4558
|
+
"kind": "function",
|
|
4559
|
+
"overrides": [],
|
|
4560
|
+
"package": "@threenative/core",
|
|
4561
|
+
"signature": "export function captureEnvironmentSnapshot(scene: Scene): IEnvironmentSourceSnapshot { … }",
|
|
4562
|
+
"situations": ["reject an environment readback that belongs to a different sky"],
|
|
4563
|
+
"summary": "The provenance of a scene's environment: which texture, at which intensity, in which colour space.",
|
|
4564
|
+
"supersedes": [],
|
|
4565
|
+
"symbol": "captureEnvironmentSnapshot"
|
|
4566
|
+
},
|
|
4567
|
+
{
|
|
4568
|
+
"aliases": [],
|
|
4569
|
+
"constraints": [],
|
|
4570
|
+
"example": "if (environmentSnapshotCurrent(scene, snapshot)) draw(snapshot);",
|
|
4571
|
+
"importPath": "@threenative/core/render/environment",
|
|
4572
|
+
"kind": "function",
|
|
4573
|
+
"overrides": [],
|
|
4574
|
+
"package": "@threenative/core",
|
|
4575
|
+
"signature": "export function environmentSnapshotCurrent( scene: Scene, snapshot: IEnvironmentSourceSnapshot, ): boolean { … }",
|
|
4576
|
+
"situations": ["hold a material's fill light to the sky that is on screen now"],
|
|
4577
|
+
"summary": "Whether the scene's environment still matches the snapshot a sample was taken from.",
|
|
4578
|
+
"supersedes": [],
|
|
4579
|
+
"symbol": "environmentSnapshotCurrent"
|
|
4580
|
+
},
|
|
4581
|
+
{
|
|
4582
|
+
"aliases": [],
|
|
4583
|
+
"constraints": [],
|
|
4584
|
+
"example": "if (isWebGLFallbackRenderer(renderer)) skipMaterialLane();",
|
|
4585
|
+
"importPath": "@threenative/core/render/environment",
|
|
4586
|
+
"kind": "function",
|
|
4587
|
+
"overrides": [],
|
|
4588
|
+
"package": "@threenative/core",
|
|
4589
|
+
"signature": "export function isWebGLFallbackRenderer(renderer: unknown): boolean { … }",
|
|
4590
|
+
"situations": [
|
|
4591
|
+
"refuse a GPU-only lane on a WebGL fallback instead of drawing something wrong"
|
|
4592
|
+
],
|
|
4593
|
+
"summary": "Whether a `WebGPURenderer` wrapper is running three's WebGL backend behind it.",
|
|
4594
|
+
"supersedes": [],
|
|
4595
|
+
"symbol": "isWebGLFallbackRenderer"
|
|
4596
|
+
},
|
|
4597
|
+
{
|
|
4598
|
+
"aliases": [],
|
|
4599
|
+
"constraints": [
|
|
4600
|
+
"high tier, browser, hardware WebGPU, not mobile, not software, not a WebGL fallback"
|
|
4601
|
+
],
|
|
4602
|
+
"example": "if (materialLightingEnabled(\"high\", env)) lightMaterials();",
|
|
4603
|
+
"importPath": "@threenative/core/render/environment",
|
|
4604
|
+
"kind": "function",
|
|
4605
|
+
"overrides": [],
|
|
4606
|
+
"package": "@threenative/core",
|
|
4607
|
+
"signature": "export function materialLightingEnabled( tier: QualityTier, environment: IMaterialLightingEnvironment, ): boolean { … }",
|
|
4608
|
+
"situations": ["decide whether this renderer is the admitted material lane"],
|
|
4609
|
+
"summary": "Whether `tier` may run the material-lighting lane in `environment`.",
|
|
4610
|
+
"supersedes": [],
|
|
4611
|
+
"symbol": "materialLightingEnabled"
|
|
4612
|
+
},
|
|
4613
|
+
{
|
|
4614
|
+
"aliases": [],
|
|
4615
|
+
"constraints": [],
|
|
4616
|
+
"example": "const m = measureEnvironment(scene, 2048);",
|
|
4617
|
+
"importPath": "@threenative/core/render/environment",
|
|
4618
|
+
"kind": "function",
|
|
4619
|
+
"overrides": [],
|
|
4620
|
+
"package": "@threenative/core",
|
|
4621
|
+
"signature": "export function measureEnvironment(scene: Scene, maxSourceTexels: number): IEnvironmentMeasurement { … }",
|
|
4622
|
+
"situations": [
|
|
4623
|
+
"measure what a scene's environment actually contributes",
|
|
4624
|
+
"sample the environment on the GPU without stalling the frame",
|
|
4625
|
+
"keep an environment readback from reaching a frame it does not belong to"
|
|
4626
|
+
],
|
|
4627
|
+
"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).",
|
|
4628
|
+
"supersedes": [],
|
|
4629
|
+
"symbol": "measureEnvironment"
|
|
4630
|
+
},
|
|
4631
|
+
{
|
|
4632
|
+
"aliases": [],
|
|
4633
|
+
"constraints": [],
|
|
4634
|
+
"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});",
|
|
4635
|
+
"importPath": "@threenative/core/render/environment",
|
|
4636
|
+
"kind": "function",
|
|
4637
|
+
"overrides": [],
|
|
4638
|
+
"package": "@threenative/core",
|
|
4639
|
+
"signature": "export function reportEnvironmentContribution( scene: Scene, options: IContributionControls, measurement?: IEnvironmentMeasurement, ) { … }",
|
|
4640
|
+
"situations": [
|
|
4641
|
+
"measure what a scene's environment actually contributes",
|
|
4642
|
+
"sample the environment on the GPU without stalling the frame",
|
|
4643
|
+
"keep an environment readback from reaching a frame it does not belong to"
|
|
4644
|
+
],
|
|
4645
|
+
"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).",
|
|
4646
|
+
"supersedes": [],
|
|
4647
|
+
"symbol": "reportEnvironmentContribution"
|
|
4648
|
+
},
|
|
4649
|
+
{
|
|
4650
|
+
"aliases": [],
|
|
4651
|
+
"constraints": [
|
|
4652
|
+
"the sample must be the qualified 64x32 float RGBA readback; anything else is refused by name"
|
|
4653
|
+
],
|
|
4654
|
+
"example": "const m = sampledRadiance(readback, 1);",
|
|
4655
|
+
"importPath": "@threenative/core/render/environment",
|
|
4656
|
+
"kind": "function",
|
|
4657
|
+
"overrides": [],
|
|
4658
|
+
"package": "@threenative/core",
|
|
4659
|
+
"signature": "export function sampledRadiance(samples: unknown, intensity: number): IEnvironmentMeasurement { … }",
|
|
4660
|
+
"situations": [
|
|
4661
|
+
"turn an environment readback into the radiance a material's fill light needs",
|
|
4662
|
+
"know why an environment sample could not be measured"
|
|
4663
|
+
],
|
|
4664
|
+
"summary": "The mean radiance and colour of a bounded linear sample, or `unknown` with the reason.",
|
|
4665
|
+
"supersedes": [],
|
|
4666
|
+
"symbol": "sampledRadiance"
|
|
4667
|
+
},
|
|
4668
|
+
{
|
|
4669
|
+
"aliases": [],
|
|
4670
|
+
"constraints": [
|
|
4671
|
+
"off unless the renderer is the admitted high-tier WebGPU lane; every refusal is reported by name",
|
|
4672
|
+
"the readback is abandoned after the deadline and the frame keeps the previous answer"
|
|
4673
|
+
],
|
|
4674
|
+
"example": "const sample = await sampleEnvironment(renderer, scene, env);",
|
|
4675
|
+
"importPath": "@threenative/core/render/environment",
|
|
4676
|
+
"kind": "function",
|
|
4677
|
+
"overrides": [],
|
|
4678
|
+
"package": "@threenative/core",
|
|
4679
|
+
"signature": "export async function sampleEnvironment( renderer: unknown, scene: Scene, environment: IMaterialLightingEnvironment, ): Promise<IEnvironmentSample> { … }",
|
|
4680
|
+
"situations": [
|
|
4681
|
+
"measure what a scene's environment actually contributes without stalling the frame",
|
|
4682
|
+
"give a material's fill light the environment's own radiance"
|
|
4683
|
+
],
|
|
4684
|
+
"summary": "Measures and samples the scene's real environment on the GPU, bounded by a readback deadline.",
|
|
4685
|
+
"supersedes": [],
|
|
4686
|
+
"symbol": "sampleEnvironment"
|
|
4687
|
+
},
|
|
4688
|
+
{
|
|
4689
|
+
"aliases": [],
|
|
4690
|
+
"constraints": [],
|
|
4691
|
+
"example": "if (samplingSourceSupported(source)) sample(source);",
|
|
4692
|
+
"importPath": "@threenative/core/render/environment",
|
|
4693
|
+
"kind": "function",
|
|
4694
|
+
"overrides": [],
|
|
4695
|
+
"package": "@threenative/core",
|
|
4696
|
+
"signature": "export function samplingSourceSupported(source: NonNullable<Scene[\"environment\"]>): boolean { … }",
|
|
4697
|
+
"situations": ["know why an environment was not sampled on the GPU"],
|
|
4698
|
+
"summary": "Whether an environment texture's mapping and colour space are qualified for the bounded GPU sample.",
|
|
4699
|
+
"supersedes": [],
|
|
4700
|
+
"symbol": "samplingSourceSupported"
|
|
4701
|
+
},
|
|
4326
4702
|
{
|
|
4327
4703
|
"aliases": [],
|
|
4328
4704
|
"constraints": [
|
|
@@ -4790,6 +5166,25 @@
|
|
|
4790
5166
|
"supersedes": [],
|
|
4791
5167
|
"symbol": "startWorkerGame"
|
|
4792
5168
|
},
|
|
5169
|
+
{
|
|
5170
|
+
"aliases": [],
|
|
5171
|
+
"constraints": [
|
|
5172
|
+
"open a new budget each frame; a unit always finishes, so one unit can cross the limit"
|
|
5173
|
+
],
|
|
5174
|
+
"example": "tiles.follow(player.position, new AdmissionBudget(2, () => performance.now()));",
|
|
5175
|
+
"importPath": "@threenative/core/world",
|
|
5176
|
+
"kind": "class",
|
|
5177
|
+
"overrides": [],
|
|
5178
|
+
"package": "@threenative/core",
|
|
5179
|
+
"signature": "export class AdmissionBudget implements IAdmissionBudget { … }",
|
|
5180
|
+
"situations": [
|
|
5181
|
+
"streamed terrain tiles or cells hitch the frame that admits them",
|
|
5182
|
+
"cap how many milliseconds a frame spends building streamed content"
|
|
5183
|
+
],
|
|
5184
|
+
"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.",
|
|
5185
|
+
"supersedes": [],
|
|
5186
|
+
"symbol": "AdmissionBudget"
|
|
5187
|
+
},
|
|
4793
5188
|
{
|
|
4794
5189
|
"aliases": [],
|
|
4795
5190
|
"constraints": [
|
|
@@ -4842,6 +5237,24 @@
|
|
|
4842
5237
|
"supersedes": [],
|
|
4843
5238
|
"symbol": "bakedNoise"
|
|
4844
5239
|
},
|
|
5240
|
+
{
|
|
5241
|
+
"aliases": [],
|
|
5242
|
+
"constraints": [
|
|
5243
|
+
"throws `TN_STATIC_POSE_GROUND` where the ground does not answer; check `samples` before trusting `gap`"
|
|
5244
|
+
],
|
|
5245
|
+
"example": "const ring = baseRingGap(geometry, matrix, ground); if (ring.samples >= 4) matrix.elements[13] -= ring.gap + 0.5;",
|
|
5246
|
+
"importPath": "@threenative/core/world",
|
|
5247
|
+
"kind": "function",
|
|
5248
|
+
"overrides": [],
|
|
5249
|
+
"package": "@threenative/core",
|
|
5250
|
+
"signature": "export function baseRingGap( geometry: BufferGeometry, matrix: Matrix4, ground: StaticGroundQuery, options: { … }",
|
|
5251
|
+
"situations": [
|
|
5252
|
+
"a cliff or crag model rests on a buried stem while its wide base hangs over the downhill ground"
|
|
5253
|
+
],
|
|
5254
|
+
"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.",
|
|
5255
|
+
"supersedes": [],
|
|
5256
|
+
"symbol": "baseRingGap"
|
|
5257
|
+
},
|
|
4845
5258
|
{
|
|
4846
5259
|
"aliases": [],
|
|
4847
5260
|
"constraints": [
|
|
@@ -4858,6 +5271,22 @@
|
|
|
4858
5271
|
"supersedes": [],
|
|
4859
5272
|
"symbol": "cellPlacements"
|
|
4860
5273
|
},
|
|
5274
|
+
{
|
|
5275
|
+
"aliases": [],
|
|
5276
|
+
"constraints": [
|
|
5277
|
+
"the footprint is every vertex at the geometry's lowest local y; throws `TN_STATIC_POSE_GROUND` where the ground does not answer"
|
|
5278
|
+
],
|
|
5279
|
+
"example": "matrix.elements[13] -= footprintGap(geometry, matrix, ground, 0.08);",
|
|
5280
|
+
"importPath": "@threenative/core/world",
|
|
5281
|
+
"kind": "function",
|
|
5282
|
+
"overrides": [],
|
|
5283
|
+
"package": "@threenative/core",
|
|
5284
|
+
"signature": "export function footprintGap( geometry: BufferGeometry, matrix: Matrix4, ground: StaticGroundQuery, margin = 0, ): number { … }",
|
|
5285
|
+
"situations": ["a rock snapped to a slope shows a lip or a gap under its downhill side"],
|
|
5286
|
+
"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.",
|
|
5287
|
+
"supersedes": [],
|
|
5288
|
+
"symbol": "footprintGap"
|
|
5289
|
+
},
|
|
4861
5290
|
{
|
|
4862
5291
|
"aliases": [],
|
|
4863
5292
|
"constraints": [
|
|
@@ -4975,6 +5404,25 @@
|
|
|
4975
5404
|
"supersedes": [],
|
|
4976
5405
|
"symbol": "lakeReach"
|
|
4977
5406
|
},
|
|
5407
|
+
{
|
|
5408
|
+
"aliases": [],
|
|
5409
|
+
"constraints": [
|
|
5410
|
+
"the lake row and field come from the game's bake; the game's material shades the geometry"
|
|
5411
|
+
],
|
|
5412
|
+
"example": "const geometry = lakeSurfaceGeometry({ ...lake, margin: 1.12 }, field, { maxDepth: 1.6 });",
|
|
5413
|
+
"importPath": "@threenative/core/world",
|
|
5414
|
+
"kind": "function",
|
|
5415
|
+
"overrides": [],
|
|
5416
|
+
"package": "@threenative/core",
|
|
5417
|
+
"signature": "export function lakeSurfaceGeometry( lake: IWaterLake, field: Heightfield, options: ILakeSurfaceOptions = { … }",
|
|
5418
|
+
"situations": [
|
|
5419
|
+
"draw a lake's water surface from the baked level and seed",
|
|
5420
|
+
"a lake's drawn water and the swimmer's water disagree"
|
|
5421
|
+
],
|
|
5422
|
+
"summary": "A lake's water surface: a level disc out to `lakeReach`, the footprint `WaterBodies` floods, with a `metres` attribute (water depth over the ground). Only cells with water at a corner get triangles, so the surface does not hover over dry hillside and the shore follows the ground's contour. The rings pack towards the middle, so an irregular basin costs vertices where the camera sees them. Returns `undefined` when the basin holds no water at its level.",
|
|
5423
|
+
"supersedes": [],
|
|
5424
|
+
"symbol": "lakeSurfaceGeometry"
|
|
5425
|
+
},
|
|
4978
5426
|
{
|
|
4979
5427
|
"aliases": [],
|
|
4980
5428
|
"constraints": [
|
|
@@ -5011,6 +5459,22 @@
|
|
|
5011
5459
|
"supersedes": [],
|
|
5012
5460
|
"symbol": "loadWorldHeightmap"
|
|
5013
5461
|
},
|
|
5462
|
+
{
|
|
5463
|
+
"aliases": [],
|
|
5464
|
+
"constraints": [
|
|
5465
|
+
"a section's `material` can be `undefined` for a group naming a missing material slot; skip it"
|
|
5466
|
+
],
|
|
5467
|
+
"example": "for (const section of meshSections(mesh)) parts.push(sectionGeometry(mesh, box, section));",
|
|
5468
|
+
"importPath": "@threenative/core/world",
|
|
5469
|
+
"kind": "function",
|
|
5470
|
+
"overrides": [],
|
|
5471
|
+
"package": "@threenative/core",
|
|
5472
|
+
"signature": "export function meshSections(mesh: Mesh): IMeshSection[] { … }",
|
|
5473
|
+
"situations": ["scatter or instance an imported glTF model that has several materials"],
|
|
5474
|
+
"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.",
|
|
5475
|
+
"supersedes": [],
|
|
5476
|
+
"symbol": "meshSections"
|
|
5477
|
+
},
|
|
5014
5478
|
{
|
|
5015
5479
|
"aliases": [],
|
|
5016
5480
|
"constraints": [
|
|
@@ -5027,6 +5491,81 @@
|
|
|
5027
5491
|
"supersedes": [],
|
|
5028
5492
|
"symbol": "noiseVolume"
|
|
5029
5493
|
},
|
|
5494
|
+
{
|
|
5495
|
+
"aliases": [],
|
|
5496
|
+
"constraints": [
|
|
5497
|
+
"one bad normal recomputes them all; an intentionally hard-edged model loses its authored split normals only if one is bad"
|
|
5498
|
+
],
|
|
5499
|
+
"example": "geometry.scale(1.1, 1, 1.1); repairZeroNormals(geometry);",
|
|
5500
|
+
"importPath": "@threenative/core/world",
|
|
5501
|
+
"kind": "function",
|
|
5502
|
+
"overrides": [],
|
|
5503
|
+
"package": "@threenative/core",
|
|
5504
|
+
"signature": "export function repairZeroNormals(geometry: BufferGeometry): boolean { … }",
|
|
5505
|
+
"situations": ["an imported model draws black or unlit because it ships zero normals"],
|
|
5506
|
+
"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.",
|
|
5507
|
+
"supersedes": [],
|
|
5508
|
+
"symbol": "repairZeroNormals"
|
|
5509
|
+
},
|
|
5510
|
+
{
|
|
5511
|
+
"aliases": [],
|
|
5512
|
+
"constraints": [
|
|
5513
|
+
"stations, width and reach come from the game's bake; the game's material shades the geometry"
|
|
5514
|
+
],
|
|
5515
|
+
"example": "const geometry = riverRibbonGeometry(rivers, field, { maxDepth: 1.6 });",
|
|
5516
|
+
"importPath": "@threenative/core/world",
|
|
5517
|
+
"kind": "function",
|
|
5518
|
+
"overrides": [],
|
|
5519
|
+
"package": "@threenative/core",
|
|
5520
|
+
"signature": "export function riverRibbonGeometry( rivers: readonly { … }",
|
|
5521
|
+
"situations": [
|
|
5522
|
+
"draw a river's water surface from the baked stations",
|
|
5523
|
+
"a river's water stops in a straight edge, or a swimmer floats where no water is drawn",
|
|
5524
|
+
"share one river shape between the drawn water and the swimmer",
|
|
5525
|
+
"river water hangs over dry ground past the river's head or tail"
|
|
5526
|
+
],
|
|
5527
|
+
"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.",
|
|
5528
|
+
"supersedes": [],
|
|
5529
|
+
"symbol": "riverRibbonGeometry"
|
|
5530
|
+
},
|
|
5531
|
+
{
|
|
5532
|
+
"aliases": [],
|
|
5533
|
+
"constraints": [
|
|
5534
|
+
"`box` is the whole model's world bounds after any unit normalisation; call `mesh.updateWorldMatrix` first"
|
|
5535
|
+
],
|
|
5536
|
+
"example": "const box = new Box3().setFromObject(root); const geometry = sectionGeometry(mesh, box, section);",
|
|
5537
|
+
"importPath": "@threenative/core/world",
|
|
5538
|
+
"kind": "function",
|
|
5539
|
+
"overrides": [],
|
|
5540
|
+
"package": "@threenative/core",
|
|
5541
|
+
"signature": "export function sectionGeometry( mesh: Mesh, box: Box3, section: IMeshSection, options: { … }",
|
|
5542
|
+
"situations": [
|
|
5543
|
+
"the crown of an instanced tree floats off its trunk, or the parts of a model separate",
|
|
5544
|
+
"turn each part of an imported model into a geometry for an instanced prop batch"
|
|
5545
|
+
],
|
|
5546
|
+
"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.",
|
|
5547
|
+
"supersedes": [],
|
|
5548
|
+
"symbol": "sectionGeometry"
|
|
5549
|
+
},
|
|
5550
|
+
{
|
|
5551
|
+
"aliases": [],
|
|
5552
|
+
"constraints": [
|
|
5553
|
+
"heights are row-major, `resolution` by `resolution`, across `size` metres; measured once, never per frame"
|
|
5554
|
+
],
|
|
5555
|
+
"example": "const { distance, exposed } = shoreField(world.heights, world.resolution, world.size, world.waterLevel);",
|
|
5556
|
+
"importPath": "@threenative/core/world",
|
|
5557
|
+
"kind": "function",
|
|
5558
|
+
"overrides": [],
|
|
5559
|
+
"package": "@threenative/core",
|
|
5560
|
+
"signature": "export function shoreField( heights: ArrayLike<number>, resolution: number, size: number, level: number, options: IShoreFieldOptions = { … }",
|
|
5561
|
+
"situations": [
|
|
5562
|
+
"surf breaks only on water open to the sea, not in a sheltered lagoon",
|
|
5563
|
+
"distance from each water cell to the shore, for a foam or depth mask"
|
|
5564
|
+
],
|
|
5565
|
+
"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.",
|
|
5566
|
+
"supersedes": [],
|
|
5567
|
+
"symbol": "shoreField"
|
|
5568
|
+
},
|
|
5030
5569
|
{
|
|
5031
5570
|
"aliases": [],
|
|
5032
5571
|
"constraints": ["radius is metres; the footprint never grows with load, only deeper"],
|
|
@@ -5062,6 +5601,7 @@
|
|
|
5062
5601
|
"signature": "export class SnowField { … }",
|
|
5063
5602
|
"situations": [
|
|
5064
5603
|
"leave footprints, tracks and tyre ruts in snow that persist and fill in over time",
|
|
5604
|
+
"let a fresh snowfall slowly fill older tracks back in as the field recovers",
|
|
5065
5605
|
"let a pushed sphere carve a connected track and a dropped one settle into a crater",
|
|
5066
5606
|
"store snow deformation that rendered geometry and collision both read",
|
|
5067
5607
|
"reset a snowfield between rounds or change its depth at runtime",
|
|
@@ -5071,6 +5611,44 @@
|
|
|
5071
5611
|
"supersedes": [],
|
|
5072
5612
|
"symbol": "SnowField"
|
|
5073
5613
|
},
|
|
5614
|
+
{
|
|
5615
|
+
"aliases": [],
|
|
5616
|
+
"constraints": [
|
|
5617
|
+
"static geometry only; a skinned model uses `GroundSnap`; the sort is cached per geometry, so do not mutate its positions"
|
|
5618
|
+
],
|
|
5619
|
+
"example": "placed.position.y += ground - staticLowestY(geometry, matrix);",
|
|
5620
|
+
"importPath": "@threenative/core/world",
|
|
5621
|
+
"kind": "function",
|
|
5622
|
+
"overrides": [],
|
|
5623
|
+
"package": "@threenative/core",
|
|
5624
|
+
"signature": "export function staticLowestY(geometry: BufferGeometry, matrix: Matrix4): number { … }",
|
|
5625
|
+
"situations": [
|
|
5626
|
+
"stand a scattered rock, tree or crate on the ground by its lowest point, not its origin",
|
|
5627
|
+
"props hover or sink because their pivot is not at their base"
|
|
5628
|
+
],
|
|
5629
|
+
"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)`.",
|
|
5630
|
+
"supersedes": [],
|
|
5631
|
+
"symbol": "staticLowestY"
|
|
5632
|
+
},
|
|
5633
|
+
{
|
|
5634
|
+
"aliases": [],
|
|
5635
|
+
"constraints": [
|
|
5636
|
+
"the mesh is `field.toGeometry()` drawn upright under a uniform scale; read `matrixWorld` after it settles"
|
|
5637
|
+
],
|
|
5638
|
+
"example": "const ground = surfaceSampler(field, mesh.matrixWorld); const y = ground(x, z) ?? fallback;",
|
|
5639
|
+
"importPath": "@threenative/core/world",
|
|
5640
|
+
"kind": "function",
|
|
5641
|
+
"overrides": [],
|
|
5642
|
+
"package": "@threenative/core",
|
|
5643
|
+
"signature": "export function surfaceSampler(field: Heightfield, matrixWorld: Matrix4): SurfaceSampler { … }",
|
|
5644
|
+
"situations": [
|
|
5645
|
+
"stand props or a player on the drawn terrain triangles under a moved or scaled mesh",
|
|
5646
|
+
"props float or sink where the terrain mesh is drawn under a transform"
|
|
5647
|
+
],
|
|
5648
|
+
"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.",
|
|
5649
|
+
"supersedes": [],
|
|
5650
|
+
"symbol": "surfaceSampler"
|
|
5651
|
+
},
|
|
5074
5652
|
{
|
|
5075
5653
|
"aliases": ["stream terrain across chunks"],
|
|
5076
5654
|
"constraints": [
|
|
@@ -5089,7 +5667,9 @@
|
|
|
5089
5667
|
"situations": [
|
|
5090
5668
|
"stream terrain without cracks",
|
|
5091
5669
|
"keep generated terrain resident around a moving player",
|
|
5092
|
-
"put a generated terrain tile into a game-owned physics world"
|
|
5670
|
+
"put a generated terrain tile into a game-owned physics world",
|
|
5671
|
+
"a hole or a flicker where streamed terrain tiles are still building (`settledHalf`)",
|
|
5672
|
+
"split the ground between streamed tiles and a far mesh around the player (`settledHalf`)"
|
|
5093
5673
|
],
|
|
5094
5674
|
"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
5675
|
"supersedes": [],
|
|
@@ -5131,6 +5711,25 @@
|
|
|
5131
5711
|
"supersedes": [],
|
|
5132
5712
|
"symbol": "validateWorldPackage"
|
|
5133
5713
|
},
|
|
5714
|
+
{
|
|
5715
|
+
"aliases": [],
|
|
5716
|
+
"constraints": [
|
|
5717
|
+
"`ctx.beforeRender` runs on every world draw, also behind the curtain; join the promise to the curtain's hold"
|
|
5718
|
+
],
|
|
5719
|
+
"example": "const warm = warmUnculled(ctx, lake.mesh); ctx.startup.hold(\"lake\", () => warm);",
|
|
5720
|
+
"importPath": "@threenative/core/world",
|
|
5721
|
+
"kind": "function",
|
|
5722
|
+
"overrides": [],
|
|
5723
|
+
"package": "@threenative/core",
|
|
5724
|
+
"signature": "export function warmUnculled( ctx: { … }",
|
|
5725
|
+
"situations": [
|
|
5726
|
+
"the first frames after the loading curtain hitch on pipeline builds for content behind the camera",
|
|
5727
|
+
"streamed terrain or a lake compiles its pipelines after the reveal"
|
|
5728
|
+
],
|
|
5729
|
+
"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.",
|
|
5730
|
+
"supersedes": [],
|
|
5731
|
+
"symbol": "warmUnculled"
|
|
5732
|
+
},
|
|
5134
5733
|
{
|
|
5135
5734
|
"aliases": [],
|
|
5136
5735
|
"constraints": [
|
|
@@ -5542,7 +6141,10 @@
|
|
|
5542
6141
|
},
|
|
5543
6142
|
{
|
|
5544
6143
|
"aliases": [],
|
|
5545
|
-
"constraints": [
|
|
6144
|
+
"constraints": [
|
|
6145
|
+
"place rapier() before recast() in the plugin list",
|
|
6146
|
+
"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)"
|
|
6147
|
+
],
|
|
5546
6148
|
"example": "const game = defineGame({ plugins: [rapier()] });",
|
|
5547
6149
|
"importPath": "@threenative/physics",
|
|
5548
6150
|
"kind": "function",
|
|
@@ -6249,6 +6851,22 @@
|
|
|
6249
6851
|
"supersedes": [],
|
|
6250
6852
|
"symbol": "requestedPlaytestClockMode"
|
|
6251
6853
|
},
|
|
6854
|
+
{
|
|
6855
|
+
"aliases": [],
|
|
6856
|
+
"constraints": [
|
|
6857
|
+
"an unreadable load is a refusal, not a silence: an unmeasured machine cannot vouch"
|
|
6858
|
+
],
|
|
6859
|
+
"example": "import { absolutesVerdict, readHostLoad } from \"@threenative/playtest/runner\";\nconst load = readHostLoad();\nif (absolutesVerdict(load) === \"invalid-absolute\") ignoreAbsoluteMilliseconds();",
|
|
6860
|
+
"importPath": "@threenative/playtest/runner",
|
|
6861
|
+
"kind": "function",
|
|
6862
|
+
"overrides": [],
|
|
6863
|
+
"package": "@threenative/playtest",
|
|
6864
|
+
"signature": "export function absolutesVerdict(reading: IPerfHostLoadReading): IPerfHostLoad[\"absolutes\"] { … }",
|
|
6865
|
+
"situations": ["mark a benchmark run invalid because the machine was busy"],
|
|
6866
|
+
"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.",
|
|
6867
|
+
"supersedes": [],
|
|
6868
|
+
"symbol": "absolutesVerdict"
|
|
6869
|
+
},
|
|
6252
6870
|
{
|
|
6253
6871
|
"aliases": [],
|
|
6254
6872
|
"constraints": ["Android evidence must name its target and transport"],
|
|
@@ -6957,6 +7575,22 @@
|
|
|
6957
7575
|
"supersedes": [],
|
|
6958
7576
|
"symbol": "preflightDisplay"
|
|
6959
7577
|
},
|
|
7578
|
+
{
|
|
7579
|
+
"aliases": [],
|
|
7580
|
+
"constraints": [
|
|
7581
|
+
"an unreadable load is a refusal, not a silence: an unmeasured machine cannot vouch"
|
|
7582
|
+
],
|
|
7583
|
+
"example": "import { absolutesVerdict, readHostLoad } from \"@threenative/playtest/runner\";\nconst load = readHostLoad();\nif (absolutesVerdict(load) === \"invalid-absolute\") ignoreAbsoluteMilliseconds();",
|
|
7584
|
+
"importPath": "@threenative/playtest/runner",
|
|
7585
|
+
"kind": "function",
|
|
7586
|
+
"overrides": [],
|
|
7587
|
+
"package": "@threenative/playtest",
|
|
7588
|
+
"signature": "export function readHostLoad( source: IPerfHostLoadSource = { … }",
|
|
7589
|
+
"situations": ["mark a benchmark run invalid because the machine was busy"],
|
|
7590
|
+
"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.",
|
|
7591
|
+
"supersedes": [],
|
|
7592
|
+
"symbol": "readHostLoad"
|
|
7593
|
+
},
|
|
6960
7594
|
{
|
|
6961
7595
|
"aliases": [],
|
|
6962
7596
|
"constraints": [
|
|
@@ -7111,18 +7745,17 @@
|
|
|
7111
7745
|
},
|
|
7112
7746
|
{
|
|
7113
7747
|
"aliases": [],
|
|
7114
|
-
"constraints": [
|
|
7115
|
-
|
|
7748
|
+
"constraints": [
|
|
7749
|
+
"the driver must prepare the app bundle and the transport must answer the handshake"
|
|
7750
|
+
],
|
|
7751
|
+
"example": "await runDevicePlaytest(config, { name: \"android\", driver, transport, processName, mailboxPaths });",
|
|
7116
7752
|
"importPath": "@threenative/playtest/runner",
|
|
7117
7753
|
"kind": "function",
|
|
7118
7754
|
"overrides": [],
|
|
7119
7755
|
"package": "@threenative/playtest",
|
|
7120
7756
|
"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.",
|
|
7757
|
+
"situations": ["execute a scenario on a device target with a custom driver"],
|
|
7758
|
+
"summary": "Run a playtest on any device lane (Android, desktop or iOS) through its driver and transport.",
|
|
7126
7759
|
"supersedes": [],
|
|
7127
7760
|
"symbol": "runDevicePlaytest"
|
|
7128
7761
|
},
|
|
@@ -8138,8 +8771,15 @@
|
|
|
8138
8771
|
"package": "@threenative/terrain",
|
|
8139
8772
|
"requires": ["npm i -D @threenative/terrain"],
|
|
8140
8773
|
"signature": "export function bakeBiome(options: IBakeBiomeOptions): IBakedBiome { … }",
|
|
8141
|
-
"situations": [
|
|
8142
|
-
|
|
8774
|
+
"situations": [
|
|
8775
|
+
"bake one biome's world package from an evaluated recipe and a biome file",
|
|
8776
|
+
"generate terrain with mountains, hills, a river, a lake or an island from a request in words",
|
|
8777
|
+
"generate a landscape or open world map for a game",
|
|
8778
|
+
"procedural terrain for a level: a volcanic island, a mountain valley or a coast",
|
|
8779
|
+
"make a canyon, a volcano, a fjord, a desert, a tundra or a forest world",
|
|
8780
|
+
"cook the real terrain of a place on Earth from its latitude and longitude"
|
|
8781
|
+
],
|
|
8782
|
+
"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
8783
|
"supersedes": [],
|
|
8144
8784
|
"symbol": "bakeBiome"
|
|
8145
8785
|
},
|
|
@@ -8267,6 +8907,25 @@
|
|
|
8267
8907
|
"supersedes": [],
|
|
8268
8908
|
"symbol": "decodeHeightPNG"
|
|
8269
8909
|
},
|
|
8910
|
+
{
|
|
8911
|
+
"aliases": [],
|
|
8912
|
+
"constraints": [
|
|
8913
|
+
"throws `TN_PROP_BUCKET_INVALID` when the record buffer, the IDs and the runs disagree"
|
|
8914
|
+
],
|
|
8915
|
+
"example": "for (const record of decodePropBucket(bucket)) pose(record.key, record.position, record.quaternion);",
|
|
8916
|
+
"importPath": "@threenative/terrain",
|
|
8917
|
+
"kind": "function",
|
|
8918
|
+
"overrides": [],
|
|
8919
|
+
"package": "@threenative/terrain",
|
|
8920
|
+
"requires": ["npm i -D @threenative/terrain"],
|
|
8921
|
+
"signature": "export function decodePropBucket(bucket: IPropBucketPackage): IPropBucketRecord[] { … }",
|
|
8922
|
+
"situations": [
|
|
8923
|
+
"read a baked prop bucket back into placements to ground them on this machine's terrain"
|
|
8924
|
+
],
|
|
8925
|
+
"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.",
|
|
8926
|
+
"supersedes": [],
|
|
8927
|
+
"symbol": "decodePropBucket"
|
|
8928
|
+
},
|
|
8270
8929
|
{
|
|
8271
8930
|
"aliases": [],
|
|
8272
8931
|
"constraints": ["authoring data only; the game owns appearance, physics and rendering"],
|
|
@@ -8454,6 +9113,23 @@
|
|
|
8454
9113
|
"supersedes": [],
|
|
8455
9114
|
"symbol": "landformBackdrop"
|
|
8456
9115
|
},
|
|
9116
|
+
{
|
|
9117
|
+
"aliases": [],
|
|
9118
|
+
"constraints": ["the tile must cover the whole mountain; a summit crop lifts as a cone"],
|
|
9119
|
+
"example": "const lifted = liftMassif({ id: \"hill\", size: 400, resolution: 3, heights: [0, 0, 0, 0, 90, 0, 0, 0, 0] });",
|
|
9120
|
+
"importPath": "@threenative/terrain",
|
|
9121
|
+
"kind": "function",
|
|
9122
|
+
"overrides": [],
|
|
9123
|
+
"package": "@threenative/terrain",
|
|
9124
|
+
"requires": ["npm i -D @threenative/terrain"],
|
|
9125
|
+
"signature": "export function liftMassif(tile: IMassifTile): Float32Array { … }",
|
|
9126
|
+
"situations": [
|
|
9127
|
+
"measure how tall a surveyed mountain stands above the valley floor around it"
|
|
9128
|
+
],
|
|
9129
|
+
"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.",
|
|
9130
|
+
"supersedes": [],
|
|
9131
|
+
"symbol": "liftMassif"
|
|
9132
|
+
},
|
|
8457
9133
|
{
|
|
8458
9134
|
"aliases": [],
|
|
8459
9135
|
"constraints": ["authoring data only; the game owns appearance, physics and rendering"],
|
|
@@ -8503,6 +9179,27 @@
|
|
|
8503
9179
|
"supersedes": [],
|
|
8504
9180
|
"symbol": "orderedScatterRules"
|
|
8505
9181
|
},
|
|
9182
|
+
{
|
|
9183
|
+
"aliases": [],
|
|
9184
|
+
"constraints": [
|
|
9185
|
+
"the tile must be a whole mountain whose border is valley floor; erosion after it carves the survey"
|
|
9186
|
+
],
|
|
9187
|
+
"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] } });",
|
|
9188
|
+
"importPath": "@threenative/terrain",
|
|
9189
|
+
"kind": "function",
|
|
9190
|
+
"overrides": [
|
|
9191
|
+
"`at`, `bearing`, `distance`, `height`, `top`, `face` and `keepOut` on the same call"
|
|
9192
|
+
],
|
|
9193
|
+
"package": "@threenative/terrain",
|
|
9194
|
+
"requires": ["npm i -D @threenative/terrain"],
|
|
9195
|
+
"signature": "export function placeMassif( terrain: Terrain, options: IPlaceMassifOptions, ): { … }",
|
|
9196
|
+
"situations": [
|
|
9197
|
+
"put a real-shaped mountain behind a generated world, a different one per seed"
|
|
9198
|
+
],
|
|
9199
|
+
"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.",
|
|
9200
|
+
"supersedes": [],
|
|
9201
|
+
"symbol": "placeMassif"
|
|
9202
|
+
},
|
|
8506
9203
|
{
|
|
8507
9204
|
"aliases": [],
|
|
8508
9205
|
"constraints": [],
|
|
@@ -8780,6 +9477,23 @@
|
|
|
8780
9477
|
"supersedes": [],
|
|
8781
9478
|
"symbol": "createEditorSelection"
|
|
8782
9479
|
},
|
|
9480
|
+
{
|
|
9481
|
+
"aliases": [],
|
|
9482
|
+
"constraints": [],
|
|
9483
|
+
"example": "const box = createTweakBox({ title: \"Fog\", knobs: { density: { min: 0, max: 0.1, value: 0.02 } }, onChange: (name, value) => console.info(name, value) });",
|
|
9484
|
+
"importPath": "@threenative/terrain/editor",
|
|
9485
|
+
"kind": "function",
|
|
9486
|
+
"overrides": [],
|
|
9487
|
+
"package": "@threenative/terrain",
|
|
9488
|
+
"requires": ["npm i -D @threenative/terrain"],
|
|
9489
|
+
"signature": "export function createTweakBox<K extends string>(options: ITweakBoxOptions<K>): ITweakBox<K> { … }",
|
|
9490
|
+
"situations": [
|
|
9491
|
+
"tune look numbers by eye with live range bars and colour pickers while the game runs"
|
|
9492
|
+
],
|
|
9493
|
+
"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.",
|
|
9494
|
+
"supersedes": [],
|
|
9495
|
+
"symbol": "createTweakBox"
|
|
9496
|
+
},
|
|
8783
9497
|
{
|
|
8784
9498
|
"aliases": [],
|
|
8785
9499
|
"constraints": [
|