@threenative/core 0.3.4 → 0.3.6
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/capabilities.json +1505 -79
- package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
- package/dist/{canvas-layer-DDmC_VVF.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
- package/dist/{game-CljaDv4D.d.ts → game-Jz4Fdoeb.d.ts} +114 -11
- package/dist/hot.d.ts +4 -4
- package/dist/index.d.ts +712 -118
- package/dist/index.js +12437 -4955
- package/dist/{gpu-readback-CqJEfWNQ.d.ts → model-lod-BDAUYgsS.d.ts} +80 -5
- package/dist/playtest.d.ts +6 -10
- package/dist/playtest.js +57 -24
- package/dist/react-css.d.ts +62 -0
- package/dist/react-css.js +591 -0
- package/dist/react.d.ts +2 -2
- package/dist/{renderer-CfsS2hxi.d.ts → renderer-9yEo9hPa.d.ts} +489 -22
- package/dist/terrain-jobs-worker.d.ts +2 -0
- package/dist/terrain-jobs-worker.js +130 -0
- package/dist/ui-layer.js +59 -8
- package/dist/world.d.ts +766 -73
- package/dist/world.js +9307 -3543
- package/gpl/recipes/export_world.py +18 -1
- package/mcp/blender-server.mjs +7 -4
- package/mcp/blender.mjs +3 -4
- package/mcp/engine-server.mjs +2 -2
- package/mcp/servers.mjs +4 -4
- package/package.json +15 -9
- package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
- package/patches/three@0.185.1.patch +6594 -700
- package/scripts/apply-three-patch.mjs +62 -4
- package/src/animation-blend.ts +264 -0
- package/src/animation-composition.ts +362 -0
- package/src/animation-layers.ts +260 -0
- package/src/animation-root-motion.ts +283 -0
- package/src/animation.ts +896 -0
- package/src/assets.ts +1303 -0
- package/src/atmosphere/index.ts +335 -0
- package/src/atmosphere/luts.ts +298 -0
- package/src/atmosphere/params.ts +323 -0
- package/src/audio.ts +912 -0
- package/src/billboard.ts +124 -0
- package/src/bone-lengths.ts +157 -0
- package/src/camera-shake.ts +116 -0
- package/src/canvas-layer.ts +47 -0
- package/src/clip-audit.ts +401 -0
- package/src/clustered-batch.ts +492 -0
- package/src/clustered-mesh.ts +638 -0
- package/src/compute-driven.ts +176 -0
- package/src/compute-timing.ts +318 -0
- package/src/config.ts +593 -0
- package/src/debug.ts +82 -0
- package/src/engine-render-hook.ts +25 -0
- package/src/entities.ts +79 -0
- package/src/entity-snapshot.ts +53 -0
- package/src/flight.ts +683 -0
- package/src/fluid-field.ts +748 -0
- package/src/fluid-particles.ts +1253 -0
- package/src/frame-budget.ts +1368 -0
- package/src/game.ts +2408 -0
- package/src/geometry-capture.ts +1098 -0
- package/src/gpu-class.ts +160 -0
- package/src/gpu-frame-observation.ts +424 -0
- package/src/gpu-readback.ts +143 -0
- package/src/gpu-scene-bvh.ts +464 -0
- package/src/grounding.ts +100 -0
- package/src/hot.ts +161 -0
- package/src/import-meta.d.ts +13 -0
- package/src/index.ts +1536 -0
- package/src/input.ts +690 -0
- package/src/instanced-batch-lod.ts +283 -0
- package/src/instanced-batch.ts +274 -0
- package/src/interpolation.ts +129 -0
- package/src/launch-diagnostics.ts +161 -0
- package/src/loop.ts +574 -0
- package/src/matrix-world.ts +245 -0
- package/src/merge-parts.ts +812 -0
- package/src/model-lod.ts +1315 -0
- package/src/net-protocol.ts +333 -0
- package/src/net-session.ts +477 -0
- package/src/net.ts +80 -0
- package/src/ocean/fft.ts +72 -0
- package/src/ocean/spectral.ts +728 -0
- package/src/particle-significance.ts +102 -0
- package/src/particles.ts +648 -0
- package/src/path-follow.ts +175 -0
- package/src/picking.ts +250 -0
- package/src/pipeline-census.ts +1566 -0
- package/src/platform.ts +210 -0
- package/src/playtest.ts +850 -0
- package/src/pointer-events.ts +411 -0
- package/src/pose-measure.ts +435 -0
- package/src/profiling/FrameCounters.ts +231 -0
- package/src/profiling/Spans.ts +548 -0
- package/src/profiling/opacity-convention.ts +21 -0
- package/src/profiling/render-list-validate.ts +175 -0
- package/src/profiling/render-trap-audit.ts +84 -0
- package/src/profiling/scene-warning.ts +190 -0
- package/src/profiling/span-probes.ts +191 -0
- package/src/profiling/unlit-foliage-warning.ts +149 -0
- package/src/projection-apply.ts +1529 -0
- package/src/projection-marker.ts +142 -0
- package/src/projection-plan.ts +1258 -0
- package/src/projection-skinned.ts +419 -0
- package/src/projection-stability.ts +409 -0
- package/src/projection-uniform.ts +328 -0
- package/src/random.ts +41 -0
- package/src/react-css.ts +604 -0
- package/src/react-glyphs.ts +114 -0
- package/src/react-host.ts +576 -0
- package/src/react-layout.ts +265 -0
- package/src/react.ts +60 -0
- package/src/render/alpha-antialiasing.ts +159 -0
- package/src/render/batched-velocity.ts +126 -0
- package/src/render/chain.ts +1021 -0
- package/src/render/daylight.ts +189 -0
- package/src/render/depth-pyramid.ts +596 -0
- package/src/render/foliage-alpha.ts +166 -0
- package/src/render/material-key.ts +60 -0
- package/src/render/mesh-pool.ts +144 -0
- package/src/render/probe-volume.ts +1668 -0
- package/src/render/resolution-subrect.ts +253 -0
- package/src/render/velocity.ts +442 -0
- package/src/render/virtual-shadow-pages.ts +827 -0
- package/src/render/virtual-shadow-partial.ts +174 -0
- package/src/render/virtual-shadow.ts +3330 -0
- package/src/render/world-impostor-surface.ts +722 -0
- package/src/render/world-impostor.ts +558 -0
- package/src/render-camera-cull.ts +441 -0
- package/src/render-pass-budget.ts +501 -0
- package/src/renderProjection.ts +758 -0
- package/src/renderer-config.ts +127 -0
- package/src/renderer.ts +1847 -0
- package/src/replay-protocol.ts +85 -0
- package/src/replay.ts +205 -0
- package/src/resolution-scaler.ts +819 -0
- package/src/rig-preparation.ts +271 -0
- package/src/ripple-field.ts +432 -0
- package/src/scale.ts +109 -0
- package/src/scene.ts +239 -0
- package/src/schedule.ts +155 -0
- package/src/skeletal-mesh.ts +61 -0
- package/src/skeleton.ts +100 -0
- package/src/snow-field.ts +744 -0
- package/src/softbody-topology.ts +269 -0
- package/src/softbody.ts +516 -0
- package/src/sprite-animator.ts +222 -0
- package/src/startup-readiness.ts +386 -0
- package/src/state.ts +66 -0
- package/src/static-transform.ts +274 -0
- package/src/storage-buffer.ts +253 -0
- package/src/streaming.ts +308 -0
- package/src/target-fps.ts +92 -0
- package/src/terrain-jobs-worker.ts +17 -0
- package/src/terrain-jobs.ts +353 -0
- package/src/textures.ts +39 -0
- package/src/tracers.ts +237 -0
- package/src/ui-bridge.ts +368 -0
- package/src/ui-hit-regions.ts +380 -0
- package/src/ui-layer.ts +83 -0
- package/src/ui-state.ts +220 -0
- package/src/version.ts +2 -0
- package/src/viewport.ts +253 -0
- package/src/warmup.ts +1357 -0
- package/src/water-surface.ts +384 -0
- package/src/wave-field.ts +524 -0
- package/src/world-capabilities.ts +131 -0
- package/src/world-cell-proxy.ts +392 -0
- package/src/world-cells.ts +10564 -0
- package/src/world-gpu-scene.ts +3354 -0
- package/src/world-heightmap.ts +82 -0
- package/src/world-package.ts +469 -0
- package/src/world-passes.ts +582 -0
- package/src/world-region.ts +17 -0
- package/src/world-terrain-splat.ts +564 -0
- package/src/world-tiles.ts +3826 -0
- package/src/world-topology.ts +370 -0
- package/src/world-validate.ts +48 -0
- package/src/world.ts +805 -0
package/src/index.ts
ADDED
|
@@ -0,0 +1,1536 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The version this library reports.
|
|
3
|
+
*
|
|
4
|
+
* It read `0.1.0` while the package published `0.2.0`, and `__tests__/build.spec.ts` asserted the
|
|
5
|
+
* stale literal, so the test held the bug in place rather than catching it. A literal is
|
|
6
|
+
* unavoidable here — core is bundled for browsers and cannot read `package.json` at runtime — so
|
|
7
|
+
* the spec now asserts this equals the manifest instead of asserting a number somebody typed.
|
|
8
|
+
*/
|
|
9
|
+
export const version = "0.3.6";
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Play a skinned or sprite animation from game code.
|
|
13
|
+
*
|
|
14
|
+
* A locomotion clip's playback rate is matched to the ground the body actually covers, so feet
|
|
15
|
+
* do not skate or spin — on by default, `strideSync: false` to keep the authored rate, and
|
|
16
|
+
* `player.stride` reports the measurement either way. Name the body a game moves as
|
|
17
|
+
* `strideRoot` when the rig is a child of it. Clips authored **in place** — every ActorX and
|
|
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.
|
|
20
|
+
* @situation play an animation on a character
|
|
21
|
+
* @situation switch a character between idle and attack clips
|
|
22
|
+
* @situation stop a walking character's feet from sliding or spinning
|
|
23
|
+
* @situation match a walk or run cycle to how fast a character is moving
|
|
24
|
+
* @situation match an in-place walk cycle with no root motion to the body's speed
|
|
25
|
+
* @situation find out what speed an animation clip was authored for
|
|
26
|
+
* @constraint name the body a game moves as strideRoot when the animated rig is a child of it
|
|
27
|
+
* @constraint a one-shot clip always plays at its authored rate; the matched rate re-times loops only
|
|
28
|
+
* @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
|
+
* @override strideSync controls whether the matched rate is applied while stride is still measured
|
|
30
|
+
* @example const player = new AnimationPlayer({ clips, root: rig, strideRoot: body });
|
|
31
|
+
*/
|
|
32
|
+
export { AnimationPlayer } from "./animation.js";
|
|
33
|
+
export type {
|
|
34
|
+
IAnimationPlayerOptions,
|
|
35
|
+
IAnimationPlayOptions,
|
|
36
|
+
IStrideReport,
|
|
37
|
+
} from "./animation.js";
|
|
38
|
+
/**
|
|
39
|
+
* Compose game-authored locomotion and masked actions on one Three.js mixer.
|
|
40
|
+
* @situation synchronize walk/run/strafe clips with different durations
|
|
41
|
+
* @situation reload with the upper body while locomotion continues
|
|
42
|
+
* @situation apply an additive recoil clip with an explicit reference pose
|
|
43
|
+
* @situation route root motion through collision-aware character movement
|
|
44
|
+
* @constraint one base phase, one masked override, at most two additive layers and eight actions
|
|
45
|
+
* @constraint root motion requires a separate rig below the body; advance, CharacterBody3D.move, finish with observed accepted motion after physics, then existing IK
|
|
46
|
+
* @constraint root motion excludes velocity-driven stride sync; unsupported parent transforms throw
|
|
47
|
+
* @constraint source clips remain immutable; dispose at scene exit
|
|
48
|
+
* @example const animation = new AnimationComposer({ root: rig, clips, samples: ["walk", "run"] });
|
|
49
|
+
* animation.setWeights([0.5, 0.5]); animation.update(dt);
|
|
50
|
+
*/
|
|
51
|
+
export { AnimationComposer } from "./animation-composition.js";
|
|
52
|
+
export type { IAnimationComposerOptions } from "./animation-composition.js";
|
|
53
|
+
export type { IAnimationLayer, IAnimationMask } from "./animation-layers.js";
|
|
54
|
+
export type {
|
|
55
|
+
IAnimationMotionDelta,
|
|
56
|
+
IAnimationRootMotionOptions,
|
|
57
|
+
} from "./animation-root-motion.js";
|
|
58
|
+
/**
|
|
59
|
+
* Select finite, normalized locomotion weights from sorted thresholds or a fixed triangulation.
|
|
60
|
+
* @situation calculate 1D walk/run blend weights from speed
|
|
61
|
+
* @situation calculate 2D locomotion weights from forward and strafe intent
|
|
62
|
+
* @constraint duplicate samples, collinear triangles and invalid/incomplete triangulations throw at initialization
|
|
63
|
+
* @constraint outside 2D queries project to the nearest boundary subedge; output is borrowed scratch
|
|
64
|
+
* @example const blend = new BlendSpace1D([0, 2]); animation.setWeights(blend.sample(speed));
|
|
65
|
+
*/
|
|
66
|
+
export { BlendSpace1D, BlendSpace2D } from "./animation-blend.js";
|
|
67
|
+
/**
|
|
68
|
+
* Shared preparation for an imported rigged character.
|
|
69
|
+
*
|
|
70
|
+
* Instances the rig with a skeleton-safe clone, normalises size with skin-aware measurement,
|
|
71
|
+
* validates requested clips against the file and rig at load time, and sets up AnimationPlayer
|
|
72
|
+
* with honest stride-root accounting.
|
|
73
|
+
* @situation put an animated character in the scene
|
|
74
|
+
* @situation my imported character renders deformed
|
|
75
|
+
* @situation instance an imported rigged character
|
|
76
|
+
* @situation validate animation clips on a character rig at load time
|
|
77
|
+
* @situation prepare a skinned character with safe skeleton cloning and stride sync
|
|
78
|
+
* @constraint use strideRoot to name the body moved by game code when the rig is parented under it
|
|
79
|
+
* @constraint requiredClips fails closed at load time if any requested clip is missing or binds 0 tracks
|
|
80
|
+
* @override strideSync controls whether locomotion playback rate matches ground covered
|
|
81
|
+
* @override size normalises the instance to real-world metres with skin-aware measurement
|
|
82
|
+
* @example import { SkeletalMesh3D } from "@threenative/core";
|
|
83
|
+
* const character = new SkeletalMesh3D({
|
|
84
|
+
* source: gltf.scene, clips: gltf.animations, requiredClips: ["idle", "walk"],
|
|
85
|
+
* size: { metres: 1.8, axis: "height" }, strideRoot: body,
|
|
86
|
+
* });
|
|
87
|
+
* body.add(character.root); character.play("idle");
|
|
88
|
+
* function update(dt: number): void { character.update(dt); }
|
|
89
|
+
*/
|
|
90
|
+
export { SkeletalMesh3D } from "./skeletal-mesh.js";
|
|
91
|
+
export type { ISkeletalMesh3DOptions } from "./skeletal-mesh.js";
|
|
92
|
+
/**
|
|
93
|
+
* Face a game-owned object toward a perspective or orthographic camera.
|
|
94
|
+
* @situation keep a world-space marker or nameplate facing the camera
|
|
95
|
+
* @situation billboard a tree, label, or effect under a rotated parent
|
|
96
|
+
* @constraint call update from the owning scene; no global scene scan is installed
|
|
97
|
+
* @constraint orthographic cameras use their forward direction, and lockAxis restricts world rotation
|
|
98
|
+
* @example const billboard = new Billboard3D(label, { camera });
|
|
99
|
+
* billboard.update();
|
|
100
|
+
*/
|
|
101
|
+
export { Billboard3D } from "./billboard.js";
|
|
102
|
+
export type { BillboardLockAxis, IBillboard3DOptions } from "./billboard.js";
|
|
103
|
+
/**
|
|
104
|
+
* Produce a game-authored camera shake offset for a template-owned camera rig.
|
|
105
|
+
* @situation add a hit, explosion, or landing shake to a camera
|
|
106
|
+
* @situation compose a transient camera offset after camera damping
|
|
107
|
+
* @constraint amplitude, rotationAmplitude, frequency, decay, and curve are required game choices
|
|
108
|
+
* @constraint update returns an offset and never writes to a camera
|
|
109
|
+
* @example const shake = new CameraShake({ amplitude, rotationAmplitude, frequency, decay, curve });
|
|
110
|
+
*/
|
|
111
|
+
export { CameraShake } from "./camera-shake.js";
|
|
112
|
+
export type { CameraShakeCurve, ICameraShakeOffset, ICameraShakeOptions } from "./camera-shake.js";
|
|
113
|
+
/**
|
|
114
|
+
* Create the portable asset loader a scene also receives as `ctx.assets`.
|
|
115
|
+
* @situation preload models, textures, or audio before a scene enters
|
|
116
|
+
* @situation load assets from a nonstandard base path or a compiled asset manifest
|
|
117
|
+
* @alias different area props
|
|
118
|
+
* @alias first playable screen external assets
|
|
119
|
+
* @constraint reuse the loader handed to scenes as `ctx.assets` instead of building parallel caches
|
|
120
|
+
* @example const assets = createAssetLoader({ basePath: "/assets" });
|
|
121
|
+
* const rock = await assets.texture("rock.png");
|
|
122
|
+
*/
|
|
123
|
+
export { createAssetLoader } from "./assets.js";
|
|
124
|
+
export { onLaunchFailure } from "./launch-diagnostics.js";
|
|
125
|
+
export { resetAudioCueLedger } from "./audio.js";
|
|
126
|
+
export type { ILaunchFailure, LaunchFailureKind } from "./launch-diagnostics.js";
|
|
127
|
+
export type { IAssetLoader, IAssetLoaderOptions, ITextureOptions } from "./assets.js";
|
|
128
|
+
export type {
|
|
129
|
+
IAudioBusOptions,
|
|
130
|
+
IAudioCompressorOptions,
|
|
131
|
+
IAudioPlayOptions,
|
|
132
|
+
} from "./audio.js";
|
|
133
|
+
/**
|
|
134
|
+
* Route effects through a named audio bus.
|
|
135
|
+
* @situation play a sound effect with a volume bus
|
|
136
|
+
* @situation mute or adjust a category of game audio
|
|
137
|
+
* @situation keep a gunshot audible at 20 metres by tuning positional falloff
|
|
138
|
+
* @situation hold a loud mix below clipping with a compressor on the bus
|
|
139
|
+
* @situation play cannon, wave, and ship sound effects
|
|
140
|
+
* @constraint create buses before playing clips and dispose them with the game
|
|
141
|
+
* @constraint refDistance and rolloffFactor tune positional falloff and apply to playAt only
|
|
142
|
+
* @constraint compressor takes threshold, knee, ratio, attack and release from the game and takes effect on the bus sum
|
|
143
|
+
* @supersedes new Audio(
|
|
144
|
+
* @example const effects = new AudioBus({ camera });
|
|
145
|
+
*/
|
|
146
|
+
export { AudioBus } from "./audio.js";
|
|
147
|
+
/**
|
|
148
|
+
* Manage a camera or screen-facing canvas layer.
|
|
149
|
+
* @situation place a HUD layer above the Three.js scene
|
|
150
|
+
* @situation attach a canvas layer to a camera
|
|
151
|
+
* @example const hud = new CanvasLayer(ctx.viewport);
|
|
152
|
+
*/
|
|
153
|
+
export { CanvasLayer } from "./canvas-layer.js";
|
|
154
|
+
export type {
|
|
155
|
+
IThreeNativeAudioConfig,
|
|
156
|
+
IThreeNativeAudioLoop,
|
|
157
|
+
IThreeNativeAudioOverride,
|
|
158
|
+
IThreeNativeAudioSpectrum,
|
|
159
|
+
IThreeNativeBootSplash,
|
|
160
|
+
IThreeNativeConfig,
|
|
161
|
+
IThreeNativeIconVariants,
|
|
162
|
+
IThreeNativeLodConfig,
|
|
163
|
+
IThreeNativeLodGenerationConfig,
|
|
164
|
+
IThreeNativeLodOverride,
|
|
165
|
+
IThreeNativeLodRuntimeConfig,
|
|
166
|
+
IThreeNativeTexturesConfig,
|
|
167
|
+
ThreeNativeBackgroundMode,
|
|
168
|
+
ThreeNativeLodMinTrianglesScope,
|
|
169
|
+
ThreeNativeLodPreset,
|
|
170
|
+
ThreeNativeOrientation,
|
|
171
|
+
ThreeNativeUiRenderer,
|
|
172
|
+
} from "./config.js";
|
|
173
|
+
/**
|
|
174
|
+
* Create a deterministic random source for portable gameplay.
|
|
175
|
+
* @situation get a seeded deterministic random number generator — the same mulberry32 a game would hand-roll
|
|
176
|
+
* @situation seed enemy patrol choices
|
|
177
|
+
* @situation reproduce the same procedural level in a playtest
|
|
178
|
+
* @constraint use the returned source instead of Math.random for replayable behavior
|
|
179
|
+
* @supersedes Math.random(
|
|
180
|
+
* @example const random = createRandom(42);
|
|
181
|
+
*/
|
|
182
|
+
export { createRandom } from "./random.js";
|
|
183
|
+
export type { IRandom } from "./random.js";
|
|
184
|
+
/**
|
|
185
|
+
* Define the portable game entry shared by web and native.
|
|
186
|
+
* @situation start a ThreeNative game from src/game.ts
|
|
187
|
+
* @situation register physics and gameplay plugins
|
|
188
|
+
* @situation let the player zoom the camera with a wheel, pinch, or gamepad axis
|
|
189
|
+
* @situation frame a camera behind the player
|
|
190
|
+
* @alias nearest target crosshair spawns
|
|
191
|
+
* @alias third-person camera
|
|
192
|
+
* @alias restart run without page reload
|
|
193
|
+
* @alias field of view while aiming
|
|
194
|
+
* @constraint keep DOM and React mounting in src/main.ts
|
|
195
|
+
* @constraint bind scroll or pinch and read the intent with ctx.input.axis(name); do not add a window wheel listener
|
|
196
|
+
* @constraint scroll: true uses the DOM wheel sign on browser and native: negative deltaY toward the user is positive intent
|
|
197
|
+
* @example const game = defineGame({ input: { zoom: { scroll: true, pinch: true } }, scenes: { Play }, start: "Play" });
|
|
198
|
+
*/
|
|
199
|
+
export { defineGame } from "./game.js";
|
|
200
|
+
export {
|
|
201
|
+
ATMOSPHERE_LUT_RESOLUTIONS,
|
|
202
|
+
Atmosphere,
|
|
203
|
+
AtmosphereLuts,
|
|
204
|
+
LUT_RESOLUTIONS,
|
|
205
|
+
directionFromSolarPosition,
|
|
206
|
+
directionalTransmittance,
|
|
207
|
+
resolveAtmosphereLutResolutions,
|
|
208
|
+
resolveAtmosphereParameters,
|
|
209
|
+
solarPosition,
|
|
210
|
+
solarPositionAt,
|
|
211
|
+
updateAtmosphereParameters,
|
|
212
|
+
zenithTransmittance,
|
|
213
|
+
} from "./atmosphere/index.js";
|
|
214
|
+
export type {
|
|
215
|
+
AtmosphereDirection,
|
|
216
|
+
AtmosphereRgb,
|
|
217
|
+
IAtmosphereLutResolution,
|
|
218
|
+
IAtmosphereLutResolutions,
|
|
219
|
+
IAtmosphereOptions,
|
|
220
|
+
IAtmosphereParameterPatch,
|
|
221
|
+
IAtmosphereParameters,
|
|
222
|
+
IAtmosphereScenePass,
|
|
223
|
+
IResolvedAtmosphereParameters,
|
|
224
|
+
ISolarPosition,
|
|
225
|
+
ISolarPositionInput,
|
|
226
|
+
} from "./atmosphere/index.js";
|
|
227
|
+
/**
|
|
228
|
+
* Register game-owned IComputeDriven objects with the shared compute lifetime.
|
|
229
|
+
* @situation use IComputeDriven for a cloth, fluid, boid, or other GPU simulation
|
|
230
|
+
* @situation run a cloth or fluid simulation with ordered GPU passes
|
|
231
|
+
* @situation keep IComputeDriven kernels warm before the first visible frame
|
|
232
|
+
* @constraint add the object through ctx.add so it attaches, dispatches, and releases with its scene
|
|
233
|
+
* @example const registry = new ComputeDrivenRegistry(); registry.add(cloth, ctx.renderer.raw);
|
|
234
|
+
*/
|
|
235
|
+
export { ComputeDrivenRegistry } from "./compute-driven.js";
|
|
236
|
+
export type { IComputeDriven } from "./compute-driven.js";
|
|
237
|
+
export { SoftBody3D } from "./softbody.js";
|
|
238
|
+
export type { ISoftBody3DOptions, ISoftBodyCollision } from "./softbody.js";
|
|
239
|
+
/**
|
|
240
|
+
* Pack a selected static scene into TSL storage nodes for an upstream BVH ray query.
|
|
241
|
+
* @situation trace thousands of scene rays inside a TSL kernel
|
|
242
|
+
* @situation build a contact-occlusion or visibility query over loaded meshes
|
|
243
|
+
* @constraint call rebuild() after a scene transform or geometry change; the snapshot is static by default
|
|
244
|
+
* @constraint rebuild() is an explicit CPU SAH build proportional to selected triangles; process() is a no-op, and the game pays upstream traversal per shader ray
|
|
245
|
+
* @example const bvh = ctx.add(new GPUSceneBVH(ctx.scene, { include: (object) => object.userData.traceable === true }));
|
|
246
|
+
*/
|
|
247
|
+
export { GPUSceneBVH, bvhIntersectFirstHit, rayStruct } from "./gpu-scene-bvh.js";
|
|
248
|
+
export type {
|
|
249
|
+
GPUSceneBVHTraceFunction,
|
|
250
|
+
IGPUSceneBVHMaterialGroup,
|
|
251
|
+
IGPUSceneBVHOptions,
|
|
252
|
+
} from "./gpu-scene-bvh.js";
|
|
253
|
+
/**
|
|
254
|
+
* Collapse many copies of one game-authored shape into a single draw, without counting them first.
|
|
255
|
+
*
|
|
256
|
+
* `new InstancedMesh(geometry, material, count)` needs the count before anything is placed, so a
|
|
257
|
+
* procedural builder ends up walking its layout twice or over-allocating. Place as you go and
|
|
258
|
+
* `build()` once; the shape, the surface and every transform stay the game's, and the built mesh
|
|
259
|
+
* is returned so instances can still be animated by the index `place` and `span` hand back.
|
|
260
|
+
* @situation draw hundreds of repeated props without hundreds of draw calls
|
|
261
|
+
* @situation draw thousands of identical instanced blocks or obstacles in one mesh
|
|
262
|
+
* @situation automatically select instanced prop detail from projected screen error using baked AutoLOD chains
|
|
263
|
+
* @situation place repeated props when the count is not known until the layout has been walked
|
|
264
|
+
* @situation build a chain, railing, cable, or tie rod out of point-to-point segments
|
|
265
|
+
* @alias landmarks points of interest
|
|
266
|
+
* @alias obstacles collectibles increasing pace
|
|
267
|
+
* @constraint geometry and material are required and come from the game; the batch chooses neither
|
|
268
|
+
* @constraint span stretches along +Y, so its geometry must be unit-height and centred on the origin
|
|
269
|
+
* @constraint placing after build() throws, and build() returns undefined when nothing was placed
|
|
270
|
+
* @constraint baked AutoLOD chains survive geometry clone/transform preparation and partition instances automatically into spatially bounded draws in the engine frame loop at 4 px projected error; public instance slots remain stable
|
|
271
|
+
* @constraint unavailable authored levels report TN_INSTANCED_LOD_FAILED once naming the batch; a million-triangle batch with no chain reports TN_INSTANCED_LOD_UNAVAILABLE
|
|
272
|
+
* @override autoLod: false leaves selection to the game; autoLod.maxPixelError and hysteresis override the measured-camera budget; lods supplies authored distance/geometry levels and wins over the baked chain
|
|
273
|
+
* @override castShadow and receiveShadow pass through to the built mesh and default to Three.js's own false
|
|
274
|
+
* @example const curbs = new InstancedBatch({ geometry: new BoxGeometry(1, 1, 1), material });
|
|
275
|
+
* curbs.place({ position: [x, 0.08, z], rotation: [0, angle, 0], scale: [length, 0.18, 0.42] });
|
|
276
|
+
* curbs.build({ castShadow: true, name: "curbs", parent: ctx.scene });
|
|
277
|
+
*/
|
|
278
|
+
export { InstancedBatch } from "./instanced-batch.js";
|
|
279
|
+
export type {
|
|
280
|
+
IInstancedBatchBuildOptions,
|
|
281
|
+
IInstancedBatchOptions,
|
|
282
|
+
IInstancedPlacement,
|
|
283
|
+
} from "./instanced-batch.js";
|
|
284
|
+
/**
|
|
285
|
+
* Merge pieces a game authored out of primitives into one buffer, keeping each piece's own look.
|
|
286
|
+
*
|
|
287
|
+
* `InstancedBatch` collapses many copies of one shape; this collapses many *different* shapes that
|
|
288
|
+
* never move relative to each other — a building, a ship, a character built from boxes, or the
|
|
289
|
+
* static parts of an imported glTF model. Two things go wrong every time and neither is about how
|
|
290
|
+
* any of it looks. `mergeGeometries` hands back `null` on mismatched inputs instead of throwing,
|
|
291
|
+
* and the usual mismatch is invisible: one `ExtrudeGeometry` is non-indexed while every other
|
|
292
|
+
* primitive is indexed, so the merge fails at the first piece and the scene never loads. And a
|
|
293
|
+
* merged buffer draws with one surface, so per-piece colour is gone unless every piece carries a
|
|
294
|
+
* flat `color` attribute written before the merge. Both are mechanical. By default every part is
|
|
295
|
+
* stripped to position and the normals are recomputed from the merged buffer; pass `preserve` to
|
|
296
|
+
* keep authored normals and texture UVs while baking each part's object transform. Geometry,
|
|
297
|
+
* placement, colour and the surface it draws with all stay the game's.
|
|
298
|
+
*
|
|
299
|
+
* @situation bake a building, ship or character authored out of primitives into one draw call
|
|
300
|
+
* @situation merge multiple static Three.js meshes into one mesh per material
|
|
301
|
+
* @situation consolidate the static parts of an imported glTF model into one buffer
|
|
302
|
+
* @situation preserve texture UV coordinates and authored normals while baking object transforms
|
|
303
|
+
* @situation merge many small geometries and keep each piece's own colour
|
|
304
|
+
* @situation stop mergeGeometries from silently returning null on an extruded shape
|
|
305
|
+
* @constraint every part is de-indexed; without preserve it is stripped to position and normals are recomputed from the merged buffer
|
|
306
|
+
* @constraint preserve keeps the listed channels, transforming position and normal by the part's placement matrix while UV values are retained unchanged
|
|
307
|
+
* @constraint a part that does not carry a listed preserve channel throws naming the label, the part and the channel
|
|
308
|
+
* @constraint either every part names a color or none does, and a mix throws
|
|
309
|
+
* @constraint an empty part list throws, and a merge three.js refuses throws naming the label
|
|
310
|
+
* @override color is per part and optional; without it no colour attribute is written and the surface alone decides
|
|
311
|
+
* @override preserve is optional and empty by default: position-only merge with recomputed normals, exactly as before
|
|
312
|
+
* @example const wall = new Mesh(mergeParts(pieces, { label: "gatehouse" }), stone);
|
|
313
|
+
* // pieces are meshes, or { geometry, matrix, color } when the colour is per piece:
|
|
314
|
+
* const banner = mergeParts([{ color: 0x8b2f1a, geometry: cloth, matrix: placement }], { label: "banner" });
|
|
315
|
+
* // keep a model's texture UVs and authored normals while baking its transforms:
|
|
316
|
+
* const hull = mergeParts(hullParts, { label: "hull", preserve: ["uv", "normal"] });
|
|
317
|
+
*/
|
|
318
|
+
export { mergeParts } from "./merge-parts.js";
|
|
319
|
+
export type { IMergePart, IMergePartsOptions } from "./merge-parts.js";
|
|
320
|
+
/**
|
|
321
|
+
* Bake a hierarchy's static meshes into one mesh per material, with their transforms baked in.
|
|
322
|
+
*
|
|
323
|
+
* @situation collapse a building or ship of dozens of boxes into one draw call per material
|
|
324
|
+
* @situation consolidate the static parts of a group before adding it to the scene
|
|
325
|
+
* @constraint the material is the game's own instance and the split follows the materials the game
|
|
326
|
+
* already made; nothing here decides appearance
|
|
327
|
+
* @constraint the meshes come back in root's local space and unparented, with the originals still in the
|
|
328
|
+
* tree: add them to root and remove the sources yourself, or both draw
|
|
329
|
+
* @constraint a skinned or instanced mesh, and a mesh with several materials, is left out — its
|
|
330
|
+
* vertices are not its own to bake
|
|
331
|
+
* @constraint a group where only some meshes carry uv throws naming the label rather than losing the
|
|
332
|
+
* texture mapping; a missing normal is recomputed
|
|
333
|
+
* @override skip leaves one mesh out of its group and out of the result
|
|
334
|
+
* @example const [hull, deck] = mergeByMaterial(ship, { label: "ship" });
|
|
335
|
+
* // a piece that must keep moving at run time:
|
|
336
|
+
* const [steady] = mergeByMaterial(ship, { label: "ship", skip: (mesh) => mesh.name === "radar" });
|
|
337
|
+
*/
|
|
338
|
+
export { mergeByMaterial } from "./merge-parts.js";
|
|
339
|
+
export type { IMergeByMaterialOptions } from "./merge-parts.js";
|
|
340
|
+
/**
|
|
341
|
+
* Read a debug switch from the URL, or from `TN_DEBUG_*` in the environment on a native launch.
|
|
342
|
+
* @situation read a debug toggle from the URL or an environment variable
|
|
343
|
+
* @constraint a name in camelCase becomes UPPER_SNAKE: `debugFlag("freeCam")` reads `?freeCam` or `TN_DEBUG_FREE_CAM`
|
|
344
|
+
* @constraint `0` and `false` are off, so a saved URL cannot turn a switch back on
|
|
345
|
+
* @example import { debugFlag } from "@threenative/core";
|
|
346
|
+
* if (debugFlag("freeCam")) camera.flyMode = true;
|
|
347
|
+
*/
|
|
348
|
+
export { debugFlag } from "./debug.js";
|
|
349
|
+
/**
|
|
350
|
+
* Publish one game object under `__THREENATIVE__.debug` for a capture script or the console.
|
|
351
|
+
* @situation expose a game object to a capture script or the console in dev builds
|
|
352
|
+
* @constraint development builds only; a production build publishes nothing
|
|
353
|
+
* @example import { exposeDebug } from "@threenative/core";
|
|
354
|
+
* exposeDebug("player", player);
|
|
355
|
+
* // then from the console: __THREENATIVE__.debug.player
|
|
356
|
+
*/
|
|
357
|
+
export { exposeDebug } from "./debug.js";
|
|
358
|
+
/**
|
|
359
|
+
* Draw a model too detailed for the screen to resolve, without submitting the part it cannot.
|
|
360
|
+
*
|
|
361
|
+
* **This is on, and a game does not call it.** Any primitive of 65,536 triangles or more bakes to a
|
|
362
|
+
* cluster DAG in the asset pipeline, the loader returns a `ClusteredMesh` for it, and the engine
|
|
363
|
+
* takes the cut every frame before it renders. Each frame the mesh submits one draw holding only
|
|
364
|
+
* the clusters whose error projects to fewer than `errorPixels` screen pixels; a mesh nothing has
|
|
365
|
+
* cut yet draws in full, so the worst case is an ordinary `Mesh`. Geometry, surface and every
|
|
366
|
+
* appearance parameter stay the game's.
|
|
367
|
+
*
|
|
368
|
+
* @situation draw a model too detailed for the screen to resolve
|
|
369
|
+
* @situation import a scanned or sculpted mesh of millions of triangles and still hold the frame
|
|
370
|
+
* @situation stop a dense rock face or terrain body from costing its full triangle count up close
|
|
371
|
+
* @constraint the bake happens in the asset pipeline, never at run time — there is no runtime flag
|
|
372
|
+
* @constraint the payload costs about 3-4x a baked primitive's bytes; `assets.models.virtual: "none"` opts out and `minSourceTriangles` moves the 65,536 line
|
|
373
|
+
* @constraint needs a perspective camera; a screen-space error has no meaning without one
|
|
374
|
+
* @constraint one shadow cut is chosen at load and does not follow a shadow camera
|
|
375
|
+
* @override errorPixels sets the screen-space error budget, default 1 pixel
|
|
376
|
+
* @override recutDistance sets how far the camera moves before the cut is retaken, default a thousandth of the mesh's radius
|
|
377
|
+
* @example
|
|
378
|
+
* // Nothing to call: the loader returns one of these and the engine cuts it every frame.
|
|
379
|
+
* const face = await ctx.assets.model("quarry-face.glb");
|
|
380
|
+
* ctx.scene.add(face.scene);
|
|
381
|
+
*/
|
|
382
|
+
export { ClusteredMesh } from "./clustered-mesh.js";
|
|
383
|
+
/**
|
|
384
|
+
* Draw many copies of one over-detailed body, each at the detail its own distance earns.
|
|
385
|
+
*
|
|
386
|
+
* `InstancedBatch` collapses repeated props into one draw and gives every copy the same triangles.
|
|
387
|
+
* This gives a copy two hundred metres away a coarser cut than one twelve metres away, and still
|
|
388
|
+
* submits one draw per distance group rather than one per copy — which is what makes four hundred
|
|
389
|
+
* scanned boulders affordable. The shape, the surface and every transform stay the game's.
|
|
390
|
+
*
|
|
391
|
+
* @situation draw hundreds of copies of a scanned or sculpted body without hundreds of draw calls
|
|
392
|
+
* @situation stop distant copies of a dense prop from costing their full triangle count
|
|
393
|
+
* @constraint the body's geometry must carry a cluster table from `assets.models.virtual`
|
|
394
|
+
* @constraint every copy is placed before build(); place() after build() throws
|
|
395
|
+
* @override distanceRatio sets how wide one distance group is, default 1.25
|
|
396
|
+
* @override errorPixels sets the screen-space error budget, default 1 pixel
|
|
397
|
+
* @example
|
|
398
|
+
* const boulders = new ClusteredBatch({ geometry, material, table });
|
|
399
|
+
* boulders.place({ position: [x, y, z], rotation: [0, angle, 0] });
|
|
400
|
+
* boulders.build({ name: "boulders", parent: ctx.scene });
|
|
401
|
+
* // in the scene's update, before the render:
|
|
402
|
+
* boulders.update(ctx.camera, ctx.renderer.domElement.height);
|
|
403
|
+
*/
|
|
404
|
+
export { ClusteredBatch } from "./clustered-batch.js";
|
|
405
|
+
export type {
|
|
406
|
+
IClusteredBatchBuildOptions,
|
|
407
|
+
IClusteredBatchOptions,
|
|
408
|
+
IClusteredPlacement,
|
|
409
|
+
} from "./clustered-batch.js";
|
|
410
|
+
/**
|
|
411
|
+
* Take every clustered mesh under a root through this frame's cut, before the render.
|
|
412
|
+
*
|
|
413
|
+
* The engine already does this for the scene it renders; reach for it only to cut a subtree the
|
|
414
|
+
* engine does not render, such as one staged for a camera of your own.
|
|
415
|
+
*
|
|
416
|
+
* @situation cut a virtual-geometry subtree the engine does not render itself
|
|
417
|
+
* @example updateClusteredMeshes(stagedRoot, myCamera, ctx.renderer.domElement.height);
|
|
418
|
+
*/
|
|
419
|
+
export { updateClusteredMeshes } from "./clustered-mesh.js";
|
|
420
|
+
// `VirtualGeometryPlugin`, `selectClusterCut` and `pixelsPerUnit` are deliberately not exported: the
|
|
421
|
+
// loader registers the plugin itself, and the other two are the rule's internals — a game that had
|
|
422
|
+
// to call them would be re-implementing the cut rather than using it.
|
|
423
|
+
export type { IClusteredMeshOptions, IClusterTable } from "./clustered-mesh.js";
|
|
424
|
+
/**
|
|
425
|
+
* Draw a model at the detail its projected geometric error earns, from a chain the asset cook baked.
|
|
426
|
+
*
|
|
427
|
+
* **This is engine-owned, and a game does not call it.** `assets.lod: {}` opts in — the default-on
|
|
428
|
+
* front door opens after qualification — the `model` pass bakes `TN_discrete_lod` into eligible
|
|
429
|
+
* models, the loader registers the reader, and the engine runs the selection every frame before it
|
|
430
|
+
* renders. Each frame the mesh picks the cheapest baked level whose measured error projects to fewer
|
|
431
|
+
* than the resolved pixel budget, taking the camera's own projection, zoom, viewport and a
|
|
432
|
+
* conservative nearest depth into account. Refinement is immediate; coarsening waits for the
|
|
433
|
+
* resolved hysteresis. A mesh with no baked chain draws its full geometry.
|
|
434
|
+
*
|
|
435
|
+
* @situation draw a vehicle or hull built from many small meshes at distance without its full triangles
|
|
436
|
+
* @situation stop a distant model from costing its authored mesh count and triangle count
|
|
437
|
+
* @situation one source model, right detail by default, no hand-authored LOD files
|
|
438
|
+
* @constraint the chain is baked by the asset cook; there is no runtime generation and no runtime flag
|
|
439
|
+
* @constraint `assets.lod: false` opts out globally and `assets.lod.overrides` per asset, with no runtime controller installed
|
|
440
|
+
* @constraint only static indexed triangles are eligible; skinned, morphed, alpha-blended or authored-LOD meshes keep full detail
|
|
441
|
+
* @constraint the real gate is measured benefit: a level must save at least `minSaving` (20% default) of its predecessor, and a mesh that cannot is skipped, not forced
|
|
442
|
+
* @override `assets.lod.generation.maxLevels`, `.minTriangles`, `.minTrianglesScope`, `.minSaving` and `.errorTargets` move the bake's ceiling, pre-filter, its scope, its saving rule and its error ladder; `assets.lod.runtime.maxPixelError` and `.hysteresis` move the runtime budget and coarsen band; all by project, preset or asset
|
|
443
|
+
* @example
|
|
444
|
+
* // Nothing to call: the loader returns a mesh with the chain and the engine selects every frame.
|
|
445
|
+
* const hull = await ctx.assets.model("hull.glb");
|
|
446
|
+
* ctx.scene.add(hull.scene);
|
|
447
|
+
*/
|
|
448
|
+
export {
|
|
449
|
+
DISCRETE_LOD_DEFAULT_ERROR_PIXELS,
|
|
450
|
+
DISCRETE_LOD_DEFAULT_HYSTERESIS,
|
|
451
|
+
updateModelLods,
|
|
452
|
+
} from "./model-lod.js";
|
|
453
|
+
/**
|
|
454
|
+
* The full-detail geometry of a mesh the loader gave an automatic LOD chain.
|
|
455
|
+
*
|
|
456
|
+
* Selection swaps `mesh.geometry`, so a ray test or a collision body built from the current geometry
|
|
457
|
+
* would change with the camera. Framework picking and gameplay collide against this instead: the
|
|
458
|
+
* authored LOD0, which never changes as the camera moves.
|
|
459
|
+
*
|
|
460
|
+
* @situation collide or ray-test the authored geometry of a mesh whose render detail changes with distance
|
|
461
|
+
* @example const geometry = baseGeometryOf(mesh);
|
|
462
|
+
*/
|
|
463
|
+
export { baseGeometryOf } from "./model-lod.js";
|
|
464
|
+
/**
|
|
465
|
+
* The screen pixels one world unit covers at `depth` for this camera and viewport.
|
|
466
|
+
*
|
|
467
|
+
* Perspective divides the projected scale by the depth; orthographic has no depth term and uses the
|
|
468
|
+
* frustum height instead. This is the number a level of detail is chosen against: multiply a
|
|
469
|
+
* level's world-space error by it and you have the on-screen error a player can see, which is the
|
|
470
|
+
* comparison `updateModelLods` makes from the baked chain.
|
|
471
|
+
*
|
|
472
|
+
* @situation pick a level of detail from an object's projected size in pixels on screen
|
|
473
|
+
* @situation know how many screen pixels a world-space error covers at a given distance
|
|
474
|
+
* @constraint a non-positive viewport height, a non-positive frustum height or an unprojectable camera throws
|
|
475
|
+
* @constraint a non-positive depth has no projected scale and returns Infinity
|
|
476
|
+
* @example const pixels = lodPixelScale(camera, canvas.clientHeight, mesh.position.distanceTo(camera.position));
|
|
477
|
+
*/
|
|
478
|
+
export { lodPixelScale } from "./model-lod.js";
|
|
479
|
+
/**
|
|
480
|
+
* Keep an object drawn even when the render camera cannot resolve it.
|
|
481
|
+
*
|
|
482
|
+
* The engine's projected-size gate is on by default: an object whose world bounding sphere
|
|
483
|
+
* projects to fewer than 0.5 raster pixels in the camera about to render it is not submitted, per
|
|
484
|
+
* camera. Mark the player's own cockpit, a nameplate, a quest marker, or anything a game never
|
|
485
|
+
* wants to pop out of the frame. `alwaysRender(object, false)` removes the marker. Camera-attached
|
|
486
|
+
* objects and shadow casters are already kept, and the number of marked objects is reported beside
|
|
487
|
+
* the cull in the `TN_PROJECTION` window rather than hidden. The threshold itself is
|
|
488
|
+
* `renderer.minimumProjectedPixels` — a larger number cuts more aggressively, `false` leaves
|
|
489
|
+
* every object drawn while still measuring.
|
|
490
|
+
*
|
|
491
|
+
* @situation keep a small object drawn when the engine would skip it as too far to resolve
|
|
492
|
+
* @situation stop my cockpit, marker or player model popping out at distance
|
|
493
|
+
* @situation a tiny object disappeared at range and I need it always visible
|
|
494
|
+
* @situation widen or narrow the projected-size cull with a named threshold
|
|
495
|
+
* @constraint the marker is per object and is reported as `exemptMarked` in the projection window
|
|
496
|
+
* @constraint `renderer.minimumProjectedPixels: false` leaves the scene drawn and keeps the measurement on
|
|
497
|
+
* @override renderer.minimumProjectedPixels sets the projected-pixel threshold, default 0.5
|
|
498
|
+
* @example import { alwaysRender } from "@threenative/core";
|
|
499
|
+
* alwaysRender(ctx.camera.children[0]); // a camera-attached cockpit stays drawn
|
|
500
|
+
*/
|
|
501
|
+
export { alwaysRender } from "./render-camera-cull.js";
|
|
502
|
+
/**
|
|
503
|
+
* Walk the scene graph's world matrices each frame without recursing into a hidden subtree.
|
|
504
|
+
*
|
|
505
|
+
* On by default as `renderer.matrixWorld: "visible"`. three's `updateMatrixWorld` recurses into
|
|
506
|
+
* every child whatever its `visible` flag, so a hidden LOD body, a merged stand-in and a parked
|
|
507
|
+
* model cost a world-matrix multiply each while nothing under them can draw. This pass mirrors
|
|
508
|
+
* three exactly for every visible node and defers a hidden node's subtree until the frame it shows
|
|
509
|
+
* again. A class that overrides `updateMatrixWorld` (`SkinnedMesh`, `Camera`) runs its own, and a
|
|
510
|
+
* hidden node that holds bones is walked, so no skeleton or view matrix goes stale.
|
|
511
|
+
*
|
|
512
|
+
* @situation update the world matrices of the visible objects each frame instead of the whole scene
|
|
513
|
+
* @situation the per-frame world matrix walk is hot in a profile
|
|
514
|
+
* @situation stop multiplying matrices for hidden models, LOD levels and merged stand-ins
|
|
515
|
+
* @situation a game needs every node walked, exactly as three's own updateMatrixWorld does
|
|
516
|
+
* @constraint a game that reads a hidden object's matrixWorld directly must use getWorldPosition or updateWorldMatrix(true, false) first
|
|
517
|
+
* @constraint `renderer.matrixWorld: "all"` visits every node; `TN_PROJECTION` reports the visited count either way
|
|
518
|
+
* @override renderer.matrixWorld: "all" runs three's full walk instead of the visible-only default
|
|
519
|
+
* @example import { MatrixWorldPass } from "@threenative/core";
|
|
520
|
+
* const pass = new MatrixWorldPass(); // renderer.matrixWorld defaults to "visible"
|
|
521
|
+
*/
|
|
522
|
+
export { MatrixWorldPass } from "./matrix-world.js";
|
|
523
|
+
export type { IMatrixWorldReport, MatrixWorldMode } from "./matrix-world.js";
|
|
524
|
+
/**
|
|
525
|
+
* Read where the frame's milliseconds went, per presented frame, on any platform; each
|
|
526
|
+
* `TN_FRAME_BUDGET` window also carries the GPU time per resolved frame and the draw calls and
|
|
527
|
+
* triangles each render pass submitted.
|
|
528
|
+
* @situation show an on-screen frame time meter with p50, p95 and p99 percentiles
|
|
529
|
+
* @situation find out why a game runs slowly on a phone
|
|
530
|
+
* @situation attribute a frame to present wait, simulation, three.js render, or overlay
|
|
531
|
+
* @situation tell whether the GPU is the frame's constraint from a per-frame series, not one lagged timestamp
|
|
532
|
+
* @situation split a frame's draw calls and triangles per render pass (main, shadow, reflection)
|
|
533
|
+
* @situation tell a shadow or reflection pass's cost from the main colour pass
|
|
534
|
+
* @situation retain every asynchronous GPU render frame for a complete paired benchmark
|
|
535
|
+
* @constraint on by default and printed as TN_FRAME_BUDGET; defineGame({ frameBudget: false }) silences the marker, not the measurement
|
|
536
|
+
* @constraint per-pass numbers are attributed to the innermost active render call, so nested shadow and reflection passes do not read as main
|
|
537
|
+
* @constraint GPU is a mean/p50/p95/max series over resolved frames (`gpu`) with `gpuStale` counting frames that had no fresh reading; absent means no timestamps, never zero
|
|
538
|
+
* @constraint `ctx.renderer.observeGpuFrames({ maxFrames, maxQueries })` is opt-in, bounded and fail-closed; `take()` delivers immutable complete render-query groups once, while `status()` reports pending/undrained/queued membership and losses
|
|
539
|
+
* @constraint observation preserves ordinary sampling; a complete benchmark explicitly requests `renderer.gpuTimestampFrameInterval: 1` and joins Three query IDs to actual world renders, including separate overlay IDs
|
|
540
|
+
* @constraint `stop()` fences allocated frames and drains existing resolver work; `dispose()` invalidates late completions, and a failed observation must be disposed before replacement
|
|
541
|
+
* @example defineGame({ frameBudget: { reportEvery: 120 }, scenes: { Play } });
|
|
542
|
+
*/
|
|
543
|
+
export {
|
|
544
|
+
FRAME_BUDGET_MARKER,
|
|
545
|
+
FRAME_BUDGET_PHASES,
|
|
546
|
+
FRAME_HITCH_MARKER,
|
|
547
|
+
FrameBudget,
|
|
548
|
+
} from "./frame-budget.js";
|
|
549
|
+
export type {
|
|
550
|
+
FrameBudgetPhase,
|
|
551
|
+
IFrameBudgetOptions,
|
|
552
|
+
IFrameBudgetSimulation,
|
|
553
|
+
IFrameBudgetPassSummary,
|
|
554
|
+
IFrameBudgetSummary,
|
|
555
|
+
IFrameBudgetWindow,
|
|
556
|
+
IFramePhaseSample,
|
|
557
|
+
} from "./frame-budget.js";
|
|
558
|
+
export type { FramePassKind, IRenderPassSample, MainDrawSource } from "./render-pass-budget.js";
|
|
559
|
+
/**
|
|
560
|
+
* Read what frame rate a game gets when its config does not say, and why.
|
|
561
|
+
*
|
|
562
|
+
* `display.maxFps` follows the display — capped at 120 on desktop and web, 60 on mobile — rather
|
|
563
|
+
* than the 60 every template used to ship, and an explicit number still wins with `0` still
|
|
564
|
+
* uncapping. The engine calls this itself; a game calls it when it needs the same number for its
|
|
565
|
+
* own frame-rate-dependent work, and `TN_FRAME_BUDGET` reports the resolved target and its source
|
|
566
|
+
* on every window.
|
|
567
|
+
* @situation my game does frame-rate-dependent work and must not hardcode 60
|
|
568
|
+
* @constraint pass the measured display rate when you have one; without it the answer is the 60 fallback and says so
|
|
569
|
+
* @example resolveTargetFps(config, getPlatform()).targetFps;
|
|
570
|
+
*/
|
|
571
|
+
export {
|
|
572
|
+
DEFAULT_TARGET_FPS,
|
|
573
|
+
MAX_TARGET_FPS,
|
|
574
|
+
resolveTargetFps,
|
|
575
|
+
snapRefreshRate,
|
|
576
|
+
} from "./target-fps.js";
|
|
577
|
+
export type { ITargetFps, TargetFpsSource } from "./target-fps.js";
|
|
578
|
+
/**
|
|
579
|
+
* Attribute the render phase to 100% with a nested span tree, off unless `TN_FRAME_SPANS` asks.
|
|
580
|
+
* Every non-leaf reports its own time minus the spans inside it, so an unmeasured part shows up as
|
|
581
|
+
* a residual instead of being filed under "other"; a child that outlives its parent reports a
|
|
582
|
+
* negative residual rather than a clamped zero.
|
|
583
|
+
* @situation find out what inside the render phase is actually costing the frame
|
|
584
|
+
* @situation tell a shadow pass's traversal from the main pass's, with the residual computed
|
|
585
|
+
* @situation price an optimisation against a measured part of the phase rather than the whole of it
|
|
586
|
+
* @constraint off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return
|
|
587
|
+
* @constraint the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames
|
|
588
|
+
* @constraint measurement only: no span changes what is drawn, in what order, or with which renderer
|
|
589
|
+
* @example if (spansRequested()) setSpanRecorder(new SpanRecorder());
|
|
590
|
+
*/
|
|
591
|
+
export {
|
|
592
|
+
SPANS,
|
|
593
|
+
SPANS_FLAG,
|
|
594
|
+
SPANS_MARKER,
|
|
595
|
+
SPAN_COUNT,
|
|
596
|
+
SPAN_NAMES,
|
|
597
|
+
SpanRecorder,
|
|
598
|
+
addSpan,
|
|
599
|
+
beginSpan,
|
|
600
|
+
endSpan,
|
|
601
|
+
formatSpansWindow,
|
|
602
|
+
setSpanRecorder,
|
|
603
|
+
spanNow,
|
|
604
|
+
spanRecorder,
|
|
605
|
+
spansRequested,
|
|
606
|
+
} from "./profiling/Spans.js";
|
|
607
|
+
export type { ISpanSummary, ISpanWindow, SpanId } from "./profiling/Spans.js";
|
|
608
|
+
/**
|
|
609
|
+
* Attach the span probes to a renderer: three's `render`, `_projectObject`, the render list's
|
|
610
|
+
* `sort`, the per-draw submission, and the scene-graph walk. Installed for you when
|
|
611
|
+
* `TN_FRAME_SPANS` asks; exported so a harness can wrap a renderer it owns.
|
|
612
|
+
* @situation measure which part of three's render path costs the frame
|
|
613
|
+
* @situation attach the span tree to a renderer a test or a tool constructed itself
|
|
614
|
+
* @constraint returns an uninstall that restores every wrapper, asserted by test
|
|
615
|
+
* @constraint a renderer whose internals have moved loses that span rather than throwing, and it is absent from the report rather than zero
|
|
616
|
+
* @constraint only the outermost `_projectObject` opens a span, because three's recurses per child
|
|
617
|
+
* @example const uninstall = installSpanProbes(renderer.raw, scene);
|
|
618
|
+
*/
|
|
619
|
+
export { installSpanProbes } from "./profiling/span-probes.js";
|
|
620
|
+
export type { ISpanProbeTarget } from "./profiling/span-probes.js";
|
|
621
|
+
/**
|
|
622
|
+
* Count the frame's host-boundary crossings and the bytes it writes into GPU buffers, off unless
|
|
623
|
+
* `TN_FRAME_SPANS` asks for them. On the frame budget's own window as `counters`, so a crossing
|
|
624
|
+
* count and a millisecond split describe the same frames.
|
|
625
|
+
* @situation decide whether a CPU-bound frame is paying for the V8-to-host boundary
|
|
626
|
+
* @situation measure how many bytes a frame writes into GPU buffers, and how many commands it issues
|
|
627
|
+
* @constraint counts command-encoder and queue methods only; `mapAsync` and the presentation path are named, not folded in
|
|
628
|
+
* @constraint `gpuBytes` is `queue.writeBuffer` exactly, so it reconciles against a driver; texture uploads are not included
|
|
629
|
+
* @constraint `jsAllocBytes` needs `performance.memory` and stays absent where the platform lacks it
|
|
630
|
+
* @example const counters = FrameCounters.install(counterDeviceOf(renderer.raw));
|
|
631
|
+
*/
|
|
632
|
+
export { FrameCounters, counterDeviceOf } from "./profiling/FrameCounters.js";
|
|
633
|
+
export type { ICounterDevice, IFrameCounters } from "./profiling/FrameCounters.js";
|
|
634
|
+
/**
|
|
635
|
+
* Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its
|
|
636
|
+
* 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 as
|
|
638
|
+
* `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
|
|
639
|
+
* @situation find out whether a slow frame is the scene's shape or the device
|
|
640
|
+
* @situation tell an authoring agent what to reduce before it promises a merge
|
|
641
|
+
* @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
|
|
642
|
+
* @constraint no verdict without a measured GPU reading and a pass census — an absent measurement is not evidence
|
|
643
|
+
* @constraint the record carries objects considered, draws per pass, triangles per draw and shadow-exempt casters, so the reader is not dependent on the ranking
|
|
644
|
+
* @example defineGame({ display: { maxFps: 60 }, scenes: { Play } });
|
|
645
|
+
*/
|
|
646
|
+
export {
|
|
647
|
+
SCENE_WARNING_MARKER,
|
|
648
|
+
describeSceneShape,
|
|
649
|
+
describeSceneWarning,
|
|
650
|
+
displayPeriodMs,
|
|
651
|
+
formatSceneWarning,
|
|
652
|
+
sceneWarning,
|
|
653
|
+
} from "./profiling/scene-warning.js";
|
|
654
|
+
export type { ISceneShape, ISceneWarning } from "./profiling/scene-warning.js";
|
|
655
|
+
/**
|
|
656
|
+
* Tell the agent that built the scene that its imported foliage is drawing with no image-based light:
|
|
657
|
+
* an alpha-cutout `MeshStandardMaterial` (or its Node twin) with `scene.environment` unset and no
|
|
658
|
+
* `envMap` of its own gets a hemisphere fill and one flat dark value, which is cardboard. Printed
|
|
659
|
+
* once per scene entry as `TN_UNLIT_FOLIAGE`, after `enter()`, with the fix in the same line.
|
|
660
|
+
* @situation catch the "why does my forest look like cardboard" question before a human plays it
|
|
661
|
+
* @situation audit a scene a game built from imported GLB foliage
|
|
662
|
+
* @constraint derived from the scene graph, not from a constant: cutout PBR with no environment in the scene and none on the material
|
|
663
|
+
* @constraint it changes nothing and never throws — the environment is appearance, so setting it stays the game's decision
|
|
664
|
+
* @override `material.userData.tnUnlitOk = true` on a material a game deliberately renders unlit (the same `userData.tn*` naming the alpha and impostor conventions use)
|
|
665
|
+
* @example defineGame({ scenes: { Forest } }); // one TN_UNLIT_FOLIAGE line when the forest has no sky
|
|
666
|
+
*/
|
|
667
|
+
export {
|
|
668
|
+
UNLIT_FOLIAGE_FIX,
|
|
669
|
+
UNLIT_FOLIAGE_MARKER,
|
|
670
|
+
formatUnlitFoliageWarning,
|
|
671
|
+
unlitFoliageWarning,
|
|
672
|
+
} from "./profiling/unlit-foliage-warning.js";
|
|
673
|
+
export type { IUnlitFoliageWarning } from "./profiling/unlit-foliage-warning.js";
|
|
674
|
+
/**
|
|
675
|
+
* Catch scene state that silently loses environment fill or ignores authored opacity.
|
|
676
|
+
* After `enter()` the game first applies the opacity convention: a drawn material with
|
|
677
|
+
* `opacity < 1` turns transparent and one `TN_OPACITY_TRANSPARENT` console warning names it
|
|
678
|
+
* (override: `alphaHash: true`, or `opacity: 1`). It then prints `TN_ENVIRONMENT_TOO_SMALL`
|
|
679
|
+
* as a console error with the fix, so playtest `noConsoleErrors` rejects it.
|
|
680
|
+
* @situation audit an equirectangular sky too narrow for three's WebGPU PMREM
|
|
681
|
+
* @situation find visible opaque materials whose authored opacity is ignored
|
|
682
|
+
* @constraint structural scene reads only, one visible-tree walk per entry, at most five material examples
|
|
683
|
+
* @constraint the audit itself changes no scene state; the game loop's opacity convention is the only writer
|
|
684
|
+
* @example renderTrapAudit(ctx.scene); // marker lines with the fixes, or an empty array
|
|
685
|
+
*/
|
|
686
|
+
export {
|
|
687
|
+
ENVIRONMENT_TOO_SMALL_MARKER,
|
|
688
|
+
OPACITY_IGNORED_MARKER,
|
|
689
|
+
renderTrapAudit,
|
|
690
|
+
} from "./profiling/render-trap-audit.js";
|
|
691
|
+
/**
|
|
692
|
+
* Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the
|
|
693
|
+
* subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and
|
|
694
|
+
* `invalidateStatic(object)` announces a write deeper inside one.
|
|
695
|
+
* @situation cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves
|
|
696
|
+
* @situation keep a frozen subtree correct when the game does move it after all
|
|
697
|
+
* @constraint staticness is authored, never guessed; no heuristic watches gameplay and decides for you
|
|
698
|
+
* @constraint it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless
|
|
699
|
+
* @constraint a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
|
|
700
|
+
* @example invalidateStatic(drawbridge);
|
|
701
|
+
*/
|
|
702
|
+
export {
|
|
703
|
+
STATIC_TRANSFORM_MARKER,
|
|
704
|
+
invalidateStatic,
|
|
705
|
+
isStatic,
|
|
706
|
+
refreshStaticTransforms,
|
|
707
|
+
resetStaticTransforms,
|
|
708
|
+
staticTransformCensus,
|
|
709
|
+
unmarkStatic,
|
|
710
|
+
} from "./static-transform.js";
|
|
711
|
+
/**
|
|
712
|
+
* Freeze a subtree nobody moves: `markStatic(root)` composes its transforms once and stops the
|
|
713
|
+
* per-frame recompose.
|
|
714
|
+
*
|
|
715
|
+
* It is the call a game makes on scenery, terrain, buildings and props. The engine re-arms a root
|
|
716
|
+
* whose own transform the game changes; a write deeper inside a frozen subtree is announced with
|
|
717
|
+
* `invalidateStatic(object)`.
|
|
718
|
+
*
|
|
719
|
+
* @situation freeze a static mesh or subtree so its matrices are not recomputed every frame
|
|
720
|
+
* @situation stop the engine recomposing the transforms of props, terrain and buildings each frame
|
|
721
|
+
* @constraint staticness is authored, never guessed; no heuristic watches gameplay and decides for you
|
|
722
|
+
* @constraint a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
|
|
723
|
+
* @example markStatic(island); invalidateStatic(drawbridge);
|
|
724
|
+
*/
|
|
725
|
+
export { markStatic } from "./static-transform.js";
|
|
726
|
+
export type { IStaticTransformCensus } from "./static-transform.js";
|
|
727
|
+
/**
|
|
728
|
+
* Prove that nothing a cache skipped changed the picture: `TN_RENDERLIST_VALIDATE=1` recomputes
|
|
729
|
+
* every world matrix the long way, every frame, and throws on the first element that disagrees
|
|
730
|
+
* with what the frame is about to draw.
|
|
731
|
+
* @situation prove a static freeze did not leave a stale transform on screen
|
|
732
|
+
* @situation gate a scene in CI against silent transform divergence
|
|
733
|
+
* @constraint off by default and expensive by construction — it does the work it is checking, twice
|
|
734
|
+
* @constraint it throws on the first divergence rather than logging; a validation mode that continues is one nobody reads
|
|
735
|
+
* @constraint it proves the frames it ran on and nothing else
|
|
736
|
+
* @example if (renderListValidationRequested()) console.log(formatValidationReport(report));
|
|
737
|
+
*/
|
|
738
|
+
export {
|
|
739
|
+
RENDERLIST_VALIDATE_FLAG,
|
|
740
|
+
RENDERLIST_VALIDATE_MARKER,
|
|
741
|
+
RenderListValidator,
|
|
742
|
+
formatValidationReport,
|
|
743
|
+
renderListValidationRequested,
|
|
744
|
+
validateWorldMatrices,
|
|
745
|
+
} from "./profiling/render-list-validate.js";
|
|
746
|
+
export type { IValidationReport } from "./profiling/render-list-validate.js";
|
|
747
|
+
export {
|
|
748
|
+
GEOMETRY_CAPTURE_DEFAULT_LIMIT,
|
|
749
|
+
GEOMETRY_CAPTURE_MAX_LIMIT,
|
|
750
|
+
GEOMETRY_CAPTURE_SORTS,
|
|
751
|
+
GEOMETRY_CAPTURE_TIMEOUT_MS,
|
|
752
|
+
GEOMETRY_CAPTURE_WALK_CAP,
|
|
753
|
+
GEOMETRY_ASSET_KEY,
|
|
754
|
+
} from "./geometry-capture.js";
|
|
755
|
+
export type {
|
|
756
|
+
GeometryCaptureSort,
|
|
757
|
+
IGeometryCaptureAsset,
|
|
758
|
+
IGeometryCaptureMesh,
|
|
759
|
+
IGeometryCapturePass,
|
|
760
|
+
IGeometryCaptureReport,
|
|
761
|
+
IGeometryCaptureRequest,
|
|
762
|
+
IGeometryCaptureRow,
|
|
763
|
+
} from "./geometry-capture.js";
|
|
764
|
+
/**
|
|
765
|
+
* Register work that reads a body or camera after physics has moved it and before this frame draws.
|
|
766
|
+
* The engine owns the phase ordering; a callback cannot be misplaced by plugin-array order.
|
|
767
|
+
* @situation read a body after physics has moved it
|
|
768
|
+
* @situation place a camera or aim from the solved character transform
|
|
769
|
+
* @constraint register from a scene context; callbacks are cleared when that scene exits
|
|
770
|
+
* @example afterPhysics(ctx, (dt) => camera.position.copy(player.mesh.position));
|
|
771
|
+
*/
|
|
772
|
+
export { afterPhysics } from "./loop.js";
|
|
773
|
+
export type { AfterPhysicsCallback } from "./loop.js";
|
|
774
|
+
/**
|
|
775
|
+
* Compose game-provided render nodes in a measured, fail-closed chain. Authored stages use an
|
|
776
|
+
* opaque id and anchor before or after a built-in or another supplied stage; the engine does not
|
|
777
|
+
* need to know the effect's visual vocabulary.
|
|
778
|
+
* @situation compose screen-space effects in a canonical order
|
|
779
|
+
* @situation insert a game-authored post stage into the measured render chain
|
|
780
|
+
* @situation report which render tier and velocity route actually ran
|
|
781
|
+
* @constraint stage factories own colour, strength, and all other appearance choices
|
|
782
|
+
* @constraint authored stages declare exactly one before or after anchor
|
|
783
|
+
* @example const chain = new RenderChain(renderer, { input: colour, stages, request: { stages: ["bloom"], tier: "auto" } });
|
|
784
|
+
*/
|
|
785
|
+
export {
|
|
786
|
+
RENDER_CHAIN_MARKER,
|
|
787
|
+
RENDER_CHAIN_STAGE_ORDER,
|
|
788
|
+
RENDER_CHAIN_TIERS,
|
|
789
|
+
RenderChain,
|
|
790
|
+
readRenderChainObservation,
|
|
791
|
+
readRenderChainReport,
|
|
792
|
+
} from "./render/chain.js";
|
|
793
|
+
export type {
|
|
794
|
+
IRenderChainApplied,
|
|
795
|
+
IRenderChainBudgetWindow,
|
|
796
|
+
IRenderChainDroppedStage,
|
|
797
|
+
IRenderChainOptions,
|
|
798
|
+
IRenderChainRenderer,
|
|
799
|
+
IRenderChainRequest,
|
|
800
|
+
IRenderChainStage,
|
|
801
|
+
IRenderChainStageContext,
|
|
802
|
+
IRenderChainVelocityMeasurement,
|
|
803
|
+
IRenderChainVelocityResult,
|
|
804
|
+
IRenderChainVelocityReport,
|
|
805
|
+
IRenderChainVelocityRequest,
|
|
806
|
+
RenderChainSource,
|
|
807
|
+
RenderChainStageId,
|
|
808
|
+
RenderChainStageName,
|
|
809
|
+
RenderChainTier,
|
|
810
|
+
RenderChainTierRequest,
|
|
811
|
+
RenderChainVelocitySource,
|
|
812
|
+
} from "./render/chain.js";
|
|
813
|
+
/**
|
|
814
|
+
* Bake static diffuse irradiance that reaches surfaces from outside the camera view.
|
|
815
|
+
* @situation light bouncing from a room I cannot see
|
|
816
|
+
* @situation light a wall with an off-screen emitter
|
|
817
|
+
* @alias readable world lighting
|
|
818
|
+
* @constraint request a bake after static geometry and lights are authored; this is static-lighting-first, not fully dynamic relighting
|
|
819
|
+
* @constraint add the volume with ctx.add() so its incremental work is measured in the render phase
|
|
820
|
+
* @constraint call sample() or sampleNode() from a game-owned material before screen-space GI; the volume owns no light, material, or colour
|
|
821
|
+
* @override density, bounds, bakeBudgetMs, and bounces are game-owned choices
|
|
822
|
+
* @example const probes = new ProbeVolume({ bounds, density: 0.5 }); ctx.add(probes); void probes.requestBake(scene);
|
|
823
|
+
*/
|
|
824
|
+
export {
|
|
825
|
+
ATLAS_PADDING,
|
|
826
|
+
PROBE_VOLUME_MARKER,
|
|
827
|
+
ProbeVolume,
|
|
828
|
+
} from "./render/probe-volume.js";
|
|
829
|
+
/**
|
|
830
|
+
* Read the most recent observation from a probe volume.
|
|
831
|
+
* @situation inspect the latest probe bake observation
|
|
832
|
+
* @constraint the returned observation is a measurement; it does not own lighting or materials
|
|
833
|
+
* @example const observation = readProbeVolumeObservation(probes);
|
|
834
|
+
*/
|
|
835
|
+
export { readProbeVolumeObservation } from "./render/probe-volume.js";
|
|
836
|
+
export type {
|
|
837
|
+
IProbeVolumeBakeProgress,
|
|
838
|
+
IProbeVolumeCoefficient,
|
|
839
|
+
IProbeVolumeObservation,
|
|
840
|
+
IProbeVolumeOptions,
|
|
841
|
+
ProbeVolumeDensity,
|
|
842
|
+
} from "./render/probe-volume.js";
|
|
843
|
+
/**
|
|
844
|
+
* Provision screen-space motion data for temporal nodes and keep per-instance history at the
|
|
845
|
+
* frame boundary.
|
|
846
|
+
* @situation keep a skinned character or instanced crowd stable in a temporal stage
|
|
847
|
+
* @situation add the velocity output to a Three.js scene pass
|
|
848
|
+
* @constraint call `VelocityTracker.update()` before the render and `commit()` after it
|
|
849
|
+
* @constraint a pass is only given a velocity target when a temporal stage consumes it
|
|
850
|
+
* @example
|
|
851
|
+
* const scenePass = pass(scene, camera);
|
|
852
|
+
* ensureVelocityOutput(scenePass);
|
|
853
|
+
* renderer.setOutputNode(scenePass);
|
|
854
|
+
* const tracker = new VelocityTracker();
|
|
855
|
+
* tracker.update(scene);
|
|
856
|
+
* renderer.render(scene, camera);
|
|
857
|
+
* tracker.commit(scene);
|
|
858
|
+
*/
|
|
859
|
+
export {
|
|
860
|
+
VELOCITY_OUTPUT_NAME,
|
|
861
|
+
VELOCITY_PREVIOUS_BONE_MATRICES,
|
|
862
|
+
VELOCITY_PREVIOUS_INSTANCE_MATRICES,
|
|
863
|
+
VELOCITY_PREVIOUS_WORLD_MATRIX,
|
|
864
|
+
VelocityTracker,
|
|
865
|
+
ensureVelocityOutput,
|
|
866
|
+
readVelocityPreviousBoneMatrices,
|
|
867
|
+
readVelocityPreviousMatrices,
|
|
868
|
+
readVelocityPreviousWorldMatrix,
|
|
869
|
+
velocityTexture,
|
|
870
|
+
withVelocityContext,
|
|
871
|
+
} from "./render/velocity.js";
|
|
872
|
+
export type { IVelocityRenderPass } from "./render/velocity.js";
|
|
873
|
+
/**
|
|
874
|
+
* One directional shadow for a whole open world: camera-centred clip levels, each snapped to its
|
|
875
|
+
* own texel grid and re-rendered only when its window moves. Tracked casters draw into a
|
|
876
|
+
* per-level mover map every frame, so animated casters do not invalidate the cached levels after
|
|
877
|
+
* the one refresh caused by tracking or untracking them.
|
|
878
|
+
* Plugs into three's own `light.shadow.shadowNode` slot, so every material receives it.
|
|
879
|
+
* @situation crisp shadows close to the player across a large outdoor level
|
|
880
|
+
* @situation shadow map too coarse over a big terrain
|
|
881
|
+
* @situation one directional light shadow for a whole open world
|
|
882
|
+
* @situation shadows shimmer when the camera moves
|
|
883
|
+
* @constraint the light must be a DirectionalLight with `castShadow` and a target in the scene
|
|
884
|
+
* @constraint clipExtents are half-widths in world units, finest first, strictly increasing
|
|
885
|
+
* @constraint movers sort themselves: a layer-0 caster whose world matrix, instance matrix or deformation changed draws through the mover maps and leaves the cached levels, and returns to them after `staticAfterFrames` quiet frames; the cache redraws only the region it left
|
|
886
|
+
* @constraint `trackCaster(object)` is the override that pins an object as a mover for good (it enables layer `VIRTUAL_SHADOW_MOVER_LAYER` on the object and its descendants), and `pinStatic(object)` opts an object out of detection; tracking or untracking refreshes only that object's region
|
|
887
|
+
* @constraint call `object.layers.set(VIRTUAL_SHADOW_CASTER_LAYER)` for a mesh that exists only to cast; the level cameras already render that layer and the main camera never does
|
|
888
|
+
* @override 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
|
|
889
|
+
* @example
|
|
890
|
+
* const sun = new DirectionalLight(0xffffff, 3);
|
|
891
|
+
* sun.castShadow = true;
|
|
892
|
+
* sun.shadow.shadowNode = new VirtualShadowNode(sun, { clipExtents: [12, 40, 120] });
|
|
893
|
+
*/
|
|
894
|
+
export {
|
|
895
|
+
VIRTUAL_SHADOW_CASTER_LAYER,
|
|
896
|
+
VIRTUAL_SHADOW_MARKER,
|
|
897
|
+
VIRTUAL_SHADOW_MOVER_LAYER,
|
|
898
|
+
VIRTUAL_SHADOW_WIDE_CASTER_LAYER,
|
|
899
|
+
VirtualShadowNode,
|
|
900
|
+
} from "./render/virtual-shadow.js";
|
|
901
|
+
export { readVirtualShadowMarker } from "./render/virtual-shadow.js";
|
|
902
|
+
/**
|
|
903
|
+
* An outdoor daylight rig: physical sky, one sun with open-world shadows that follow the eye,
|
|
904
|
+
* hemisphere fill, sky-coloured haze and the AgX tone curve. Every value is the game's.
|
|
905
|
+
*
|
|
906
|
+
* @situation daytime sky, sun and shadows for a large outdoor map
|
|
907
|
+
* @situation distant terrain should fade into the sky instead of a coloured wall
|
|
908
|
+
* @situation match a Blender look-dev scene's sun, sky and exposure in the game
|
|
909
|
+
* @constraint every value is required; there is no default sun, sky, haze or exposure
|
|
910
|
+
* @constraint `skySize` must keep the sky box's corners inside the camera's far plane
|
|
911
|
+
* @constraint shadowExtents follow `VirtualShadowNode`: half-widths, finest first, strictly increasing
|
|
912
|
+
* @override sky uniforms stay live on `daylight.sky`; the light and fill are `daylight.sun` and `daylight.fill`
|
|
913
|
+
* @example
|
|
914
|
+
* const daylight = new Daylight({ follow: ctx.camera, sunDirection, sunColor, sunIntensity: 4, shadowExtents: [24, 96, 320], sky: { turbidity: 3, rayleigh: 1.4, mieCoefficient: 0.004, mieDirectionalG: 0.8 }, fill: { sky, ground, intensity: 1.1 }, haze: { color: horizon, density: 0.0011 }, exposure: 2 ** -0.6, skySize: 1600 });
|
|
915
|
+
* ctx.add(daylight);
|
|
916
|
+
*/
|
|
917
|
+
export { Daylight } from "./render/daylight.js";
|
|
918
|
+
export type { IDaylightOptions } from "./render/daylight.js";
|
|
919
|
+
export type { IVirtualShadowOptions, IVirtualShadowStats } from "./render/virtual-shadow.js";
|
|
920
|
+
/**
|
|
921
|
+
* Attach hundreds of built objects to the scene in slices, presenting a frame between each.
|
|
922
|
+
* @situation add hundreds of built objects to the scene without one multi-second frame
|
|
923
|
+
* @situation stream a detail tier in behind a loading curtain without the page looking hung
|
|
924
|
+
* @constraint the objects, and where each one goes, stay the game's; this decides only when each joins the graph
|
|
925
|
+
* @constraint input order is the attach order and cannot be changed
|
|
926
|
+
* @constraint a false `while` stops the run and is reported as `stopped`, never thrown
|
|
927
|
+
* @override a slice ends on an 8 ms budget unless the game gives `sliceSize`, and the reported sliceSize is then the measured average; `marker: false` silences the TN_ADD_SLICES line, not the report
|
|
928
|
+
* @example const report = await addInSlices(objects, (object) => ctx.add(object), {
|
|
929
|
+
* onProgress: ({ added, total }) => setProgress(added / total),
|
|
930
|
+
* while: () => generation.live,
|
|
931
|
+
* });
|
|
932
|
+
*/
|
|
933
|
+
export { addInSlices } from "./streaming.js";
|
|
934
|
+
export type {
|
|
935
|
+
IAddInSlicesOptions,
|
|
936
|
+
IAddInSlicesProgress,
|
|
937
|
+
IAddInSlicesReport,
|
|
938
|
+
} from "./streaming.js";
|
|
939
|
+
/**
|
|
940
|
+
* Load a list with bounded concurrency, returning results in the input's order.
|
|
941
|
+
* @situation load many models or textures in parallel instead of one at a time
|
|
942
|
+
* @situation keep a loading screen moving while a list of assets downloads
|
|
943
|
+
* @constraint results are written to each item's own index and never appended, so a positional lookup finds the same asset on every load
|
|
944
|
+
* @constraint the first rejection rejects the call and no lane starts a load it had not begun
|
|
945
|
+
* @override concurrency defaults to 6; `marker: false` silences the TN_LOAD_ALL line, not onProgress
|
|
946
|
+
* @example const species = await loadAll(names, (name) => ctx.assets.model(`flora/${name}.glb`));
|
|
947
|
+
*/
|
|
948
|
+
export { loadAll } from "./streaming.js";
|
|
949
|
+
export type { ILoadAllOptions, ILoadAllProgress } from "./streaming.js";
|
|
950
|
+
export { warmUpScene } from "./warmup.js";
|
|
951
|
+
export type {
|
|
952
|
+
IWarmUpCacheOptions,
|
|
953
|
+
IWarmUpOptions,
|
|
954
|
+
IWarmUpProgress,
|
|
955
|
+
IWarmUpRenderer,
|
|
956
|
+
IWarmUpReport,
|
|
957
|
+
IWarmUpObservation,
|
|
958
|
+
WarmUpCacheStatus,
|
|
959
|
+
WarmUpObservationStatus,
|
|
960
|
+
} from "./warmup.js";
|
|
961
|
+
export type {
|
|
962
|
+
IGame,
|
|
963
|
+
IGameObservationContribution,
|
|
964
|
+
IGameObservationSampleRequest,
|
|
965
|
+
IGamePluginHooks,
|
|
966
|
+
IGamePluginRuntime,
|
|
967
|
+
IGamePlatformSource,
|
|
968
|
+
} from "./game.js";
|
|
969
|
+
/**
|
|
970
|
+
* Simulate a spectral ocean — cascaded wave spectra inverse-transformed on the GPU each frame.
|
|
971
|
+
* @situation make an ocean whose surface is the view rather than a background
|
|
972
|
+
* @situation float a boat on waves the GPU is drawing
|
|
973
|
+
* @situation drive a water material from a wave simulation without writing an FFT
|
|
974
|
+
* @situation sail a ship on simulated ocean waves with buoyancy
|
|
975
|
+
* @constraint it draws nothing; the game supplies the mesh, the material and every colour
|
|
976
|
+
* @constraint CPU height is a throttled copy carrying staleFrames, never this frame and never exact
|
|
977
|
+
* @constraint an exact free CPU height needs an analytic wave field instead; that is a different contract
|
|
978
|
+
* @constraint cascades are ordered largest patchSize first and every tuning number is required
|
|
979
|
+
* @example const sea = ctx.add(new SpectralOcean(oceanOptions));
|
|
980
|
+
*/
|
|
981
|
+
export { SpectralOcean } from "./ocean/spectral.js";
|
|
982
|
+
export type {
|
|
983
|
+
ISpectralOceanCascade,
|
|
984
|
+
ISpectralOceanHeight,
|
|
985
|
+
ISpectralOceanOptions,
|
|
986
|
+
} from "./ocean/spectral.js";
|
|
987
|
+
/**
|
|
988
|
+
* Copy a GPU buffer back to the CPU on a throttle, and report how old each sample is.
|
|
989
|
+
* @situation read a GPU simulation on the CPU without stalling the frame
|
|
990
|
+
* @situation float a body on a wave field whose height only exists on the GPU
|
|
991
|
+
* @situation count GPU-side survivors for a diagnostic without blocking drawing
|
|
992
|
+
* @situation keep a ship floating on simulated ocean waves
|
|
993
|
+
* @constraint the copy is asynchronous, so every sample carries staleFrames and is never this frame
|
|
994
|
+
* @constraint WebGPU only; the seam throws on a WebGL2 renderer rather than returning nothing
|
|
995
|
+
* @constraint one copy is in flight at a time and requests made during one are dropped, not queued
|
|
996
|
+
* @example const heights = new GPUReadback({ attribute: field.value, everyFrames: 4 });
|
|
997
|
+
*/
|
|
998
|
+
export { GPUReadback } from "./gpu-readback.js";
|
|
999
|
+
export type { IGPUReadbackOptions, IGPUReadbackSample } from "./gpu-readback.js";
|
|
1000
|
+
/**
|
|
1001
|
+
* Dispatch a game-owned particle surface and process function through a pooled system.
|
|
1002
|
+
* @situation emit sparks, smoke, or other transient effects
|
|
1003
|
+
* @situation update many small visual particles
|
|
1004
|
+
* @situation trail dust, exhaust, or spray behind a moving object
|
|
1005
|
+
* @situation emit cannon smoke and muzzle flash particles
|
|
1006
|
+
* @situation fire a cannonball projectile with cannon smoke particles
|
|
1007
|
+
* @situation splash spray droplets with lifetime and gravity
|
|
1008
|
+
* @situation spawn water droplets, mist, or foam bubbles above a fluid surface
|
|
1009
|
+
* @situation falling snowflakes, rain or ash around the player that thicken into a windy storm or blizzard
|
|
1010
|
+
* @situation kick up a spray of powder snow or dust where a foot or a ball lands
|
|
1011
|
+
* @situation a hit, impact or explosion burst that starts at the point and moment it is asked for, and a second hit that must not move the first hit's live particles
|
|
1012
|
+
* @situation emitParticle a burst of GPU particles at a world position with its own free slots
|
|
1013
|
+
* @constraint geometry, color, and timing remain supplied by the game
|
|
1014
|
+
* @constraint a `spawn` kernel makes bursts requests: `emitParticle({ count, origin })` reserves ring slots, the engine stamps `buffers.births` and `process` reads age as `runtime.time - births[i]`; there is no readback
|
|
1015
|
+
* @constraint a spawn emitter is world space (identity world matrix); `localCoords: true` follows the parent
|
|
1016
|
+
* @constraint requests over `amount` or `maxSpawnPerFrame` clamp, add to `stats.clamped` and warn once; `stats.recycledLive` is `undefined` without the `lifetime` option
|
|
1017
|
+
* @constraint the emitter measures its own bounds and stops computing and drawing after graceSeconds outside the camera view
|
|
1018
|
+
* @constraint a game needs no emitting = visible gate, and an emitter with no measured bounds is never culled for leaving the view
|
|
1019
|
+
* @constraint when measured GPU cost passes the frame budget, the smallest projected emitters pause first, and cull.reason reads outside-view or over-budget
|
|
1020
|
+
* @override localCoords, maxSpawnPerFrame and lifetime tune a spawn emitter; `restart()` kills every particle and rewinds the ring
|
|
1021
|
+
* @override onCull: "clear" restarts a returning effect, the default "pause" resumes it with buffers intact
|
|
1022
|
+
* @override bounds supplies a fixed local Box3 and skips GPU measurement, padding enlarges the world box, boundsEveryFrames sets the measurement cadence
|
|
1023
|
+
* @override graceSeconds sets the seconds outside the view before culling, and Infinity disables view culling
|
|
1024
|
+
* @example const particles = new GPUParticles3D(particleOptions);
|
|
1025
|
+
* particles.emitParticle({ count: 220, origin: hit.position });
|
|
1026
|
+
*/
|
|
1027
|
+
export { GPUParticles3D } from "./particles.js";
|
|
1028
|
+
export type {
|
|
1029
|
+
IEmitParticleRequest,
|
|
1030
|
+
IGPUParticles3DOptions,
|
|
1031
|
+
IGPUParticles3DRuntime,
|
|
1032
|
+
IGPUParticles3DSpawnBuffers,
|
|
1033
|
+
IGPUParticles3DSpawnRequest,
|
|
1034
|
+
IGPUParticles3DStats,
|
|
1035
|
+
} from "./particles.js";
|
|
1036
|
+
/**
|
|
1037
|
+
* Simulate a deterministic 2D velocity-and-dye field on the GPU while exposing its data to game-owned rendering.
|
|
1038
|
+
* @situation simulate smoke, fire, fog, wind, or fluid response on a grid
|
|
1039
|
+
* @situation inject a touch, pointer, or gameplay impulse into a fluid field
|
|
1040
|
+
* @situation sample fluid dye or velocity in a game-owned render node
|
|
1041
|
+
* @situation simulate ocean currents and wind affecting a sailing ship
|
|
1042
|
+
* @situation simulate ocean fluid dynamics and currents that affect a ship
|
|
1043
|
+
* @constraint add the field through `ctx.add` so renderer attachment, fixed-step dispatch, and release are automatic
|
|
1044
|
+
* @constraint `dye` and `velocity` are numeric samplers; appearance stays in the game's `src/render/` code
|
|
1045
|
+
* @constraint the conformance sample measures mean absolute velocity divergence at 0.001732 after four 32² steps with pressureIterations 2, below the 0.0025 threshold
|
|
1046
|
+
* @override pressureIterations, viscosity, vorticity, and splatRadius tune the solver without changing its pass order
|
|
1047
|
+
* @example const field = new FluidField2D({ resolution: 256, pressureIterations: 20 });
|
|
1048
|
+
* ctx.add(field);
|
|
1049
|
+
* field.splat({ x: 0.5, y: 0.5 }, { x: 0.2, y: 0 }, 1);
|
|
1050
|
+
*/
|
|
1051
|
+
export { FluidField2D } from "./fluid-field.js";
|
|
1052
|
+
export type { IFluidFieldOptions, IFluidFieldSampler, IFluidFieldVector2 } from "./fluid-field.js";
|
|
1053
|
+
/**
|
|
1054
|
+
* Simulate liquid as GPU particles (pour, splash, dam break, waterfall) and expose positions, a density volume and a surface height while the game owns every look.
|
|
1055
|
+
* @situation pour, splash, or dam-break water that fills a container and flows around obstacles
|
|
1056
|
+
* @situation simulate water or another liquid as particles in a fluid simulation
|
|
1057
|
+
* @situation drop a ball or box into liquid and let it displace and float on the water
|
|
1058
|
+
* @situation emit a stream or waterfall of particle fluid and drain it somewhere else
|
|
1059
|
+
* @situation sample particle-fluid density or surface height in a game-owned render node
|
|
1060
|
+
* @constraint add the fluid through `ctx.add` so renderer attachment, fixed-step dispatch, and release are automatic
|
|
1061
|
+
* @constraint a renderer without WebGPU compute throws a named error at attach; it never draws nothing
|
|
1062
|
+
* @constraint `emit` recycles the oldest slot once `capacity` slots have been used; `fill` stops at capacity
|
|
1063
|
+
* @constraint `sample` and `stats` read a throttled GPU copy and report `staleFrames`; they are never live
|
|
1064
|
+
* @override iterations, viscosity, cohesion, vorticity, gravity and maxSpeed tune the solver without changing its pass order
|
|
1065
|
+
* @example const water = new FluidParticles3D({ capacity: 6000 });
|
|
1066
|
+
* ctx.add(water);
|
|
1067
|
+
* water.fill([-2.8, 0.1, -1.5], [-0.6, 3, 1.5]);
|
|
1068
|
+
*/
|
|
1069
|
+
export { FluidParticles3D } from "./fluid-particles.js";
|
|
1070
|
+
export type {
|
|
1071
|
+
IFluidBounds,
|
|
1072
|
+
IFluidCollider,
|
|
1073
|
+
IFluidParticlesOptions,
|
|
1074
|
+
IFluidParticlesStats,
|
|
1075
|
+
} from "./fluid-particles.js";
|
|
1076
|
+
/**
|
|
1077
|
+
* Propagate a disturbance across a patch of water surface and let it fade.
|
|
1078
|
+
* @situation make a splash or explosion ripple outward across water
|
|
1079
|
+
* @situation show the sea reacting to a bomb, shell, or torpedo hitting it
|
|
1080
|
+
* @situation leave a foam trail behind something moving through water
|
|
1081
|
+
* @situation disturb a water surface the player can see respond
|
|
1082
|
+
* @situation spread and drift foam on a water surface over time
|
|
1083
|
+
* @constraint it draws nothing; the game supplies the mesh, the material and every colour
|
|
1084
|
+
* @constraint add its height to an analytic swell, never in place of one
|
|
1085
|
+
* @constraint the patch is finite and its rim absorbs; call recenter to keep it over the action
|
|
1086
|
+
* @constraint there is no obstacle mask, because a mask is only correct for a body that never moves
|
|
1087
|
+
* @override speed, damping, foamHalfLife, current, step and maxSteps tune the solve; the default
|
|
1088
|
+
* step is 1/60s or the CFL stability limit for the given resolution and speed, whichever is smaller
|
|
1089
|
+
* @example const ripples = new RippleField({ resolution: 128, size: 400 });
|
|
1090
|
+
* ripples.impulse(hit.x, hit.z, 6, -40, 0.5);
|
|
1091
|
+
* ripples.advance(dt);
|
|
1092
|
+
* const lift = ripples.heightAt(boat.x, boat.z);
|
|
1093
|
+
*/
|
|
1094
|
+
export { RippleField } from "./ripple-field.js";
|
|
1095
|
+
export type { IRippleFieldFlow, IRippleFieldOptions } from "./ripple-field.js";
|
|
1096
|
+
/**
|
|
1097
|
+
* Evaluate analytic waves on CPU and displace game-owned vertices with the matching TSL graph.
|
|
1098
|
+
* @situation float a boat on waves
|
|
1099
|
+
* @situation make water move
|
|
1100
|
+
* @situation find the water surface height at a point
|
|
1101
|
+
* @constraint supply every wave amplitude, wavelength, direction, speed and warp value
|
|
1102
|
+
* @constraint call setTime for the default graph clock when the game advances its own time
|
|
1103
|
+
* @constraint sample allocates a result and a normal vector; ask heightAt when only the height is
|
|
1104
|
+
* wanted, and the warp jacobian, every slope and both allocations are skipped
|
|
1105
|
+
* @example const field = new WaveField({ waves });
|
|
1106
|
+
* const { height, normal } = field.sample(x, z, elapsed);
|
|
1107
|
+
* const lift = field.heightAt(x, z, elapsed);
|
|
1108
|
+
*/
|
|
1109
|
+
export { WaveField } from "./wave-field.js";
|
|
1110
|
+
export type {
|
|
1111
|
+
IWaveFieldDomainWarp,
|
|
1112
|
+
IWaveFieldGraphOptions,
|
|
1113
|
+
IWaveFieldOptions,
|
|
1114
|
+
IWaveFieldSample,
|
|
1115
|
+
IWaveFieldWave,
|
|
1116
|
+
WaveDirection,
|
|
1117
|
+
} from "./wave-field.js";
|
|
1118
|
+
/**
|
|
1119
|
+
* Give a horizontal water surface the world mirrored in it, the world beneath it, and the metres
|
|
1120
|
+
* of water between them.
|
|
1121
|
+
* @situation reflect the sky and the shoreline in a lake, pond or river
|
|
1122
|
+
* @situation see the bed through the water and have the shallows fade at the shore
|
|
1123
|
+
* @situation know how deep the water is under a pixel without a second render pass
|
|
1124
|
+
* @situation stop a water surface repeating in visible bands or stripes
|
|
1125
|
+
* @situation keep a crowd of small actors out of the water's reflection so the frame can afford it
|
|
1126
|
+
* @situation stop the water reflection redrawing the whole world every frame
|
|
1127
|
+
* @situation automatically reflect terrain and large casters without redrawing instanced small props
|
|
1128
|
+
* @constraint it draws nothing; the game supplies the mesh, the material and every colour
|
|
1129
|
+
* @constraint the material must be transparent so the frame beneath it is already drawn
|
|
1130
|
+
* @constraint thickness is metres, saturating at maxThickness; sky behind the surface reads deep
|
|
1131
|
+
* @constraint one reflection is a second draw of the world; resolutionScale is its pixels only
|
|
1132
|
+
* @constraint omitted reflection.layers automatically reflects terrain-sized surfaces and large non-instanced casters, excluding instanced/skinned props; TN_WATER_REFLECTION_DEFAULT reports the set once
|
|
1133
|
+
* @override reflection.layers is an explicit Three Layers mask and wins over automatic filtering, including layer-0 mask 1; reflection.minSize overrides the default 10 metre minimum extent
|
|
1134
|
+
* @constraint reflection.refreshInterval is in presented frames; 1 is every frame, and the default
|
|
1135
|
+
* @constraint the mirror plane is level, from level alone; do not parent target to a scaled mesh
|
|
1136
|
+
* @example const surface = new WaterSurface3D({ level: 0, maxThickness: 3, reflection: { resolutionScale: 0.5 } });
|
|
1137
|
+
* material.colorNode = mix(surface.refractionAt(offset), surface.reflectionAt(offset), fresnel);
|
|
1138
|
+
*/
|
|
1139
|
+
export { WaterSurface3D } from "./water-surface.js";
|
|
1140
|
+
export type { IWaterReflectionOptions, IWaterSurfaceOptions } from "./water-surface.js";
|
|
1141
|
+
/**
|
|
1142
|
+
* Build a soft round sprite as pixel data instead of painting a canvas.
|
|
1143
|
+
* @situation give smoke, flash, or glow sprites a radial alpha falloff
|
|
1144
|
+
* @situation generate sprite images that render identically under every backend
|
|
1145
|
+
* @constraint canvas-painted images sample black under WebGPURenderer; write sprites as pixel data there
|
|
1146
|
+
* @example const puff = softCircleDataTexture(64, 0.25);
|
|
1147
|
+
*/
|
|
1148
|
+
export { softCircleDataTexture } from "./textures.js";
|
|
1149
|
+
/**
|
|
1150
|
+
* Pool travelling bullet-streak meshes for hitscan shots.
|
|
1151
|
+
* @situation show where a hitscan round went
|
|
1152
|
+
* @situation show each round a weapon fires, one tracer per trigger press
|
|
1153
|
+
* @situation draw incoming fire without spawning projectiles
|
|
1154
|
+
* @constraint the surface comes from the game; pooling, travel, and fading belong to the engine
|
|
1155
|
+
* @constraint update once per frame and dispose with the owning scene
|
|
1156
|
+
* @example const tracers = new TracerPool3D(ctx.scene, tracerOptions);
|
|
1157
|
+
* tracers.spawn(muzzle, shotDirection, hit.distance);
|
|
1158
|
+
*/
|
|
1159
|
+
export { TracerPool3D } from "./tracers.js";
|
|
1160
|
+
export type { ITracerPool3DOptions, ITracerSpawnOptions } from "./tracers.js";
|
|
1161
|
+
/**
|
|
1162
|
+
* Move an object along a Three.js curve with Godot-style path following.
|
|
1163
|
+
* @situation move an enemy or prop along a patrol path
|
|
1164
|
+
* @situation sample a racing line from a curve
|
|
1165
|
+
* @example const follower = new PathFollow3D({ points: patrolPoints, loop: true, speed: 3 });
|
|
1166
|
+
*/
|
|
1167
|
+
export { PathFollow3D } from "./path-follow.js";
|
|
1168
|
+
/**
|
|
1169
|
+
* Keep a rendered model's feet on a surface while preserving an auditable override.
|
|
1170
|
+
* @situation keep a character's feet on the floor
|
|
1171
|
+
* @situation correct visual grounding after an animation update
|
|
1172
|
+
* @constraint import from `@threenative/core`; this moves the rendered model, not its physics collider
|
|
1173
|
+
* @override enabled controls whether correction is applied while clearance is still measured
|
|
1174
|
+
* @example import { GroundSnap } from "@threenative/core";
|
|
1175
|
+
* const snap = new GroundSnap(character, { enabled: true });
|
|
1176
|
+
*/
|
|
1177
|
+
export { GroundSnap } from "./grounding.js";
|
|
1178
|
+
/**
|
|
1179
|
+
* Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
|
|
1180
|
+
* @situation fly an airplane with lift, drag, stall and control authority
|
|
1181
|
+
* @situation launch an aircraft off a moving carrier deck
|
|
1182
|
+
* @situation apply component damage or a loadout to an aircraft's performance
|
|
1183
|
+
* @constraint every mass, area, power and inertia value comes from the game's airframe
|
|
1184
|
+
* @constraint damage, stores and configuration arrive as the game's own modifier sample
|
|
1185
|
+
* @example const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });
|
|
1186
|
+
* model.step(1 / 60, { turn: -1, pitch: 0.4 });
|
|
1187
|
+
*/
|
|
1188
|
+
export {
|
|
1189
|
+
FlightModel,
|
|
1190
|
+
NEUTRAL_FLIGHT_MODIFIERS,
|
|
1191
|
+
aerodynamicCoefficients,
|
|
1192
|
+
airDensity,
|
|
1193
|
+
aircraftMass,
|
|
1194
|
+
attitudeAxes,
|
|
1195
|
+
gearClearance,
|
|
1196
|
+
setAttitude,
|
|
1197
|
+
} from "./flight.js";
|
|
1198
|
+
export type {
|
|
1199
|
+
IAircraftAirframe,
|
|
1200
|
+
IFlightAxes,
|
|
1201
|
+
IFlightControls,
|
|
1202
|
+
IFlightDeck,
|
|
1203
|
+
IFlightEnvironment,
|
|
1204
|
+
IFlightForces,
|
|
1205
|
+
IFlightModelOptions,
|
|
1206
|
+
IFlightModifiers,
|
|
1207
|
+
IFlightQuaternion,
|
|
1208
|
+
IFlightState,
|
|
1209
|
+
IFlightVector3,
|
|
1210
|
+
} from "./flight.js";
|
|
1211
|
+
export type { IGroundSnapOptions } from "./grounding.js";
|
|
1212
|
+
/**
|
|
1213
|
+
* Measure a Three.js pose for grounded or attachment-aware checks.
|
|
1214
|
+
* @situation inspect a skinned model's posed bounds
|
|
1215
|
+
* @situation verify a character's visual pose
|
|
1216
|
+
* @constraint precise per-vertex measurement is opt-in and not for frame loops
|
|
1217
|
+
* @example const measurement = measureThreePose(model);
|
|
1218
|
+
*/
|
|
1219
|
+
export { measureThreePose, posedBounds } from "./pose-measure.js";
|
|
1220
|
+
export type {
|
|
1221
|
+
IMeasureThreePoseOptions,
|
|
1222
|
+
IThreePoseBounds,
|
|
1223
|
+
IThreePoseMeasurement,
|
|
1224
|
+
ThreePoseQuaternion,
|
|
1225
|
+
ThreePoseVector,
|
|
1226
|
+
} from "./pose-measure.js";
|
|
1227
|
+
export type {
|
|
1228
|
+
IPathFollow3DOptions,
|
|
1229
|
+
IPathFollow3DProjection,
|
|
1230
|
+
IPathFollow3DSample,
|
|
1231
|
+
} from "./path-follow.js";
|
|
1232
|
+
/**
|
|
1233
|
+
* Dispatch portable pointer events from the game surface to registered Three.js objects.
|
|
1234
|
+
* @situation let the player click on a thing in the world
|
|
1235
|
+
* @situation show a 3D object while a pointer hovers over it
|
|
1236
|
+
* @situation handle touch and mouse taps on a loaded model without naming its child meshes
|
|
1237
|
+
* @situation drag a crate or prop with the mouse or a finger
|
|
1238
|
+
* @constraint listeners are side-table registrations; Three.js prototypes are never patched
|
|
1239
|
+
* @constraint one raycast serves each active pointer and no raycast runs when nothing is registered
|
|
1240
|
+
* @example ctx.pointer.on(tile, "tapped", (event) => place(event.point));
|
|
1241
|
+
*/
|
|
1242
|
+
export { PointerEvents3D } from "./pointer-events.js";
|
|
1243
|
+
export type {
|
|
1244
|
+
IPointerDragHandle,
|
|
1245
|
+
IPointerEvent3D,
|
|
1246
|
+
IPointerEvents3D,
|
|
1247
|
+
IPointerEvents3DOptions,
|
|
1248
|
+
IPointerEvents3DPicker,
|
|
1249
|
+
IPointerState,
|
|
1250
|
+
PointerEvent3DListener,
|
|
1251
|
+
PointerEvent3DType,
|
|
1252
|
+
} from "./pointer-events.js";
|
|
1253
|
+
/**
|
|
1254
|
+
* Read the host platform without reaching for browser globals.
|
|
1255
|
+
* @situation branch a portable game on web or native
|
|
1256
|
+
* @situation choose touch controls for a mobile device
|
|
1257
|
+
* @situation can I raytrace on native
|
|
1258
|
+
* @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
|
|
1260
|
+
* @example if (isMobile()) showTouchControls();
|
|
1261
|
+
*/
|
|
1262
|
+
export { getPlatform, isMobile, isNative, isTouchscreenAvailable, isWeb } from "./platform.js";
|
|
1263
|
+
export type {
|
|
1264
|
+
IPlatformInfo,
|
|
1265
|
+
PlatformFormFactor,
|
|
1266
|
+
PlatformOS,
|
|
1267
|
+
PlatformRuntime,
|
|
1268
|
+
} from "./platform.js";
|
|
1269
|
+
/**
|
|
1270
|
+
* Raycast the game scene using the framework's picker.
|
|
1271
|
+
* @situation select an object under the pointer
|
|
1272
|
+
* @situation interact with the first collider or mesh hit
|
|
1273
|
+
* @supersedes new Raycaster(
|
|
1274
|
+
* @example const picker = new ScenePicker({ camera: ctx.camera, scene: ctx.scene, pointer: () => ctx.input.raw.pointer, viewport: ctx.viewport });
|
|
1275
|
+
*/
|
|
1276
|
+
export { ScenePicker } from "./picking.js";
|
|
1277
|
+
export type { IRaycastOptions, IScenePickerOptions } from "./picking.js";
|
|
1278
|
+
/**
|
|
1279
|
+
* Record or replay deterministic game input and state.
|
|
1280
|
+
* @situation reproduce a gameplay bug from recorded input
|
|
1281
|
+
* @situation run a deterministic replay in a playtest
|
|
1282
|
+
* @alias fixed seed fixed-step simulation
|
|
1283
|
+
* @constraint use a seeded random source and fixed-step simulation for meaningful replays
|
|
1284
|
+
* @example const driver = createReplayDriver(recording, ctx.renderer.domElement);
|
|
1285
|
+
*/
|
|
1286
|
+
export { createReplayDriver, replay } from "./replay.js";
|
|
1287
|
+
export type { IReplayOptions, Recording } from "./replay.js";
|
|
1288
|
+
/**
|
|
1289
|
+
* Validate and parse a replay recording file.
|
|
1290
|
+
* @situation validate a recording before replaying it in another host
|
|
1291
|
+
* @constraint recordings are version 1; the parser fails closed with TN_REPLAY_* codes
|
|
1292
|
+
* @example const recording = parseReplayRecording(rawRecording);
|
|
1293
|
+
*/
|
|
1294
|
+
export { parseReplayRecording } from "./replay-protocol.js";
|
|
1295
|
+
export type {
|
|
1296
|
+
IReplayRecording,
|
|
1297
|
+
IReplayRecordingSample,
|
|
1298
|
+
ReplayPointer,
|
|
1299
|
+
} from "./replay-protocol.js";
|
|
1300
|
+
/**
|
|
1301
|
+
* Schedule delayed and repeating callbacks or tween numeric properties with game-owned cleanup.
|
|
1302
|
+
* @situation delay an enemy patrol transition
|
|
1303
|
+
* @situation run a callback every simulation tick
|
|
1304
|
+
* @situation tween a numeric property with a game-owned curve
|
|
1305
|
+
* @situation a countdown timer: end the level when its time limit runs out
|
|
1306
|
+
* @alias tower defense game
|
|
1307
|
+
* @alias spawn waves
|
|
1308
|
+
* @constraint dispose returned handles when the owning scene exits
|
|
1309
|
+
* @constraint ease receives progress in the range 0 to 1 and its return value is the interpolation factor
|
|
1310
|
+
* @example const door = { y: 0 };
|
|
1311
|
+
* await ctx.tween(door, { y: 2.4 }, 0.5, { ease: (t) => 1 - (1 - t) ** 3 });
|
|
1312
|
+
*/
|
|
1313
|
+
export { Scheduler } from "./schedule.js";
|
|
1314
|
+
export type { ITweenOptions, ScheduleHandle } from "./schedule.js";
|
|
1315
|
+
/**
|
|
1316
|
+
* Implement a portable Godot-shaped game scene lifecycle.
|
|
1317
|
+
* @situation add a playable level or menu scene
|
|
1318
|
+
* @situation move scene setup and per-frame gameplay out of the entry point
|
|
1319
|
+
* @situation run scene work once per actual world draw, after the frame's last fixed update and before the projection packs
|
|
1320
|
+
* @constraint scene code must stay portable across web and native
|
|
1321
|
+
* @example class Play extends Scene { update(ctx, dt) {} }
|
|
1322
|
+
* @example ctx.beforeRender(() => packBatches()); // cleared on scene change and stop, like ctx.afterPhysics
|
|
1323
|
+
*/
|
|
1324
|
+
export { Scene } from "./scene.js";
|
|
1325
|
+
export type { ICtx, SceneFrame } from "./scene.js";
|
|
1326
|
+
/**
|
|
1327
|
+
* Advance a game-owned non-uniform sprite atlas on the fixed step.
|
|
1328
|
+
* @situation play an animated pickup or sprite-sheet effect
|
|
1329
|
+
* @situation sequence atlas frames with different authored durations
|
|
1330
|
+
* @constraint the game supplies the atlas texture, surface, filtering, layout, and every frame duration
|
|
1331
|
+
* @constraint update is driven by the scene fixed step; no wall clock or default frame rate is used
|
|
1332
|
+
* @example const animator = new SpriteAnimator3D({ texture: atlas, frames, mode: "pingPong" });
|
|
1333
|
+
*/
|
|
1334
|
+
export { SpriteAnimator3D } from "./sprite-animator.js";
|
|
1335
|
+
export type {
|
|
1336
|
+
ISpriteAnimator3DOptions,
|
|
1337
|
+
ISpriteFrame3D,
|
|
1338
|
+
SpritePlaybackMode,
|
|
1339
|
+
} from "./sprite-animator.js";
|
|
1340
|
+
/**
|
|
1341
|
+
* Keep transient render surfaces in the renderer's pipeline cache before first use.
|
|
1342
|
+
* @situation prewarm a projectile, tracer, particle, or other transient effect
|
|
1343
|
+
* @situation avoid a long first-use frame for a newly visible effect
|
|
1344
|
+
* @constraint keep the surface visible with zero opacity; do not hide it with `visible = false`
|
|
1345
|
+
* @supersedes .visible = false
|
|
1346
|
+
* @example prewarm(tracerPool);
|
|
1347
|
+
*/
|
|
1348
|
+
export { prewarm } from "./renderer.js";
|
|
1349
|
+
/**
|
|
1350
|
+
* Read the renderer's bounded, versioned pipeline capture in a diagnostic or playtest tool.
|
|
1351
|
+
* @situation inspect shader and pipeline creation work during a real launch
|
|
1352
|
+
* @situation correlate pipeline creation with material, object, pass, and shader identities
|
|
1353
|
+
* @constraint the capture is bounded and incomplete when the backend cannot expose an observation
|
|
1354
|
+
* @example const capture = game.runtime.pipelineCensus?.();
|
|
1355
|
+
* // The game normally reaches this through `runtime.pipelineCensus`; direct construction exists
|
|
1356
|
+
* // for renderer adapters and contract tests, not for gameplay.
|
|
1357
|
+
*/
|
|
1358
|
+
export {
|
|
1359
|
+
DEFAULT_PIPELINE_CENSUS_LIMIT,
|
|
1360
|
+
PIPELINE_CENSUS_CAPABILITY,
|
|
1361
|
+
PIPELINE_CENSUS_VERSION,
|
|
1362
|
+
createPipelineCensus,
|
|
1363
|
+
PipelineCensus,
|
|
1364
|
+
} from "./pipeline-census.js";
|
|
1365
|
+
export type {
|
|
1366
|
+
IPipelineCensus,
|
|
1367
|
+
IPipelineCensusCounts,
|
|
1368
|
+
IPipelineCensusEvent,
|
|
1369
|
+
IPipelineCensusOptions,
|
|
1370
|
+
IPipelineProvenance,
|
|
1371
|
+
IPipelineShaderObservation,
|
|
1372
|
+
PipelineCensusMode,
|
|
1373
|
+
PipelineCensusStatus,
|
|
1374
|
+
} from "./pipeline-census.js";
|
|
1375
|
+
/**
|
|
1376
|
+
* Scale an asset to a real-world measurement and return the applied factor.
|
|
1377
|
+
* @situation make a character exactly 1.8 metres tall
|
|
1378
|
+
* @situation normalize a prop or weapon to a known longest axis
|
|
1379
|
+
* @constraint skinned height uses a crown bone; game-specific asset expectations stay in render code
|
|
1380
|
+
* @supersedes new Box3().setFromObject(
|
|
1381
|
+
* @example normaliseToMetres(character, { metres: 1.8, axis: "height" });
|
|
1382
|
+
*/
|
|
1383
|
+
export { normaliseToMetres } from "./scale.js";
|
|
1384
|
+
export type { INormaliseToMetresOptions, NormaliseAxis } from "./scale.js";
|
|
1385
|
+
/**
|
|
1386
|
+
* Repair an exported rig whose animation clips are z-mirrored against its own bind pose.
|
|
1387
|
+
* @situation find out why a skinned character renders deformed
|
|
1388
|
+
* @situation repair an imported character that walks backwards with its spine folded
|
|
1389
|
+
* @situation load a rigged GLB through a custom loader and keep the framework's repair
|
|
1390
|
+
* @constraint the model loader already applies this automatically; only a game loading GLBs around it needs the call
|
|
1391
|
+
* @constraint detection votes per tracked bone and converts only on an overwhelming signature; a file that does not carry it is left byte-identical
|
|
1392
|
+
* @example import { reconcileMirroredClips } from "@threenative/core";
|
|
1393
|
+
* if (reconcileMirroredClips(gltf.scene, gltf.animations)) console.info("clips were z-mirrored; repaired");
|
|
1394
|
+
*/
|
|
1395
|
+
export { reconcileMirroredClips } from "./assets.js";
|
|
1396
|
+
/**
|
|
1397
|
+
* Attach a game-owned object to a named skeleton bone.
|
|
1398
|
+
* @situation put a weapon in a character's hand
|
|
1399
|
+
* @situation hold a rifle in a character's right hand
|
|
1400
|
+
* @situation add an enemy that patrols the level, chases the player when it sees them, and holds a rifle in its right hand
|
|
1401
|
+
* @situation attach an accessory to a skinned model
|
|
1402
|
+
* @situation equip crew with swords and pistols
|
|
1403
|
+
* @situation put a sword or pistol in a crew member's hand
|
|
1404
|
+
* @constraint when a request is to hold or attach a weapon to a hand, import and call `attachToBone` from `@threenative/core`; do not manually parent, position, or rotate the rifle
|
|
1405
|
+
* @constraint if a stock visual has no skeleton, add a portable Three.js Bone named `RightHand` under the character, then call `attachToBone`; do not replace the helper with manual parenting
|
|
1406
|
+
* @example import { attachToBone } from "@threenative/core";
|
|
1407
|
+
* attachToBone(character, "RightHand", rifle);
|
|
1408
|
+
*/
|
|
1409
|
+
export { attachToBone } from "./skeleton.js";
|
|
1410
|
+
/**
|
|
1411
|
+
* List the names of every bone in a character hierarchy.
|
|
1412
|
+
* @situation inspect the available bones before attaching a game-owned object
|
|
1413
|
+
* @situation debug a missing skeleton bone name
|
|
1414
|
+
* @example import { skeletonBones } from "@threenative/core";
|
|
1415
|
+
* const bones = skeletonBones(character);
|
|
1416
|
+
*/
|
|
1417
|
+
export { skeletonBones } from "./skeleton.js";
|
|
1418
|
+
/**
|
|
1419
|
+
* Measure whether a named bone reaches the object it is supposed to be touching, in metres.
|
|
1420
|
+
* @situation check that a seated character's hands reach the keyboard
|
|
1421
|
+
* @situation check that a character's hips meet the chair it is sitting on
|
|
1422
|
+
* @situation turn "the character is not touching the prop" into a number a scenario can assert
|
|
1423
|
+
* @constraint this walks the target's vertices; call it on a check or a debug sample, not every frame
|
|
1424
|
+
* @example import { boneContact } from "@threenative/core";
|
|
1425
|
+
* const contact = boneContact(worker, "hand_r", keyboard);
|
|
1426
|
+
*/
|
|
1427
|
+
export { boneContact } from "./skeleton.js";
|
|
1428
|
+
export type { IBoneContactReport } from "./skeleton.js";
|
|
1429
|
+
/**
|
|
1430
|
+
* Score a retargeted clip against the source it came from, per bone, in degrees.
|
|
1431
|
+
* @situation find out why a retargeted animation looks wrong on a character
|
|
1432
|
+
* @situation tell a fixed retarget from one that merely moved
|
|
1433
|
+
* @situation catch a retarget that rolled every limb about its own axis
|
|
1434
|
+
* @constraint each bone is compared as a whole quaternion relative to its own rig's bind pose, so the two rigs never have to share a bind convention; a bone-direction check reports zero on the roll this catches
|
|
1435
|
+
* @constraint both rigs must face the same way in world space, and both are driven and then restored to the transforms they arrived with
|
|
1436
|
+
* @override bones maps one rig's bone names onto the other's when they differ; samples sets how many poses are compared
|
|
1437
|
+
* @example import { clipPoseError } from "@threenative/core";
|
|
1438
|
+
* const report = clipPoseError({ root: rig, clip: retargeted }, { root: source, clip: original });
|
|
1439
|
+
*/
|
|
1440
|
+
export { clipPoseError } from "./clip-audit.js";
|
|
1441
|
+
/**
|
|
1442
|
+
* Report which of a clip's tracks bind to nothing on a character.
|
|
1443
|
+
* @situation find out why a character plays its bind pose instead of the animation
|
|
1444
|
+
* @situation check that a loaded clip actually drives the model it was written for
|
|
1445
|
+
* @constraint the reason is Three.js's own, captured off its console hook so a scenario's console assertions stay clean
|
|
1446
|
+
* @example import { clipTrackBindings } from "@threenative/core";
|
|
1447
|
+
* const bindings = clipTrackBindings(character, clip);
|
|
1448
|
+
*/
|
|
1449
|
+
export { clipTrackBindings } from "./clip-audit.js";
|
|
1450
|
+
/**
|
|
1451
|
+
* Report which bones of a character a clip does not drive.
|
|
1452
|
+
* @situation find out why a character keeps the previous animation's hand shape
|
|
1453
|
+
* @situation check how much of a rig a clip covers before shipping it
|
|
1454
|
+
* @constraint a track that binds nothing counts as driving nothing
|
|
1455
|
+
* @example import { clipBoneCoverage } from "@threenative/core";
|
|
1456
|
+
* const coverage = clipBoneCoverage(character, clip);
|
|
1457
|
+
*/
|
|
1458
|
+
export { clipBoneCoverage } from "./clip-audit.js";
|
|
1459
|
+
export type {
|
|
1460
|
+
IBonePoseError,
|
|
1461
|
+
IClipBindingReport,
|
|
1462
|
+
IClipCoverageReport,
|
|
1463
|
+
IClipPoseErrorOptions,
|
|
1464
|
+
IClipPoseErrorReport,
|
|
1465
|
+
IClipPoseSubject,
|
|
1466
|
+
IClipTrackBinding,
|
|
1467
|
+
} from "./clip-audit.js";
|
|
1468
|
+
/**
|
|
1469
|
+
* Measure a rig's parent→child bone distances, in world space, as it stands right now.
|
|
1470
|
+
* @situation capture a rig's bind-pose bone lengths before any clip plays
|
|
1471
|
+
* @situation measure a skeleton for the bone-length invariance check
|
|
1472
|
+
* @constraint the baseline and the later comparison must come from the same rig under the same ancestor transform, so a uniform scale cancels
|
|
1473
|
+
* @example import { boneLengths } from "@threenative/core";
|
|
1474
|
+
* const baseline = boneLengths(character);
|
|
1475
|
+
*/
|
|
1476
|
+
export { boneLengths } from "./bone-lengths.js";
|
|
1477
|
+
/**
|
|
1478
|
+
* Compare a rig's bone distances now against a captured snapshot and name every bone that moved.
|
|
1479
|
+
* @situation find out why a skinned character renders deformed
|
|
1480
|
+
* @situation check that an animated pose keeps the skeleton rigid
|
|
1481
|
+
* @situation name the bone that breaks a posed skeleton without taking a screenshot
|
|
1482
|
+
* @constraint a rigid skeleton preserves every parent→child distance under any pose; a named bone is a defect with an address
|
|
1483
|
+
* @constraint this is a diagnostic — it reports numbers and names; it moves nothing and decides no appearance
|
|
1484
|
+
* @example import { boneLengths, boneLengthDeviations } from "@threenative/core";
|
|
1485
|
+
* const report = boneLengthDeviations(character, boneLengths(character));
|
|
1486
|
+
* if (!report.rigid && report.worst !== null) console.log(report.worst.bone, report.worst.ratio);
|
|
1487
|
+
*/
|
|
1488
|
+
export { boneLengthDeviations } from "./bone-lengths.js";
|
|
1489
|
+
export type {
|
|
1490
|
+
IBoneLengthDeviation,
|
|
1491
|
+
IBoneLengthDeviationReport,
|
|
1492
|
+
IBoneLengthDeviationsOptions,
|
|
1493
|
+
IBoneLengthSnapshot,
|
|
1494
|
+
} from "./bone-lengths.js";
|
|
1495
|
+
export type {
|
|
1496
|
+
ContextMenuPolicy,
|
|
1497
|
+
IInputAction,
|
|
1498
|
+
IInputGamepad,
|
|
1499
|
+
InputBindings,
|
|
1500
|
+
InputPlatformSource,
|
|
1501
|
+
IRawInputPointer,
|
|
1502
|
+
IRawInputPointerEdge,
|
|
1503
|
+
IRawInputState,
|
|
1504
|
+
} from "./input.js";
|
|
1505
|
+
/**
|
|
1506
|
+
* The map a game reads input through: named actions, 2D vectors and scalar axes resolved from
|
|
1507
|
+
* keyboard, gamepad, mouse, wheel, pinch and touch.
|
|
1508
|
+
*
|
|
1509
|
+
* `defineGame({ input })` builds one and hands it to the running game as `ctx.input`, so the usual
|
|
1510
|
+
* route is a binding in the config and `ctx.input.axis("move")` in the update. Construct one
|
|
1511
|
+
* directly to drive a menu, a replay or a test outside a running game.
|
|
1512
|
+
*
|
|
1513
|
+
* @situation map WASD keys to a movement axis instead of reading the held key set in the update loop
|
|
1514
|
+
* @situation read a jump, a fire or a reload as one named action bound to key, gamepad button and mouse button together
|
|
1515
|
+
* @situation read mouse look, wheel zoom or a two-finger pinch as an axis the frame loop already ticks
|
|
1516
|
+
* @constraint `buttons` is the gamepad and `mouseButtons` the mouse; `up`/`down`/`left`/`right` are the directions of `vector(name)`, not the keys that press it
|
|
1517
|
+
* @constraint scroll, pinch and pointer-relative sources are declared on the binding and read through `axis(name)`; a game adds no window listener of its own
|
|
1518
|
+
* @example const game = defineGame({ input: { move: { up: ["KeyW"], down: ["KeyS"], left: ["KeyA"], right: ["KeyD"] } }, scenes: { Play } });
|
|
1519
|
+
* // inside the scene, per frame: ctx.input.axis("move") is 0 at rest and 1 at full tilt
|
|
1520
|
+
*/
|
|
1521
|
+
export { InputMap } from "./input.js";
|
|
1522
|
+
/**
|
|
1523
|
+
* Lock the pointer to the game's surface: the capture every first-person mouse look needs.
|
|
1524
|
+
*
|
|
1525
|
+
* A browser grants capture only from a user gesture, so call it from a click or a pointerdown
|
|
1526
|
+
* handler. A relative binding such as `look: { pointerRelative: true }` already requests capture on
|
|
1527
|
+
* the first canvas click; this is the same request for a game that starts capture from another
|
|
1528
|
+
* named gesture, and `ctx.input.captureMouse()` is the map's own way to ask.
|
|
1529
|
+
*
|
|
1530
|
+
* @situation lock the mouse pointer so first-person mouse look keeps the cursor out of the way
|
|
1531
|
+
* @situation stop the cursor leaving the window in the middle of a turn
|
|
1532
|
+
* @constraint the browser grants capture only from a user gesture and a refusal is reported, never swallowed
|
|
1533
|
+
* @constraint a relative binding requests capture on canvas click unless `captureOnClick: false` opts out
|
|
1534
|
+
* @example canvas.addEventListener("click", () => captureMouse(canvas));
|
|
1535
|
+
*/
|
|
1536
|
+
export { captureMouse } from "./input.js";
|