@threenative/core 0.3.5 → 0.3.8
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 +3 -5
- package/capabilities.json +739 -50
- package/dist/{assets-CqvE429w.d.ts → assets-YUbXa3-Y.d.ts} +101 -2
- package/dist/{canvas-layer-C1-5CviZ.d.ts → canvas-layer-vCtanIeB.d.ts} +1 -1
- package/dist/{game-Bj8G1wmD.d.ts → game-cb99J-YE.d.ts} +112 -31
- package/dist/hot.d.ts +4 -4
- package/dist/hot.js +23 -5
- package/dist/index.d.ts +1742 -29
- package/dist/index.js +22445 -12411
- package/dist/{model-lod-BDAUYgsS.d.ts → model-lod-CTpZ6imz.d.ts} +1 -1
- package/dist/net.js +39 -12
- package/dist/playtest.d.ts +4 -4
- package/dist/playtest.js +59 -10
- package/dist/react-css.js +23 -0
- package/dist/react.d.ts +2 -2
- package/dist/{renderer-9yEo9hPa.d.ts → renderer-rZm0hVqq.d.ts} +178 -5
- package/dist/ui-layer.d.ts +11 -2
- package/dist/ui-layer.js +76 -4
- package/dist/worker.d.ts +36 -0
- package/dist/worker.js +1088 -0
- package/dist/world.d.ts +11 -3
- package/dist/world.js +1117 -197
- package/mcp/animation-server.mjs +265 -0
- package/mcp/animation.mjs +22 -0
- package/mcp/call.mjs +105 -0
- package/mcp/devtools.mjs +5 -0
- package/mcp/engine-server.mjs +713 -37
- package/mcp/launch.mjs +3 -2
- package/mcp/servers.d.mts +2 -0
- package/mcp/servers.mjs +33 -8
- package/package.json +12 -8
- package/patches/three@0.185.1-prd269-upgrade.patch +308 -0
- package/patches/three@0.185.1.patch +481 -272
- package/src/animation-packet-state.ts +88 -0
- package/src/animation-pose-packet.ts +537 -0
- package/src/animation.ts +779 -31
- package/src/asset-cache.ts +719 -0
- package/src/assets.ts +521 -152
- package/src/audio.ts +29 -3
- package/src/auto-batch.ts +792 -0
- package/src/config.ts +2 -0
- package/src/frame-budget.ts +268 -2
- package/src/game.ts +544 -106
- package/src/grounding.ts +7 -6
- package/src/hot.ts +19 -5
- package/src/index.ts +381 -6
- package/src/input.ts +21 -2
- package/src/interpolation.ts +19 -1
- package/src/launch-diagnostics.ts +7 -2
- package/src/look/ao-multibounce.ts +29 -0
- package/src/look/ao-reach.ts +39 -0
- package/src/look/auto-exposure.ts +264 -0
- package/src/look/default-tone-mapping.ts +44 -0
- package/src/look/exposure-graph.ts +208 -0
- package/src/look/exposure-readback.ts +97 -0
- package/src/look/exposure-settings.ts +132 -0
- package/src/look/filmic-tone-mapping.ts +852 -0
- package/src/look/gi-registry.ts +55 -0
- package/src/look/local-exposure.ts +507 -0
- package/src/look/look-diagnostics.ts +24 -0
- package/src/look/motion-blur.ts +42 -0
- package/src/look/quality.ts +309 -0
- package/src/look/reflection-trace.ts +344 -0
- package/src/look/unreal-bloom.ts +295 -0
- package/src/look/vignette.ts +14 -0
- package/src/look/world-environment.ts +2033 -0
- package/src/loop.ts +40 -6
- package/src/merge-parts.ts +25 -10
- package/src/model-lod.ts +14 -0
- package/src/net-session.ts +58 -14
- package/src/ocean/spectral.ts +41 -7
- package/src/picking.ts +72 -5
- package/src/platform.ts +29 -1
- package/src/playtest.ts +69 -12
- package/src/profiling/FrameCounters.ts +166 -5
- package/src/profiling/FrameStages.ts +289 -0
- package/src/profiling/Spans.ts +39 -25
- package/src/profiling/debug-telemetry.ts +312 -0
- package/src/profiling/scene-warning.ts +42 -6
- package/src/projection-apply.ts +11 -3
- package/src/projection-content.ts +189 -0
- package/src/projection-marker.ts +6 -2
- package/src/projection-plan.ts +279 -28
- package/src/projection-skinned.ts +620 -5
- package/src/projection-stability.ts +16 -0
- package/src/projection-uniform.ts +5 -1
- package/src/quiet-markers.ts +56 -0
- package/src/render/budget-ladder.ts +256 -0
- package/src/render/chain.ts +89 -7
- package/src/render/exposure-units.ts +59 -0
- package/src/render/frame-time-budget.ts +162 -0
- package/src/render/gi-budget.ts +231 -0
- package/src/render/gi-visualize.ts +49 -0
- package/src/render/material-key.ts +1 -0
- package/src/render/probe-volume.ts +196 -36
- package/src/render/rough-diffuse.ts +177 -0
- package/src/render/scene-trace.ts +532 -0
- package/src/render/shadow-filter-budget.ts +237 -0
- package/src/render/sky-capture.ts +194 -0
- package/src/render/soft-shadow.ts +607 -0
- package/src/render/surface-cache.ts +418 -0
- package/src/render/traced-reflections.ts +408 -0
- package/src/render/two-sided-foliage.ts +120 -0
- package/src/render/virtual-shadow-pages.ts +112 -12
- package/src/render/virtual-shadow.ts +386 -38
- package/src/render-camera-cull.ts +536 -31
- package/src/render-pass-budget.ts +140 -22
- package/src/renderProjection.ts +65 -9
- package/src/renderer-config.ts +3 -2
- package/src/renderer.ts +289 -14
- package/src/resolution-scaler.ts +65 -7
- package/src/skeletal-mesh.ts +4 -0
- package/src/snow-field.ts +46 -0
- package/src/softbody.ts +6 -5
- package/src/startup-offscreen-bytes.ts +168 -0
- package/src/startup-readiness.ts +137 -2
- package/src/ui-bridge.ts +38 -0
- package/src/ui-hit-regions.ts +6 -2
- package/src/ui-layer.ts +1 -0
- package/src/ui-state.ts +32 -3
- package/src/version.ts +1 -1
- package/src/viewport.ts +8 -5
- package/src/warmup.ts +76 -10
- package/src/worker-audio.ts +579 -0
- package/src/worker.ts +842 -0
- package/src/world-cells.ts +4 -1
- package/gpl/LICENSE.GPL +0 -117
- package/gpl/convert.py +0 -192
- package/gpl/fixtures/make_world_fixture.py +0 -184
- package/gpl/recipes/_common.py +0 -180
- package/gpl/recipes/bake_ao.py +0 -111
- package/gpl/recipes/decimate.py +0 -70
- package/gpl/recipes/export_world.py +0 -699
- package/gpl/recipes/retarget.py +0 -131
- package/gpl/recipes/unwrap.py +0 -71
- package/mcp/blender-server.mjs +0 -689
- package/mcp/blender.mjs +0 -26
package/capabilities.json
CHANGED
|
@@ -533,6 +533,23 @@
|
|
|
533
533
|
"supersedes": [],
|
|
534
534
|
"symbol": "wrapTiles"
|
|
535
535
|
},
|
|
536
|
+
{
|
|
537
|
+
"aliases": [],
|
|
538
|
+
"constraints": [
|
|
539
|
+
"the material needs the foliage marker and subsurfaceColor, else nothing is added and false is returned; call once per material",
|
|
540
|
+
"the material needs `twoSidedFoliage = true` and a `subsurfaceColor`, or nothing is added and false is returned; backIrradiance is a vec3 node in the unit of `irradianceNode`; call once per material"
|
|
541
|
+
],
|
|
542
|
+
"example": "addFoliageBackLight(leaf, backIrradiance);",
|
|
543
|
+
"importPath": "@threenative/core",
|
|
544
|
+
"kind": "function",
|
|
545
|
+
"overrides": [],
|
|
546
|
+
"package": "@threenative/core",
|
|
547
|
+
"signature": "export function addFoliageBackLight(material: Material, backIrradiance: Node<\"vec3\">): boolean { … }",
|
|
548
|
+
"situations": ["add bounce light to the far face of a two sided foliage leaf"],
|
|
549
|
+
"summary": "Adds subsurfaceColor times the far-face irradiance to a Two Sided Foliage leaf's emissive node.",
|
|
550
|
+
"supersedes": [],
|
|
551
|
+
"symbol": "addFoliageBackLight"
|
|
552
|
+
},
|
|
536
553
|
{
|
|
537
554
|
"aliases": [],
|
|
538
555
|
"constraints": [
|
|
@@ -713,13 +730,16 @@
|
|
|
713
730
|
"constraints": [
|
|
714
731
|
"name the body a game moves as strideRoot when the animated rig is a child of it",
|
|
715
732
|
"a one-shot clip always plays at its authored rate; the matched rate re-times loops only",
|
|
733
|
+
"a foot mesh is measured at its lowest geometry point (the sole), never its origin; a skinned mesh is measured through its bones",
|
|
734
|
+
"`stride.inPlace: true` with `clipGroundSpeed: 0` means no foot plant was found and stride sync is not active; the playtest `stride` observation carries `inPlace`",
|
|
716
735
|
"the matched rate is held inside 0.15x-3x; a speed outside what the clip's own stride supports is clamped, and `stride.rate` says so"
|
|
717
736
|
],
|
|
718
737
|
"example": "const player = new AnimationPlayer({ clips, root: rig, strideRoot: body });",
|
|
719
738
|
"importPath": "@threenative/core",
|
|
720
739
|
"kind": "class",
|
|
721
740
|
"overrides": [
|
|
722
|
-
"strideSync controls whether the matched rate is applied while stride is still measured"
|
|
741
|
+
"strideSync controls whether the matched rate is applied while stride is still measured",
|
|
742
|
+
"updateRate: \"auto\" chooses the camera-based interval; 1 is full evaluation, and another positive safe integer requests that interval; a public `mixer` `\"loop\"` listener promotes effective evaluation to 1 to preserve event timing"
|
|
723
743
|
],
|
|
724
744
|
"package": "@threenative/core",
|
|
725
745
|
"signature": "export class AnimationPlayer { … }",
|
|
@@ -729,9 +749,11 @@
|
|
|
729
749
|
"stop a walking character's feet from sliding or spinning",
|
|
730
750
|
"match a walk or run cycle to how fast a character is moving",
|
|
731
751
|
"match an in-place walk cycle with no root motion to the body's speed",
|
|
732
|
-
"find out what speed an animation clip was authored for"
|
|
752
|
+
"find out what speed an animation clip was authored for",
|
|
753
|
+
"reduce animation CPU for distant characters",
|
|
754
|
+
"inspect the effective animation evaluation rate"
|
|
733
755
|
],
|
|
734
|
-
"summary": "Play a skinned or sprite animation from game code. A locomotion clip's playback rate is matched to the ground the body actually covers, so feet do not skate or spin — on by default, `strideSync: false` to keep the authored rate, and `player.stride` reports the measurement either way. Name the body a game moves as `strideRoot` when the rig is a child of it. Clips authored **in place** — every ActorX and Unreal export, every Mixamo \"in place\" clip, every stock animal pack — are matched too: their stride is read off the ground a planted foot sweeps, and `stride.inPlace` says so.",
|
|
756
|
+
"summary": "Play a skinned or sprite animation from game code. A locomotion clip's playback rate is matched to the ground the body actually covers, so feet do not skate or spin — on by default, `strideSync: false` to keep the authored rate, and `player.stride` reports the measurement either way. Name the body a game moves as `strideRoot` when the rig is a child of it. Clips authored **in place** — every ActorX and Unreal export, every Mixamo \"in place\" clip, every stock animal pack — are matched too: their stride is read off the ground a planted foot sweeps, and `stride.inPlace` says so. A mesh counts at its lowest geometry point, so a boot's origin may sit anywhere; an in-place clip with no foot plant reports `inPlace: true` and `clipGroundSpeed: 0`, and stride sync stays off. Evaluation is automatic by default: `updateRate: \"auto\"` follows measured camera visibility and projected size. `updateRate: 1` evaluates every frame; another positive safe integer names that frame interval. `updateRateReport` reports the effective rate, whether a named override is active, and whether the latest update evaluated. One-shots and fades stay full-rate; root-motion `AnimationComposer` advances every tick, and auto camera-ray targets and camera-parented rigs stay full-rate. A public `mixer` `\"loop\"` listener promotes the player to full-rate and observes only loop events after registration, so skipped pre-registration cycles are not replayed; `updateRateReport` reports that effective rate.",
|
|
735
757
|
"supersedes": [],
|
|
736
758
|
"symbol": "AnimationPlayer"
|
|
737
759
|
},
|
|
@@ -838,6 +860,28 @@
|
|
|
838
860
|
"supersedes": ["new Audio("],
|
|
839
861
|
"symbol": "AudioBus"
|
|
840
862
|
},
|
|
863
|
+
{
|
|
864
|
+
"aliases": [],
|
|
865
|
+
"constraints": [
|
|
866
|
+
"WebGPU renderers only: a renderer without WebGPU keeps the fixed exposure and says so"
|
|
867
|
+
],
|
|
868
|
+
"example": "const slow = { ...exposureSettings, rateDown: 0.5 }; const node = new AutoExposureNode(input, slow, 1);",
|
|
869
|
+
"importPath": "@threenative/core",
|
|
870
|
+
"kind": "class",
|
|
871
|
+
"overrides": [
|
|
872
|
+
"every `IExposureSettings` field, spread over `exposureSettings` and passed to `AutoExposureNode`, replaces the Unreal default",
|
|
873
|
+
"`setExposureBias(stops)` is Unreal's Exposure Compensation, live: the game changes it per place or weather (`WorldEnvironment.apply` returns the node as `exposure`)"
|
|
874
|
+
],
|
|
875
|
+
"package": "@threenative/core",
|
|
876
|
+
"signature": "export class AutoExposureNode extends TempNode<\"float\"> { … }",
|
|
877
|
+
"situations": [
|
|
878
|
+
"the frame should expose itself the way a fresh Unreal project does as the sun and the view change",
|
|
879
|
+
"a white snowfield or a bright storm should not meter to middle grey, and the compensation changes with the weather"
|
|
880
|
+
],
|
|
881
|
+
"summary": "Auto exposure with Unreal 5.8.3's metering: a 64-bin histogram of log2 luminance (the darkest and brightest 10% ignored), key 0.18 x 2, -10 to +20 EV100, 3 stops/s brighter and 1 stop/s darker. `AutoExposureNode` meters a colour texture and outputs the adapted exposure; `exposureSettings` holds the defaults.",
|
|
882
|
+
"supersedes": [],
|
|
883
|
+
"symbol": "AutoExposureNode"
|
|
884
|
+
},
|
|
841
885
|
{
|
|
842
886
|
"aliases": [],
|
|
843
887
|
"constraints": [],
|
|
@@ -996,6 +1040,26 @@
|
|
|
996
1040
|
"supersedes": [],
|
|
997
1041
|
"symbol": "boneLengths"
|
|
998
1042
|
},
|
|
1043
|
+
{
|
|
1044
|
+
"aliases": [],
|
|
1045
|
+
"constraints": [
|
|
1046
|
+
"levels are listed cheapest first, and the frame period is the game's own display target",
|
|
1047
|
+
"a frame without a resolved GPU reading never moves the level"
|
|
1048
|
+
],
|
|
1049
|
+
"example": "const ladder = new BudgetLadder({ levels: [\"low\", \"high\"], framePeriodMs: 1000 / 60, start: \"high\" }); const window = ladder.observe(stageMs, frameMs);",
|
|
1050
|
+
"importPath": "@threenative/core",
|
|
1051
|
+
"kind": "class",
|
|
1052
|
+
"overrides": ["explicit: true keeps the level and only reports a frame over the target"],
|
|
1053
|
+
"package": "@threenative/core",
|
|
1054
|
+
"signature": "export class BudgetLadder<L extends string> { … }",
|
|
1055
|
+
"situations": [
|
|
1056
|
+
"step a render stage down when the GPU frame goes over the frame period",
|
|
1057
|
+
"pick a quality level from measured GPU time without oscillating"
|
|
1058
|
+
],
|
|
1059
|
+
"summary": "A cost ladder for one render stage: the whole GPU frame against the frame period moves it, by Unreal's DynamicRenderScaling rule. A frame over the period for 2 frames in a row steps the level down at once, a frame over the period less 10% headroom steps it down after the 8-frame change period, and a frame with room steps it up. A stage steps only when it could absorb the overage at zero cost, and a level that failed is retried after a growing wait. It decides when to move; the game applies the move.",
|
|
1060
|
+
"supersedes": [],
|
|
1061
|
+
"symbol": "BudgetLadder"
|
|
1062
|
+
},
|
|
999
1063
|
{
|
|
1000
1064
|
"aliases": [],
|
|
1001
1065
|
"constraints": [
|
|
@@ -1225,16 +1289,24 @@
|
|
|
1225
1289
|
{
|
|
1226
1290
|
"aliases": ["different area props", "first playable screen external assets"],
|
|
1227
1291
|
"constraints": [
|
|
1228
|
-
"reuse the loader handed to scenes as `ctx.assets` instead of building parallel caches"
|
|
1292
|
+
"reuse the loader handed to scenes as `ctx.assets` instead of building parallel caches",
|
|
1293
|
+
"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",
|
|
1294
|
+
"web only: a native host reads installed files, so `ctx.assets.cache` reports `enabled: false` with the reason and `prefetch` resolves at once"
|
|
1229
1295
|
],
|
|
1230
1296
|
"example": "const assets = createAssetLoader({ basePath: \"/assets\" });\nconst rock = await assets.texture(\"rock.png\");",
|
|
1231
1297
|
"importPath": "@threenative/core",
|
|
1232
1298
|
"kind": "function",
|
|
1233
|
-
"overrides": [
|
|
1299
|
+
"overrides": [
|
|
1300
|
+
"`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`"
|
|
1301
|
+
],
|
|
1234
1302
|
"package": "@threenative/core",
|
|
1235
1303
|
"signature": "export function createAssetLoader(options: IAssetLoaderOptions = { … }",
|
|
1236
1304
|
"situations": [
|
|
1237
1305
|
"preload models, textures, or audio before a scene enters",
|
|
1306
|
+
"keep downloaded web assets on disk between visits",
|
|
1307
|
+
"download the next scene before the player gets there",
|
|
1308
|
+
"free the disk cache from a settings menu",
|
|
1309
|
+
"prefetch assets into the Cache Storage disk cache of a large web game",
|
|
1238
1310
|
"load assets from a nonstandard base path or a compiled asset manifest"
|
|
1239
1311
|
],
|
|
1240
1312
|
"summary": "Create the portable asset loader a scene also receives as `ctx.assets`.",
|
|
@@ -1383,7 +1455,7 @@
|
|
|
1383
1455
|
"find out whether a slow frame is the scene's shape or the device",
|
|
1384
1456
|
"tell an authoring agent what to reduce before it promises a merge"
|
|
1385
1457
|
],
|
|
1386
|
-
"summary": "Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.",
|
|
1458
|
+
"summary": "Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default in a debug launch, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.",
|
|
1387
1459
|
"supersedes": [],
|
|
1388
1460
|
"symbol": "describeSceneShape"
|
|
1389
1461
|
},
|
|
@@ -1404,7 +1476,7 @@
|
|
|
1404
1476
|
"find out whether a slow frame is the scene's shape or the device",
|
|
1405
1477
|
"tell an authoring agent what to reduce before it promises a merge"
|
|
1406
1478
|
],
|
|
1407
|
-
"summary": "Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.",
|
|
1479
|
+
"summary": "Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default in a debug launch, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.",
|
|
1408
1480
|
"supersedes": [],
|
|
1409
1481
|
"symbol": "describeSceneWarning"
|
|
1410
1482
|
},
|
|
@@ -1453,7 +1525,7 @@
|
|
|
1453
1525
|
"find out whether a slow frame is the scene's shape or the device",
|
|
1454
1526
|
"tell an authoring agent what to reduce before it promises a merge"
|
|
1455
1527
|
],
|
|
1456
|
-
"summary": "Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.",
|
|
1528
|
+
"summary": "Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default in a debug launch, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.",
|
|
1457
1529
|
"supersedes": [],
|
|
1458
1530
|
"symbol": "displayPeriodMs"
|
|
1459
1531
|
},
|
|
@@ -1501,6 +1573,66 @@
|
|
|
1501
1573
|
"supersedes": [],
|
|
1502
1574
|
"symbol": "ensureVelocityOutput"
|
|
1503
1575
|
},
|
|
1576
|
+
{
|
|
1577
|
+
"aliases": [],
|
|
1578
|
+
"constraints": [
|
|
1579
|
+
"arguments must be finite; multipliers, apertures, shutter times, ISO and luminance must be > 0",
|
|
1580
|
+
"every argument must be finite and greater than zero"
|
|
1581
|
+
],
|
|
1582
|
+
"example": "renderer.toneMappingExposure = exposureFromEv100(ev100FromCamera(4, 1 / 60, 100));",
|
|
1583
|
+
"importPath": "@threenative/core",
|
|
1584
|
+
"kind": "function",
|
|
1585
|
+
"overrides": [],
|
|
1586
|
+
"package": "@threenative/core",
|
|
1587
|
+
"signature": "export function ev100FromCamera(aperture: number, shutterSeconds: number, iso: number): number { … }",
|
|
1588
|
+
"situations": [
|
|
1589
|
+
"expose a frame lit in lux and nits with a physical camera exposure value",
|
|
1590
|
+
"expose like a camera with an aperture, a shutter time and an ISO"
|
|
1591
|
+
],
|
|
1592
|
+
"summary": "Photometric exposure units: EV100 to the renderer multiplier and back, a physical camera's EV100, and a meter reading. Conversion only; the exposure and the light values are the game's.",
|
|
1593
|
+
"supersedes": [],
|
|
1594
|
+
"symbol": "ev100FromCamera"
|
|
1595
|
+
},
|
|
1596
|
+
{
|
|
1597
|
+
"aliases": [],
|
|
1598
|
+
"constraints": [
|
|
1599
|
+
"arguments must be finite; multipliers, apertures, shutter times, ISO and luminance must be > 0",
|
|
1600
|
+
"multiplier must be finite and greater than zero"
|
|
1601
|
+
],
|
|
1602
|
+
"example": "renderer.toneMappingExposure = exposureFromEv100(ev100FromCamera(4, 1 / 60, 100));",
|
|
1603
|
+
"importPath": "@threenative/core",
|
|
1604
|
+
"kind": "function",
|
|
1605
|
+
"overrides": [],
|
|
1606
|
+
"package": "@threenative/core",
|
|
1607
|
+
"signature": "export function ev100FromExposure(multiplier: number): number { … }",
|
|
1608
|
+
"situations": [
|
|
1609
|
+
"expose a frame lit in lux and nits with a physical camera exposure value",
|
|
1610
|
+
"report a hand-set exposure multiplier as an EV100"
|
|
1611
|
+
],
|
|
1612
|
+
"summary": "Photometric exposure units: EV100 to the renderer multiplier and back, a physical camera's EV100, and a meter reading. Conversion only; the exposure and the light values are the game's.",
|
|
1613
|
+
"supersedes": [],
|
|
1614
|
+
"symbol": "ev100FromExposure"
|
|
1615
|
+
},
|
|
1616
|
+
{
|
|
1617
|
+
"aliases": [],
|
|
1618
|
+
"constraints": [
|
|
1619
|
+
"arguments must be finite; multipliers, apertures, shutter times, ISO and luminance must be > 0",
|
|
1620
|
+
"luminance must be finite and greater than zero"
|
|
1621
|
+
],
|
|
1622
|
+
"example": "renderer.toneMappingExposure = exposureFromEv100(ev100FromCamera(4, 1 / 60, 100));",
|
|
1623
|
+
"importPath": "@threenative/core",
|
|
1624
|
+
"kind": "function",
|
|
1625
|
+
"overrides": [],
|
|
1626
|
+
"package": "@threenative/core",
|
|
1627
|
+
"signature": "export function ev100FromLuminance(luminance: number): number { … }",
|
|
1628
|
+
"situations": [
|
|
1629
|
+
"expose a frame lit in lux and nits with a physical camera exposure value",
|
|
1630
|
+
"meter a frame's average luminance in cd/m² into an exposure value"
|
|
1631
|
+
],
|
|
1632
|
+
"summary": "Photometric exposure units: EV100 to the renderer multiplier and back, a physical camera's EV100, and a meter reading. Conversion only; the exposure and the light values are the game's.",
|
|
1633
|
+
"supersedes": [],
|
|
1634
|
+
"symbol": "ev100FromLuminance"
|
|
1635
|
+
},
|
|
1504
1636
|
{
|
|
1505
1637
|
"aliases": [],
|
|
1506
1638
|
"constraints": ["development builds only; a production build publishes nothing"],
|
|
@@ -1515,6 +1647,23 @@
|
|
|
1515
1647
|
"supersedes": [],
|
|
1516
1648
|
"symbol": "exposeDebug"
|
|
1517
1649
|
},
|
|
1650
|
+
{
|
|
1651
|
+
"aliases": [],
|
|
1652
|
+
"constraints": [
|
|
1653
|
+
"arguments must be finite; multipliers, apertures, shutter times, ISO and luminance must be > 0",
|
|
1654
|
+
"ev100 must be finite; a unitless scene keeps its own multiplier instead"
|
|
1655
|
+
],
|
|
1656
|
+
"example": "renderer.toneMappingExposure = exposureFromEv100(ev100FromCamera(4, 1 / 60, 100));",
|
|
1657
|
+
"importPath": "@threenative/core",
|
|
1658
|
+
"kind": "function",
|
|
1659
|
+
"overrides": [],
|
|
1660
|
+
"package": "@threenative/core",
|
|
1661
|
+
"signature": "export function exposureFromEv100(ev100: number): number { … }",
|
|
1662
|
+
"situations": ["expose a frame lit in lux and nits with a physical camera exposure value"],
|
|
1663
|
+
"summary": "Photometric exposure units: EV100 to the renderer multiplier and back, a physical camera's EV100, and a meter reading. Conversion only; the exposure and the light values are the game's.",
|
|
1664
|
+
"supersedes": [],
|
|
1665
|
+
"symbol": "exposureFromEv100"
|
|
1666
|
+
},
|
|
1518
1667
|
{
|
|
1519
1668
|
"aliases": [],
|
|
1520
1669
|
"constraints": [
|
|
@@ -1606,7 +1755,7 @@
|
|
|
1606
1755
|
"find out whether a slow frame is the scene's shape or the device",
|
|
1607
1756
|
"tell an authoring agent what to reduce before it promises a merge"
|
|
1608
1757
|
],
|
|
1609
|
-
"summary": "Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.",
|
|
1758
|
+
"summary": "Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default in a debug launch, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.",
|
|
1610
1759
|
"supersedes": [],
|
|
1611
1760
|
"symbol": "formatSceneWarning"
|
|
1612
1761
|
},
|
|
@@ -1750,7 +1899,9 @@
|
|
|
1750
1899
|
"aliases": [],
|
|
1751
1900
|
"constraints": [
|
|
1752
1901
|
"only use the returned platform facts; native globals are host-owned",
|
|
1753
|
-
"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"
|
|
1902
|
+
"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",
|
|
1903
|
+
"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",
|
|
1904
|
+
"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"
|
|
1754
1905
|
],
|
|
1755
1906
|
"example": "if (isMobile()) showTouchControls();",
|
|
1756
1907
|
"importPath": "@threenative/core",
|
|
@@ -1767,6 +1918,49 @@
|
|
|
1767
1918
|
"supersedes": [],
|
|
1768
1919
|
"symbol": "getPlatform"
|
|
1769
1920
|
},
|
|
1921
|
+
{
|
|
1922
|
+
"aliases": ["lumen scalability", "sg.GlobalIlluminationQuality", "final gather method"],
|
|
1923
|
+
"constraints": [
|
|
1924
|
+
"the method never changes while the game runs: the primary resolution scale is the run-time lever",
|
|
1925
|
+
"the GPU time of a pass is read by the scene name three or the game gave it, so name every GI pass in `stages`",
|
|
1926
|
+
"timestamp queries are needed: without them every window is unobserved"
|
|
1927
|
+
],
|
|
1928
|
+
"example": "const gi = new GIBudget({ method: \"screenProbeGather\", stages: [\"SSGI\"], framePeriodMs: 1000 / 60 });\nctx.beforeRender(() => gi.observeRenderer(ctx.renderer.raw));",
|
|
1929
|
+
"importPath": "@threenative/core",
|
|
1930
|
+
"kind": "class",
|
|
1931
|
+
"overrides": [],
|
|
1932
|
+
"package": "@threenative/core",
|
|
1933
|
+
"signature": "export class GIBudget { … }",
|
|
1934
|
+
"situations": [
|
|
1935
|
+
"global illumination costs too much on a weak GPU",
|
|
1936
|
+
"see what share of the GPU frame the bounce light takes",
|
|
1937
|
+
"quality tier for indirect lighting that follows the hardware"
|
|
1938
|
+
],
|
|
1939
|
+
"summary": "Reports what a game's global illumination costs against the frame period: the GI share of the GPU frame and whether the frame fits its period less 10% headroom. The method (`none`, `irradianceField`, `screenProbeGather`) holds its level while the game runs, as Unreal's Lumen does: a frame over its period gets cheaper through the primary resolution scale, and the GI pass follows the lower resolution. The budget is the frame period, never a GI time in milliseconds, because a stage reading moves with the GPU clock.",
|
|
1940
|
+
"supersedes": [],
|
|
1941
|
+
"symbol": "GIBudget"
|
|
1942
|
+
},
|
|
1943
|
+
{
|
|
1944
|
+
"aliases": ["lumen visualize", "indirect diffuse only", "r.Lumen.Visualize.IndirectDiffuse"],
|
|
1945
|
+
"constraints": [
|
|
1946
|
+
"the game's render chain builds the indirectDiffuse node (gathered and cached light times albedo); this class draws nothing else",
|
|
1947
|
+
"a mode whose term the chain did not build throws instead of showing the finished frame"
|
|
1948
|
+
],
|
|
1949
|
+
"example": "const view = new GIVisualize({ mode: \"indirectDiffuse\", beauty: frame, indirectDiffuse: albedo.mul(bounce) });\npipeline.outputNode = view.node;",
|
|
1950
|
+
"importPath": "@threenative/core",
|
|
1951
|
+
"kind": "class",
|
|
1952
|
+
"overrides": ["mode: \"off\" returns the finished frame unchanged"],
|
|
1953
|
+
"package": "@threenative/core",
|
|
1954
|
+
"signature": "export class GIVisualize { … }",
|
|
1955
|
+
"situations": [
|
|
1956
|
+
"see only the bounce light of a frame",
|
|
1957
|
+
"compare indirect lighting alone against Unreal",
|
|
1958
|
+
"debug global illumination by looking at the indirect diffuse term"
|
|
1959
|
+
],
|
|
1960
|
+
"summary": "Shows the indirect diffuse light of a frame by itself, the counterpart of Unreal's Lumen `Visualize IndirectDiffuse` mode, so a lighting gap against a reference can be told apart from a scene gap. The game's chain builds the term; this class selects it and fails when the term is missing.",
|
|
1961
|
+
"supersedes": [],
|
|
1962
|
+
"symbol": "GIVisualize"
|
|
1963
|
+
},
|
|
1770
1964
|
{
|
|
1771
1965
|
"aliases": [],
|
|
1772
1966
|
"constraints": [
|
|
@@ -1891,6 +2085,24 @@
|
|
|
1891
2085
|
"supersedes": [],
|
|
1892
2086
|
"symbol": "InputMap"
|
|
1893
2087
|
},
|
|
2088
|
+
{
|
|
2089
|
+
"aliases": [],
|
|
2090
|
+
"constraints": [
|
|
2091
|
+
"WebGPU renderers only: a renderer without a node library keeps ACES and reports `TN_TONEMAP`"
|
|
2092
|
+
],
|
|
2093
|
+
"example": "const renderer = await createRenderer({ toneMapping: \"aces\" }); // the named override",
|
|
2094
|
+
"importPath": "@threenative/core",
|
|
2095
|
+
"kind": "function",
|
|
2096
|
+
"overrides": [
|
|
2097
|
+
"`createRenderer({ toneMapping: \"aces\" | \"agx\" | \"neutral\" | \"none\" })` or `game.renderer.toneMapping` in the game config; setting `renderer.raw.toneMapping` later wins"
|
|
2098
|
+
],
|
|
2099
|
+
"package": "@threenative/core",
|
|
2100
|
+
"signature": "export function installFilmicToneMapping( raw: unknown, c: IFilmicCurve = FILMIC_CURVE, grade: IColorGrade = COLOR_GRADE, ): number | undefined { … }",
|
|
2101
|
+
"situations": ["the frame should tone map the way a fresh Unreal project does"],
|
|
2102
|
+
"summary": "Unreal 5.8.3's tone curve, the default tone mapping of `createRenderer` and `Game`: a filmic curve in ACEScg (slope 0.88, toe 0.55, shoulder 0.26) after the gamut expansion and blue correction of Unreal's colour LUT. `installFilmicToneMapping` registers it as three's custom tone mapping.",
|
|
2103
|
+
"supersedes": [],
|
|
2104
|
+
"symbol": "installFilmicToneMapping"
|
|
2105
|
+
},
|
|
1894
2106
|
{
|
|
1895
2107
|
"aliases": [],
|
|
1896
2108
|
"constraints": [
|
|
@@ -1966,7 +2178,9 @@
|
|
|
1966
2178
|
"aliases": [],
|
|
1967
2179
|
"constraints": [
|
|
1968
2180
|
"only use the returned platform facts; native globals are host-owned",
|
|
1969
|
-
"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"
|
|
2181
|
+
"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",
|
|
2182
|
+
"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",
|
|
2183
|
+
"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"
|
|
1970
2184
|
],
|
|
1971
2185
|
"example": "if (isMobile()) showTouchControls();",
|
|
1972
2186
|
"importPath": "@threenative/core",
|
|
@@ -1987,7 +2201,9 @@
|
|
|
1987
2201
|
"aliases": [],
|
|
1988
2202
|
"constraints": [
|
|
1989
2203
|
"only use the returned platform facts; native globals are host-owned",
|
|
1990
|
-
"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"
|
|
2204
|
+
"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",
|
|
2205
|
+
"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",
|
|
2206
|
+
"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"
|
|
1991
2207
|
],
|
|
1992
2208
|
"example": "if (isMobile()) showTouchControls();",
|
|
1993
2209
|
"importPath": "@threenative/core",
|
|
@@ -2029,7 +2245,9 @@
|
|
|
2029
2245
|
"aliases": [],
|
|
2030
2246
|
"constraints": [
|
|
2031
2247
|
"only use the returned platform facts; native globals are host-owned",
|
|
2032
|
-
"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"
|
|
2248
|
+
"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",
|
|
2249
|
+
"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",
|
|
2250
|
+
"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"
|
|
2033
2251
|
],
|
|
2034
2252
|
"example": "if (isMobile()) showTouchControls();",
|
|
2035
2253
|
"importPath": "@threenative/core",
|
|
@@ -2050,7 +2268,9 @@
|
|
|
2050
2268
|
"aliases": [],
|
|
2051
2269
|
"constraints": [
|
|
2052
2270
|
"only use the returned platform facts; native globals are host-owned",
|
|
2053
|
-
"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"
|
|
2271
|
+
"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",
|
|
2272
|
+
"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",
|
|
2273
|
+
"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"
|
|
2054
2274
|
],
|
|
2055
2275
|
"example": "if (isMobile()) showTouchControls();",
|
|
2056
2276
|
"importPath": "@threenative/core",
|
|
@@ -2067,6 +2287,40 @@
|
|
|
2067
2287
|
"supersedes": [],
|
|
2068
2288
|
"symbol": "isWeb"
|
|
2069
2289
|
},
|
|
2290
|
+
{
|
|
2291
|
+
"aliases": [],
|
|
2292
|
+
"constraints": [
|
|
2293
|
+
"sourceRadius is 0 or more; both distances are positive metres; the result is the geometric tangent, before penumbraScale"
|
|
2294
|
+
],
|
|
2295
|
+
"example": "const tangent = lampPenumbraTangent(0.05, 2, 3);",
|
|
2296
|
+
"importPath": "@threenative/core",
|
|
2297
|
+
"kind": "function",
|
|
2298
|
+
"overrides": [],
|
|
2299
|
+
"package": "@threenative/core",
|
|
2300
|
+
"signature": "export function lampPenumbraTangent( sourceRadius: number, blockerDistance: number, receiverDistance: number, ): number { … }",
|
|
2301
|
+
"situations": ["measure a lamp shadow's penumbra width without a GPU"],
|
|
2302
|
+
"summary": "A lamp's penumbra radius in tangent units at a receiver, from the lamp's source radius and the blocker and receiver distances.",
|
|
2303
|
+
"supersedes": [],
|
|
2304
|
+
"symbol": "lampPenumbraTangent"
|
|
2305
|
+
},
|
|
2306
|
+
{
|
|
2307
|
+
"aliases": [],
|
|
2308
|
+
"constraints": [
|
|
2309
|
+
"counters that do not add up to the frame's shadow draws throw TN_LAMP_SHADOW_INVALID"
|
|
2310
|
+
],
|
|
2311
|
+
"example": "const line = lampShadowMarker(renderer, frame);\nif (line !== undefined) console.info(line);",
|
|
2312
|
+
"importPath": "@threenative/core",
|
|
2313
|
+
"kind": "function",
|
|
2314
|
+
"overrides": [],
|
|
2315
|
+
"package": "@threenative/core",
|
|
2316
|
+
"signature": "export function lampShadowMarker( renderer: { … }",
|
|
2317
|
+
"situations": [
|
|
2318
|
+
"log lamp shadow redraws and GPU time apart from the sun's on the owned engine"
|
|
2319
|
+
],
|
|
2320
|
+
"summary": "The `TN_LAMP_SHADOW` line for the renderer's last frame, or `undefined` on a renderer that keeps no lamp counters (three's own).",
|
|
2321
|
+
"supersedes": [],
|
|
2322
|
+
"symbol": "lampShadowMarker"
|
|
2323
|
+
},
|
|
2070
2324
|
{
|
|
2071
2325
|
"aliases": [],
|
|
2072
2326
|
"constraints": [
|
|
@@ -2286,6 +2540,22 @@
|
|
|
2286
2540
|
"supersedes": [],
|
|
2287
2541
|
"symbol": "PathFollow3D"
|
|
2288
2542
|
},
|
|
2543
|
+
{
|
|
2544
|
+
"aliases": [],
|
|
2545
|
+
"constraints": [
|
|
2546
|
+
"inputs must be finite and non-negative; sizes must be positive and angle < PI/2 radians"
|
|
2547
|
+
],
|
|
2548
|
+
"example": "const radius = penumbraUv(10, angle, 40, 2048);",
|
|
2549
|
+
"importPath": "@threenative/core",
|
|
2550
|
+
"kind": "function",
|
|
2551
|
+
"overrides": [],
|
|
2552
|
+
"package": "@threenative/core",
|
|
2553
|
+
"signature": "export function penumbraUv( gapMetres: number, sourceAngleRad: number, frustumWidthMetres: number, mapSize: number, ): number { … }",
|
|
2554
|
+
"situations": ["measure a source-angle shadow's filter radius without a GPU"],
|
|
2555
|
+
"summary": "Convert world-space caster gap to a shadow UV radius, floored at one texel.",
|
|
2556
|
+
"supersedes": [],
|
|
2557
|
+
"symbol": "penumbraUv"
|
|
2558
|
+
},
|
|
2289
2559
|
{
|
|
2290
2560
|
"aliases": [],
|
|
2291
2561
|
"constraints": [
|
|
@@ -2361,11 +2631,12 @@
|
|
|
2361
2631
|
"symbol": "prewarm"
|
|
2362
2632
|
},
|
|
2363
2633
|
{
|
|
2364
|
-
"aliases": ["readable world lighting"],
|
|
2634
|
+
"aliases": ["readable world lighting", "lumen translucency volume", "translucency gi"],
|
|
2365
2635
|
"constraints": [
|
|
2366
2636
|
"request a bake after static geometry and lights are authored; this is static-lighting-first, not fully dynamic relighting",
|
|
2367
2637
|
"add the volume with ctx.add() so its incremental work is measured in the render phase",
|
|
2368
|
-
"call sample() or sampleNode() from a game-owned material before screen-space GI; the volume owns no light, material, or colour"
|
|
2638
|
+
"call sample() or sampleNode() from a game-owned material before screen-space GI; the volume owns no light, material, or colour",
|
|
2639
|
+
"a translucent material or a fog sample has no side that faces the light: it reads sampleNonDirectional(position), one atlas fetch, the same in every direction (divide by pi for a radiance)"
|
|
2369
2640
|
],
|
|
2370
2641
|
"example": "const probes = new ProbeVolume({ bounds, density: 0.5 }); ctx.add(probes); void probes.requestBake(scene);",
|
|
2371
2642
|
"importPath": "@threenative/core",
|
|
@@ -2375,12 +2646,64 @@
|
|
|
2375
2646
|
"signature": "export class ProbeVolume extends Object3D implements IComputeDriven { … }",
|
|
2376
2647
|
"situations": [
|
|
2377
2648
|
"light bouncing from a room I cannot see",
|
|
2378
|
-
"light a wall with an off-screen emitter"
|
|
2649
|
+
"light a wall with an off-screen emitter",
|
|
2650
|
+
"glass or fog inside a room takes the room's bounce light"
|
|
2379
2651
|
],
|
|
2380
2652
|
"summary": "Bake static diffuse irradiance that reaches surfaces from outside the camera view.",
|
|
2381
2653
|
"supersedes": [],
|
|
2382
2654
|
"symbol": "ProbeVolume"
|
|
2383
2655
|
},
|
|
2656
|
+
{
|
|
2657
|
+
"aliases": [],
|
|
2658
|
+
"constraints": ["an unknown tier name throws with the names it expected"],
|
|
2659
|
+
"example": "const world = new WorldEnvironment({ ...qualityPreset(qualityTiers.resolve({ gpuClass: renderer.gpuClass })), bloomEnabled: false });",
|
|
2660
|
+
"importPath": "@threenative/core",
|
|
2661
|
+
"kind": "function",
|
|
2662
|
+
"overrides": [
|
|
2663
|
+
"pass any `IWorldEnvironmentOptions` field after `qualityPreset(tier)`, or an explicit `tier` to `qualityTiers.resolve`"
|
|
2664
|
+
],
|
|
2665
|
+
"package": "@threenative/core",
|
|
2666
|
+
"signature": "export function qualityPreset(tier: string): IWorldEnvironmentOptions { … }",
|
|
2667
|
+
"situations": [
|
|
2668
|
+
"pick a start tier for the GPU class and read what that tier costs the look",
|
|
2669
|
+
"build a `WorldEnvironment` for a weaker device from a named tier"
|
|
2670
|
+
],
|
|
2671
|
+
"summary": "The quality tiers of the Unreal 5.8.3 look: what `high` (a desktop, Unreal's Epic), `medium` and `low` (a phone) turn on, how a GPU family picks its start tier, and the global illumination and shadow filter settings per tier named after Unreal's scalability levels. A `WorldEnvironment` with no options starts from `high`. `qualityTiers` holds the tier tables: `resolve` picks a start tier from a GPU class, `gi` and `shadow` read a tier's settings.",
|
|
2672
|
+
"supersedes": [],
|
|
2673
|
+
"symbol": "qualityPreset"
|
|
2674
|
+
},
|
|
2675
|
+
{
|
|
2676
|
+
"aliases": [],
|
|
2677
|
+
"constraints": ["non-marker lines and malformed markers return `undefined`"],
|
|
2678
|
+
"example": "const report = readGIMarker(line); if (report?.verdict === \"over\") console.log(report.reason);",
|
|
2679
|
+
"importPath": "@threenative/core",
|
|
2680
|
+
"kind": "function",
|
|
2681
|
+
"overrides": [],
|
|
2682
|
+
"package": "@threenative/core",
|
|
2683
|
+
"signature": "export function readGIMarker(line: string): IGIBudgetReport | undefined { … }",
|
|
2684
|
+
"situations": ["inspect which global illumination method ran and what the frame cost"],
|
|
2685
|
+
"summary": "Parse a `TN_GI` console line back into its report, or `undefined`.",
|
|
2686
|
+
"supersedes": [],
|
|
2687
|
+
"symbol": "readGIMarker"
|
|
2688
|
+
},
|
|
2689
|
+
{
|
|
2690
|
+
"aliases": [],
|
|
2691
|
+
"constraints": [
|
|
2692
|
+
"non-marker lines and markers whose sun and lamp draws do not add up return `undefined`"
|
|
2693
|
+
],
|
|
2694
|
+
"example": "const stats = readLampShadowMarker(line);\nif (stats !== undefined) console.log(stats.lamps.redraws);",
|
|
2695
|
+
"importPath": "@threenative/core",
|
|
2696
|
+
"kind": "function",
|
|
2697
|
+
"overrides": [],
|
|
2698
|
+
"package": "@threenative/core",
|
|
2699
|
+
"signature": "export function readLampShadowMarker(line: string): ILampShadowStats | undefined { … }",
|
|
2700
|
+
"situations": [
|
|
2701
|
+
"count lamp shadow redraws from a renderer log, for example a moving-caster run"
|
|
2702
|
+
],
|
|
2703
|
+
"summary": "Parse a `TN_LAMP_SHADOW` line back into its stats, or `undefined`.",
|
|
2704
|
+
"supersedes": [],
|
|
2705
|
+
"symbol": "readLampShadowMarker"
|
|
2706
|
+
},
|
|
2384
2707
|
{
|
|
2385
2708
|
"aliases": [],
|
|
2386
2709
|
"constraints": [
|
|
@@ -2442,6 +2765,20 @@
|
|
|
2442
2765
|
"supersedes": [],
|
|
2443
2766
|
"symbol": "readRenderChainReport"
|
|
2444
2767
|
},
|
|
2768
|
+
{
|
|
2769
|
+
"aliases": [],
|
|
2770
|
+
"constraints": ["non-marker lines and malformed markers return `undefined`"],
|
|
2771
|
+
"example": "const report = readShadowTierMarker(line); if (report?.stepped) console.log(report.reason);",
|
|
2772
|
+
"importPath": "@threenative/core",
|
|
2773
|
+
"kind": "function",
|
|
2774
|
+
"overrides": [],
|
|
2775
|
+
"package": "@threenative/core",
|
|
2776
|
+
"signature": "export function readShadowTierMarker(line: string): IShadowFilterReport | undefined { … }",
|
|
2777
|
+
"situations": ["inspect which shadow filter tier ran and why it stepped"],
|
|
2778
|
+
"summary": "Parse a `TN_SHADOW_TIER` console line back into its report, or `undefined`.",
|
|
2779
|
+
"supersedes": [],
|
|
2780
|
+
"symbol": "readShadowTierMarker"
|
|
2781
|
+
},
|
|
2445
2782
|
{
|
|
2446
2783
|
"aliases": [],
|
|
2447
2784
|
"constraints": [
|
|
@@ -2824,12 +3161,12 @@
|
|
|
2824
3161
|
"kind": "function",
|
|
2825
3162
|
"overrides": [],
|
|
2826
3163
|
"package": "@threenative/core",
|
|
2827
|
-
"signature": "export function sceneWarning( window: IFrameBudgetWindow, shape: ISceneShape | undefined, declaredTargetFps: number | undefined, ): ISceneWarning | undefined { … }",
|
|
3164
|
+
"signature": "export function sceneWarning( window: IFrameBudgetWindow, shape: ISceneShape | undefined, declaredTargetFps: number | undefined, gpuClass?: string, ): ISceneWarning | undefined { … }",
|
|
2828
3165
|
"situations": [
|
|
2829
3166
|
"find out whether a slow frame is the scene's shape or the device",
|
|
2830
3167
|
"tell an authoring agent what to reduce before it promises a merge"
|
|
2831
3168
|
],
|
|
2832
|
-
"summary": "Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.",
|
|
3169
|
+
"summary": "Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default in a debug launch, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.",
|
|
2833
3170
|
"supersedes": [],
|
|
2834
3171
|
"symbol": "sceneWarning"
|
|
2835
3172
|
},
|
|
@@ -2898,6 +3235,30 @@
|
|
|
2898
3235
|
"supersedes": [],
|
|
2899
3236
|
"symbol": "setSpanRecorder"
|
|
2900
3237
|
},
|
|
3238
|
+
{
|
|
3239
|
+
"aliases": ["virtual shadow map scalability", "sg.ShadowQuality"],
|
|
3240
|
+
"constraints": [
|
|
3241
|
+
"the game rebuilds its filter with the tier's sample counts on each step; this class draws nothing",
|
|
3242
|
+
"timestamp queries are needed: without them every window is unobserved and the tier holds",
|
|
3243
|
+
"the rule reads the whole GPU frame and the `Shadow` stage, which the receiver filter inside the colour pass is not part of"
|
|
3244
|
+
],
|
|
3245
|
+
"example": "const filter = new ShadowFilterBudget({ tier: \"high\", framePeriodMs: 1000 / 60, onStep: (tier) => { light.shadow.filterNode = filterFor(tier); } });\nctx.beforeRender(() => filter.observeRenderer(ctx.renderer.raw));",
|
|
3246
|
+
"importPath": "@threenative/core",
|
|
3247
|
+
"kind": "class",
|
|
3248
|
+
"overrides": [
|
|
3249
|
+
"explicit: true keeps the game's own sample counts and reports an over-budget frame"
|
|
3250
|
+
],
|
|
3251
|
+
"package": "@threenative/core",
|
|
3252
|
+
"signature": "export class ShadowFilterBudget { … }",
|
|
3253
|
+
"situations": [
|
|
3254
|
+
"soft shadow filter costs too much on a weak GPU",
|
|
3255
|
+
"step the shadow quality tier when the GPU frame goes over the frame period",
|
|
3256
|
+
"shadow quality tier that follows the hardware"
|
|
3257
|
+
],
|
|
3258
|
+
"summary": "Steps a game's soft-shadow tier down (`low`, `medium`, `high`) when the whole GPU frame stays over the frame period, and back up when the frame has room, by the settings of Unreal's virtual shadow map budget (a linear model, 5% headroom). A frame that is slow for another reason keeps its shadows: the tier steps only when the shadow passes could absorb the overage. The game owns the sample counts of each tier and rebuilds its filter on each step; the tiers follow Unreal's `sg.ShadowQuality` Low, Medium and Epic.",
|
|
3259
|
+
"supersedes": [],
|
|
3260
|
+
"symbol": "ShadowFilterBudget"
|
|
3261
|
+
},
|
|
2901
3262
|
{
|
|
2902
3263
|
"aliases": [],
|
|
2903
3264
|
"constraints": [
|
|
@@ -2909,7 +3270,8 @@
|
|
|
2909
3270
|
"kind": "class",
|
|
2910
3271
|
"overrides": [
|
|
2911
3272
|
"strideSync controls whether locomotion playback rate matches ground covered",
|
|
2912
|
-
"size normalises the instance to real-world metres with skin-aware measurement"
|
|
3273
|
+
"size normalises the instance to real-world metres with skin-aware measurement",
|
|
3274
|
+
"updateRate: \"auto\" chooses the camera-based interval; 1 is full evaluation, and another positive safe integer requests that interval; a public `mixer` `\"loop\"` listener promotes effective evaluation to 1 to preserve event timing"
|
|
2913
3275
|
],
|
|
2914
3276
|
"package": "@threenative/core",
|
|
2915
3277
|
"signature": "export class SkeletalMesh3D extends AnimationPlayer { … }",
|
|
@@ -2918,9 +3280,11 @@
|
|
|
2918
3280
|
"my imported character renders deformed",
|
|
2919
3281
|
"instance an imported rigged character",
|
|
2920
3282
|
"validate animation clips on a character rig at load time",
|
|
2921
|
-
"prepare a skinned character with safe skeleton cloning and stride sync"
|
|
3283
|
+
"prepare a skinned character with safe skeleton cloning and stride sync",
|
|
3284
|
+
"reduce animation CPU for a crowd of imported rigs",
|
|
3285
|
+
"inspect an imported rig's effective animation evaluation rate"
|
|
2922
3286
|
],
|
|
2923
|
-
"summary": "Shared preparation for an imported rigged character. Instances the rig with a skeleton-safe clone, normalises size with skin-aware measurement, validates requested clips against the file and rig at load time, and sets up AnimationPlayer with honest stride-root accounting.",
|
|
3287
|
+
"summary": "Shared preparation for an imported rigged character. Instances the rig with a skeleton-safe clone, normalises size with skin-aware measurement, validates requested clips against the file and rig at load time, and sets up AnimationPlayer with honest stride-root accounting. Animation evaluation inherits AnimationPlayer's automatic camera-based `updateRate: \"auto\"` default; `updateRate: 1` evaluates every frame, another positive safe integer requests that interval, and `updateRateReport` exposes the effective rate, override status and latest result. One-shots and fades stay full-rate; root-motion `AnimationComposer` advances every tick, and auto camera-ray targets and camera-parented rigs stay full-rate. A public `mixer` `\"loop\"` listener promotes effective evaluation to 1 and observes only loop events after registration, so skipped pre-registration cycles are not replayed.",
|
|
2924
3288
|
"supersedes": [],
|
|
2925
3289
|
"symbol": "SkeletalMesh3D"
|
|
2926
3290
|
},
|
|
@@ -2941,6 +3305,40 @@
|
|
|
2941
3305
|
"supersedes": [],
|
|
2942
3306
|
"symbol": "skeletonBones"
|
|
2943
3307
|
},
|
|
3308
|
+
{
|
|
3309
|
+
"aliases": [],
|
|
3310
|
+
"constraints": [
|
|
3311
|
+
"use an initialized WebGPURenderer; the game supplies the sky and assigns the texture",
|
|
3312
|
+
"call update once per frame on an initialized WebGPURenderer; assign texture after it returns true",
|
|
3313
|
+
"sky nodes use a world-space view direction; keep supplied sky resources alive until dispose"
|
|
3314
|
+
],
|
|
3315
|
+
"example": "const capture = new SkyCapture(renderer, skyNode); if (capture.update(sun)) scene.environment = capture.texture;",
|
|
3316
|
+
"importPath": "@threenative/core",
|
|
3317
|
+
"kind": "class",
|
|
3318
|
+
"overrides": [],
|
|
3319
|
+
"package": "@threenative/core",
|
|
3320
|
+
"signature": "export class SkyCapture { … }",
|
|
3321
|
+
"situations": ["light a scene from a procedural sky when its sun moves"],
|
|
3322
|
+
"summary": "Capture game-owned sky radiance into a sun-triggered, frame-budgeted environment map.",
|
|
3323
|
+
"supersedes": [],
|
|
3324
|
+
"symbol": "SkyCapture"
|
|
3325
|
+
},
|
|
3326
|
+
{
|
|
3327
|
+
"aliases": [],
|
|
3328
|
+
"constraints": [
|
|
3329
|
+
"use an initialized WebGPURenderer; the game supplies the sky and assigns the texture"
|
|
3330
|
+
],
|
|
3331
|
+
"example": "const capture = new SkyCapture(renderer, skyNode); if (capture.update(sun)) scene.environment = capture.texture;",
|
|
3332
|
+
"importPath": "@threenative/core",
|
|
3333
|
+
"kind": "class",
|
|
3334
|
+
"overrides": [],
|
|
3335
|
+
"package": "@threenative/core",
|
|
3336
|
+
"signature": "export class SkyCaptureSchedule { … }",
|
|
3337
|
+
"situations": ["light a scene from a procedural sky when its sun moves"],
|
|
3338
|
+
"summary": "Capture game-owned sky radiance into a sun-triggered, frame-budgeted environment map.",
|
|
3339
|
+
"supersedes": [],
|
|
3340
|
+
"symbol": "SkyCaptureSchedule"
|
|
3341
|
+
},
|
|
2944
3342
|
{
|
|
2945
3343
|
"aliases": [],
|
|
2946
3344
|
"constraints": [
|
|
@@ -3038,6 +3436,38 @@
|
|
|
3038
3436
|
"supersedes": [],
|
|
3039
3437
|
"symbol": "solarPositionAt"
|
|
3040
3438
|
},
|
|
3439
|
+
{
|
|
3440
|
+
"aliases": [],
|
|
3441
|
+
"constraints": [
|
|
3442
|
+
"sourceAngleRad is required, in radians in [0, PI/2); orthographic depth shadows only, not VSM"
|
|
3443
|
+
],
|
|
3444
|
+
"example": "sun.shadow.filterNode = sourceAngleShadowFilter({ sourceAngleRad: angle });",
|
|
3445
|
+
"importPath": "@threenative/core",
|
|
3446
|
+
"kind": "function",
|
|
3447
|
+
"overrides": [],
|
|
3448
|
+
"package": "@threenative/core",
|
|
3449
|
+
"signature": "export function sourceAngleShadowFilter( { … }",
|
|
3450
|
+
"situations": ["soften a directional shadow as the caster-receiver gap grows"],
|
|
3451
|
+
"summary": "Source-angle blocker search and variable-radius PCF on three's shadow map.",
|
|
3452
|
+
"supersedes": [],
|
|
3453
|
+
"symbol": "sourceAngleShadowFilter"
|
|
3454
|
+
},
|
|
3455
|
+
{
|
|
3456
|
+
"aliases": ["PCSS soft shadows"],
|
|
3457
|
+
"constraints": [
|
|
3458
|
+
"sourceRadius is required, in metres, 0 or more (0 is one hard tap); penumbraScale, the share of the geometric penumbra kept, is in (0, 4] and defaults to 0.6, the width Unreal's lamp ray test resolves; forward-depth maps only"
|
|
3459
|
+
],
|
|
3460
|
+
"example": "lamp.shadow.filterNode = sourceRadiusShadowFilter({ sourceRadius: 0.05 });",
|
|
3461
|
+
"importPath": "@threenative/core",
|
|
3462
|
+
"kind": "function",
|
|
3463
|
+
"overrides": ["penumbraScale: 1 gives the geometric penumbra of a disk lamp"],
|
|
3464
|
+
"package": "@threenative/core",
|
|
3465
|
+
"signature": "export function sourceRadiusShadowFilter( { … }",
|
|
3466
|
+
"situations": ["soften a lamp's shadow by the lamp's size, as Unreal's SourceRadius does"],
|
|
3467
|
+
"summary": "Source-radius blocker search and variable-radius PCF on a spot or point light's shadow map.",
|
|
3468
|
+
"supersedes": [],
|
|
3469
|
+
"symbol": "sourceRadiusShadowFilter"
|
|
3470
|
+
},
|
|
3041
3471
|
{
|
|
3042
3472
|
"aliases": [],
|
|
3043
3473
|
"constraints": [
|
|
@@ -3170,6 +3600,25 @@
|
|
|
3170
3600
|
"supersedes": [],
|
|
3171
3601
|
"symbol": "SpriteAnimator3D"
|
|
3172
3602
|
},
|
|
3603
|
+
{
|
|
3604
|
+
"aliases": [],
|
|
3605
|
+
"constraints": [
|
|
3606
|
+
"absent before a whole frame resolves and on an adapter without timestamp queries; the frame number counts each reading once"
|
|
3607
|
+
],
|
|
3608
|
+
"example": "const reading = stageGpuReading(renderer); const ssgiMs = reading?.stages.SSGI;",
|
|
3609
|
+
"importPath": "@threenative/core",
|
|
3610
|
+
"kind": "function",
|
|
3611
|
+
"overrides": [],
|
|
3612
|
+
"package": "@threenative/core",
|
|
3613
|
+
"signature": "export function stageGpuReading(renderer: unknown): IStageGpuReading | undefined { … }",
|
|
3614
|
+
"situations": [
|
|
3615
|
+
"read the GPU cost of one post-processing stage",
|
|
3616
|
+
"tell which render pass takes the GPU time"
|
|
3617
|
+
],
|
|
3618
|
+
"summary": "Read the GPU milliseconds of each named render pass of the newest resolved frame, such as `SSGI` or `AO`, with the whole frame's total.",
|
|
3619
|
+
"supersedes": [],
|
|
3620
|
+
"symbol": "stageGpuReading"
|
|
3621
|
+
},
|
|
3173
3622
|
{
|
|
3174
3623
|
"aliases": [],
|
|
3175
3624
|
"constraints": [
|
|
@@ -3191,6 +3640,70 @@
|
|
|
3191
3640
|
"supersedes": [],
|
|
3192
3641
|
"symbol": "staticTransformCensus"
|
|
3193
3642
|
},
|
|
3643
|
+
{
|
|
3644
|
+
"aliases": ["lumen surface cache", "lumen scene", "mesh cards"],
|
|
3645
|
+
"constraints": [
|
|
3646
|
+
"the materials are fixed when the cache is built; build a new one when a material or a map changes",
|
|
3647
|
+
"a map whose image the runtime does not show to JavaScript (the owned engine's glTF maps) returns the flat colour and is listed in `report.fallbacks`; the `images` option hands over its pixels",
|
|
3648
|
+
"the cache owns no colour, texture or light; the game's materials and lamps are the only source"
|
|
3649
|
+
],
|
|
3650
|
+
"example": "const cache = SurfaceCache.from(materials); cache.albedo(slot, hit.uv.x, hit.uv.y, out);",
|
|
3651
|
+
"importPath": "@threenative/core",
|
|
3652
|
+
"kind": "class",
|
|
3653
|
+
"overrides": [
|
|
3654
|
+
"atlasSize and cardTexelDensityScale size the atlas; images supplies the pixels of a map the runtime hides"
|
|
3655
|
+
],
|
|
3656
|
+
"package": "@threenative/core",
|
|
3657
|
+
"signature": "export class SurfaceCache { … }",
|
|
3658
|
+
"situations": ["give a traced bounce ray the texture colour and glow of the surface it hits"],
|
|
3659
|
+
"summary": "The Surface Cache: what a traced global-illumination ray reads where it hits a surface. A material atlas (base colour and emissive maps reduced to small tiles) answers the albedo and the glow at the hit UV; a flat material keeps its colour. `SurfaceLights` adds the scene's point and spot lamps at the hit, the brightest eight.",
|
|
3660
|
+
"supersedes": [],
|
|
3661
|
+
"symbol": "SurfaceCache"
|
|
3662
|
+
},
|
|
3663
|
+
{
|
|
3664
|
+
"aliases": [],
|
|
3665
|
+
"constraints": [
|
|
3666
|
+
"the cap skips the ninth-brightest lamp and every one after it, and counts them in `skipped`",
|
|
3667
|
+
"the caller answers each shadow ray; the class owns no scene"
|
|
3668
|
+
],
|
|
3669
|
+
"example": "const lamps = new SurfaceLights(lights); lamps.shade(point, normal, albedo, out, (i) => !occluded(i));",
|
|
3670
|
+
"importPath": "@threenative/core",
|
|
3671
|
+
"kind": "class",
|
|
3672
|
+
"overrides": ["maxLights caps the lamps evaluated at one hit"],
|
|
3673
|
+
"package": "@threenative/core",
|
|
3674
|
+
"signature": "export class SurfaceLights { … }",
|
|
3675
|
+
"situations": ["light the hit of a traced ray with the scene's point and spot lamps"],
|
|
3676
|
+
"summary": "The local lamps at the hit of a traced ray: the point and spot lights whose range reaches it, the brightest eight, one shadow ray each. The Surface Cache gives the hit its colour; this gives it the lamps.",
|
|
3677
|
+
"supersedes": [],
|
|
3678
|
+
"symbol": "SurfaceLights"
|
|
3679
|
+
},
|
|
3680
|
+
{
|
|
3681
|
+
"aliases": ["lumen reflections", "dedicated reflection rays"],
|
|
3682
|
+
"constraints": [
|
|
3683
|
+
"the pack is a snapshot of the static triangles taken when the object is built: build a new one after geometry moves",
|
|
3684
|
+
"instanced, skinned, batched and morphing meshes are not in the pack; report.skippedMoving counts them",
|
|
3685
|
+
"trace only pixels at or below maxRoughnessToTrace (0.4, Unreal's cut-off): each ray walks the tree",
|
|
3686
|
+
"a ray visits at most maxSteps tree nodes, then reports a miss; hit light, the miss colour and the blend with the frame stay in the game's src/render/",
|
|
3687
|
+
"the pack needs a device with float32-filterable"
|
|
3688
|
+
],
|
|
3689
|
+
"example": "const traced = new TracedReflections(ctx.scene); const hit = traced.trace({ origin, direction, far: 30 }); // light hit.albedo at hit.position in the stage",
|
|
3690
|
+
"importPath": "@threenative/core",
|
|
3691
|
+
"kind": "class",
|
|
3692
|
+
"overrides": [
|
|
3693
|
+
"maxRoughnessToTrace, roughnessFadeLength, maxRoughnessToEvaluateRoughSpecular, roughSpecularFadeLength and maxSteps are game-owned choices"
|
|
3694
|
+
],
|
|
3695
|
+
"package": "@threenative/core",
|
|
3696
|
+
"signature": "export class TracedReflections { … }",
|
|
3697
|
+
"situations": [
|
|
3698
|
+
"reflect what is behind the camera in a mirror or a chrome sphere",
|
|
3699
|
+
"make a glossy or wet floor reflect objects that are off screen",
|
|
3700
|
+
"trace a shadow ray from a reflected surface toward the sun",
|
|
3701
|
+
"split a surface's specular by roughness into traced, radiance-cache and diffuse-GI shares"
|
|
3702
|
+
],
|
|
3703
|
+
"summary": "Reflection rays against the scene's triangles, in TSL. For a smooth surface, a ray finds what the screen cannot show (a room behind the camera, the far side of an object) and returns the hit's position, normal and material. The game lights the hit in its own stage. The kernel is plain TSL: float textures and a loop, no storage buffer.",
|
|
3704
|
+
"supersedes": [],
|
|
3705
|
+
"symbol": "TracedReflections"
|
|
3706
|
+
},
|
|
3194
3707
|
{
|
|
3195
3708
|
"aliases": [],
|
|
3196
3709
|
"constraints": [
|
|
@@ -3308,6 +3821,26 @@
|
|
|
3308
3821
|
"supersedes": [],
|
|
3309
3822
|
"symbol": "updateModelLods"
|
|
3310
3823
|
},
|
|
3824
|
+
{
|
|
3825
|
+
"aliases": ["Substrate EON, Diffuse_EON, Diffuse_GGX_Rough, rough diffuse, Oren-Nayar"],
|
|
3826
|
+
"constraints": [
|
|
3827
|
+
"direct light only, indirect light stays Lambert; standard and physical materials; a lamp's `sourceRadius` in metres fades the effect to Lambert at 20 cm; a material changed after its first draw needs `needsUpdate`"
|
|
3828
|
+
],
|
|
3829
|
+
"example": "useRoughDiffuse(scene);",
|
|
3830
|
+
"importPath": "@threenative/core",
|
|
3831
|
+
"kind": "function",
|
|
3832
|
+
"overrides": [
|
|
3833
|
+
"material.roughDiffuse = false, or useRoughDiffuse(root, false), puts Lambert back"
|
|
3834
|
+
],
|
|
3835
|
+
"package": "@threenative/core",
|
|
3836
|
+
"signature": "export function useRoughDiffuse(root: Object3D, enabled = true): number { … }",
|
|
3837
|
+
"situations": [
|
|
3838
|
+
"shade rough surfaces under a sun or a lamp the way Unreal's Substrate does, not as flat Lambert"
|
|
3839
|
+
],
|
|
3840
|
+
"summary": "Unreal's Substrate rough diffuse (EON) on standard and physical materials, so direct sun and lamp light meets a rough surface the way Unreal shades it. The same `roughDiffuse` flag works on three's WebGPU renderer and on the owned engine.",
|
|
3841
|
+
"supersedes": [],
|
|
3842
|
+
"symbol": "useRoughDiffuse"
|
|
3843
|
+
},
|
|
3311
3844
|
{
|
|
3312
3845
|
"aliases": [],
|
|
3313
3846
|
"constraints": [
|
|
@@ -3387,7 +3920,8 @@
|
|
|
3387
3920
|
"overrides": [
|
|
3388
3921
|
"bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults, and `marker: false` silences the TN_VIRTUAL_SHADOW line, not the measurement",
|
|
3389
3922
|
"bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults",
|
|
3390
|
-
"followViewFocus: false keeps eye follow; receiverPlaneBias: false uses only authored bias"
|
|
3923
|
+
"followViewFocus: false keeps eye follow; receiverPlaneBias: false uses only authored bias",
|
|
3924
|
+
"minWindowAspect: below 1, a level is as high as `sin(sun elevation)` times its width, never under this, so a low sun's floor shadows keep the texel density of a high sun's; the default 1 keeps square levels"
|
|
3391
3925
|
],
|
|
3392
3926
|
"package": "@threenative/core",
|
|
3393
3927
|
"signature": "export class VirtualShadowNode extends ShadowBaseNode { … }",
|
|
@@ -3493,6 +4027,28 @@
|
|
|
3493
4027
|
"supersedes": [],
|
|
3494
4028
|
"symbol": "withVelocityContext"
|
|
3495
4029
|
},
|
|
4030
|
+
{
|
|
4031
|
+
"aliases": [],
|
|
4032
|
+
"constraints": [
|
|
4033
|
+
"post stages run on WebGPU only: a renderer without it keeps the fixed exposure and reports `TN_AUTO_EXPOSURE_REFUSED`, and a missing node library keeps ACES and reports `TN_TONEMAP`",
|
|
4034
|
+
"an unknown option value throws instead of becoming the default"
|
|
4035
|
+
],
|
|
4036
|
+
"example": "const world = new WorldEnvironment({ tonemapMode: \"aces\", autoExposureEnabled: false, exposure: 0.8 }); world.apply(renderer, scene, view);",
|
|
4037
|
+
"importPath": "@threenative/core",
|
|
4038
|
+
"kind": "class",
|
|
4039
|
+
"overrides": [
|
|
4040
|
+
"every option on `IWorldEnvironmentOptions`: `tonemapMode: \"aces\" | \"agx\" | \"neutral\"`, `autoExposureEnabled: false` with a fixed `exposure`, `bloomEnabled`, `gtaoEnabled`, `ssgiEnabled`, `screenSpaceAA`"
|
|
4041
|
+
],
|
|
4042
|
+
"package": "@threenative/core",
|
|
4043
|
+
"signature": "export class WorldEnvironment { … }",
|
|
4044
|
+
"situations": [
|
|
4045
|
+
"a scene should light and tone map like a fresh Unreal level without wiring each post stage by hand",
|
|
4046
|
+
"turn one lighting effect off, or pick a cheaper tier, for a weak GPU or a stylised look"
|
|
4047
|
+
],
|
|
4048
|
+
"summary": "The node that says which lighting effects a scene runs and how strong they are, with a fresh Unreal 5.8.3 project's defaults: the filmic tone curve, Unreal-metered auto exposure, screen-space GI and ambient occlusion, SMAA, Unreal's bloom and local exposure. It builds the post chain through `renderer.createRenderChain()` and prints `TN_RENDER_CHAIN` naming every stage as applied or refused with a reason. Property names are Godot's `Environment` where it has one.",
|
|
4049
|
+
"supersedes": [],
|
|
4050
|
+
"symbol": "WorldEnvironment"
|
|
4051
|
+
},
|
|
3496
4052
|
{
|
|
3497
4053
|
"aliases": [],
|
|
3498
4054
|
"constraints": [
|
|
@@ -3814,6 +4370,34 @@
|
|
|
3814
4370
|
"supersedes": [],
|
|
3815
4371
|
"symbol": "subscribeUiState"
|
|
3816
4372
|
},
|
|
4373
|
+
{
|
|
4374
|
+
"aliases": [],
|
|
4375
|
+
"constraints": [],
|
|
4376
|
+
"example": "serveWorkerGame(game);",
|
|
4377
|
+
"importPath": "@threenative/core/worker",
|
|
4378
|
+
"kind": "function",
|
|
4379
|
+
"overrides": [],
|
|
4380
|
+
"package": "@threenative/core",
|
|
4381
|
+
"signature": "export function serveWorkerGame( game: { … }",
|
|
4382
|
+
"situations": ["run the game loop in a web worker so a busy page cannot stall its frames"],
|
|
4383
|
+
"summary": "Runs inside the worker: wire the page's messages to the unchanged portable game. Call it last in the worker entry, after the game module evaluated: it posts the ready message the page waits for before it sends the canvas.",
|
|
4384
|
+
"supersedes": [],
|
|
4385
|
+
"symbol": "serveWorkerGame"
|
|
4386
|
+
},
|
|
4387
|
+
{
|
|
4388
|
+
"aliases": [],
|
|
4389
|
+
"constraints": [],
|
|
4390
|
+
"example": "const handle = startWorkerGame(new Worker(new URL(\"./worker.ts\", import.meta.url), { type: \"module\" }), root);",
|
|
4391
|
+
"importPath": "@threenative/core/worker",
|
|
4392
|
+
"kind": "function",
|
|
4393
|
+
"overrides": [],
|
|
4394
|
+
"package": "@threenative/core",
|
|
4395
|
+
"signature": "export function startWorkerGame( worker: Worker, container: HTMLElement, ): { … }",
|
|
4396
|
+
"situations": ["host a worker-run game's canvas, input and HUD on the page"],
|
|
4397
|
+
"summary": "Runs on the page: own the canvas and the DOM, and feed the worker game. Call it before the UI mounts: the HUD's bridge host globals exist from this call on.",
|
|
4398
|
+
"supersedes": [],
|
|
4399
|
+
"symbol": "startWorkerGame"
|
|
4400
|
+
},
|
|
3817
4401
|
{
|
|
3818
4402
|
"aliases": [],
|
|
3819
4403
|
"constraints": [
|
|
@@ -4040,6 +4624,7 @@
|
|
|
4040
4624
|
"aliases": [],
|
|
4041
4625
|
"constraints": [
|
|
4042
4626
|
"surface is the game's; this class creates no material, colour or geometry",
|
|
4627
|
+
"a cell's model loads at `soon` priority, so a file the running scene awaits through `ctx.assets` starts first",
|
|
4043
4628
|
"budgets are hard caps that report pressure instead of over-committing",
|
|
4044
4629
|
"model loads are bounded by `concurrency` (default 12) across every resident cell, not per cell",
|
|
4045
4630
|
"refilters are bounded by `rebuildsPerUpdate` (default 16) per update, nearest cell first",
|
|
@@ -4374,11 +4959,16 @@
|
|
|
4374
4959
|
},
|
|
4375
4960
|
{
|
|
4376
4961
|
"aliases": ["hitscan camera"],
|
|
4377
|
-
"constraints": [
|
|
4962
|
+
"constraints": [
|
|
4963
|
+
"query results are bounded by the configured result limit",
|
|
4964
|
+
"intersectRay ignores a solid that contains the ray origin and returns the next real hit or none, like Godot hit_from_inside false"
|
|
4965
|
+
],
|
|
4378
4966
|
"example": "const space = new PhysicsDirectSpaceState3D(context);",
|
|
4379
4967
|
"importPath": "@threenative/physics",
|
|
4380
4968
|
"kind": "class",
|
|
4381
|
-
"overrides": [
|
|
4969
|
+
"overrides": [
|
|
4970
|
+
"hitFromInside: true returns the solid around the ray origin as a distance 0 hit with a zero normal"
|
|
4971
|
+
],
|
|
4382
4972
|
"package": "@threenative/physics",
|
|
4383
4973
|
"requires": ["npm i @threenative/physics"],
|
|
4384
4974
|
"signature": "export class PhysicsDirectSpaceState3D { … }",
|
|
@@ -5101,7 +5691,7 @@
|
|
|
5101
5691
|
"kind": "function",
|
|
5102
5692
|
"overrides": [],
|
|
5103
5693
|
"package": "@threenative/playtest",
|
|
5104
|
-
"signature": "export async function advanceFixedStep( page: Page, bridge:
|
|
5694
|
+
"signature": "export async function advanceFixedStep( page: Page, bridge: { … }",
|
|
5105
5695
|
"situations": [
|
|
5106
5696
|
"run a complete browser or device playtest",
|
|
5107
5697
|
"capture diagnostics and screenshots from a managed server"
|
|
@@ -6191,6 +6781,23 @@
|
|
|
6191
6781
|
"supersedes": [],
|
|
6192
6782
|
"symbol": "withBrowserCapture"
|
|
6193
6783
|
},
|
|
6784
|
+
{
|
|
6785
|
+
"aliases": [],
|
|
6786
|
+
"constraints": ["invalid flags throw a named usage error"],
|
|
6787
|
+
"example": "const config = parseStandalonePlaytestArgs(argv);",
|
|
6788
|
+
"importPath": "@threenative/playtest/runner",
|
|
6789
|
+
"kind": "function",
|
|
6790
|
+
"overrides": [],
|
|
6791
|
+
"package": "@threenative/playtest",
|
|
6792
|
+
"signature": "export function withScenarioClock<T extends { … }",
|
|
6793
|
+
"situations": [
|
|
6794
|
+
"invoke the playtest CLI from a scaffold",
|
|
6795
|
+
"validate runner flags before launching a browser"
|
|
6796
|
+
],
|
|
6797
|
+
"summary": "Parse standalone playtest runner configuration.",
|
|
6798
|
+
"supersedes": [],
|
|
6799
|
+
"symbol": "withScenarioClock"
|
|
6800
|
+
},
|
|
6194
6801
|
{
|
|
6195
6802
|
"aliases": [],
|
|
6196
6803
|
"constraints": ["missing observations and malformed assertions fail closed"],
|
|
@@ -7906,7 +8513,9 @@
|
|
|
7906
8513
|
},
|
|
7907
8514
|
{
|
|
7908
8515
|
"aliases": [],
|
|
7909
|
-
"constraints": [
|
|
8516
|
+
"constraints": [
|
|
8517
|
+
"returns undefined until the game publishes its first state and while the loading cover is up"
|
|
8518
|
+
],
|
|
7910
8519
|
"example": "const score = useUiState<GameState, number>((state) => state.score);",
|
|
7911
8520
|
"importPath": "@threenative/ui",
|
|
7912
8521
|
"kind": "function",
|
|
@@ -7922,6 +8531,23 @@
|
|
|
7922
8531
|
"supersedes": [],
|
|
7923
8532
|
"symbol": "useUiState"
|
|
7924
8533
|
},
|
|
8534
|
+
{
|
|
8535
|
+
"aliases": [],
|
|
8536
|
+
"constraints": [
|
|
8537
|
+
"needs a non-empty reason, reported once as TN_UI_STARTUP_OVERRIDE; every other HUD uses useUiState"
|
|
8538
|
+
],
|
|
8539
|
+
"example": "const loading = useUiStateDuringStartup<GameState, number>({ reason: \"staged loading overlay\" }, (state) => state.loading.progress);",
|
|
8540
|
+
"importPath": "@threenative/ui",
|
|
8541
|
+
"kind": "function",
|
|
8542
|
+
"overrides": [],
|
|
8543
|
+
"package": "@threenative/ui",
|
|
8544
|
+
"requires": ["npm i @threenative/ui"],
|
|
8545
|
+
"signature": "export function useUiStateDuringStartup<TState extends object>(options: { … }",
|
|
8546
|
+
"situations": ["draw a staged loading overlay from the startup progress the game publishes"],
|
|
8547
|
+
"summary": "Read the game's published state while the loading cover is still up, for a UI that draws its own loading screen.",
|
|
8548
|
+
"supersedes": [],
|
|
8549
|
+
"symbol": "useUiStateDuringStartup"
|
|
8550
|
+
},
|
|
7925
8551
|
{
|
|
7926
8552
|
"symbol": "createStormAudio",
|
|
7927
8553
|
"package": "template:rain",
|
|
@@ -8147,29 +8773,6 @@
|
|
|
8147
8773
|
"supersedes": [],
|
|
8148
8774
|
"aliases": []
|
|
8149
8775
|
},
|
|
8150
|
-
{
|
|
8151
|
-
"symbol": "WorldEnvironment",
|
|
8152
|
-
"package": "three",
|
|
8153
|
-
"importPath": "src/render/worldEnvironment.ts",
|
|
8154
|
-
"kind": "class",
|
|
8155
|
-
"signature": "class WorldEnvironment",
|
|
8156
|
-
"summary": "The generated file that composes every lighting stage and prints TN_RENDER_CHAIN naming each one as applied or refused with a reason. It is the game's source, not the framework's — edit it.",
|
|
8157
|
-
"situations": [
|
|
8158
|
-
"turn a lighting or post-processing effect on or off",
|
|
8159
|
-
"find out why an effect you enabled is not visible",
|
|
8160
|
-
"change how the scene is lit, graded, or tonemapped",
|
|
8161
|
-
"match a reference image's lighting"
|
|
8162
|
-
],
|
|
8163
|
-
"example": "src/render/postprocessing.ts — edit the preset it passes to WorldEnvironment",
|
|
8164
|
-
"constraints": [
|
|
8165
|
-
"Read the TN_RENDER_CHAIN line before assuming a stage ran: it names every stage as applied or dropped, with the reason it was dropped.",
|
|
8166
|
-
"A stage reported `applied` can still be invisible if its own inputs are wrong — the chain reports whether it built, not whether you can see it.",
|
|
8167
|
-
"Appearance belongs here, in generated game source. Nothing in packages/ decides how the scene looks."
|
|
8168
|
-
],
|
|
8169
|
-
"overrides": [],
|
|
8170
|
-
"supersedes": [],
|
|
8171
|
-
"aliases": []
|
|
8172
|
-
},
|
|
8173
8776
|
{
|
|
8174
8777
|
"symbol": "bloom",
|
|
8175
8778
|
"package": "three",
|
|
@@ -8504,5 +9107,91 @@
|
|
|
8504
9107
|
]
|
|
8505
9108
|
}
|
|
8506
9109
|
],
|
|
9110
|
+
"starterKits": [
|
|
9111
|
+
{
|
|
9112
|
+
"blurb": "A three-room grid dungeon of mannequin fighters: melee, the Arcane Surge, loot, equipment, persistence, and a real character sheet.",
|
|
9113
|
+
"name": "action-rpg",
|
|
9114
|
+
"title": "Action RPG",
|
|
9115
|
+
"words": ["action-rpg"]
|
|
9116
|
+
},
|
|
9117
|
+
{
|
|
9118
|
+
"blurb": "Wren crosses a sunlit clearing and a three-room moss dungeon with lock-on sword combat, a shield, a block-and-switch puzzle, a small key and the Stone Warden mini-boss.",
|
|
9119
|
+
"name": "adventure",
|
|
9120
|
+
"title": "Lantern Vale",
|
|
9121
|
+
"words": ["adventure", "zelda", "ocarina", "action-adventure"]
|
|
9122
|
+
},
|
|
9123
|
+
{
|
|
9124
|
+
"blurb": "A stout sprout-keeper in a knit beanie runs one free-roam island with a triple jump, long jump, backflip, side flip, wall kick, dive, ground pound and ledge grab, collecting three Sunseeds past bumblets, hoppers and spiked thornbacks.",
|
|
9125
|
+
"name": "collectathon",
|
|
9126
|
+
"title": "Hop Garden",
|
|
9127
|
+
"words": ["collectathon", "mario", "sm64", "super-mario", "3d-platformer"]
|
|
9128
|
+
},
|
|
9129
|
+
{
|
|
9130
|
+
"blurb": "Eight karts race three laps of Clover Loop, a figure-8 with a bridge, a jump over a creek and boost pads, with a hop into a power-slide, mini-turbo sparks, item boxes with burrs, acorns and nitro cans, and seven CPU drivers on a rubber band.",
|
|
9131
|
+
"name": "kart",
|
|
9132
|
+
"title": "Clover Cup",
|
|
9133
|
+
"words": ["kart-racer", "mario-kart", "mariokart", "mk64", "kart"]
|
|
9134
|
+
},
|
|
9135
|
+
{
|
|
9136
|
+
"blurb": "A fox runs ninety-seven metres of floating meadow, rope bridges and stompable walkers to a goal flag, with three hearts, five gems and a double jump.",
|
|
9137
|
+
"name": "platformer",
|
|
9138
|
+
"title": "Fox Dash",
|
|
9139
|
+
"words": ["platformer"]
|
|
9140
|
+
},
|
|
9141
|
+
{
|
|
9142
|
+
"blurb": "A forty-five body vault: shove the pile, walk through the glowing ward, and stand on the seal.",
|
|
9143
|
+
"name": "puzzle",
|
|
9144
|
+
"title": "Physics puzzle",
|
|
9145
|
+
"words": ["physics-puzzle"]
|
|
9146
|
+
},
|
|
9147
|
+
{
|
|
9148
|
+
"blurb": "Three laps, ordered checklines, rescue sectors, boost pads, and route-progress ranking.",
|
|
9149
|
+
"name": "racing",
|
|
9150
|
+
"title": "Circuit racing",
|
|
9151
|
+
"words": ["racing"]
|
|
9152
|
+
},
|
|
9153
|
+
{
|
|
9154
|
+
"blurb": "A real-time coastal weather study: shape rain, cloud, wind, fog and wetness, and watch a coastline answer.",
|
|
9155
|
+
"name": "rain",
|
|
9156
|
+
"title": "Rain",
|
|
9157
|
+
"words": ["rain"]
|
|
9158
|
+
},
|
|
9159
|
+
{
|
|
9160
|
+
"blurb": "Three commanders, a seeded world, fog of war and a deterministic 0.05 s simulation headless in src/sim/.",
|
|
9161
|
+
"name": "rts",
|
|
9162
|
+
"title": "Real-time strategy",
|
|
9163
|
+
"words": ["rts"]
|
|
9164
|
+
},
|
|
9165
|
+
{
|
|
9166
|
+
"blurb": "Three lanes, a track that builds itself ahead of you, and obstacles that end the run.",
|
|
9167
|
+
"name": "runner",
|
|
9168
|
+
"title": "Endless runner",
|
|
9169
|
+
"words": ["endless-runner"]
|
|
9170
|
+
},
|
|
9171
|
+
{
|
|
9172
|
+
"blurb": "A wind-and-wave sailing starter with buoyancy, ordered course buoys, and a ship you can reshape.",
|
|
9173
|
+
"name": "sailing",
|
|
9174
|
+
"title": "Sailing",
|
|
9175
|
+
"words": ["sailing"]
|
|
9176
|
+
},
|
|
9177
|
+
{
|
|
9178
|
+
"blurb": "Mouse look, a weapon in your hands, aim down the sights, reload, and targets that hunt you.",
|
|
9179
|
+
"name": "shooter",
|
|
9180
|
+
"title": "First-person shooter",
|
|
9181
|
+
"words": ["shooter"]
|
|
9182
|
+
},
|
|
9183
|
+
{
|
|
9184
|
+
"blurb": "Deformable snow that remembers every footstep, a ball that carves its own track, and weather you can turn into a blizzard.",
|
|
9185
|
+
"name": "snow",
|
|
9186
|
+
"title": "Snow glade",
|
|
9187
|
+
"words": ["snow"]
|
|
9188
|
+
},
|
|
9189
|
+
{
|
|
9190
|
+
"blurb": "Four towers with three upgrade levels, twelve waves, two bosses and an orbital strike on a mossy diorama.",
|
|
9191
|
+
"name": "tower-defense",
|
|
9192
|
+
"title": "Tower defense",
|
|
9193
|
+
"words": ["strategy"]
|
|
9194
|
+
}
|
|
9195
|
+
],
|
|
8507
9196
|
"version": 2
|
|
8508
9197
|
}
|