@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/src/grounding.ts
CHANGED
|
@@ -4,7 +4,12 @@ import { measureThreePose, posedBounds } from "./pose-measure.js";
|
|
|
4
4
|
export interface IGroundSnapOptions {
|
|
5
5
|
/** Whether to apply the correction. Measurement and `clearance` continue when this is false. */
|
|
6
6
|
readonly enabled?: boolean;
|
|
7
|
-
/**
|
|
7
|
+
/**
|
|
8
|
+
* Maximum downward correction speed in metres per second. Unset follows the authored pose
|
|
9
|
+
* exactly. A pose below the surface is still raised at once: the rate stops the snap pulling a
|
|
10
|
+
* run cycle's flight phase onto the floor, where the leading foot skates, and never lets a foot
|
|
11
|
+
* sink through it.
|
|
12
|
+
*/
|
|
8
13
|
readonly maxRate?: number;
|
|
9
14
|
/** Visual meshes to measure. Defaults to every mesh below `model`. */
|
|
10
15
|
readonly meshes?: readonly Object3D[];
|
|
@@ -50,7 +55,7 @@ export class GroundSnap {
|
|
|
50
55
|
|
|
51
56
|
const desired = surfaceY - before.min[1];
|
|
52
57
|
const correction =
|
|
53
|
-
this.maxRate === undefined ? desired :
|
|
58
|
+
this.maxRate === undefined || desired > 0 ? desired : Math.max(desired, -this.maxRate * dt);
|
|
54
59
|
if (this.enabled) this.applyWorldCorrection(group, correction);
|
|
55
60
|
|
|
56
61
|
// Re-read after the move. The group may be under a scaled or rotated parent, so the local
|
|
@@ -94,7 +99,3 @@ function validateMaxRate(maxRate: number | undefined): void {
|
|
|
94
99
|
throw new Error("GroundSnap maxRate must be finite and non-negative.");
|
|
95
100
|
}
|
|
96
101
|
}
|
|
97
|
-
|
|
98
|
-
function clamp(value: number, min: number, max: number): number {
|
|
99
|
-
return Math.min(max, Math.max(min, value));
|
|
100
|
-
}
|
package/src/hot.ts
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
import { audioRuntimeSnapshot } from "./audio.js";
|
|
4
4
|
import type { IGame } from "./game.js";
|
|
5
|
+
import { hostDocument, hostWindow } from "./platform.js";
|
|
5
6
|
export interface IHotDiagnostics {
|
|
6
7
|
readonly reloads: number;
|
|
7
8
|
readonly entities: number;
|
|
@@ -15,6 +16,8 @@ type HotData = {
|
|
|
15
16
|
readonly reloads: number;
|
|
16
17
|
/** The scene the session was in. Absent for data written before scene resume existed. */
|
|
17
18
|
readonly sceneName?: string | undefined;
|
|
19
|
+
/** The session's startup had lifted its cover, so its HUD was showing. */
|
|
20
|
+
readonly revealed?: boolean;
|
|
18
21
|
};
|
|
19
22
|
const isDev =
|
|
20
23
|
(import.meta as ImportMeta & { env?: Record<"DEV", boolean | undefined> }).env?.DEV === true;
|
|
@@ -48,16 +51,22 @@ export function acceptHotUpdate<TState extends Record<string, unknown>, TPhysics
|
|
|
48
51
|
// game and boots it at `config.start` — so a session that was playing came back holding its own
|
|
49
52
|
// state on the main menu, with every entity and its physics world gone, and the store insisting
|
|
50
53
|
// the screen was still "playing". Resuming the scene is what makes the restored state true.
|
|
54
|
+
// Whether this session's HUD is showing: carried from a restart that kept it, else this
|
|
55
|
+
// startup's own reveal. One save can update the module twice, the second before this startup
|
|
56
|
+
// is ready, and that update must not cover a HUD the player is looking at.
|
|
57
|
+
let revealed = false;
|
|
51
58
|
if (carried?.sceneName !== undefined) {
|
|
52
59
|
try {
|
|
53
|
-
game.resumeScene(carried.sceneName);
|
|
60
|
+
game.resumeScene(carried.sceneName, { revealed: carried.revealed === true });
|
|
61
|
+
revealed = carried.revealed === true;
|
|
54
62
|
} catch {
|
|
55
63
|
// A scene that no longer exists in the updated module is not a reason to lose the reload;
|
|
56
64
|
// the game boots at its start scene, which is what it would have done anyway.
|
|
57
65
|
}
|
|
58
66
|
}
|
|
59
|
-
|
|
60
|
-
|
|
67
|
+
const page = hostWindow();
|
|
68
|
+
if (isDev && page !== undefined) {
|
|
69
|
+
const host = page as unknown as Record<string, unknown> &
|
|
61
70
|
Partial<Record<"__THREENATIVE__", Record<string, unknown> & { hot?: () => IHotDiagnostics }>>;
|
|
62
71
|
host.__THREENATIVE__ = {
|
|
63
72
|
...host.__THREENATIVE__,
|
|
@@ -73,7 +82,12 @@ export function acceptHotUpdate<TState extends Record<string, unknown>, TPhysics
|
|
|
73
82
|
game.state.flush();
|
|
74
83
|
const state = game.state.getState();
|
|
75
84
|
assertPortableState(state);
|
|
76
|
-
data.threenative = {
|
|
85
|
+
data.threenative = {
|
|
86
|
+
reloads: reloads + 1,
|
|
87
|
+
revealed: revealed || game.ctx?.startup.phase === "ready",
|
|
88
|
+
sceneName: game.sceneName,
|
|
89
|
+
state,
|
|
90
|
+
};
|
|
77
91
|
} catch (error) {
|
|
78
92
|
data.threenative = undefined;
|
|
79
93
|
hot.invalidate(error instanceof Error ? error.message : String(error));
|
|
@@ -115,7 +129,7 @@ function diagnostics<TState extends Record<string, unknown>, TPhysics>(
|
|
|
115
129
|
reloads,
|
|
116
130
|
entities: ctx === undefined ? 0 : Object.keys(ctx.entities.snapshot()).length,
|
|
117
131
|
sceneObjects,
|
|
118
|
-
canvases:
|
|
132
|
+
canvases: hostDocument()?.querySelectorAll("canvas").length ?? 0,
|
|
119
133
|
audio: audioRuntimeSnapshot(),
|
|
120
134
|
physics: typeof physics?.numBodies === "function" ? physics.numBodies() : null,
|
|
121
135
|
};
|
package/src/index.ts
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
* unavoidable here — core is bundled for browsers and cannot read `package.json` at runtime — so
|
|
7
7
|
* the spec now asserts this equals the manifest instead of asserting a number somebody typed.
|
|
8
8
|
*/
|
|
9
|
-
export const version = "0.3.
|
|
9
|
+
export const version = "0.3.8";
|
|
10
10
|
|
|
11
11
|
/**
|
|
12
12
|
* Play a skinned or sprite animation from game code.
|
|
@@ -16,23 +16,39 @@ export const version = "0.3.5";
|
|
|
16
16
|
* `player.stride` reports the measurement either way. Name the body a game moves as
|
|
17
17
|
* `strideRoot` when the rig is a child of it. Clips authored **in place** — every ActorX and
|
|
18
18
|
* Unreal export, every Mixamo "in place" clip, every stock animal pack — are matched too: their
|
|
19
|
-
* stride is read off the ground a planted foot sweeps, and `stride.inPlace` says so.
|
|
19
|
+
* stride is read off the ground a planted foot sweeps, and `stride.inPlace` says so. A mesh counts
|
|
20
|
+
* at its lowest geometry point, so a boot's origin may sit anywhere; an in-place clip with no
|
|
21
|
+
* foot plant reports `inPlace: true` and `clipGroundSpeed: 0`, and stride sync stays off.
|
|
22
|
+
* Evaluation is automatic by default: `updateRate: "auto"` follows measured camera visibility
|
|
23
|
+
* and projected size. `updateRate: 1` evaluates every frame; another positive safe integer names
|
|
24
|
+
* that frame interval. `updateRateReport` reports the effective rate, whether a named override is
|
|
25
|
+
* active, and whether the latest update evaluated. One-shots and fades stay full-rate; root-motion
|
|
26
|
+
* `AnimationComposer` advances every tick, and auto camera-ray targets and camera-parented rigs
|
|
27
|
+
* stay full-rate. A public `mixer` `"loop"` listener promotes the player to full-rate and observes
|
|
28
|
+
* only loop events after registration, so skipped pre-registration cycles are not replayed;
|
|
29
|
+
* `updateRateReport` reports that effective rate.
|
|
20
30
|
* @situation play an animation on a character
|
|
21
31
|
* @situation switch a character between idle and attack clips
|
|
22
32
|
* @situation stop a walking character's feet from sliding or spinning
|
|
23
33
|
* @situation match a walk or run cycle to how fast a character is moving
|
|
24
34
|
* @situation match an in-place walk cycle with no root motion to the body's speed
|
|
25
35
|
* @situation find out what speed an animation clip was authored for
|
|
36
|
+
* @situation reduce animation CPU for distant characters
|
|
37
|
+
* @situation inspect the effective animation evaluation rate
|
|
26
38
|
* @constraint name the body a game moves as strideRoot when the animated rig is a child of it
|
|
27
39
|
* @constraint a one-shot clip always plays at its authored rate; the matched rate re-times loops only
|
|
40
|
+
* @constraint a foot mesh is measured at its lowest geometry point (the sole), never its origin; a skinned mesh is measured through its bones
|
|
41
|
+
* @constraint `stride.inPlace: true` with `clipGroundSpeed: 0` means no foot plant was found and stride sync is not active; the playtest `stride` observation carries `inPlace`
|
|
28
42
|
* @constraint 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
|
|
29
43
|
* @override strideSync controls whether the matched rate is applied while stride is still measured
|
|
44
|
+
* @override 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
|
|
30
45
|
* @example const player = new AnimationPlayer({ clips, root: rig, strideRoot: body });
|
|
31
46
|
*/
|
|
32
47
|
export { AnimationPlayer } from "./animation.js";
|
|
33
48
|
export type {
|
|
34
49
|
IAnimationPlayerOptions,
|
|
35
50
|
IAnimationPlayOptions,
|
|
51
|
+
IAnimationUpdateRateReport,
|
|
36
52
|
IStrideReport,
|
|
37
53
|
} from "./animation.js";
|
|
38
54
|
/**
|
|
@@ -70,15 +86,25 @@ export { BlendSpace1D, BlendSpace2D } from "./animation-blend.js";
|
|
|
70
86
|
* Instances the rig with a skeleton-safe clone, normalises size with skin-aware measurement,
|
|
71
87
|
* validates requested clips against the file and rig at load time, and sets up AnimationPlayer
|
|
72
88
|
* with honest stride-root accounting.
|
|
89
|
+
* Animation evaluation inherits AnimationPlayer's automatic camera-based `updateRate: "auto"`
|
|
90
|
+
* default; `updateRate: 1` evaluates every frame, another positive safe integer requests that
|
|
91
|
+
* interval, and `updateRateReport` exposes the effective rate, override status and latest result.
|
|
92
|
+
* One-shots and fades stay full-rate; root-motion `AnimationComposer` advances every tick, and
|
|
93
|
+
* auto camera-ray targets and camera-parented rigs stay full-rate. A public `mixer` `"loop"`
|
|
94
|
+
* listener promotes effective evaluation to 1 and observes only loop events after registration,
|
|
95
|
+
* so skipped pre-registration cycles are not replayed.
|
|
73
96
|
* @situation put an animated character in the scene
|
|
74
97
|
* @situation my imported character renders deformed
|
|
75
98
|
* @situation instance an imported rigged character
|
|
76
99
|
* @situation validate animation clips on a character rig at load time
|
|
77
100
|
* @situation prepare a skinned character with safe skeleton cloning and stride sync
|
|
101
|
+
* @situation reduce animation CPU for a crowd of imported rigs
|
|
102
|
+
* @situation inspect an imported rig's effective animation evaluation rate
|
|
78
103
|
* @constraint use strideRoot to name the body moved by game code when the rig is parented under it
|
|
79
104
|
* @constraint requiredClips fails closed at load time if any requested clip is missing or binds 0 tracks
|
|
80
105
|
* @override strideSync controls whether locomotion playback rate matches ground covered
|
|
81
106
|
* @override size normalises the instance to real-world metres with skin-aware measurement
|
|
107
|
+
* @override 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
|
|
82
108
|
* @example import { SkeletalMesh3D } from "@threenative/core";
|
|
83
109
|
* const character = new SkeletalMesh3D({
|
|
84
110
|
* source: gltf.scene, clips: gltf.animations, requiredClips: ["idle", "walk"],
|
|
@@ -113,10 +139,17 @@ export type { CameraShakeCurve, ICameraShakeOffset, ICameraShakeOptions } from "
|
|
|
113
139
|
/**
|
|
114
140
|
* Create the portable asset loader a scene also receives as `ctx.assets`.
|
|
115
141
|
* @situation preload models, textures, or audio before a scene enters
|
|
142
|
+
* @situation keep downloaded web assets on disk between visits
|
|
143
|
+
* @situation download the next scene before the player gets there
|
|
144
|
+
* @situation free the disk cache from a settings menu
|
|
145
|
+
* @situation prefetch assets into the Cache Storage disk cache of a large web game
|
|
116
146
|
* @situation load assets from a nonstandard base path or a compiled asset manifest
|
|
117
147
|
* @alias different area props
|
|
118
148
|
* @alias first playable screen external assets
|
|
119
149
|
* @constraint reuse the loader handed to scenes as `ctx.assets` instead of building parallel caches
|
|
150
|
+
* @constraint 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
|
|
151
|
+
* @constraint web only: a native host reads installed files, so `ctx.assets.cache` reports `enabled: false` with the reason and `prefetch` resolves at once
|
|
152
|
+
* @override `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`
|
|
120
153
|
* @example const assets = createAssetLoader({ basePath: "/assets" });
|
|
121
154
|
* const rock = await assets.texture("rock.png");
|
|
122
155
|
*/
|
|
@@ -124,7 +157,15 @@ export { createAssetLoader } from "./assets.js";
|
|
|
124
157
|
export { onLaunchFailure } from "./launch-diagnostics.js";
|
|
125
158
|
export { resetAudioCueLedger } from "./audio.js";
|
|
126
159
|
export type { ILaunchFailure, LaunchFailureKind } from "./launch-diagnostics.js";
|
|
127
|
-
export type {
|
|
160
|
+
export type {
|
|
161
|
+
IAssetCacheState,
|
|
162
|
+
IAssetLoader,
|
|
163
|
+
IAssetLoaderOptions,
|
|
164
|
+
IAssetPrefetchProgress,
|
|
165
|
+
IAssetRequestOptions,
|
|
166
|
+
ITextureOptions,
|
|
167
|
+
} from "./assets.js";
|
|
168
|
+
export type { AssetPriority, IAssetCacheReport } from "./asset-cache.js";
|
|
128
169
|
export type {
|
|
129
170
|
IAudioBusOptions,
|
|
130
171
|
IAudioCompressorOptions,
|
|
@@ -224,6 +265,15 @@ export type {
|
|
|
224
265
|
ISolarPosition,
|
|
225
266
|
ISolarPositionInput,
|
|
226
267
|
} from "./atmosphere/index.js";
|
|
268
|
+
/**
|
|
269
|
+
* Capture game-owned sky radiance into a sun-triggered, frame-budgeted environment map.
|
|
270
|
+
* @situation light a scene from a procedural sky when its sun moves
|
|
271
|
+
* @constraint use an initialized WebGPURenderer; the game supplies the sky and assigns the texture
|
|
272
|
+
* @example const capture = new SkyCapture(renderer, skyNode); if (capture.update(sun)) scene.environment = capture.texture;
|
|
273
|
+
*/
|
|
274
|
+
export { SkyCapture, SkyCaptureSchedule } from "./render/sky-capture.js";
|
|
275
|
+
export type { ISkyCaptureOptions } from "./render/sky-capture.js";
|
|
276
|
+
|
|
227
277
|
/**
|
|
228
278
|
* Register game-owned IComputeDriven objects with the shared compute lifetime.
|
|
229
279
|
* @situation use IComputeDriven for a cloth, fluid, boid, or other GPU simulation
|
|
@@ -250,6 +300,31 @@ export type {
|
|
|
250
300
|
IGPUSceneBVHMaterialGroup,
|
|
251
301
|
IGPUSceneBVHOptions,
|
|
252
302
|
} from "./gpu-scene-bvh.js";
|
|
303
|
+
/**
|
|
304
|
+
* Reflection rays against the scene's triangles, in TSL. For a smooth surface, a ray finds what the screen cannot
|
|
305
|
+
* show (a room behind the camera, the far side of an object) and returns the hit's position, normal and material.
|
|
306
|
+
* The game lights the hit in its own stage. The kernel is plain TSL: float textures and a loop, no storage buffer.
|
|
307
|
+
* @situation reflect what is behind the camera in a mirror or a chrome sphere
|
|
308
|
+
* @situation make a glossy or wet floor reflect objects that are off screen
|
|
309
|
+
* @situation trace a shadow ray from a reflected surface toward the sun
|
|
310
|
+
* @situation split a surface's specular by roughness into traced, radiance-cache and diffuse-GI shares
|
|
311
|
+
* @alias lumen reflections
|
|
312
|
+
* @alias dedicated reflection rays
|
|
313
|
+
* @constraint the pack is a snapshot of the static triangles taken when the object is built: build a new one after geometry moves
|
|
314
|
+
* @constraint instanced, skinned, batched and morphing meshes are not in the pack; report.skippedMoving counts them
|
|
315
|
+
* @constraint trace only pixels at or below maxRoughnessToTrace (0.4, Unreal's cut-off): each ray walks the tree
|
|
316
|
+
* @constraint 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/
|
|
317
|
+
* @constraint the pack needs a device with float32-filterable
|
|
318
|
+
* @override maxRoughnessToTrace, roughnessFadeLength, maxRoughnessToEvaluateRoughSpecular, roughSpecularFadeLength and maxSteps are game-owned choices
|
|
319
|
+
* @example const traced = new TracedReflections(ctx.scene); const hit = traced.trace({ origin, direction, far: 30 }); // light hit.albedo at hit.position in the stage
|
|
320
|
+
*/
|
|
321
|
+
export { TracedReflections } from "./render/traced-reflections.js";
|
|
322
|
+
export type {
|
|
323
|
+
IReflectionRoute,
|
|
324
|
+
ITracedHit,
|
|
325
|
+
ITracedRay,
|
|
326
|
+
ITracedReflectionsOptions,
|
|
327
|
+
} from "./render/traced-reflections.js";
|
|
253
328
|
/**
|
|
254
329
|
* Collapse many copies of one game-authored shape into a single draw, without counting them first.
|
|
255
330
|
*
|
|
@@ -556,6 +631,117 @@ export type {
|
|
|
556
631
|
IFramePhaseSample,
|
|
557
632
|
} from "./frame-budget.js";
|
|
558
633
|
export type { FramePassKind, IRenderPassSample, MainDrawSource } from "./render-pass-budget.js";
|
|
634
|
+
/**
|
|
635
|
+
* Read the GPU milliseconds of each named render pass of the newest resolved frame, such as `SSGI`
|
|
636
|
+
* or `AO`, with the whole frame's total.
|
|
637
|
+
* @situation read the GPU cost of one post-processing stage
|
|
638
|
+
* @situation tell which render pass takes the GPU time
|
|
639
|
+
* @constraint absent before a whole frame resolves and on an adapter without timestamp queries; the frame number counts each reading once
|
|
640
|
+
* @example const reading = stageGpuReading(renderer); const ssgiMs = reading?.stages.SSGI;
|
|
641
|
+
*/
|
|
642
|
+
export { stageGpuReading } from "./render-pass-budget.js";
|
|
643
|
+
export type { IStageGpuReading } from "./render-pass-budget.js";
|
|
644
|
+
/**
|
|
645
|
+
* A cost ladder for one render stage: the whole GPU frame against the frame period moves it, by
|
|
646
|
+
* Unreal's DynamicRenderScaling rule. A frame over the period for 2 frames in a row steps the level
|
|
647
|
+
* down at once, a frame over the period less 10% headroom steps it down after the 8-frame change
|
|
648
|
+
* period, and a frame with room steps it up. A stage steps only when it could absorb the overage at
|
|
649
|
+
* zero cost, and a level that failed is retried after a growing wait. It decides when to move; the
|
|
650
|
+
* game applies the move.
|
|
651
|
+
* @situation step a render stage down when the GPU frame goes over the frame period
|
|
652
|
+
* @situation pick a quality level from measured GPU time without oscillating
|
|
653
|
+
* @constraint levels are listed cheapest first, and the frame period is the game's own display target
|
|
654
|
+
* @constraint a frame without a resolved GPU reading never moves the level
|
|
655
|
+
* @override explicit: true keeps the level and only reports a frame over the target
|
|
656
|
+
* @example const ladder = new BudgetLadder({ levels: ["low", "high"], framePeriodMs: 1000 / 60, start: "high" }); const window = ladder.observe(stageMs, frameMs);
|
|
657
|
+
*/
|
|
658
|
+
export { BudgetLadder } from "./render/budget-ladder.js";
|
|
659
|
+
export type { BudgetVerdict, IBudgetLadderOptions, IBudgetWindow } from "./render/budget-ladder.js";
|
|
660
|
+
/**
|
|
661
|
+
* Reports what a game's global illumination costs against the frame period: the GI share of the GPU
|
|
662
|
+
* frame and whether the frame fits its period less 10% headroom. The method (`none`,
|
|
663
|
+
* `irradianceField`, `screenProbeGather`) holds its level while the game runs, as Unreal's Lumen
|
|
664
|
+
* does: a frame over its period gets cheaper through the primary resolution scale, and the GI pass
|
|
665
|
+
* follows the lower resolution. The budget is the frame period, never a GI time in milliseconds,
|
|
666
|
+
* because a stage reading moves with the GPU clock.
|
|
667
|
+
* @situation global illumination costs too much on a weak GPU
|
|
668
|
+
* @situation see what share of the GPU frame the bounce light takes
|
|
669
|
+
* @situation quality tier for indirect lighting that follows the hardware
|
|
670
|
+
* @constraint the method never changes while the game runs: the primary resolution scale is the run-time lever
|
|
671
|
+
* @constraint 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`
|
|
672
|
+
* @constraint timestamp queries are needed: without them every window is unobserved
|
|
673
|
+
* @alias lumen scalability
|
|
674
|
+
* @alias sg.GlobalIlluminationQuality
|
|
675
|
+
* @alias final gather method
|
|
676
|
+
* @example
|
|
677
|
+
* const gi = new GIBudget({ method: "screenProbeGather", stages: ["SSGI"], framePeriodMs: 1000 / 60 });
|
|
678
|
+
* ctx.beforeRender(() => gi.observeRenderer(ctx.renderer.raw));
|
|
679
|
+
*/
|
|
680
|
+
export { GI_METHODS, GIBudget } from "./render/gi-budget.js";
|
|
681
|
+
/**
|
|
682
|
+
* Shows the indirect diffuse light of a frame by itself, the counterpart of Unreal's Lumen
|
|
683
|
+
* `Visualize IndirectDiffuse` mode, so a lighting gap against a reference can be told apart from a scene gap.
|
|
684
|
+
* The game's chain builds the term; this class selects it and fails when the term is missing.
|
|
685
|
+
* @situation see only the bounce light of a frame
|
|
686
|
+
* @situation compare indirect lighting alone against Unreal
|
|
687
|
+
* @situation debug global illumination by looking at the indirect diffuse term
|
|
688
|
+
* @constraint the game's render chain builds the indirectDiffuse node (gathered and cached light times albedo); this class draws nothing else
|
|
689
|
+
* @constraint a mode whose term the chain did not build throws instead of showing the finished frame
|
|
690
|
+
* @override mode: "off" returns the finished frame unchanged
|
|
691
|
+
* @alias lumen visualize
|
|
692
|
+
* @alias indirect diffuse only
|
|
693
|
+
* @alias r.Lumen.Visualize.IndirectDiffuse
|
|
694
|
+
* @example
|
|
695
|
+
* const view = new GIVisualize({ mode: "indirectDiffuse", beauty: frame, indirectDiffuse: albedo.mul(bounce) });
|
|
696
|
+
* pipeline.outputNode = view.node;
|
|
697
|
+
*/
|
|
698
|
+
export { GI_VISUALIZE_MODES, GIVisualize } from "./render/gi-visualize.js";
|
|
699
|
+
export type { GIVisualizeMode, IGIVisualizeOptions } from "./render/gi-visualize.js";
|
|
700
|
+
/**
|
|
701
|
+
* Steps a game's soft-shadow tier down (`low`, `medium`, `high`) when the whole GPU frame stays over
|
|
702
|
+
* the frame period, and back up when the frame has room, by the settings of Unreal's virtual shadow
|
|
703
|
+
* map budget (a linear model, 5% headroom). A frame that is slow for another reason keeps its
|
|
704
|
+
* shadows: the tier steps only when the shadow passes could absorb the overage. The game owns the
|
|
705
|
+
* sample counts of each tier and rebuilds its filter on each step; the tiers follow Unreal's
|
|
706
|
+
* `sg.ShadowQuality` Low, Medium and Epic.
|
|
707
|
+
* @situation soft shadow filter costs too much on a weak GPU
|
|
708
|
+
* @situation step the shadow quality tier when the GPU frame goes over the frame period
|
|
709
|
+
* @situation shadow quality tier that follows the hardware
|
|
710
|
+
* @constraint the game rebuilds its filter with the tier's sample counts on each step; this class draws nothing
|
|
711
|
+
* @constraint timestamp queries are needed: without them every window is unobserved and the tier holds
|
|
712
|
+
* @constraint the rule reads the whole GPU frame and the `Shadow` stage, which the receiver filter inside the colour pass is not part of
|
|
713
|
+
* @override explicit: true keeps the game's own sample counts and reports an over-budget frame
|
|
714
|
+
* @alias virtual shadow map scalability
|
|
715
|
+
* @alias sg.ShadowQuality
|
|
716
|
+
* @example
|
|
717
|
+
* const filter = new ShadowFilterBudget({ tier: "high", framePeriodMs: 1000 / 60, onStep: (tier) => { light.shadow.filterNode = filterFor(tier); } });
|
|
718
|
+
* ctx.beforeRender(() => filter.observeRenderer(ctx.renderer.raw));
|
|
719
|
+
*/
|
|
720
|
+
export {
|
|
721
|
+
SHADOW_FILTER_TIERS,
|
|
722
|
+
SHADOW_STAGES,
|
|
723
|
+
ShadowFilterBudget,
|
|
724
|
+
} from "./render/shadow-filter-budget.js";
|
|
725
|
+
/**
|
|
726
|
+
* Parse a `TN_SHADOW_TIER` console line back into its report, or `undefined`.
|
|
727
|
+
* @situation inspect which shadow filter tier ran and why it stepped
|
|
728
|
+
* @constraint non-marker lines and malformed markers return `undefined`
|
|
729
|
+
* @example const report = readShadowTierMarker(line); if (report?.stepped) console.log(report.reason);
|
|
730
|
+
*/
|
|
731
|
+
export { readShadowTierMarker } from "./render/shadow-filter-budget.js";
|
|
732
|
+
export type {
|
|
733
|
+
IShadowFilterBudgetOptions,
|
|
734
|
+
IShadowFilterReport,
|
|
735
|
+
ShadowFilterTier,
|
|
736
|
+
} from "./render/shadow-filter-budget.js";
|
|
737
|
+
/**
|
|
738
|
+
* Parse a `TN_GI` console line back into its report, or `undefined`.
|
|
739
|
+
* @situation inspect which global illumination method ran and what the frame cost
|
|
740
|
+
* @constraint non-marker lines and malformed markers return `undefined`
|
|
741
|
+
* @example const report = readGIMarker(line); if (report?.verdict === "over") console.log(report.reason);
|
|
742
|
+
*/
|
|
743
|
+
export { readGIMarker } from "./render/gi-budget.js";
|
|
744
|
+
export type { GIMethod, IGIBudgetOptions, IGIBudgetReport } from "./render/gi-budget.js";
|
|
559
745
|
/**
|
|
560
746
|
* Read what frame rate a game gets when its config does not say, and why.
|
|
561
747
|
*
|
|
@@ -634,8 +820,8 @@ export type { ICounterDevice, IFrameCounters } from "./profiling/FrameCounters.j
|
|
|
634
820
|
/**
|
|
635
821
|
* Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its
|
|
636
822
|
* JS render phase is longer than the display's own period is a scene-shape problem, and the engine
|
|
637
|
-
* already has the shape. On by default, printed at most once per reported window
|
|
638
|
-
* `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
|
|
823
|
+
* already has the shape. On by default in a debug launch, printed at most once per reported window
|
|
824
|
+
* as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
|
|
639
825
|
* @situation find out whether a slow frame is the scene's shape or the device
|
|
640
826
|
* @situation tell an authoring agent what to reduce before it promises a merge
|
|
641
827
|
* @constraint the rule is derived from the frame's own numbers; the display period comes from the host's presentation cap or the game's declared target, never a constant
|
|
@@ -814,10 +1000,14 @@ export type {
|
|
|
814
1000
|
* Bake static diffuse irradiance that reaches surfaces from outside the camera view.
|
|
815
1001
|
* @situation light bouncing from a room I cannot see
|
|
816
1002
|
* @situation light a wall with an off-screen emitter
|
|
1003
|
+
* @situation glass or fog inside a room takes the room's bounce light
|
|
817
1004
|
* @alias readable world lighting
|
|
1005
|
+
* @alias lumen translucency volume
|
|
1006
|
+
* @alias translucency gi
|
|
818
1007
|
* @constraint request a bake after static geometry and lights are authored; this is static-lighting-first, not fully dynamic relighting
|
|
819
1008
|
* @constraint add the volume with ctx.add() so its incremental work is measured in the render phase
|
|
820
1009
|
* @constraint call sample() or sampleNode() from a game-owned material before screen-space GI; the volume owns no light, material, or colour
|
|
1010
|
+
* @constraint 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)
|
|
821
1011
|
* @override density, bounds, bakeBudgetMs, and bounces are game-owned choices
|
|
822
1012
|
* @example const probes = new ProbeVolume({ bounds, density: 0.5 }); ctx.add(probes); void probes.requestBake(scene);
|
|
823
1013
|
*/
|
|
@@ -826,6 +1016,39 @@ export {
|
|
|
826
1016
|
PROBE_VOLUME_MARKER,
|
|
827
1017
|
ProbeVolume,
|
|
828
1018
|
} from "./render/probe-volume.js";
|
|
1019
|
+
/**
|
|
1020
|
+
* The Surface Cache: what a traced global-illumination ray reads where it hits a surface. A material atlas
|
|
1021
|
+
* (base colour and emissive maps reduced to small tiles) answers the albedo and the glow at the hit UV; a flat
|
|
1022
|
+
* material keeps its colour. `SurfaceLights` adds the scene's point and spot lamps at the hit, the brightest eight.
|
|
1023
|
+
* @situation give a traced bounce ray the texture colour and glow of the surface it hits
|
|
1024
|
+
* @alias lumen surface cache
|
|
1025
|
+
* @alias lumen scene
|
|
1026
|
+
* @alias mesh cards
|
|
1027
|
+
* @constraint the materials are fixed when the cache is built; build a new one when a material or a map changes
|
|
1028
|
+
* @constraint 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
|
|
1029
|
+
* @constraint the cache owns no colour, texture or light; the game's materials and lamps are the only source
|
|
1030
|
+
* @override atlasSize and cardTexelDensityScale size the atlas; images supplies the pixels of a map the runtime hides
|
|
1031
|
+
* @example const cache = SurfaceCache.from(materials); cache.albedo(slot, hit.uv.x, hit.uv.y, out);
|
|
1032
|
+
*/
|
|
1033
|
+
export { SurfaceCache } from "./render/surface-cache.js";
|
|
1034
|
+
/**
|
|
1035
|
+
* The local lamps at the hit of a traced ray: the point and spot lights whose range reaches it, the brightest eight,
|
|
1036
|
+
* one shadow ray each. The Surface Cache gives the hit its colour; this gives it the lamps.
|
|
1037
|
+
* @situation light the hit of a traced ray with the scene's point and spot lamps
|
|
1038
|
+
* @constraint the cap skips the ninth-brightest lamp and every one after it, and counts them in `skipped`
|
|
1039
|
+
* @constraint the caller answers each shadow ray; the class owns no scene
|
|
1040
|
+
* @override maxLights caps the lamps evaluated at one hit
|
|
1041
|
+
* @example const lamps = new SurfaceLights(lights); lamps.shade(point, normal, albedo, out, (i) => !occluded(i));
|
|
1042
|
+
*/
|
|
1043
|
+
export { SurfaceLights } from "./render/surface-cache.js";
|
|
1044
|
+
export type {
|
|
1045
|
+
ISurfaceCacheMaterial,
|
|
1046
|
+
ISurfaceCacheOptions,
|
|
1047
|
+
ISurfaceCacheReport,
|
|
1048
|
+
ISurfaceCacheTexture,
|
|
1049
|
+
ISurfaceLight,
|
|
1050
|
+
ISurfaceLightsOptions,
|
|
1051
|
+
} from "./render/surface-cache.js";
|
|
829
1052
|
/**
|
|
830
1053
|
* Read the most recent observation from a probe volume.
|
|
831
1054
|
* @situation inspect the latest probe bake observation
|
|
@@ -899,6 +1122,60 @@ export {
|
|
|
899
1122
|
VirtualShadowNode,
|
|
900
1123
|
} from "./render/virtual-shadow.js";
|
|
901
1124
|
export { readVirtualShadowMarker } from "./render/virtual-shadow.js";
|
|
1125
|
+
export {
|
|
1126
|
+
LAMP_SHADOW_MARKER,
|
|
1127
|
+
lampShadowMarker,
|
|
1128
|
+
readLampShadowMarker,
|
|
1129
|
+
} from "./render/virtual-shadow.js";
|
|
1130
|
+
export type { ILampShadowStats } from "./render/virtual-shadow.js";
|
|
1131
|
+
/**
|
|
1132
|
+
* Source-angle blocker search and variable-radius PCF on three's shadow map.
|
|
1133
|
+
* @situation soften a directional shadow as the caster-receiver gap grows
|
|
1134
|
+
* @constraint sourceAngleRad is required, in radians in [0, PI/2); orthographic depth shadows only, not VSM
|
|
1135
|
+
* @example sun.shadow.filterNode = sourceAngleShadowFilter({ sourceAngleRad: angle });
|
|
1136
|
+
*/
|
|
1137
|
+
export { sourceAngleShadowFilter } from "./render/soft-shadow.js";
|
|
1138
|
+
/**
|
|
1139
|
+
* Source-radius blocker search and variable-radius PCF on a spot or point light's shadow map.
|
|
1140
|
+
* @situation soften a lamp's shadow by the lamp's size, as Unreal's SourceRadius does
|
|
1141
|
+
* @constraint 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
|
|
1142
|
+
* @alias PCSS soft shadows
|
|
1143
|
+
* @override penumbraScale: 1 gives the geometric penumbra of a disk lamp
|
|
1144
|
+
* @example lamp.shadow.filterNode = sourceRadiusShadowFilter({ sourceRadius: 0.05 });
|
|
1145
|
+
*/
|
|
1146
|
+
export { sourceRadiusShadowFilter } from "./render/soft-shadow.js";
|
|
1147
|
+
/**
|
|
1148
|
+
* A lamp's penumbra radius in tangent units at a receiver, from the lamp's source radius and the blocker and receiver distances.
|
|
1149
|
+
* @situation measure a lamp shadow's penumbra width without a GPU
|
|
1150
|
+
* @constraint sourceRadius is 0 or more; both distances are positive metres; the result is the geometric tangent, before penumbraScale
|
|
1151
|
+
* @example const tangent = lampPenumbraTangent(0.05, 2, 3);
|
|
1152
|
+
*/
|
|
1153
|
+
export { lampPenumbraTangent } from "./render/soft-shadow.js";
|
|
1154
|
+
/**
|
|
1155
|
+
* Convert world-space caster gap to a shadow UV radius, floored at one texel.
|
|
1156
|
+
* @situation measure a source-angle shadow's filter radius without a GPU
|
|
1157
|
+
* @constraint inputs must be finite and non-negative; sizes must be positive and angle < PI/2 radians
|
|
1158
|
+
* @example const radius = penumbraUv(10, angle, 40, 2048);
|
|
1159
|
+
*/
|
|
1160
|
+
export { penumbraUv } from "./render/soft-shadow.js";
|
|
1161
|
+
/**
|
|
1162
|
+
* Adds subsurfaceColor times the far-face irradiance to a Two Sided Foliage leaf's emissive node.
|
|
1163
|
+
* @situation add bounce light to the far face of a two sided foliage leaf
|
|
1164
|
+
* @constraint the material needs the foliage marker and subsurfaceColor, else nothing is added and false is returned; call once per material
|
|
1165
|
+
* @example addFoliageBackLight(leaf, backIrradiance);
|
|
1166
|
+
*/
|
|
1167
|
+
export { addFoliageBackLight } from "./render/two-sided-foliage.js";
|
|
1168
|
+
export type { ISourceAngleShadowInputs, ISourceAngleShadowOptions } from "./render/soft-shadow.js";
|
|
1169
|
+
/**
|
|
1170
|
+
* Unreal's Substrate rough diffuse (EON) on standard and physical materials, so direct sun and lamp light meets a rough surface
|
|
1171
|
+
* the way Unreal shades it. The same `roughDiffuse` flag works on three's WebGPU renderer and on the owned engine.
|
|
1172
|
+
* @situation shade rough surfaces under a sun or a lamp the way Unreal's Substrate does, not as flat Lambert
|
|
1173
|
+
* @constraint 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`
|
|
1174
|
+
* @alias Substrate EON, Diffuse_EON, Diffuse_GGX_Rough, rough diffuse, Oren-Nayar
|
|
1175
|
+
* @override material.roughDiffuse = false, or useRoughDiffuse(root, false), puts Lambert back
|
|
1176
|
+
* @example useRoughDiffuse(scene);
|
|
1177
|
+
*/
|
|
1178
|
+
export { useRoughDiffuse } from "./render/rough-diffuse.js";
|
|
902
1179
|
/**
|
|
903
1180
|
* An outdoor daylight rig: physical sky, one sun with open-world shadows that follow the eye,
|
|
904
1181
|
* hemisphere fill, sky-coloured haze and the AgX tone curve. Every value is the game's.
|
|
@@ -915,7 +1192,103 @@ export { readVirtualShadowMarker } from "./render/virtual-shadow.js";
|
|
|
915
1192
|
* ctx.add(daylight);
|
|
916
1193
|
*/
|
|
917
1194
|
export { Daylight } from "./render/daylight.js";
|
|
1195
|
+
/**
|
|
1196
|
+
* Unreal 5.8.3's tone curve, the default tone mapping of `createRenderer` and `Game`: a filmic curve in ACEScg
|
|
1197
|
+
* (slope 0.88, toe 0.55, shoulder 0.26) after the gamut expansion and blue correction of Unreal's colour LUT.
|
|
1198
|
+
* `installFilmicToneMapping` registers it as three's custom tone mapping.
|
|
1199
|
+
*
|
|
1200
|
+
* @situation the frame should tone map the way a fresh Unreal project does
|
|
1201
|
+
* @constraint WebGPU renderers only: a renderer without a node library keeps ACES and reports `TN_TONEMAP`
|
|
1202
|
+
* @override `createRenderer({ toneMapping: "aces" | "agx" | "neutral" | "none" })` or `game.renderer.toneMapping` in the game config; setting `renderer.raw.toneMapping` later wins
|
|
1203
|
+
* @example const renderer = await createRenderer({ toneMapping: "aces" }); // the named override
|
|
1204
|
+
*/
|
|
1205
|
+
export { installFilmicToneMapping } from "./look/filmic-tone-mapping.js";
|
|
1206
|
+
export type { RendererToneMapping } from "./look/default-tone-mapping.js";
|
|
1207
|
+
/**
|
|
1208
|
+
* Auto exposure with Unreal 5.8.3's metering: a 64-bin histogram of log2 luminance (the darkest and brightest 10%
|
|
1209
|
+
* ignored), key 0.18 x 2, -10 to +20 EV100, 3 stops/s brighter and 1 stop/s darker. `AutoExposureNode` meters a colour
|
|
1210
|
+
* texture and outputs the adapted exposure; `exposureSettings` holds the defaults.
|
|
1211
|
+
*
|
|
1212
|
+
* @situation the frame should expose itself the way a fresh Unreal project does as the sun and the view change
|
|
1213
|
+
* @constraint WebGPU renderers only: a renderer without WebGPU keeps the fixed exposure and says so
|
|
1214
|
+
* @override every `IExposureSettings` field, spread over `exposureSettings` and passed to `AutoExposureNode`, replaces the Unreal default
|
|
1215
|
+
* @override `setExposureBias(stops)` is Unreal's Exposure Compensation, live: the game changes it per place or weather (`WorldEnvironment.apply` returns the node as `exposure`)
|
|
1216
|
+
* @situation a white snowfield or a bright storm should not meter to middle grey, and the compensation changes with the weather
|
|
1217
|
+
* @example const slow = { ...exposureSettings, rateDown: 0.5 }; const node = new AutoExposureNode(input, slow, 1);
|
|
1218
|
+
*/
|
|
1219
|
+
export { AutoExposureNode } from "./look/auto-exposure.js";
|
|
1220
|
+
export { exposureSettings } from "./look/exposure-settings.js";
|
|
1221
|
+
export type { IExposureSettings } from "./look/exposure-settings.js";
|
|
1222
|
+
/**
|
|
1223
|
+
* The node that says which lighting effects a scene runs and how strong they are, with a fresh Unreal 5.8.3 project's
|
|
1224
|
+
* defaults: the filmic tone curve, Unreal-metered auto exposure, screen-space GI and ambient occlusion, SMAA, Unreal's
|
|
1225
|
+
* bloom and local exposure. It builds the post chain through `renderer.createRenderChain()` and prints `TN_RENDER_CHAIN`
|
|
1226
|
+
* naming every stage as applied or refused with a reason. Property names are Godot's `Environment` where it has one.
|
|
1227
|
+
*
|
|
1228
|
+
* @situation a scene should light and tone map like a fresh Unreal level without wiring each post stage by hand
|
|
1229
|
+
* @situation turn one lighting effect off, or pick a cheaper tier, for a weak GPU or a stylised look
|
|
1230
|
+
* @constraint 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`
|
|
1231
|
+
* @constraint an unknown option value throws instead of becoming the default
|
|
1232
|
+
* @override every option on `IWorldEnvironmentOptions`: `tonemapMode: "aces" | "agx" | "neutral"`, `autoExposureEnabled: false` with a fixed `exposure`, `bloomEnabled`, `gtaoEnabled`, `ssgiEnabled`, `screenSpaceAA`
|
|
1233
|
+
* @example const world = new WorldEnvironment({ tonemapMode: "aces", autoExposureEnabled: false, exposure: 0.8 }); world.apply(renderer, scene, view);
|
|
1234
|
+
*/
|
|
1235
|
+
export { WorldEnvironment } from "./look/world-environment.js";
|
|
1236
|
+
export type {
|
|
1237
|
+
ChainStage,
|
|
1238
|
+
IWorldEnvironmentOptions,
|
|
1239
|
+
IWorldEnvironmentStageContext,
|
|
1240
|
+
IWorldEnvironmentTarget,
|
|
1241
|
+
OutputRenderer,
|
|
1242
|
+
ScreenSpaceAA,
|
|
1243
|
+
SsgiQuality,
|
|
1244
|
+
TonemapMode,
|
|
1245
|
+
} from "./look/world-environment.js";
|
|
1246
|
+
/**
|
|
1247
|
+
* The diagnosis switches of the calibration harness for the look (ladder layer, the alpha-squeeze BEFORE arm, a denoise
|
|
1248
|
+
* pass count, the film curve's channel clip, a GI visualisation). A game never sets them; the defaults are the shipped look.
|
|
1249
|
+
*
|
|
1250
|
+
* @situation a calibration capture needs one look effect off or one GI term alone
|
|
1251
|
+
* @constraint set them before the `WorldEnvironment` is built; the layer is 0 to 9 and 9 is everything on
|
|
1252
|
+
* @override each field of `lookDiagnostics`
|
|
1253
|
+
* @example lookDiagnostics.layer = 6; // no gather, no reflections
|
|
1254
|
+
*/
|
|
1255
|
+
export { lookDiagnostics } from "./look/look-diagnostics.js";
|
|
1256
|
+
/**
|
|
1257
|
+
* The quality tiers of the Unreal 5.8.3 look: what `high` (a desktop, Unreal's Epic), `medium` and `low` (a phone) turn
|
|
1258
|
+
* on, how a GPU family picks its start tier, and the global illumination and shadow filter settings per tier named
|
|
1259
|
+
* after Unreal's scalability levels. A `WorldEnvironment` with no options starts from `high`.
|
|
1260
|
+
*
|
|
1261
|
+
* `qualityTiers` holds the tier tables: `resolve` picks a start tier from a GPU class, `gi` and `shadow` read a tier's settings.
|
|
1262
|
+
*
|
|
1263
|
+
* @situation pick a start tier for the GPU class and read what that tier costs the look
|
|
1264
|
+
* @situation build a `WorldEnvironment` for a weaker device from a named tier
|
|
1265
|
+
* @constraint an unknown tier name throws with the names it expected
|
|
1266
|
+
* @override pass any `IWorldEnvironmentOptions` field after `qualityPreset(tier)`, or an explicit `tier` to `qualityTiers.resolve`
|
|
1267
|
+
* @example const world = new WorldEnvironment({ ...qualityPreset(qualityTiers.resolve({ gpuClass: renderer.gpuClass })), bloomEnabled: false });
|
|
1268
|
+
*/
|
|
1269
|
+
export { EPIC_SSGI, qualityPreset, qualityTiers } from "./look/quality.js";
|
|
1270
|
+
export type {
|
|
1271
|
+
FinalGatherMethod,
|
|
1272
|
+
IGiTier,
|
|
1273
|
+
IShadowFilter,
|
|
1274
|
+
IShadowTier,
|
|
1275
|
+
QualityTier,
|
|
1276
|
+
} from "./look/quality.js";
|
|
918
1277
|
export type { IDaylightOptions } from "./render/daylight.js";
|
|
1278
|
+
/**
|
|
1279
|
+
* Photometric exposure units: EV100 to the renderer multiplier and back, a physical camera's
|
|
1280
|
+
* EV100, and a meter reading. Conversion only; the exposure and the light values are the game's.
|
|
1281
|
+
*
|
|
1282
|
+
* @situation expose a frame lit in lux and nits with a physical camera exposure value
|
|
1283
|
+
* @constraint arguments must be finite; multipliers, apertures, shutter times, ISO and luminance must be > 0
|
|
1284
|
+
* @example renderer.toneMappingExposure = exposureFromEv100(ev100FromCamera(4, 1 / 60, 100));
|
|
1285
|
+
*/
|
|
1286
|
+
export {
|
|
1287
|
+
ev100FromCamera,
|
|
1288
|
+
ev100FromExposure,
|
|
1289
|
+
ev100FromLuminance,
|
|
1290
|
+
exposureFromEv100,
|
|
1291
|
+
} from "./render/exposure-units.js";
|
|
919
1292
|
export type { IVirtualShadowOptions, IVirtualShadowStats } from "./render/virtual-shadow.js";
|
|
920
1293
|
/**
|
|
921
1294
|
* Attach hundreds of built objects to the scene in slices, presenting a frame between each.
|
|
@@ -1256,7 +1629,9 @@ export type {
|
|
|
1256
1629
|
* @situation choose touch controls for a mobile device
|
|
1257
1630
|
* @situation can I raytrace on native
|
|
1258
1631
|
* @constraint only use the returned platform facts; native globals are host-owned
|
|
1259
|
-
* @constraint 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
|
|
1632
|
+
* @constraint 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
|
|
1633
|
+
* @constraint 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
|
|
1634
|
+
* @constraint 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
|
|
1260
1635
|
* @example if (isMobile()) showTouchControls();
|
|
1261
1636
|
*/
|
|
1262
1637
|
export { getPlatform, isMobile, isNative, isTouchscreenAvailable, isWeb } from "./platform.js";
|