@threenative/core 0.3.3 → 0.3.5
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 +2019 -59
- package/dist/{assets-CYKk2WTu.d.ts → assets-CqvE429w.d.ts} +45 -3
- package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
- package/dist/{canvas-layer-C1SnMoJ-.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
- package/dist/{game-D_6r-k4Y.d.ts → game-Bj8G1wmD.d.ts} +242 -17
- package/dist/hot.d.ts +5 -5
- package/dist/index.d.ts +1131 -105
- package/dist/index.js +15201 -4782
- package/dist/model-lod-BDAUYgsS.d.ts +197 -0
- package/dist/playtest.d.ts +6 -4
- package/dist/playtest.js +84 -11
- 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-Cy4qeBOA.d.ts → renderer-9yEo9hPa.d.ts} +676 -21
- package/dist/terrain-jobs-worker.d.ts +2 -0
- package/dist/terrain-jobs-worker.js +130 -0
- package/dist/ui-layer.d.ts +5 -3
- package/dist/ui-layer.js +59 -8
- package/dist/world.d.ts +1596 -17
- package/dist/world.js +17035 -521
- package/gpl/fixtures/make_world_fixture.py +184 -0
- package/gpl/recipes/_common.py +11 -0
- package/gpl/recipes/decimate.py +11 -5
- package/gpl/recipes/export_world.py +699 -0
- package/mcp/blender-server.mjs +61 -4
- package/mcp/blender.mjs +3 -4
- package/mcp/engine-server.mjs +55 -21
- 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 +8246 -389
- package/scripts/apply-three-patch.mjs +123 -41
- 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 +2390 -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 +564 -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 +839 -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/dist/gpu-readback-CMklJs6r.d.ts +0 -112
package/dist/index.d.ts
CHANGED
|
@@ -1,17 +1,18 @@
|
|
|
1
1
|
import * as three from 'three';
|
|
2
|
-
import { Object3D, AnimationClip, AnimationMixer,
|
|
3
|
-
export { I as IAssetLoader, a as IAssetLoaderOptions, c as createAssetLoader, r as reconcileMirroredClips } from './assets-
|
|
4
|
-
export { A as AudioBus, I as IAudioBusOptions, b as IAudioPlayOptions, r as resetAudioCueLedger } from './audio-
|
|
5
|
-
export { C as CanvasLayer } from './canvas-layer-
|
|
6
|
-
import {
|
|
7
|
-
export { A as AfterPhysicsCallback, C as ContextMenuPolicy, G as GEOMETRY_ASSET_KEY, c as GEOMETRY_CAPTURE_DEFAULT_LIMIT, d as GEOMETRY_CAPTURE_MAX_LIMIT, e as GEOMETRY_CAPTURE_SORTS, f as GEOMETRY_CAPTURE_TIMEOUT_MS, g as GEOMETRY_CAPTURE_WALK_CAP, h as GeometryCaptureSort, i as ICtx, I as IGame, j as IGameObservationContribution, k as IGameObservationSampleRequest, l as IGamePlatformSource, m as IGeometryCaptureAsset, n as IGeometryCaptureMesh, o as IGeometryCapturePass, p as IGeometryCaptureReport, q as IGeometryCaptureRequest, r as IGeometryCaptureRow, s as IInputAction, t as IInputGamepad, u as IPointerDragHandle, v as IPointerEvent3D, w as IPointerEvents3D, x as IPointerEvents3DOptions, y as IPointerEvents3DPicker, z as IPointerState, B as IRandom, D as IRawInputPointer, E as IRawInputPointerEdge, F as IRawInputState, H as IRaycastOptions, J as IScenePickerOptions, K as IThreeNativeAudioConfig, L as IThreeNativeAudioLoop, M as IThreeNativeAudioOverride, N as IThreeNativeAudioSpectrum, O as IThreeNativeBootSplash, P as IThreeNativeConfig, Q as IThreeNativeIconVariants, R as IThreeNativeLodConfig, S as IThreeNativeLodGenerationConfig, T as IThreeNativeLodOverride, U as IThreeNativeLodRuntimeConfig, V as IThreeNativeTexturesConfig, W as ITweenOptions, X as IWarmUpCacheOptions, Y as IWarmUpObservation, Z as IWarmUpOptions, _ as IWarmUpProgress, $ as IWarmUpRenderer, a0 as IWarmUpReport, a1 as InputBindings, a2 as
|
|
2
|
+
import { Object3D, AnimationClip, AnimationMixer, Vector3, Camera, Group, Matrix4, Mesh, BufferGeometry, InstancedMesh, Material, ColorRepresentation, Box3, Scene, DirectionalLight, HemisphereLight, Color, ToneMapping, FogExp2, Sprite, DataTexture, CatmullRomCurve3, Texture } from 'three';
|
|
3
|
+
export { I as IAssetLoader, a as IAssetLoaderOptions, b as ITextureOptions, c as createAssetLoader, r as reconcileMirroredClips } from './assets-CqvE429w.js';
|
|
4
|
+
export { A as AudioBus, I as IAudioBusOptions, b as IAudioCompressorOptions, c as IAudioPlayOptions, r as resetAudioCueLedger } from './audio-DIJE5HTr.js';
|
|
5
|
+
export { C as CanvasLayer } from './canvas-layer-C1-5CviZ.js';
|
|
6
|
+
import { b as IGamePluginRuntime, a as IGamePluginHooks } from './game-Bj8G1wmD.js';
|
|
7
|
+
export { A as AfterPhysicsCallback, C as ContextMenuPolicy, G as GEOMETRY_ASSET_KEY, c as GEOMETRY_CAPTURE_DEFAULT_LIMIT, d as GEOMETRY_CAPTURE_MAX_LIMIT, e as GEOMETRY_CAPTURE_SORTS, f as GEOMETRY_CAPTURE_TIMEOUT_MS, g as GEOMETRY_CAPTURE_WALK_CAP, h as GeometryCaptureSort, i as ICtx, I as IGame, j as IGameObservationContribution, k as IGameObservationSampleRequest, l as IGamePlatformSource, m as IGeometryCaptureAsset, n as IGeometryCaptureMesh, o as IGeometryCapturePass, p as IGeometryCaptureReport, q as IGeometryCaptureRequest, r as IGeometryCaptureRow, s as IInputAction, t as IInputGamepad, u as IPointerDragHandle, v as IPointerEvent3D, w as IPointerEvents3D, x as IPointerEvents3DOptions, y as IPointerEvents3DPicker, z as IPointerState, B as IRandom, D as IRawInputPointer, E as IRawInputPointerEdge, F as IRawInputState, H as IRaycastOptions, J as IScenePickerOptions, K as IThreeNativeAudioConfig, L as IThreeNativeAudioLoop, M as IThreeNativeAudioOverride, N as IThreeNativeAudioSpectrum, O as IThreeNativeBootSplash, P as IThreeNativeConfig, Q as IThreeNativeIconVariants, R as IThreeNativeLodConfig, S as IThreeNativeLodGenerationConfig, T as IThreeNativeLodOverride, U as IThreeNativeLodRuntimeConfig, V as IThreeNativeTexturesConfig, W as ITweenOptions, X as IWarmUpCacheOptions, Y as IWarmUpObservation, Z as IWarmUpOptions, _ as IWarmUpProgress, $ as IWarmUpRenderer, a0 as IWarmUpReport, a1 as InputBindings, a2 as InputMap, a3 as InputPlatformSource, a4 as PointerEvent3DListener, a5 as PointerEvent3DType, a6 as PointerEvents3D, a7 as Scene, a8 as SceneFrame, a9 as ScenePicker, aa as ScheduleHandle, ab as Scheduler, ac as ThreeNativeBackgroundMode, ad as ThreeNativeLodMinTrianglesScope, ae as ThreeNativeLodPreset, af as ThreeNativeOrientation, ag as ThreeNativeUiRenderer, ah as WarmUpCacheStatus, ai as WarmUpObservationStatus, aj as afterPhysics, ak as captureMouse, al as createRandom, am as defineGame, an as warmUpScene } from './game-Bj8G1wmD.js';
|
|
8
8
|
import * as three_webgpu from 'three/webgpu';
|
|
9
|
-
import { StorageTexture, ComputeNode, UniformNode, Node, TextureNode, NodeMaterial, StorageBufferNode, StructTypeNode, Data3DTexture, ShadowBaseNode, NodeBuilder, NodeFrame, SpriteNodeMaterial, StorageTextureNode } from 'three/webgpu';
|
|
10
|
-
import { I as IRendererLike, F as FramePassKind, a as IFrameBudgetWindow } from './renderer-
|
|
11
|
-
export { D as DEFAULT_PIPELINE_CENSUS_LIMIT,
|
|
12
|
-
import { I as IComputeDriven$1,
|
|
13
|
-
export { C as ComputeDrivenRegistry, G as GPUReadback,
|
|
14
|
-
import {
|
|
9
|
+
import { StorageTexture, ComputeNode, UniformNode, Node, TextureNode, NodeMaterial, StorageBufferNode, StructTypeNode, Data3DTexture, ShadowBaseNode, NodeBuilder, NodeFrame, SpriteNodeMaterial, StorageTextureNode, Storage3DTexture } from 'three/webgpu';
|
|
10
|
+
import { I as IRendererLike, F as FramePassKind, a as IFrameBudgetWindow } from './renderer-9yEo9hPa.js';
|
|
11
|
+
export { D as DEFAULT_PIPELINE_CENSUS_LIMIT, h as DEFAULT_TARGET_FPS, i as FRAME_BUDGET_MARKER, j as FRAME_BUDGET_PHASES, k as FRAME_HITCH_MARKER, l as FrameBudget, m as FrameBudgetPhase, n as FrameCounters, o as ICounterDevice, g as IFrameBudgetOptions, p as IFrameBudgetPassSummary, b as IFrameBudgetSimulation, q as IFrameBudgetSummary, r as IFrameCounters, d as IFramePhaseSample, e as IPipelineCensus, s as IPipelineCensusCounts, t as IPipelineCensusEvent, u as IPipelineCensusOptions, v as IPipelineProvenance, w as IPipelineShaderObservation, x as IPlatformInfo, y as IRenderChainApplied, z as IRenderChainBudgetWindow, A as IRenderChainDroppedStage, B as IRenderChainOptions, C as IRenderChainRenderer, E as IRenderChainRequest, G as IRenderChainStage, H as IRenderChainStageContext, J as IRenderChainVelocityMeasurement, K as IRenderChainVelocityReport, L as IRenderChainVelocityRequest, M as IRenderChainVelocityResult, c as IRenderPassSample, N as ITargetFps, O as IVelocityRenderPass, P as MAX_TARGET_FPS, Q as MainDrawSource, R as PIPELINE_CENSUS_CAPABILITY, S as PIPELINE_CENSUS_VERSION, T as PipelineCensus, U as PipelineCensusMode, V as PipelineCensusStatus, W as PlatformFormFactor, X as PlatformOS, Y as PlatformRuntime, Z as RENDER_CHAIN_MARKER, _ as RENDER_CHAIN_STAGE_ORDER, $ as RENDER_CHAIN_TIERS, a0 as RenderChain, a1 as RenderChainSource, a2 as RenderChainStageId, a3 as RenderChainStageName, a4 as RenderChainTier, a5 as RenderChainTierRequest, a6 as RenderChainVelocitySource, a7 as TargetFpsSource, a8 as VELOCITY_OUTPUT_NAME, a9 as VELOCITY_PREVIOUS_BONE_MATRICES, aa as VELOCITY_PREVIOUS_INSTANCE_MATRICES, ab as VELOCITY_PREVIOUS_WORLD_MATRIX, ac as VelocityTracker, ad as counterDeviceOf, ae as createPipelineCensus, af as ensureVelocityOutput, ag as getPlatform, ah as isMobile, ai as isNative, aj as isTouchscreenAvailable, ak as isWeb, al as prewarm, am as readRenderChainObservation, an as readRenderChainReport, ao as readVelocityPreviousBoneMatrices, ap as readVelocityPreviousMatrices, aq as readVelocityPreviousWorldMatrix, ar as resolveTargetFps, as as snapRefreshRate, at as velocityTexture, au as withVelocityContext } from './renderer-9yEo9hPa.js';
|
|
12
|
+
import { I as IComputeDriven$1, c as IGPUReadbackSample, d as IBudgetCandidate } from './model-lod-BDAUYgsS.js';
|
|
13
|
+
export { C as ComputeDrivenRegistry, D as DISCRETE_LOD_DEFAULT_ERROR_PIXELS, e as DISCRETE_LOD_DEFAULT_HYSTERESIS, G as GPUReadback, f as IGPUReadbackOptions, g as baseGeometryOf, l as lodPixelScale, u as updateModelLods } from './model-lod-BDAUYgsS.js';
|
|
14
|
+
import { SkyMesh } from 'three/addons/objects/SkyMesh.js';
|
|
15
|
+
import { Node as Node$1, UniformNode as UniformNode$1 } from 'three/src/nodes/Nodes.js';
|
|
15
16
|
import 'zustand/vanilla';
|
|
16
17
|
|
|
17
18
|
/**
|
|
@@ -83,6 +84,10 @@ declare const SPANS: {
|
|
|
83
84
|
readonly sort: 12;
|
|
84
85
|
/** Per-draw submission inside a render call, accumulated across the draws of one pass. */
|
|
85
86
|
readonly draw: 13;
|
|
87
|
+
/** Terrain block rebuild and merged-attribute swap on the calling thread. */
|
|
88
|
+
readonly terrainBlock: 14;
|
|
89
|
+
/** Terrain seam reconciliation and bridge-attribute swap on the calling thread. */
|
|
90
|
+
readonly terrainSeam: 15;
|
|
86
91
|
};
|
|
87
92
|
type SpanId = (typeof SPANS)[keyof typeof SPANS];
|
|
88
93
|
/** Names, indexed by id. The only place a span name is a string. */
|
|
@@ -165,14 +170,14 @@ declare class SpanRecorder {
|
|
|
165
170
|
/** The window just closed, or `undefined` when no frame was recorded in it. */
|
|
166
171
|
window(): ISpanWindow | undefined;
|
|
167
172
|
}
|
|
168
|
-
/** Installs or removes the recorder every `beginSpan`/`endSpan` routes to. */
|
|
173
|
+
/** Installs or removes the recorder every `beginSpan`/`endSpan` routes to, in every entry copy. */
|
|
169
174
|
declare function setSpanRecorder(next: SpanRecorder | undefined): void;
|
|
170
175
|
declare function spanRecorder(): SpanRecorder | undefined;
|
|
171
176
|
/** The one clock the spans and the frame budget share, so their numbers are comparable. */
|
|
172
177
|
declare function spanNow(): number;
|
|
173
178
|
/**
|
|
174
179
|
* Opens a span. One guarded return when spans are off — no clock read, no allocation, no branch on
|
|
175
|
-
* anything but the recorder's own presence.
|
|
180
|
+
* anything but the recorder's own presence. The opt-in native wall-time sink sees it first.
|
|
176
181
|
*/
|
|
177
182
|
declare function beginSpan(id: SpanId): void;
|
|
178
183
|
declare function endSpan(id: SpanId): void;
|
|
@@ -290,11 +295,197 @@ declare class AnimationPlayer {
|
|
|
290
295
|
/** The clip behind a name, for a game that wants the action or the raw `AnimationClip`. */
|
|
291
296
|
clip(name: string): AnimationClip;
|
|
292
297
|
play(name: string, options?: IAnimationPlayOptions): void;
|
|
298
|
+
/**
|
|
299
|
+
* Whether a clip has posed the skeleton. False until the first `play` or `playWeighted`, so a
|
|
300
|
+
* rig that never plays a clip stays observably in its bind pose.
|
|
301
|
+
*/
|
|
302
|
+
get posed(): boolean;
|
|
303
|
+
/**
|
|
304
|
+
* Play several clips at once, at weights the game computed — the plumbing half of a locomotion
|
|
305
|
+
* blend space. The samples, the thresholds and the interpolation domain stay the game's: this
|
|
306
|
+
* takes the answer (`{ clip, weight }[]`) and owns what happens to the actions.
|
|
307
|
+
*
|
|
308
|
+
* What it guarantees, because every blend space needs the same four things:
|
|
309
|
+
*
|
|
310
|
+
* - **One mixer, one updater, one action per clip.** Nothing here creates an `AnimationMixer`.
|
|
311
|
+
* - **A still-contributing clip keeps its phase.** Returning to a walk mid-cycle does not
|
|
312
|
+
* restart it — the same convention `play` follows.
|
|
313
|
+
* - **An entering clip joins the gait.** Its normalized time is set to the dominant
|
|
314
|
+
* contributor's, so a walk→run change does not cross the feet mid-stride. Pass
|
|
315
|
+
* `phaseSync: false` for authored cycles that are deliberately out of phase with each other.
|
|
316
|
+
* - **Weights stay finite, non-negative and summing to 1.** Malformed input throws rather than
|
|
317
|
+
* producing a pose nobody can explain.
|
|
318
|
+
*
|
|
319
|
+
* `transition` is the bounded authored transition: weights move linearly towards the request
|
|
320
|
+
* over that many seconds, so a large instantaneous intent change cannot pop the pose, and `0`
|
|
321
|
+
* snaps them on the call. A clip that drops out of the request fades to zero and is then
|
|
322
|
+
* stopped, so repeated blends release their actions.
|
|
323
|
+
*
|
|
324
|
+
* Entries are played as loops. Events — a hit, a death, a reload — are `play`'s job.
|
|
325
|
+
*/
|
|
326
|
+
playWeighted(entries: readonly {
|
|
327
|
+
readonly clip: string;
|
|
328
|
+
readonly weight: number;
|
|
329
|
+
}[], options?: {
|
|
330
|
+
readonly transition?: number;
|
|
331
|
+
readonly phaseSync?: boolean;
|
|
332
|
+
}): void;
|
|
293
333
|
update(dt: number): void;
|
|
294
334
|
stop(): void;
|
|
295
335
|
dispose(): void;
|
|
296
336
|
}
|
|
297
337
|
|
|
338
|
+
interface IAnimationMask {
|
|
339
|
+
readonly bones: readonly string[];
|
|
340
|
+
readonly descendants?: boolean;
|
|
341
|
+
/** Explicit root ownership; refused when root motion owns that same track. */
|
|
342
|
+
readonly includeRoot?: boolean;
|
|
343
|
+
}
|
|
344
|
+
interface IAnimationLayer {
|
|
345
|
+
readonly name: string;
|
|
346
|
+
readonly clip: string;
|
|
347
|
+
readonly mask: IAnimationMask;
|
|
348
|
+
readonly mode: "override" | "additive";
|
|
349
|
+
readonly once?: boolean;
|
|
350
|
+
readonly reference?: {
|
|
351
|
+
readonly clip: AnimationClip;
|
|
352
|
+
readonly time: number;
|
|
353
|
+
};
|
|
354
|
+
}
|
|
355
|
+
|
|
356
|
+
/*!
|
|
357
|
+
* Selectively adapted from GGEZ packages/anim-core/src/root-motion.ts
|
|
358
|
+
* (translation difference, quaternion yaw) at
|
|
359
|
+
* 45ed541cb163ef98694467758f60d5533373ac60. Adds explicit root binding,
|
|
360
|
+
* continuous loop intervals, yaw unwrapping and validated Three transforms.
|
|
361
|
+
* MIT License
|
|
362
|
+
* Copyright (c) 2026 @alightinastorm (x.com/alightinastorm)
|
|
363
|
+
* Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
364
|
+
* of this software and associated documentation files (the "Software"), to deal
|
|
365
|
+
* in the Software without restriction, including without limitation the rights
|
|
366
|
+
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
367
|
+
* copies of the Software, and to permit persons to whom the Software is
|
|
368
|
+
* furnished to do so, subject to the following conditions:
|
|
369
|
+
* The above copyright notice and this permission notice shall be included in all
|
|
370
|
+
* copies or substantial portions of the Software.
|
|
371
|
+
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
372
|
+
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
373
|
+
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
374
|
+
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
375
|
+
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
376
|
+
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
377
|
+
* SOFTWARE.
|
|
378
|
+
*/
|
|
379
|
+
|
|
380
|
+
interface IAnimationRootMotionOptions {
|
|
381
|
+
readonly bone: string;
|
|
382
|
+
/** Existing character-body object. Its parent must be identity in this first slice. */
|
|
383
|
+
readonly body: Object3D;
|
|
384
|
+
}
|
|
385
|
+
interface IAnimationMotionDelta {
|
|
386
|
+
readonly translation: Pick<Vector3, "x" | "y" | "z">;
|
|
387
|
+
readonly yaw: number;
|
|
388
|
+
}
|
|
389
|
+
|
|
390
|
+
interface IAnimationComposerOptions {
|
|
391
|
+
readonly root: Object3D;
|
|
392
|
+
/**
|
|
393
|
+
* Copied into owned pose snapshots at construction. Constant stock quaternion tracks use
|
|
394
|
+
* equivalent discrete sampling there; reauthor source keys before constructing a new composer.
|
|
395
|
+
*/
|
|
396
|
+
readonly clips: readonly AnimationClip[];
|
|
397
|
+
readonly samples: readonly string[];
|
|
398
|
+
readonly layers?: readonly IAnimationLayer[];
|
|
399
|
+
readonly rootMotion?: IAnimationRootMotionOptions;
|
|
400
|
+
}
|
|
401
|
+
/**
|
|
402
|
+
* One bounded Three player/mixer. Game-owned intent supplies normalized sample weights;
|
|
403
|
+
* every base action samples one normalized phase, while layered events retain authored time.
|
|
404
|
+
*/
|
|
405
|
+
declare class AnimationComposer {
|
|
406
|
+
#private;
|
|
407
|
+
paused: boolean;
|
|
408
|
+
constructor(options: IAnimationComposerOptions);
|
|
409
|
+
get mixer(): three.AnimationMixer<three.AnimationMixerEventMap>;
|
|
410
|
+
get root(): Object3D<three.Object3DEventMap>;
|
|
411
|
+
get phase(): number;
|
|
412
|
+
get speed(): number;
|
|
413
|
+
set speed(value: number);
|
|
414
|
+
get weights(): readonly number[];
|
|
415
|
+
get sampleTimes(): readonly number[];
|
|
416
|
+
get resources(): {
|
|
417
|
+
actions: number;
|
|
418
|
+
bindings: number;
|
|
419
|
+
scratchBytes: number;
|
|
420
|
+
clipBuffers: number;
|
|
421
|
+
clipBufferBytes: number;
|
|
422
|
+
rootBuffers: number;
|
|
423
|
+
rootBufferBytes: number;
|
|
424
|
+
};
|
|
425
|
+
/** Snapshots remain honest while blocked: phase advances at authored speed, never re-timed by the wall. */
|
|
426
|
+
get motion(): {
|
|
427
|
+
readonly authority: "phase" | "rootMotion";
|
|
428
|
+
readonly requested: Vector3;
|
|
429
|
+
readonly requestedYaw: number;
|
|
430
|
+
readonly accepted: Vector3;
|
|
431
|
+
readonly acceptedYaw: number;
|
|
432
|
+
readonly blocked: boolean;
|
|
433
|
+
};
|
|
434
|
+
get blocked(): boolean;
|
|
435
|
+
setWeights(weights: ArrayLike<number>, transition?: number): void;
|
|
436
|
+
setLayerWeight(name: string, weight: number): void;
|
|
437
|
+
/** Explicit replay; repeated weight requests do not re-fire a completed one-shot. */
|
|
438
|
+
restartLayer(name: string): void;
|
|
439
|
+
update(dt: number): void;
|
|
440
|
+
/** Borrowed proposal: queue it once with CharacterBody3D.move, then finish after physics. */
|
|
441
|
+
advance(dt: number): {
|
|
442
|
+
readonly translation: Vector3;
|
|
443
|
+
readonly yaw: number;
|
|
444
|
+
};
|
|
445
|
+
/** Final authored pose precedes the game's existing IK. This method never writes the body. */
|
|
446
|
+
finish(accepted?: IAnimationMotionDelta): void;
|
|
447
|
+
dispose(): void;
|
|
448
|
+
}
|
|
449
|
+
|
|
450
|
+
/*!
|
|
451
|
+
* Selectively adapted from GGEZ packages/anim-runtime/src/runtime/helpers.ts
|
|
452
|
+
* (findBlend1DChildren, computeTriangleBarycentricWeights, findBlend2DEdgeWeights)
|
|
453
|
+
* at 45ed541cb163ef98694467758f60d5533373ac60. Replaced graph children with
|
|
454
|
+
* validated fixed sample indices, initialization-only sorting and reusable output.
|
|
455
|
+
* MIT License
|
|
456
|
+
* Copyright (c) 2026 @alightinastorm (x.com/alightinastorm)
|
|
457
|
+
* Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
458
|
+
* of this software and associated documentation files (the "Software"), to deal
|
|
459
|
+
* in the Software without restriction, including without limitation the rights
|
|
460
|
+
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
461
|
+
* copies of the Software, and to permit persons to whom the Software is
|
|
462
|
+
* furnished to do so, subject to the following conditions:
|
|
463
|
+
* The above copyright notice and this permission notice shall be included in all
|
|
464
|
+
* copies or substantial portions of the Software.
|
|
465
|
+
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
466
|
+
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
467
|
+
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
468
|
+
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
469
|
+
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
470
|
+
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
471
|
+
* SOFTWARE.
|
|
472
|
+
*/
|
|
473
|
+
type Point = readonly [number, number];
|
|
474
|
+
type Triangle = readonly [number, number, number];
|
|
475
|
+
declare class BlendSpace1D {
|
|
476
|
+
#private;
|
|
477
|
+
readonly weights: Float64Array;
|
|
478
|
+
constructor(thresholds: readonly number[]);
|
|
479
|
+
sample(value: number): Float64Array;
|
|
480
|
+
}
|
|
481
|
+
/** Fixed complete convex-hull triangulation. Collinear triangles and overlapping tiles fail at load. */
|
|
482
|
+
declare class BlendSpace2D {
|
|
483
|
+
#private;
|
|
484
|
+
readonly weights: Float64Array;
|
|
485
|
+
constructor(points: readonly Point[], triangles: readonly Triangle[]);
|
|
486
|
+
sample(x: number, y: number): Float64Array;
|
|
487
|
+
}
|
|
488
|
+
|
|
298
489
|
type NormaliseAxis = "height" | "longest";
|
|
299
490
|
interface INormaliseToMetresOptions {
|
|
300
491
|
readonly metres: number;
|
|
@@ -405,8 +596,12 @@ declare class CameraShake {
|
|
|
405
596
|
* that needs it. The page owns the presentation (and the copy-to-clipboard button players are
|
|
406
597
|
* asked for when they report a launch that hung); this owns the noticing and the wording.
|
|
407
598
|
*/
|
|
408
|
-
/**
|
|
409
|
-
|
|
599
|
+
/**
|
|
600
|
+
* What failed. `stalled` is "no progress for a while"; `device-lost` is the GPU going away;
|
|
601
|
+
* `scene-load-failed` is a scene's `load()` rejecting and `start-failed` is `start()` rejecting,
|
|
602
|
+
* each of which otherwise reads as a stall.
|
|
603
|
+
*/
|
|
604
|
+
type LaunchFailureKind = "stalled" | "device-lost" | "scene-load-failed" | "start-failed";
|
|
410
605
|
interface ILaunchFailure {
|
|
411
606
|
readonly kind: LaunchFailureKind;
|
|
412
607
|
/** One human sentence, already naming the numbers — this is what the Copy button copies. */
|
|
@@ -571,7 +766,7 @@ type AtmosphereDirection = Vector3 | readonly [number, number, number] | Node<"v
|
|
|
571
766
|
* those, and the same object remains useful when a game supplies a completely different look.
|
|
572
767
|
* @situation render a sunrise that changes as time and place change
|
|
573
768
|
* @situation add distance haze from the depth of a scene pass
|
|
574
|
-
* @alias bright
|
|
769
|
+
* @alias green platforms bright saturated sky
|
|
575
770
|
* @constraint supply rayleigh, mie, ozone, planetRadius, and atmosphereRadius; there is no Earth fallback
|
|
576
771
|
* @constraint the game creates the sky object, surface, and sun from the returned nodes
|
|
577
772
|
* @example const atmosphere = new Atmosphere({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
|
|
@@ -721,7 +916,7 @@ declare class GPUSceneBVH extends Group implements IComputeDriven$1 {
|
|
|
721
916
|
get released(): boolean;
|
|
722
917
|
get triangleCount(): number;
|
|
723
918
|
get vertexCount(): number;
|
|
724
|
-
attachRenderer(
|
|
919
|
+
attachRenderer(_renderer: IRendererLike): void;
|
|
725
920
|
process(_renderer: IRendererLike): void;
|
|
726
921
|
/** Repack the selected scene objects and replace the GPU buffers behind the stable node handles. */
|
|
727
922
|
rebuild(): void;
|
|
@@ -729,6 +924,19 @@ declare class GPUSceneBVH extends Group implements IComputeDriven$1 {
|
|
|
729
924
|
detach(): void;
|
|
730
925
|
}
|
|
731
926
|
|
|
927
|
+
interface IInstancedLodOptions {
|
|
928
|
+
/** Baked-chain selection is automatic. `false` leaves detail to the caller. */
|
|
929
|
+
readonly autoLod?: false | {
|
|
930
|
+
readonly maxPixelError?: number;
|
|
931
|
+
readonly hysteresis?: number;
|
|
932
|
+
};
|
|
933
|
+
/** Authored distance levels win over the baked chain. Missing geometries report once at build. */
|
|
934
|
+
readonly lods?: readonly {
|
|
935
|
+
readonly distance: number;
|
|
936
|
+
readonly geometry: BufferGeometry | undefined;
|
|
937
|
+
}[];
|
|
938
|
+
}
|
|
939
|
+
|
|
732
940
|
/** One instance's transform, in the units the geometry was authored in. */
|
|
733
941
|
interface IInstancedPlacement {
|
|
734
942
|
/** World position of the instance's origin, as `[x, y, z]`. */
|
|
@@ -738,7 +946,7 @@ interface IInstancedPlacement {
|
|
|
738
946
|
/** Per-axis scale as `[x, y, z]`, or one number for all three. Default 1. */
|
|
739
947
|
readonly scale?: readonly [number, number, number] | number;
|
|
740
948
|
}
|
|
741
|
-
interface IInstancedBatchOptions {
|
|
949
|
+
interface IInstancedBatchOptions extends IInstancedLodOptions {
|
|
742
950
|
/** The shape every instance draws, supplied by the game. */
|
|
743
951
|
readonly geometry: BufferGeometry;
|
|
744
952
|
/**
|
|
@@ -757,6 +965,15 @@ interface IInstancedBatchBuildOptions {
|
|
|
757
965
|
readonly parent?: Object3D;
|
|
758
966
|
/** Passed straight to the built mesh. Default `false`, as in Three.js. */
|
|
759
967
|
readonly receiveShadow?: boolean;
|
|
968
|
+
/**
|
|
969
|
+
* An existing mesh to refill instead of creating one: used when it draws this batch's geometry
|
|
970
|
+
* and material and holds at least this many instances. Reusing matters on WebGPU, where three
|
|
971
|
+
* keys an instanced mesh's compiled node program by the mesh itself — every new InstancedMesh
|
|
972
|
+
* rebuilds its shader, and a streamed world creating hundreds a cell stalls on it.
|
|
973
|
+
*/
|
|
974
|
+
readonly into?: InstancedMesh;
|
|
975
|
+
/** Instance slots to allocate when a new mesh is created, so later refills fit. Default: count. */
|
|
976
|
+
readonly capacity?: number;
|
|
760
977
|
}
|
|
761
978
|
/**
|
|
762
979
|
* Collapses many copies of one shape into a single draw, without knowing the count up front.
|
|
@@ -777,8 +994,22 @@ declare class InstancedBatch {
|
|
|
777
994
|
constructor(options: IInstancedBatchOptions);
|
|
778
995
|
/** How many instances have been placed so far. */
|
|
779
996
|
get count(): number;
|
|
997
|
+
/**
|
|
998
|
+
* Writes every placed matrix into `target` (a mesh's `instanceMatrix.array`), starting at instance
|
|
999
|
+
* `offset`, and returns how many were written. For a caller that packs several batches into one
|
|
1000
|
+
* shared instance buffer instead of building a mesh per batch.
|
|
1001
|
+
*/
|
|
1002
|
+
writeMatrices(target: Float32Array, offset: number): number;
|
|
780
1003
|
/** The built mesh, or `undefined` before {@link build} — never a guess. */
|
|
781
1004
|
get mesh(): InstancedMesh | undefined;
|
|
1005
|
+
/**
|
|
1006
|
+
* True when this batch holds element-for-element the matrices of `other`.
|
|
1007
|
+
*
|
|
1008
|
+
* A refilter rebuilds a cell's batch from the same run in the same order, so "did the answer
|
|
1009
|
+
* change" is exactly this question, and comparing is what lets the swap skip a rebuild that came
|
|
1010
|
+
* back identical instead of writing, clearing and compacting records the buffer already holds.
|
|
1011
|
+
*/
|
|
1012
|
+
equals(other: InstancedBatch | undefined): boolean;
|
|
782
1013
|
/**
|
|
783
1014
|
* Records one instance from a matrix the game composed itself, and returns its instance index.
|
|
784
1015
|
*
|
|
@@ -833,6 +1064,33 @@ interface IMergePartsOptions {
|
|
|
833
1064
|
*/
|
|
834
1065
|
readonly preserve?: readonly ("uv" | "normal")[];
|
|
835
1066
|
}
|
|
1067
|
+
interface IMergeByMaterialOptions {
|
|
1068
|
+
/** Named in the error when a group's merge is refused. Say what was being built. */
|
|
1069
|
+
readonly label: string;
|
|
1070
|
+
/**
|
|
1071
|
+
* Leaves one mesh out of its material's group and out of the result — a piece that moves at run
|
|
1072
|
+
* time, or one a capture script addresses by name.
|
|
1073
|
+
*/
|
|
1074
|
+
readonly skip?: (mesh: Mesh) => boolean;
|
|
1075
|
+
/**
|
|
1076
|
+
* An `InstancedMesh` is baked into its material's group as one part per instance matrix while that
|
|
1077
|
+
* group stays at or below this many triangles. Above it — or absent, which is the old behaviour —
|
|
1078
|
+
* it comes back in the result untouched, because one instanced draw is already cheaper than the
|
|
1079
|
+
* triangles it expands into.
|
|
1080
|
+
*/
|
|
1081
|
+
readonly expandInstancedUnderTriangles?: number;
|
|
1082
|
+
/**
|
|
1083
|
+
* Vertices one merged group may hold before the rest of its material's parts start a second mesh.
|
|
1084
|
+
*
|
|
1085
|
+
* One merged group is one upload on the frame that first draws it, and that upload is the frame's
|
|
1086
|
+
* whole cost: measured in a browser, a streamed world created 826 GPU buffers totalling 228.8 MB
|
|
1087
|
+
* out of `createAttribute`, 33 of them over 1 MB, and the first draw of the largest chunk meshes
|
|
1088
|
+
* took up to 230 ms. Splitting a material group in traversal order — which keeps the pieces
|
|
1089
|
+
* adjacent to the pieces they were placed beside — bounds each of those uploads instead of
|
|
1090
|
+
* trading one draw for a single enormous buffer. See `CHUNK_MERGE_MAX_VERTICES`.
|
|
1091
|
+
*/
|
|
1092
|
+
readonly maxGroupVertices?: number;
|
|
1093
|
+
}
|
|
836
1094
|
/**
|
|
837
1095
|
* Merge game-authored pieces into one buffer, keeping each piece's own colour and, when asked,
|
|
838
1096
|
* its uv and authored normals.
|
|
@@ -846,8 +1104,69 @@ interface IMergePartsOptions {
|
|
|
846
1104
|
* are entirely the game's, one per part, and changing them changes nothing here. By default the
|
|
847
1105
|
* merged normals are recomputed from the merged buffer; `preserve` keeps the authored normals and
|
|
848
1106
|
* texture coordinates instead so an imported model's shading survives the bake.
|
|
1107
|
+
*
|
|
1108
|
+
* A group whose parts are all indexed merges indexed — the sum of their vertex counts, not three
|
|
1109
|
+
* times their triangles — and only a mixed group falls back to the de-indexed soup. One crossing
|
|
1110
|
+
* 65,535 vertices gets a 32-bit index, because a 16-bit one cannot name the vertex.
|
|
849
1111
|
*/
|
|
850
1112
|
declare function mergeParts(parts: Iterable<IMergePart>, options: IMergePartsOptions): BufferGeometry;
|
|
1113
|
+
/**
|
|
1114
|
+
* Bake a hierarchy's static meshes into one mesh per material, transforms and all.
|
|
1115
|
+
*
|
|
1116
|
+
* A building or a ship is dozens of boxes and cylinders that never move relative to each other, and
|
|
1117
|
+
* every one of them is a draw call. Grouping by material and merging each group is the ordinary
|
|
1118
|
+
* fix, and the ordinary fix is thirty lines an agent rewrites in every game, each time slightly
|
|
1119
|
+
* differently: walk the tree, group by material, bake `matrixWorld` into the vertices, hand the
|
|
1120
|
+
* group to `mergeParts`, build a mesh on the game's own material. The parts here are the same
|
|
1121
|
+
* `IMergePart` list, so a game that already merges by hand gets the same refusals — a group that
|
|
1122
|
+
* cannot merge throws naming `label:material`, not silently vanishing.
|
|
1123
|
+
*
|
|
1124
|
+
* Nothing here decides how anything looks: the material is the game's own instance, the geometry is
|
|
1125
|
+
* exactly what was authored, and the group split follows the materials the game already made.
|
|
1126
|
+
*
|
|
1127
|
+
* `normal` survives when every mesh in a group carries it and is recomputed otherwise. `uv` survives
|
|
1128
|
+
* when any mesh carries it, so a group where only some do is the refusal `mergeParts` raises, never
|
|
1129
|
+
* a texture silently left unmapped. Skinned meshes are left alone — their vertices are posed per
|
|
1130
|
+
* frame — and an instanced one is left alone unless `expandInstancedUnderTriangles` names a cap its
|
|
1131
|
+
* group fits under and its own shape is small enough to be worth repeating, which bakes every
|
|
1132
|
+
* instance matrix into the merge.
|
|
1133
|
+
*
|
|
1134
|
+
* `maxGroupVertices` bounds a single group, and a material whose parts cross it is merged into
|
|
1135
|
+
* several meshes in traversal order — more draws, none of them carrying a buffer big enough to stall
|
|
1136
|
+
* the frame that first submits it.
|
|
1137
|
+
*/
|
|
1138
|
+
declare function mergeByMaterial(root: Object3D, options: IMergeByMaterialOptions): Mesh[];
|
|
1139
|
+
|
|
1140
|
+
/**
|
|
1141
|
+
* A debug switch a game reads the same way on every platform it ships to.
|
|
1142
|
+
*
|
|
1143
|
+
* Two questions an agent answers differently in every game, both of which cost a rewrite: how do I
|
|
1144
|
+
* turn this on for one run without changing the code, and how does a capture script reach the object
|
|
1145
|
+
* it wants to look at. The answers here are one function each, and neither decides how anything
|
|
1146
|
+
* looks.
|
|
1147
|
+
*/
|
|
1148
|
+
/**
|
|
1149
|
+
* A debug switch read from the URL, or from the environment on a native launch.
|
|
1150
|
+
*
|
|
1151
|
+
* @situation read a debug toggle from the URL or an environment variable
|
|
1152
|
+
*
|
|
1153
|
+
* A browser asks with the query string — `?freeCam`, or `?freeCam=0` to force it off — and a native
|
|
1154
|
+
* launch asks with `TN_DEBUG_FREE_CAM`, because a query string is not something a developer sets on
|
|
1155
|
+
* a command line. `0` and `false` are off, so a saved URL that used to enable a switch still says
|
|
1156
|
+
* "off" rather than quietly turning it back on.
|
|
1157
|
+
*/
|
|
1158
|
+
declare function debugFlag(name: string): boolean;
|
|
1159
|
+
/**
|
|
1160
|
+
* Publish one game object for a capture script or the console, in development builds only.
|
|
1161
|
+
*
|
|
1162
|
+
* @situation expose a game object to a capture script or the console in dev builds
|
|
1163
|
+
*
|
|
1164
|
+
* Playtest reads `__THREENATIVE__` in a dev build and is silent in a production one, so a game that
|
|
1165
|
+
* publishes its player, its camera or a scene handle under `.debug` is reachable from the same
|
|
1166
|
+
* place a production build is not. Other keys on the shared object are left alone; the dev surfaces
|
|
1167
|
+
* the engine installs beside them keep working.
|
|
1168
|
+
*/
|
|
1169
|
+
declare function exposeDebug(name: string, value: unknown): void;
|
|
851
1170
|
|
|
852
1171
|
/**
|
|
853
1172
|
* A mesh that draws only the clusters this camera can resolve.
|
|
@@ -901,13 +1220,32 @@ interface IClusteredMeshOptions {
|
|
|
901
1220
|
}
|
|
902
1221
|
declare class ClusteredMesh extends Mesh {
|
|
903
1222
|
#private;
|
|
904
|
-
/** The baked payload.
|
|
905
|
-
|
|
1223
|
+
/** The baked payload. The bake is the only thing that writes it; a copy takes the source's. */
|
|
1224
|
+
table: IClusterTable;
|
|
906
1225
|
/** Screen-space error budget in pixels. Writable — it is the game's call. */
|
|
907
1226
|
errorPixels: number;
|
|
908
1227
|
/** Camera movement, in the mesh's own units, below which the previous cut is kept. */
|
|
909
1228
|
recutDistance: number;
|
|
910
1229
|
constructor(geometry: BufferGeometry, surface: Material | Material[], table: IClusterTable, options?: IClusteredMeshOptions);
|
|
1230
|
+
/**
|
|
1231
|
+
* A second mesh over the same body, cut for its own place in the scene.
|
|
1232
|
+
*
|
|
1233
|
+
* three's `Object3D.clone` builds through `new this.constructor()`, and this class's constructor
|
|
1234
|
+
* wants a table — so every game that stood a second copy of a cooked model where it wanted a
|
|
1235
|
+
* statue died in `assertTable` before drawing anything. The arguments are the source's own,
|
|
1236
|
+
* which is what a copy is.
|
|
1237
|
+
*/
|
|
1238
|
+
clone(recursive?: boolean): this;
|
|
1239
|
+
/**
|
|
1240
|
+
* Becomes a copy of `source`, sharing the bake and the vertices and keeping a cut of its own.
|
|
1241
|
+
*
|
|
1242
|
+
* `Mesh.copy` shares the geometry outright, which this class cannot let it do: the cut lives in
|
|
1243
|
+
* the geometry's index buffer, so two meshes on one geometry would overwrite each other's index
|
|
1244
|
+
* every frame and both would draw whichever spoke last. The copy takes the vertex attributes by
|
|
1245
|
+
* reference instead — one copy of them on the GPU, because three keys its attributes on the
|
|
1246
|
+
* attribute — and the shared table, which is frozen at bake time and cannot go stale.
|
|
1247
|
+
*/
|
|
1248
|
+
copy(source: this, recursive?: boolean): this;
|
|
911
1249
|
/** Clusters in the current cut. */
|
|
912
1250
|
get drawnClusters(): number;
|
|
913
1251
|
/** Triangles the current cut submits. */
|
|
@@ -1015,22 +1353,6 @@ declare class ClusteredBatch {
|
|
|
1015
1353
|
update(camera: Camera, viewportHeight: number): number;
|
|
1016
1354
|
}
|
|
1017
1355
|
|
|
1018
|
-
/** The LOD0 geometry of a mesh under a discrete chain, or the mesh's own geometry otherwise. */
|
|
1019
|
-
declare function baseGeometryOf(mesh: Mesh): BufferGeometry;
|
|
1020
|
-
/**
|
|
1021
|
-
* Takes every discrete-LOD mesh under `root` through this frame's selection.
|
|
1022
|
-
*
|
|
1023
|
-
* The engine calls this itself, once a frame, after matrices are synced and before the render.
|
|
1024
|
-
* Multi-view callers that need the finest level across passes use {@link selectLodLevel} directly;
|
|
1025
|
-
* this entry point selects for the one camera it is handed — which is the main view, and is at
|
|
1026
|
-
* least as fine as a shadow pass of lower resolution needs.
|
|
1027
|
-
*
|
|
1028
|
-
* @returns triangles the managed meshes will submit this frame.
|
|
1029
|
-
*/
|
|
1030
|
-
declare function updateModelLods(root: {
|
|
1031
|
-
traverse(callback: (object: object) => void): void;
|
|
1032
|
-
}, camera: Camera, viewportHeight: number): number;
|
|
1033
|
-
|
|
1034
1356
|
/**
|
|
1035
1357
|
* What the gate did on the last frame, in the shape a frame-budget window reports.
|
|
1036
1358
|
*
|
|
@@ -1096,22 +1418,39 @@ declare function alwaysRender(object: Object3D, enabled?: boolean): void;
|
|
|
1096
1418
|
*
|
|
1097
1419
|
* The pass mirrors three exactly for a visible node: `matrixAutoUpdate` -> `updateMatrix()`, then
|
|
1098
1420
|
* the `matrixWorldNeedsUpdate || force` recompute honouring `matrixWorldAutoUpdate` and a null
|
|
1099
|
-
* parent, then force the children. A node with `visible === false`
|
|
1100
|
-
*
|
|
1101
|
-
*
|
|
1102
|
-
* subtree is recomputed with `force = true`.
|
|
1421
|
+
* parent, then force the children. A node with `visible === false` defers its own compose and its
|
|
1422
|
+
* subtree's walk. Every skipped root is remembered, so the first frame it is visible again both
|
|
1423
|
+
* its own world matrix and its descendants are recomputed with `force = true`.
|
|
1103
1424
|
*
|
|
1104
1425
|
* Two things are never dropped by the pruning, because both are read while nothing above them is
|
|
1105
1426
|
* visible:
|
|
1106
1427
|
*
|
|
1107
|
-
* - a class that overrides `updateMatrixWorld` runs its own
|
|
1108
|
-
*
|
|
1109
|
-
*
|
|
1428
|
+
* - a class that overrides `updateMatrixWorld` runs its own — never a `Scene`, which three does not
|
|
1429
|
+
* override and whose method only differs when something patched the prototype. `SkinnedMesh`
|
|
1430
|
+
* refreshes `bindMatrixInverse`, `Camera` its `matrixWorldInverse`; re-implementing only the base
|
|
1431
|
+
* walk left every deck-crew sailor that had moved since load drawing with a stale bind matrix and
|
|
1110
1432
|
* vanishing from the frame. Their subtrees are small, so walking them whole costs nothing;
|
|
1111
1433
|
* - a hidden node that holds a `Bone` is walked, because a visible `SkinnedMesh` draws with its
|
|
1112
1434
|
* skeleton's matrices wherever the armature happens to sit. Whether bones sit below a node is
|
|
1113
1435
|
* decided once and remembered — a rig is built whole and does not grow.
|
|
1114
1436
|
*
|
|
1437
|
+
* A third thing is dropped, and it is the walk's largest single share on a streamed world: a subtree
|
|
1438
|
+
* frozen with `markStatic`. `markStatic` composes the subtree once and turns off the two flags that
|
|
1439
|
+
* would recompose it, which until now still left three's unconditional recursion visiting every node
|
|
1440
|
+
* under it every frame. A frozen root that carries no dirty flag is a leaf here, and it is one
|
|
1441
|
+
* whether the walk was forced or not: `refreshStaticTransforms` re-arms a root whose own transform
|
|
1442
|
+
* moved, `invalidateStatic` re-arms one something wrote inside, and both compose the subtree once at
|
|
1443
|
+
* that moment. `isStatic` is what separates the engine's freeze from a game that turned the flags off
|
|
1444
|
+
* for its own reasons. See `static-transform.ts`.
|
|
1445
|
+
*
|
|
1446
|
+
* Where the root is a native-engine object it has its own walk, `__tnUpdateMatrixWorld(force, prune)`: this
|
|
1447
|
+
* pass run natively in one call, answering the nodes it visited. The pass calls that and nothing else, since the
|
|
1448
|
+
* walk above costs a bridge call per node read and written (about 16 to 25 thousand a frame at 4,096 cubes).
|
|
1449
|
+
* With `prune` (the `"visible"` mode) the native walk leaves a hidden subtree where it stands by the same rules,
|
|
1450
|
+
* bones included; `"all"` visits every node. A JS subclass of `Object3D` that overrides `updateMatrixWorld` is not
|
|
1451
|
+
* called from inside it; the engine's own `SkinnedMesh` and `Camera` keep their derived matrices. The web and the
|
|
1452
|
+
* legacy host have no such method and walk as above.
|
|
1453
|
+
*
|
|
1115
1454
|
* A game that reads a **hidden** object's `matrixWorld` directly must not rely on this pass
|
|
1116
1455
|
* having reached it: use `getWorldPosition`/`getWorldQuaternion`/`getWorldScale` (which update the
|
|
1117
1456
|
* chain they need) or call `object.updateWorldMatrix(true, false)` first. The convention's named
|
|
@@ -1286,6 +1625,58 @@ declare function describeSceneWarning(warning: ISceneWarning): string;
|
|
|
1286
1625
|
/** The marker line. */
|
|
1287
1626
|
declare function formatSceneWarning(warning: ISceneWarning): string;
|
|
1288
1627
|
|
|
1628
|
+
/**
|
|
1629
|
+
* The engine telling the agent that built the scene what a human finds by playing it once.
|
|
1630
|
+
*
|
|
1631
|
+
* Imported foliage drawn with no image-based light looks like cardboard, and nothing in the build
|
|
1632
|
+
* says so. A GLB's leaf card is `MeshStandardMaterial` (or its Node twin), `alphaTest` above zero,
|
|
1633
|
+
* `side: DoubleSide`; with `scene.environment === null` and no `envMap` on the material, `envMapIntensity`
|
|
1634
|
+
* has nothing to apply — three r185's WebGPU path only uses it when the material carries its own
|
|
1635
|
+
* `envMap`, and `scene.environmentIntensity` only reaches a scene that has an environment. What is
|
|
1636
|
+
* left is a hemisphere fill, so a shaded needle card and its back face land on one flat dark value
|
|
1637
|
+
* and the author compensates with a tint or a fake emissive, which is the paperboard.
|
|
1638
|
+
*
|
|
1639
|
+
* So the rule is derived from the scene graph, never from a constant: cutout PBR, counted by
|
|
1640
|
+
* material, with no environment anywhere in the scene. It fires once per scene entry, warns, and
|
|
1641
|
+
* changes nothing — the fix is the game's own `scene.environment`, which is appearance and therefore
|
|
1642
|
+
* the game's to set.
|
|
1643
|
+
*/
|
|
1644
|
+
|
|
1645
|
+
/** Marker printed once per scene entry, for a log reader and a harness to grep. */
|
|
1646
|
+
declare const UNLIT_FOLIAGE_MARKER = "TN_UNLIT_FOLIAGE";
|
|
1647
|
+
/** The one line that says what to change. Never a second sentence: the fix is one decision. */
|
|
1648
|
+
declare const UNLIT_FOLIAGE_FIX = "set scene.environment (an HDRI or a sky texture) or give these materials an envMap; do not tint or flatten their normals to compensate";
|
|
1649
|
+
/** The verdict: what is affected, and enough names to find it in the scene graph. */
|
|
1650
|
+
interface IUnlitFoliageWarning {
|
|
1651
|
+
/** Distinct materials with no image-based light, the number an author can act on. */
|
|
1652
|
+
readonly materials: number;
|
|
1653
|
+
/** Meshes drawn with them, so one shared material is not mistaken for a scene-wide one. */
|
|
1654
|
+
readonly meshes: number;
|
|
1655
|
+
readonly examples: readonly string[];
|
|
1656
|
+
}
|
|
1657
|
+
/**
|
|
1658
|
+
* The warning for one scene entry, or `undefined` when nothing in it is unlit.
|
|
1659
|
+
*
|
|
1660
|
+
* Fails closed on the reading it needs: a scene with an environment, or a material carrying its own
|
|
1661
|
+
* `envMap`, gets no warning, because the absence of an image-based light is the whole claim and
|
|
1662
|
+
* anything else is speculation. Materials are counted once however many meshes share them, because
|
|
1663
|
+
* a hundred instances of one imported atlas are one decision, not a hundred.
|
|
1664
|
+
*/
|
|
1665
|
+
declare function unlitFoliageWarning(scene: Object3D & {
|
|
1666
|
+
environment?: unknown;
|
|
1667
|
+
}): IUnlitFoliageWarning | undefined;
|
|
1668
|
+
/** The marker line. */
|
|
1669
|
+
declare function formatUnlitFoliageWarning(warning: IUnlitFoliageWarning): string;
|
|
1670
|
+
|
|
1671
|
+
/** Marker for an equirectangular environment below three's minimum PMREM cube size. */
|
|
1672
|
+
declare const ENVIRONMENT_TOO_SMALL_MARKER = "TN_ENVIRONMENT_TOO_SMALL";
|
|
1673
|
+
/** Marker for a drawn material whose opacity three ignores. */
|
|
1674
|
+
declare const OPACITY_IGNORED_MARKER = "TN_OPACITY_IGNORED";
|
|
1675
|
+
/** Structural reads only: Node materials, native adapters and test stubs share this audit. */
|
|
1676
|
+
declare function renderTrapAudit(scene: Object3D & {
|
|
1677
|
+
environment?: unknown;
|
|
1678
|
+
}): string[];
|
|
1679
|
+
|
|
1289
1680
|
/**
|
|
1290
1681
|
* Authored static subtrees: stop recomposing transforms that nobody moves.
|
|
1291
1682
|
*
|
|
@@ -1609,6 +2000,8 @@ interface IClipWindow {
|
|
|
1609
2000
|
readonly level: number;
|
|
1610
2001
|
readonly extent: number;
|
|
1611
2002
|
readonly pageWorldSize: number;
|
|
2003
|
+
/** Pages a window trails its followed centre by before it moves and re-renders. */
|
|
2004
|
+
readonly refreshPages: number;
|
|
1612
2005
|
readonly minX: number;
|
|
1613
2006
|
readonly minY: number;
|
|
1614
2007
|
readonly maxX: number;
|
|
@@ -1620,8 +2013,18 @@ interface IDirectionalClipmapOptions {
|
|
|
1620
2013
|
/** Half-width of each level's window in world units, finest first. */
|
|
1621
2014
|
readonly clipExtents: readonly number[];
|
|
1622
2015
|
readonly pagesPerAxis: number;
|
|
1623
|
-
/**
|
|
1624
|
-
|
|
2016
|
+
/**
|
|
2017
|
+
* Fraction of an extent inside which a point selects that level, `(0, 1]`, default 0.9. One value
|
|
2018
|
+
* for every level, or one per level finest first, the last entry standing in for the rest.
|
|
2019
|
+
*/
|
|
2020
|
+
readonly selectionGuard?: number | readonly number[];
|
|
2021
|
+
/**
|
|
2022
|
+
* Fraction of an extent a level's window may trail its followed centre by before it re-renders,
|
|
2023
|
+
* `[0, 1)`, default 0.125. Rounded to whole texels with one texel reserved for a deferred render;
|
|
2024
|
+
* `0` keeps the old one-texel step. Larger steps re-render a level less often as the camera walks. One value
|
|
2025
|
+
* for every level, or one per level finest first, the last entry standing in for the rest.
|
|
2026
|
+
*/
|
|
2027
|
+
readonly refreshStep?: number | readonly number[];
|
|
1625
2028
|
}
|
|
1626
2029
|
/**
|
|
1627
2030
|
* Camera-centred clip windows in a light-space basis, snapped to whole pages.
|
|
@@ -1634,14 +2037,21 @@ declare class DirectionalClipmap {
|
|
|
1634
2037
|
#private;
|
|
1635
2038
|
readonly clipExtents: readonly number[];
|
|
1636
2039
|
readonly pagesPerAxis: number;
|
|
1637
|
-
|
|
2040
|
+
/**
|
|
2041
|
+
* Per level, finest first; the last entry stands in for every level past it. Mutable through
|
|
2042
|
+
* {@link setRefreshStep} so a level whose own render is expensive can be stepped further, which
|
|
2043
|
+
* is fewer grid positions for its window rather than a different grid.
|
|
2044
|
+
*/
|
|
2045
|
+
refreshStep: number[];
|
|
2046
|
+
/** Per level, finest first; the last entry stands in for every level past it. */
|
|
2047
|
+
readonly selectionGuard: readonly number[];
|
|
1638
2048
|
readonly levelCount: number;
|
|
1639
2049
|
basisU: IVector3Like;
|
|
1640
2050
|
basisV: IVector3Like;
|
|
1641
2051
|
basisW: IVector3Like;
|
|
1642
2052
|
centerWorld: IVector3Like;
|
|
1643
2053
|
centerLight: ILightSpacePoint;
|
|
1644
|
-
constructor({ direction, clipExtents, pagesPerAxis, selectionGuard, }: IDirectionalClipmapOptions);
|
|
2054
|
+
constructor({ direction, clipExtents, pagesPerAxis, selectionGuard, refreshStep, }: IDirectionalClipmapOptions);
|
|
1645
2055
|
/** Re-orient the basis; returns true when it changed enough that cached pages are stale. */
|
|
1646
2056
|
setDirection(direction: IVector3Like): boolean;
|
|
1647
2057
|
project(worldPoint: IVector3Like): ILightSpacePoint;
|
|
@@ -1650,6 +2060,8 @@ declare class DirectionalClipmap {
|
|
|
1650
2060
|
v: number;
|
|
1651
2061
|
w?: number;
|
|
1652
2062
|
}): IVector3Like;
|
|
2063
|
+
/** Re-step one level's window: the trail its followed centre may move before it re-renders. */
|
|
2064
|
+
setRefreshStep(level: number, step: number): void;
|
|
1653
2065
|
updateCenter(worldPoint: IVector3Like): readonly IClipWindow[];
|
|
1654
2066
|
getWindow(level: number): IClipWindow;
|
|
1655
2067
|
pageWorldSize(level: number): number;
|
|
@@ -1715,19 +2127,143 @@ interface IVirtualShadowOptions {
|
|
|
1715
2127
|
readonly mapSize?: number;
|
|
1716
2128
|
/**
|
|
1717
2129
|
* Texels per edge of each level's mover map — the map tracked casters draw into every frame.
|
|
1718
|
-
* Default:
|
|
1719
|
-
*
|
|
2130
|
+
* Default: `mapSize`, the cached levels' own density, so a caster keeps the edge it had at rest
|
|
2131
|
+
* while it moves and does not pop to a crisper one when it settles. Lower it to buy back fill
|
|
2132
|
+
* on a weak GPU; the soft edge it costs is on the mover only.
|
|
1720
2133
|
*/
|
|
1721
2134
|
readonly moverMapSize?: number;
|
|
1722
2135
|
/**
|
|
1723
2136
|
* Fraction of a level's extent inside which a fragment still selects that level, `(0, 1]`,
|
|
1724
2137
|
* default 0.9 — the outer ring falls through to the next level so the edge is never sampled.
|
|
2138
|
+
* `selectionGuard` minus `refreshStep`, since a window trails its centre by that much. One value
|
|
2139
|
+
* for every level, or one per level finest first, the last entry standing in for the rest.
|
|
2140
|
+
*/
|
|
2141
|
+
readonly selectionGuard?: number | readonly number[];
|
|
2142
|
+
/**
|
|
2143
|
+
* Fraction of a level's extent its window may trail the followed centre by before it re-renders,
|
|
2144
|
+
* `[0, selectionGuard)`, default 0.125 — `refreshStep: 0` keeps the old one-texel step. The step
|
|
2145
|
+
* is rounded to a whole number of that level's texels, so a walking camera re-renders a level
|
|
2146
|
+
* ~`1/refreshStep` times less often while the shadow texels stay on one fixed world grid. Costs
|
|
2147
|
+
* that much of `selectionGuard`, which it is already reduced by, so a window never reaches past
|
|
2148
|
+
* the trailing edge of a map rendered before the centre moved. One value for every level, or one
|
|
2149
|
+
* per level finest first, the last entry standing in for the rest — the fine level is the one a
|
|
2150
|
+
* walking camera re-renders most, so it is the one that wants the larger step.
|
|
2151
|
+
*/
|
|
2152
|
+
readonly refreshStep?: number | readonly number[];
|
|
2153
|
+
/**
|
|
2154
|
+
* Let a level buy itself a wider `refreshStep` out of what its own last render cost, default true.
|
|
2155
|
+
*
|
|
2156
|
+
* A level render is a whole scene draw, so the engine cannot know what one is worth until it has
|
|
2157
|
+
* paid for it: the node measures the draw it just took and smooths that reading, and a level whose
|
|
2158
|
+
* smoothed cost is a large share of the frame period is re-rendered less often. This is automatic
|
|
2159
|
+
* because the value it reacts to is a measurement, not a setting — a game sets nothing, and a
|
|
2160
|
+
* cheap level is never widened and behaves exactly as before. The widened trail is capped by the
|
|
2161
|
+
* window's own margin, so the camera stays inside the region that level serves and everything that
|
|
2162
|
+
* level serves stays inside the map; a level with no such margin is never widened at all.
|
|
2163
|
+
*
|
|
2164
|
+
* `false` puts every level back on the `refreshStep` it was given, which is also what a harness
|
|
2165
|
+
* that wants to count today's renders uses.
|
|
2166
|
+
* `?tnAdaptiveRefresh=0` in the page URL makes the default `false` from the node's first setup.
|
|
2167
|
+
*/
|
|
2168
|
+
readonly adaptiveRefresh?: boolean;
|
|
2169
|
+
/**
|
|
2170
|
+
* Fraction of the display period a level's smoothed render cost may take before its refresh trail
|
|
2171
|
+
* widens, `(0, 1]`, default 0.4.
|
|
2172
|
+
*
|
|
2173
|
+
* The period is the frame's own `deltaTime`, capped at the 60 fps frame (16.7 ms). The cap is what
|
|
2174
|
+
* keeps the budget honest: the frame that renders an expensive level is itself long because of that
|
|
2175
|
+
* render, so reading the share against its own inflated delta would count the cost twice and let
|
|
2176
|
+
* the very level that needs adapting pass its own test. At 60 Hz the cap is the frame itself; on a
|
|
2177
|
+
* 120 Hz panel the same render is twice the share it is at 60; below 60 the cap holds the budget
|
|
2178
|
+
* at the 60 fps frame rather than growing with the stall. Below the share nothing changes at all,
|
|
2179
|
+
* and above it the trail widens in proportion to the overshoot,
|
|
2180
|
+
* because that is the ratio between what the level costs and what a frame can afford to spend on
|
|
2181
|
+
* it — a level four times over the share refreshs about four times less often, until the cap
|
|
2182
|
+
* below it runs out.
|
|
2183
|
+
*/
|
|
2184
|
+
readonly expensiveRefreshShare?: number;
|
|
2185
|
+
/**
|
|
2186
|
+
* Raise the finest level's texel size gate while its own render is too expensive for the frame, default
|
|
2187
|
+
* true.
|
|
2188
|
+
*
|
|
2189
|
+
* The same measurement adaptive refresh reads — the smoothed cost of the level's own last render,
|
|
2190
|
+
* against the share of the frame it may take — drives a second, independent adaptation: a level
|
|
2191
|
+
* whose render is over budget sizes its gate up in steps of 1.5 until it is affordable again, up
|
|
2192
|
+
* to 8 times the configured gate, and halves it back toward 1 once the render is comfortably under
|
|
2193
|
+
* half the budget. The gate only ever judges a caster by its size (see `minCasterTexels`), so this
|
|
2194
|
+
* drops the tiniest props first and never a building, and a level that is cheap is never touched:
|
|
2195
|
+
* it stays at scale 1 and submits exactly what it did before.
|
|
2196
|
+
*
|
|
2197
|
+
* Coarse levels always stay at scale 1 so resolved casters survive the handover.
|
|
2198
|
+
* `false` pins every level at scale 1, which is also what a harness that wants today's draw
|
|
2199
|
+
* counts uses.
|
|
2200
|
+
*/
|
|
2201
|
+
readonly adaptiveCasterGate?: boolean;
|
|
2202
|
+
/**
|
|
2203
|
+
* How long a level waits after its own last render before an invalidation may re-render it, in
|
|
2204
|
+
* seconds. One value for every level, or one per level finest first, the last entry standing in
|
|
2205
|
+
* for the rest. Default `0.25 * extent / finestExtent` — 0.25 s, 1 s and 3.33 s for extents
|
|
2206
|
+
* 24 / 96 / 320 — and `0` renders on the very next frame, which is what the node did before.
|
|
2207
|
+
*
|
|
2208
|
+
* A streamed world invalidates its shadows on every residency update, and a cell admitted at the
|
|
2209
|
+
* ring edge lands in the coarsest window: the level that redraws for it is the one paying for the
|
|
2210
|
+
* whole ring's wide casters, ten times a second where movement alone asks for two. A level
|
|
2211
|
+
* waiting out its delay keeps the map and window it has, which is already right for every static
|
|
2212
|
+
* caster in it, so only a newly streamed caster is missing — the trade is that a far tree's
|
|
2213
|
+
* shadow can appear up to the delay late (3.33 s at extent 320, invisible on a level whose texel
|
|
2214
|
+
* is wider than the tree). A window that moved is never delayed: that is a different reason, and
|
|
2215
|
+
* it is not this option's.
|
|
2216
|
+
*/
|
|
2217
|
+
readonly invalidationDelay?: number | readonly number[];
|
|
2218
|
+
/**
|
|
2219
|
+
* How far behind the window centre each level camera sits, in world units. Default 200. An
|
|
2220
|
+
* explicit `lightDistance` *and* `depthRange` switch the level's light-space depth off the derived
|
|
2221
|
+
* span below and back onto this pair, so a game that knows its own world sizes can still say so.
|
|
1725
2222
|
*/
|
|
1726
|
-
readonly selectionGuard?: number;
|
|
1727
|
-
/** How far behind the window centre each level camera sits, in world units. Default 200. */
|
|
1728
2223
|
readonly lightDistance?: number;
|
|
1729
|
-
/**
|
|
2224
|
+
/**
|
|
2225
|
+
* Depth range each level camera covers past its centre, in world units. Default 400. Read only
|
|
2226
|
+
* together with `lightDistance`; on its own the span is still derived.
|
|
2227
|
+
*/
|
|
1730
2228
|
readonly depthRange?: number;
|
|
2229
|
+
/**
|
|
2230
|
+
* Texels of a level a caster must cover before it draws into that level, default 1.5. A level's
|
|
2231
|
+
* texel is `2 * extent / mapSize`, so the finest levels keep everything and the coarse ones keep
|
|
2232
|
+
* only what they can resolve: a fern is a whole number of texels in a 48 m window and a fraction
|
|
2233
|
+
* of one in a 640 m window, so it stops being drawn there and the shadow it casts is the ground
|
|
2234
|
+
* cover's own, not its silhouette's. Set 0 to draw every caster into every level.
|
|
2235
|
+
*/
|
|
2236
|
+
readonly minCasterTexels?: number;
|
|
2237
|
+
/** Follow the framed receiving surface when the eye is more than one fine extent above it.
|
|
2238
|
+
* Default true; false keeps eye follow for every camera. Walking cameras keep eye follow.
|
|
2239
|
+
*/
|
|
2240
|
+
readonly followViewFocus?: boolean;
|
|
2241
|
+
/** Measure receiver-plane slope across each level's texel footprint to prevent coarse acne.
|
|
2242
|
+
* Default true; false preserves only the authored bias. Custom filterNode owns its footprint.
|
|
2243
|
+
*/
|
|
2244
|
+
readonly receiverPlaneBias?: boolean;
|
|
2245
|
+
/**
|
|
2246
|
+
* Draw registered AutoLOD chains with their coarsest geometry past the finest level, default true.
|
|
2247
|
+
* Alpha-tested and transparent casters keep casting on every level that resolves their bounds;
|
|
2248
|
+
* dropping their whole shadow at the fine window edge loses canopy and fences.
|
|
2249
|
+
* Geometry swaps are restored before the next level, mover map and main pass.
|
|
2250
|
+
*/
|
|
2251
|
+
readonly shadowLodBias?: boolean;
|
|
2252
|
+
/**
|
|
2253
|
+
* Redraw only the pages an invalidation dirtied, default true. A level whose window did not move
|
|
2254
|
+
* and whose asks named under half its pages renders those rectangles alone: pages casters were
|
|
2255
|
+
* removed from are put back to the far plane first, pages casters streamed into are just drawn.
|
|
2256
|
+
* `false` renders the whole level for every invalidation, as before. A VSM shadow map always
|
|
2257
|
+
* renders whole, because its blur pass reads the entire map.
|
|
2258
|
+
*/
|
|
2259
|
+
readonly partialRedraw?: boolean;
|
|
2260
|
+
/**
|
|
2261
|
+
* Quiet frames before an automatically detected mover goes back into the cached levels, default
|
|
2262
|
+
* 100 (Unreal's `FramesStaticThreshold`). A caster whose world matrix, instance matrix or
|
|
2263
|
+
* deformation changed is drawn through the mover maps without a `trackCaster` call; this is how
|
|
2264
|
+
* long it must hold still before its shadow is baked into the cache again. Positive integer.
|
|
2265
|
+
*/
|
|
2266
|
+
readonly staticAfterFrames?: number;
|
|
1731
2267
|
/** Print the `TN_VIRTUAL_SHADOW` line every `markerEvery` frames; `false` silences it. Default 300. */
|
|
1732
2268
|
readonly marker?: boolean | number;
|
|
1733
2269
|
}
|
|
@@ -1741,14 +2277,118 @@ interface IVirtualShadowStats {
|
|
|
1741
2277
|
readonly invalidated: number;
|
|
1742
2278
|
/** Tracked casters, as of this frame. */
|
|
1743
2279
|
readonly movers: number;
|
|
2280
|
+
/**
|
|
2281
|
+
* Casters the node classified as movers by measuring them, as of this frame: a world or instance
|
|
2282
|
+
* matrix that changed, or a deforming mesh. Counted apart from {@link movers}, which is `trackCaster`.
|
|
2283
|
+
*/
|
|
2284
|
+
readonly autoMovers: number;
|
|
2285
|
+
/**
|
|
2286
|
+
* Static-to-mover and mover-to-static changes of those casters over the node's lifetime. Each one
|
|
2287
|
+
* asks the levels for one region redraw, never a full one.
|
|
2288
|
+
*/
|
|
2289
|
+
readonly autoTransitions: number;
|
|
2290
|
+
/**
|
|
2291
|
+
* Mean JS time of the classification scan per frame, in milliseconds, over the node's lifetime.
|
|
2292
|
+
* It is the number the scan's 0.05 ms budget is judged against.
|
|
2293
|
+
*/
|
|
2294
|
+
readonly autoScanMs: number;
|
|
1744
2295
|
/** Mover maps rendered this frame: one per level when at least one caster is tracked. */
|
|
1745
2296
|
readonly moverRenders: number;
|
|
1746
2297
|
/** Levels served from their cached map this frame. */
|
|
1747
2298
|
readonly cached: number;
|
|
1748
2299
|
/** Levels rendered this frame, for any reason. */
|
|
1749
2300
|
readonly rendered: number;
|
|
2301
|
+
/**
|
|
2302
|
+
* Levels that wanted a render this frame and did not get one, because the node renders at most
|
|
2303
|
+
* one level per frame. They keep the map they already have and come due again next frame.
|
|
2304
|
+
*/
|
|
2305
|
+
readonly deferred: number;
|
|
2306
|
+
/**
|
|
2307
|
+
* Levels holding a redraw for an invalidation that is still inside its own `invalidationDelay`,
|
|
2308
|
+
* so this frame is not the frame they render on. They keep the map they have, which is right for
|
|
2309
|
+
* every static caster in it: only a caster streamed in since is missing, and the cumulative
|
|
2310
|
+
* `coalesced` below is what is being waited out.
|
|
2311
|
+
*/
|
|
2312
|
+
readonly held: number;
|
|
1750
2313
|
/** Fraction of levels served from cache over the node's lifetime. */
|
|
1751
2314
|
readonly reuseRatio: number;
|
|
2315
|
+
/**
|
|
2316
|
+
* Level renders over the node's lifetime, for any reason. `byMove` and `byInvalidation` are the two
|
|
2317
|
+
* the node has — a window that moved, and an invalidation that asked and waited out its delay — and
|
|
2318
|
+
* they add up to this exactly, because a render the single per-frame budget defers is counted
|
|
2319
|
+
* against the reason that queued it and not again when it is finally taken.
|
|
2320
|
+
*/
|
|
2321
|
+
readonly rendersTotal: number;
|
|
2322
|
+
/** Of those, the renders taken because a level's window moved. */
|
|
2323
|
+
readonly byMove: number;
|
|
2324
|
+
/**
|
|
2325
|
+
* Pages every level's window travelled between its renders, over the node's lifetime: the sum of
|
|
2326
|
+
* `|ΔminX| + |ΔminY|` at each render. Unlike `byMove` it does not depend on how many frames sampled
|
|
2327
|
+
* the path, so two runs of one route at different frame rates report the same number.
|
|
2328
|
+
*/
|
|
2329
|
+
readonly windowSteps: number;
|
|
2330
|
+
/** Of those, the renders taken because an invalidation asked and its level's delay had passed. */
|
|
2331
|
+
readonly byInvalidation: number;
|
|
2332
|
+
/** Of the renders taken for an invalidation (`byInvalidation`), those whose dirty set held only streamed-in casters. */
|
|
2333
|
+
readonly byAdmission: number;
|
|
2334
|
+
/** Of the renders taken for an invalidation, those whose dirty set held anything else: a removed caster, a region-less ask, a caster flag change. */
|
|
2335
|
+
readonly byEviction: number;
|
|
2336
|
+
/** Pages the dirty set held at each render, summed over the node's lifetime. A window move counts the whole level. */
|
|
2337
|
+
readonly pagesDirty: number;
|
|
2338
|
+
/** Pages each render actually drew, summed over the node's lifetime. Equals pagesDirty once a partial redraw exists. */
|
|
2339
|
+
readonly pagesRedrawn: number;
|
|
2340
|
+
/**
|
|
2341
|
+
* Invalidation asks that cost no render of their own, over the node's lifetime: absorbed by a
|
|
2342
|
+
* render the level was taking anyway for its window, or merged into an ask already waiting out
|
|
2343
|
+
* that level's delay. The two of these are the shape of the win — with the default delays a walk
|
|
2344
|
+
* asks once a second and renders about that often, and every ask in between is counted here.
|
|
2345
|
+
*/
|
|
2346
|
+
readonly coalesced: number;
|
|
2347
|
+
/**
|
|
2348
|
+
* The same four counters per level, finest first: which window moved, which invalidation asked
|
|
2349
|
+
* for a redraw, which level took the frame's single render, and which wanted one and did not get
|
|
2350
|
+
* it. One entry per level per frame, so a harness reading this — or the `TN_VIRTUAL_SHADOW`
|
|
2351
|
+
* marker line, which carries it — can see which level a walk keeps re-rendering instead of only
|
|
2352
|
+
* how many.
|
|
2353
|
+
*/
|
|
2354
|
+
readonly perLevel: readonly IVirtualShadowLevelStat[];
|
|
2355
|
+
}
|
|
2356
|
+
/** One level's row of {@link IVirtualShadowStats}: 1 or 0 per counter, per frame. */
|
|
2357
|
+
interface IVirtualShadowLevelStat {
|
|
2358
|
+
/** The level's clip extent, in world units. */
|
|
2359
|
+
readonly extent: number;
|
|
2360
|
+
readonly deferred: number;
|
|
2361
|
+
readonly invalidated: number;
|
|
2362
|
+
readonly moved: number;
|
|
2363
|
+
readonly rendered: number;
|
|
2364
|
+
/** Caster meshes this level's chosen camera layers submit this frame. Zero if it did not render. */
|
|
2365
|
+
readonly draws: number;
|
|
2366
|
+
/** The same bill split by kind; the five parts sum to {@link draws}. */
|
|
2367
|
+
readonly drawsBy: IVirtualShadowDraws;
|
|
2368
|
+
/** The adaptive caster gate's scale on this level, 1 when it is not shedding casters. */
|
|
2369
|
+
readonly gateScale: number;
|
|
2370
|
+
/** Casters the gate hid on the render this level took this frame; zero if it did not render. */
|
|
2371
|
+
readonly gateHidden: number;
|
|
2372
|
+
}
|
|
2373
|
+
/** One level's caster draws, by the kind of mesh that submitted them. */
|
|
2374
|
+
interface IVirtualShadowDraws {
|
|
2375
|
+
/** Caster batch meshes on the cluster layer, when the cluster half is the level's choice. */
|
|
2376
|
+
readonly cluster: number;
|
|
2377
|
+
/** Key-wide caster meshes on the wide layer, when the wide half is the level's choice. */
|
|
2378
|
+
readonly wide: number;
|
|
2379
|
+
/** Small casters, submitted by the finest level and by any level rendering a prewarm. */
|
|
2380
|
+
readonly small: number;
|
|
2381
|
+
/** Merged per-chunk shadow proxies (`<name>-shadow`), drawn with either caster half. */
|
|
2382
|
+
readonly chunkProxy: number;
|
|
2383
|
+
/** Everything else casting from layer 0 — terrain, props — which every level draws. */
|
|
2384
|
+
readonly layer0: number;
|
|
2385
|
+
/**
|
|
2386
|
+
* GPU-scene keys: one mesh per `asset:level:part` drawn from the level's own twin of the dispatch's
|
|
2387
|
+
* output, which is the whole of what a keyed map submits of the world. Zero unless a provider
|
|
2388
|
+
* registered and `?tnShadowGpuKeys=1` asked, and then it replaces {@link cluster} and {@link wide}
|
|
2389
|
+
* rather than adding to them: the keys draw the placements those two would have.
|
|
2390
|
+
*/
|
|
2391
|
+
readonly keys: number;
|
|
1752
2392
|
}
|
|
1753
2393
|
declare const VIRTUAL_SHADOW_MARKER = "TN_VIRTUAL_SHADOW";
|
|
1754
2394
|
/**
|
|
@@ -1756,6 +2396,21 @@ declare const VIRTUAL_SHADOW_MARKER = "TN_VIRTUAL_SHADOW";
|
|
|
1756
2396
|
* Keep it free of other uses; the main camera never needs it (tracked objects keep layer 0).
|
|
1757
2397
|
*/
|
|
1758
2398
|
declare const VIRTUAL_SHADOW_MOVER_LAYER = 29;
|
|
2399
|
+
/**
|
|
2400
|
+
* The object layer a shadow-only caster is put on, so each level's own shadow camera renders it and
|
|
2401
|
+
* the main camera never sees it. The level cameras have it enabled already; an object that exists
|
|
2402
|
+
* only as a shadow caster calls `object.layers.set(VIRTUAL_SHADOW_CASTER_LAYER)`.
|
|
2403
|
+
*/
|
|
2404
|
+
declare const VIRTUAL_SHADOW_CASTER_LAYER = 28;
|
|
2405
|
+
/**
|
|
2406
|
+
* The wide counterpart of {@link VIRTUAL_SHADOW_CASTER_LAYER}: one caster mesh per
|
|
2407
|
+
* `asset:level:part` holding every resident cell's records, for the levels whose window covers the
|
|
2408
|
+
* whole resident ring. A level renders exactly one of the two caster layers — whichever submits
|
|
2409
|
+
* fewer draws, counted off the meshes themselves, because a cluster per square is a draw per square
|
|
2410
|
+
* for the same pixels once the window holds the ring. `WorldCells` writes both halves of every key,
|
|
2411
|
+
* so whichever a level picks is there; the main camera renders neither.
|
|
2412
|
+
*/
|
|
2413
|
+
declare const VIRTUAL_SHADOW_WIDE_CASTER_LAYER = 27;
|
|
1759
2414
|
/**
|
|
1760
2415
|
* One directional shadow for a whole open world: camera-centred clip levels, each snapped to its
|
|
1761
2416
|
* own texel grid and re-rendered only when its window moves. Movers never touch that cache: a
|
|
@@ -1770,7 +2425,9 @@ declare const VIRTUAL_SHADOW_MOVER_LAYER = 29;
|
|
|
1770
2425
|
* map type and filter, and those source settings are mirrored into each stock level node before
|
|
1771
2426
|
* rendering. Per-level map sizes, cameras, `autoUpdate` and `needsUpdate` are owned by this node.
|
|
1772
2427
|
* Each level is rendered by the stock {@link ShadowNode} through the renderer's shadow-map type,
|
|
1773
|
-
* so the look is the same code path a plain shadow uses.
|
|
2428
|
+
* so the look is the same code path a plain shadow uses. At most one level renders per frame,
|
|
2429
|
+
* finest first — a level render is a whole scene draw, and a level passed over keeps the map and
|
|
2430
|
+
* window it has, so a fragment only ever samples a map that level drew.
|
|
1774
2431
|
*
|
|
1775
2432
|
* Ported from the virtual-shadow-map prototype's clipmap and invalidation; the sparse page atlas
|
|
1776
2433
|
* is deliberately not the first cut — a page needs the scene rendered once per page, and on a
|
|
@@ -1783,8 +2440,10 @@ declare const VIRTUAL_SHADOW_MOVER_LAYER = 29;
|
|
|
1783
2440
|
* @situation shadows shimmer when the camera moves
|
|
1784
2441
|
* @constraint the light must be a DirectionalLight with `castShadow` and a target in the scene
|
|
1785
2442
|
* @constraint clipExtents are half-widths in world units, finest first, strictly increasing
|
|
1786
|
-
* @constraint
|
|
2443
|
+
* @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
|
|
2444
|
+
* @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
|
|
1787
2445
|
* @override bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults
|
|
2446
|
+
* @override followViewFocus: false keeps eye follow; receiverPlaneBias: false uses only authored bias
|
|
1788
2447
|
* @example
|
|
1789
2448
|
* const sun = new DirectionalLight(0xffffff, 3);
|
|
1790
2449
|
* sun.castShadow = true;
|
|
@@ -1793,8 +2452,18 @@ declare const VIRTUAL_SHADOW_MOVER_LAYER = 29;
|
|
|
1793
2452
|
declare class VirtualShadowNode extends ShadowBaseNode {
|
|
1794
2453
|
#private;
|
|
1795
2454
|
static get type(): string;
|
|
1796
|
-
readonly options: Required<Omit<IVirtualShadowOptions, "marker">> & {
|
|
2455
|
+
readonly options: Required<Omit<IVirtualShadowOptions, "marker" | "refreshStep" | "selectionGuard" | "invalidationDelay">> & {
|
|
1797
2456
|
readonly markerEvery: number;
|
|
2457
|
+
/** Per level, finest first; the last entry stands in for every level past it. */
|
|
2458
|
+
readonly refreshStep: readonly number[];
|
|
2459
|
+
/** The per-level `selectionGuard` each level's own window is drawn with. */
|
|
2460
|
+
readonly selectionGuard: readonly number[];
|
|
2461
|
+
/**
|
|
2462
|
+
* Per level, finest first: the seconds a dirty level waits after its own last render before an
|
|
2463
|
+
* invalidation may re-render it. Already scaled by that level's extent, so the fine levels
|
|
2464
|
+
* answer a streamed caster promptly and the coarse ones let a burst merge into one render.
|
|
2465
|
+
*/
|
|
2466
|
+
readonly invalidationDelay: readonly number[];
|
|
1798
2467
|
};
|
|
1799
2468
|
readonly clipmap: DirectionalClipmap;
|
|
1800
2469
|
/**
|
|
@@ -1818,8 +2487,32 @@ declare class VirtualShadowNode extends ShadowBaseNode {
|
|
|
1818
2487
|
*/
|
|
1819
2488
|
trackCaster(object: Object3D): string;
|
|
1820
2489
|
untrackCaster(objectOrId: Object3D | string): boolean;
|
|
2490
|
+
/**
|
|
2491
|
+
* Keep an object and its descendants out of automatic mover detection: they are static casters
|
|
2492
|
+
* whatever their transforms do, so a game that moves one takes on the stale shadow itself, or
|
|
2493
|
+
* calls `invalidateRegion`. Takes effect from the next frame.
|
|
2494
|
+
*/
|
|
2495
|
+
pinStatic(object: Object3D): void;
|
|
1821
2496
|
/** Force every level to re-render on the next frame — a tree fell, a door opened. */
|
|
1822
2497
|
invalidateAll(): void;
|
|
2498
|
+
/**
|
|
2499
|
+
* Force only the levels whose current window covers `bounds`, on the next frame. A streamed world
|
|
2500
|
+
* that hands its shadow casters over has a moving near set, and a blanket `invalidateAll()` on
|
|
2501
|
+
* every refresh redrew all three levels for a change that lands in one corner of one of them. A
|
|
2502
|
+
* level whose window does not cover the region draws the same thing either way, so skipping it is
|
|
2503
|
+
* the same frame with fewer draws in it.
|
|
2504
|
+
*
|
|
2505
|
+
* `bounds` is `{ min: {x,y,z}, max: {x,y,z} }`, a plain object so a game can hand one over without
|
|
2506
|
+
* importing three. Regions are consumed by the next `updateBefore`; one that arrives before the
|
|
2507
|
+
* levels exist is dropped, because their first frame renders all of them anyway.
|
|
2508
|
+
*
|
|
2509
|
+
* `admission` says the region only gained casters. An added caster can only bring a texel's depth
|
|
2510
|
+
* closer, so a redraw for admissions alone never has to clear what the map already holds. The
|
|
2511
|
+
* default reads `bounds.admission === true`; an explicit second argument overrides it.
|
|
2512
|
+
*/
|
|
2513
|
+
invalidateRegion(bounds: IBoundsLike & {
|
|
2514
|
+
admission?: boolean;
|
|
2515
|
+
}, admission?: boolean): void;
|
|
1823
2516
|
setup(builder: NodeBuilder): Node | null | undefined;
|
|
1824
2517
|
updateBefore(frame: NodeFrame): undefined;
|
|
1825
2518
|
dispose(): void;
|
|
@@ -1835,6 +2528,91 @@ declare class VirtualShadowNode extends ShadowBaseNode {
|
|
|
1835
2528
|
*/
|
|
1836
2529
|
declare function readVirtualShadowMarker(line: string): IVirtualShadowStats | undefined;
|
|
1837
2530
|
|
|
2531
|
+
/** Every value is the game's: this rig wires them and chooses none. */
|
|
2532
|
+
interface IDaylightOptions {
|
|
2533
|
+
/** The eye the sky, the sun's shadow windows and the haze centre on; usually the camera. */
|
|
2534
|
+
readonly follow: Object3D;
|
|
2535
|
+
/** Unit vector from the ground towards the sun. */
|
|
2536
|
+
readonly sunDirection: Vector3;
|
|
2537
|
+
readonly sunColor: Color;
|
|
2538
|
+
/** Irradiance in three's physical units; the same number a Blender sun strength carries. */
|
|
2539
|
+
readonly sunIntensity: number;
|
|
2540
|
+
/** Half-widths of the shadow windows in world units, finest first, strictly increasing. */
|
|
2541
|
+
readonly shadowExtents: readonly number[];
|
|
2542
|
+
/** Texels per shadow level edge; a level's texel is `2 * extent / shadowMapSize`. Default: the sun's `shadow.mapSize.width` (512). */
|
|
2543
|
+
readonly shadowMapSize?: number;
|
|
2544
|
+
/**
|
|
2545
|
+
* How far a window may trail the camera before it re-renders, as a fraction of its own extent:
|
|
2546
|
+
* one value for every level, or one per level finest first, the last entry standing in for the
|
|
2547
|
+
* rest. One for all of them spends the hysteresis the fine level can least afford on the coarse
|
|
2548
|
+
* one, which is the level a walking camera re-renders least. Default 0.125.
|
|
2549
|
+
*/
|
|
2550
|
+
readonly refreshStep?: number | readonly number[];
|
|
2551
|
+
/** Preetham sky parameters, as three's `SkyMesh` takes them. */
|
|
2552
|
+
readonly sky: {
|
|
2553
|
+
readonly turbidity: number;
|
|
2554
|
+
readonly rayleigh: number;
|
|
2555
|
+
readonly mieCoefficient: number;
|
|
2556
|
+
readonly mieDirectionalG: number;
|
|
2557
|
+
};
|
|
2558
|
+
/** Sky fill from above and bounce from below, as a hemisphere light. */
|
|
2559
|
+
readonly fill: {
|
|
2560
|
+
readonly sky: Color;
|
|
2561
|
+
readonly ground: Color;
|
|
2562
|
+
readonly intensity: number;
|
|
2563
|
+
};
|
|
2564
|
+
/** Exponential-squared haze in the sky's horizon colour, so distance fades into the sky. */
|
|
2565
|
+
readonly haze: {
|
|
2566
|
+
readonly color: Color;
|
|
2567
|
+
readonly density: number;
|
|
2568
|
+
};
|
|
2569
|
+
/** Linear exposure multiplier for the tone curve (2^EV). */
|
|
2570
|
+
readonly exposure: number;
|
|
2571
|
+
/** The tone curve, a look the game picks; AgX when it names none. */
|
|
2572
|
+
readonly toneMapping?: ToneMapping;
|
|
2573
|
+
/**
|
|
2574
|
+
* Edge of the sky box in world units. It must sit inside the camera's far plane with its corners
|
|
2575
|
+
* included (a box, so half-diagonal ≈ 0.87 × this).
|
|
2576
|
+
*/
|
|
2577
|
+
readonly skySize: number;
|
|
2578
|
+
}
|
|
2579
|
+
/**
|
|
2580
|
+
* An outdoor daylight rig: a physical sky that stays on the eye, one sun whose open-world shadow
|
|
2581
|
+
* windows follow the eye (`VirtualShadowNode`), a hemisphere fill, sky-coloured distance haze and
|
|
2582
|
+
* the AgX tone curve at the game's exposure. It is plumbing, not a look: every colour, angle,
|
|
2583
|
+
* intensity and density is a required option, and the rig adds nothing a game did not ask for.
|
|
2584
|
+
*
|
|
2585
|
+
* Add it with `ctx.add(daylight)`: `attachRenderer` sets tone mapping, exposure and the shadow map
|
|
2586
|
+
* once, and `process` (render cadence) keeps the sky box, the sun and its target on the eye every
|
|
2587
|
+
* frame, so a 2 km map never walks out of its own sky or shadow.
|
|
2588
|
+
*
|
|
2589
|
+
* @situation daytime sky, sun and shadows for a large outdoor map
|
|
2590
|
+
* @situation distant terrain should fade into the sky instead of a coloured wall
|
|
2591
|
+
* @situation match a Blender look-dev scene's sun, sky and exposure in the game
|
|
2592
|
+
* @constraint every value is required; there is no default sun, sky, haze or exposure
|
|
2593
|
+
* @constraint `skySize` must keep the sky box's corners inside the camera's far plane
|
|
2594
|
+
* @constraint shadowExtents follow `VirtualShadowNode`: half-widths, finest first, strictly increasing
|
|
2595
|
+
* @override sky uniforms stay live on `daylight.sky`; the light and fill are `daylight.sun` and `daylight.fill`
|
|
2596
|
+
* @example
|
|
2597
|
+
* 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 });
|
|
2598
|
+
* ctx.add(daylight);
|
|
2599
|
+
*/
|
|
2600
|
+
declare class Daylight extends Group implements IComputeDriven$1 {
|
|
2601
|
+
#private;
|
|
2602
|
+
readonly warmupNodes: readonly unknown[];
|
|
2603
|
+
readonly processCadence: "render";
|
|
2604
|
+
readonly sky: SkyMesh;
|
|
2605
|
+
readonly sun: DirectionalLight;
|
|
2606
|
+
readonly fill: HemisphereLight;
|
|
2607
|
+
constructor(options: IDaylightOptions);
|
|
2608
|
+
get released(): boolean;
|
|
2609
|
+
/** The haze this rig owns; `attachRenderer` puts it on the scene the rig was added to. */
|
|
2610
|
+
get haze(): FogExp2;
|
|
2611
|
+
attachRenderer(renderer: IRendererLike): void;
|
|
2612
|
+
process(): void;
|
|
2613
|
+
detach(): void;
|
|
2614
|
+
}
|
|
2615
|
+
|
|
1838
2616
|
/**
|
|
1839
2617
|
* Two load-time mechanisms every streaming game writes by hand, and gets wrong in the same places.
|
|
1840
2618
|
*
|
|
@@ -1879,18 +2657,13 @@ interface IAddInSlicesProgress {
|
|
|
1879
2657
|
}
|
|
1880
2658
|
interface IAddInSlicesOptions {
|
|
1881
2659
|
/**
|
|
1882
|
-
* Objects attached between presented frames
|
|
2660
|
+
* Objects attached between presented frames, when the game wants that count.
|
|
1883
2661
|
*
|
|
1884
|
-
*
|
|
1885
|
-
*
|
|
1886
|
-
*
|
|
1887
|
-
*
|
|
1888
|
-
*
|
|
1889
|
-
* one present per object.
|
|
1890
|
-
*
|
|
1891
|
-
* 256 is where the measured curve flattens without giving up the yields entirely: over a few
|
|
1892
|
-
* hundred objects it still presents a handful of frames, so a browser watchdog cannot see a hung
|
|
1893
|
-
* page, and it costs nothing against attaching everything in one go.
|
|
2662
|
+
* Omitted, a slice ends on elapsed time instead: the loop measures what the game's own `add`
|
|
2663
|
+
* costs, in the place where the cost is paid, and presents a frame once the slice has run for its
|
|
2664
|
+
* budget. Objects that cost nothing stop paying a frame each, and objects that cost more than any
|
|
2665
|
+
* fixed count allows get cut sooner than that count would. Given, the count decides and the budget
|
|
2666
|
+
* is not used at all.
|
|
1894
2667
|
*/
|
|
1895
2668
|
readonly sliceSize?: number;
|
|
1896
2669
|
/** Called once per slice, and once more for a partial final slice. */
|
|
@@ -1919,14 +2692,19 @@ interface IAddInSlicesReport {
|
|
|
1919
2692
|
readonly added: number;
|
|
1920
2693
|
/** Objects the run was given. */
|
|
1921
2694
|
readonly total: number;
|
|
1922
|
-
/** Slices the work was cut into
|
|
2695
|
+
/** Slices the work was cut into: one host turn between each, several of which can share a frame. */
|
|
1923
2696
|
readonly slices: number;
|
|
1924
2697
|
/** Wall-clock milliseconds the run took, attaching and yielding together. */
|
|
1925
2698
|
readonly elapsedMs: number;
|
|
1926
|
-
/**
|
|
2699
|
+
/**
|
|
2700
|
+
* Objects per slice this run actually landed on: the count the game chose, or — when
|
|
2701
|
+
* the budget chose — the measured average, which is the number a caller copies into `sliceSize`.
|
|
2702
|
+
*/
|
|
1927
2703
|
readonly sliceSize: number;
|
|
1928
|
-
/** Whether that
|
|
2704
|
+
/** Whether that count came from the game rather than from the engine. */
|
|
1929
2705
|
readonly sliceSizeOverridden: boolean;
|
|
2706
|
+
/** Milliseconds of attaching one slice may spend before it presents. Absent when the game gave a count. */
|
|
2707
|
+
readonly sliceBudgetMs?: number;
|
|
1930
2708
|
/** True when `while` ended the run early. `added` is then less than `total`. */
|
|
1931
2709
|
readonly stopped: boolean;
|
|
1932
2710
|
}
|
|
@@ -2042,7 +2820,7 @@ interface ISpectralOceanOptions {
|
|
|
2042
2820
|
*
|
|
2043
2821
|
* This is not the simulation resolution. It is the size of the only thing copied back off the
|
|
2044
2822
|
* GPU, so it is the whole cost of being able to float something: `readbackResolution` squared
|
|
2045
|
-
* floats, every `readbackEveryFrames` frames.
|
|
2823
|
+
* pairs of height and vertical-velocity floats, every `readbackEveryFrames` frames.
|
|
2046
2824
|
*/
|
|
2047
2825
|
readonly readbackResolution: number;
|
|
2048
2826
|
/** Frames between height copies. Ignored when `readbackResolution` is zero. */
|
|
@@ -2051,6 +2829,8 @@ interface ISpectralOceanOptions {
|
|
|
2051
2829
|
/** A height read from the CPU copy, with the age of the frame that produced it. */
|
|
2052
2830
|
interface ISpectralOceanHeight {
|
|
2053
2831
|
readonly height: number;
|
|
2832
|
+
/** Metres per second at this same point and sample time, for temporal age correction. */
|
|
2833
|
+
readonly verticalVelocity: number;
|
|
2054
2834
|
/**
|
|
2055
2835
|
* Frames between the GPU state this height came from and now.
|
|
2056
2836
|
*
|
|
@@ -2109,12 +2889,109 @@ declare class SpectralOcean extends Object3D implements IComputeDriven$1 {
|
|
|
2109
2889
|
interface IGPUParticles3DBuffers {
|
|
2110
2890
|
readonly positions: StorageBufferNode<"vec3">;
|
|
2111
2891
|
readonly velocities: StorageBufferNode<"vec3">;
|
|
2112
|
-
|
|
2113
|
-
|
|
2892
|
+
/** Emitter-clock second of each slot's last spawn. Present only when `spawn` is given. */
|
|
2893
|
+
readonly births?: StorageBufferNode<"float">;
|
|
2894
|
+
}
|
|
2895
|
+
/** The engine clock, as TSL nodes, handed to `process` as its second argument. */
|
|
2896
|
+
interface IGPUParticles3DRuntime {
|
|
2897
|
+
readonly time: Node$1<"float">;
|
|
2898
|
+
readonly delta: Node$1<"float">;
|
|
2899
|
+
}
|
|
2900
|
+
/** Engine-owned uniforms for one `emitParticle` call. The slot is `(first + instanceIndex) % amount`. */
|
|
2901
|
+
interface IGPUParticles3DSpawnRequest {
|
|
2902
|
+
readonly first: UniformNode$1<"uint", number>;
|
|
2903
|
+
readonly count: UniformNode$1<"uint", number>;
|
|
2904
|
+
readonly origin: UniformNode$1<"vec3", Vector3>;
|
|
2905
|
+
readonly direction: UniformNode$1<"vec3", Vector3>;
|
|
2906
|
+
readonly seed: UniformNode$1<"float", number>;
|
|
2907
|
+
readonly time: Node$1<"float">;
|
|
2908
|
+
}
|
|
2909
|
+
/** Buffers a spawn-driven emitter's kernels receive: `births` always exists. */
|
|
2910
|
+
interface IGPUParticles3DSpawnBuffers extends IGPUParticles3DBuffers {
|
|
2911
|
+
readonly births: StorageBufferNode<"float">;
|
|
2912
|
+
}
|
|
2913
|
+
interface IGPUParticles3DBaseOptions {
|
|
2114
2914
|
readonly amount: number;
|
|
2115
2915
|
readonly material: SpriteNodeMaterial;
|
|
2916
|
+
/** World space when `spawn` is given, emitter space otherwise. */
|
|
2917
|
+
readonly localCoords?: boolean;
|
|
2918
|
+
/**
|
|
2919
|
+
* Override the local bounds from frame zero and skip GPU measurement.
|
|
2920
|
+
* @situation Supply known bounds for a particle cloud.
|
|
2921
|
+
* @constraint Must be a finite, non-empty box in the emitter's local space.
|
|
2922
|
+
*/
|
|
2923
|
+
readonly bounds?: Box3;
|
|
2924
|
+
/**
|
|
2925
|
+
* Metres added around the world box. Defaults to half the largest world scale.
|
|
2926
|
+
* @situation Cover the sprite quad; name padding when the material uses scaleNode.
|
|
2927
|
+
* @constraint Must be finite and non-negative, in world metres.
|
|
2928
|
+
*/
|
|
2929
|
+
readonly padding?: number;
|
|
2930
|
+
/**
|
|
2931
|
+
* Keep buffers on pause, or restart on return with clear. Defaults to pause.
|
|
2932
|
+
* @situation Choose whether a returning effect continues or starts again.
|
|
2933
|
+
* @constraint Must be pause or clear.
|
|
2934
|
+
*/
|
|
2935
|
+
readonly onCull?: "pause" | "clear";
|
|
2936
|
+
/**
|
|
2937
|
+
* Seconds continuously outside the view before culling. Defaults to 1.
|
|
2938
|
+
* @situation Avoid toggling effects near the view edge; Infinity disables view culling.
|
|
2939
|
+
* @constraint Must be non-negative; Infinity is allowed.
|
|
2940
|
+
*/
|
|
2941
|
+
readonly graceSeconds?: number;
|
|
2942
|
+
/**
|
|
2943
|
+
* Frames between GPU bounds measurements. Defaults to 8.
|
|
2944
|
+
* @situation Trade readback cost for a delayed view of the cloud bounds.
|
|
2945
|
+
* @constraint Must be a positive integer; paused emitters do not measure.
|
|
2946
|
+
*/
|
|
2947
|
+
readonly boundsEveryFrames?: number;
|
|
2948
|
+
}
|
|
2949
|
+
/** The closed-form tier: every particle is a function of time, `start` seeds the buffers. */
|
|
2950
|
+
interface IGPUParticles3DClosedFormOptions extends IGPUParticles3DBaseOptions {
|
|
2116
2951
|
readonly start: (buffers: IGPUParticles3DBuffers) => ComputeNode;
|
|
2117
|
-
readonly process: (buffers: IGPUParticles3DBuffers) => ComputeNode;
|
|
2952
|
+
readonly process: (buffers: IGPUParticles3DBuffers, runtime: IGPUParticles3DRuntime) => ComputeNode;
|
|
2953
|
+
readonly spawn?: undefined;
|
|
2954
|
+
readonly lifetime?: undefined;
|
|
2955
|
+
readonly maxSpawnPerFrame?: undefined;
|
|
2956
|
+
}
|
|
2957
|
+
/** The spawn tier: a burst is a request, and the engine owns the slots and the birth stamps. */
|
|
2958
|
+
interface IGPUParticles3DSpawnOptions extends IGPUParticles3DBaseOptions {
|
|
2959
|
+
/** Optional here: the engine already resets every birth. */
|
|
2960
|
+
readonly start?: (buffers: IGPUParticles3DSpawnBuffers) => ComputeNode;
|
|
2961
|
+
readonly process: (buffers: IGPUParticles3DSpawnBuffers, runtime: IGPUParticles3DRuntime) => ComputeNode;
|
|
2962
|
+
/**
|
|
2963
|
+
* Writes one burst. Dispatched over `amount` threads per `emitParticle`: a thread with
|
|
2964
|
+
* `instanceIndex >= request.count` returns at once. ponytail: costs `amount` threads per emit;
|
|
2965
|
+
* upgrade to an indirect dispatch of `count` threads if `amount` passes about 100,000.
|
|
2966
|
+
*/
|
|
2967
|
+
readonly spawn: (buffers: IGPUParticles3DSpawnBuffers, request: IGPUParticles3DSpawnRequest) => ComputeNode;
|
|
2968
|
+
/** Game-owned longest life in seconds. Lets `stats.recycledLive` count slots recycled while alive. */
|
|
2969
|
+
readonly lifetime?: number;
|
|
2970
|
+
/** Cap on particles spawned between two `process` calls. Defaults to `amount`. */
|
|
2971
|
+
readonly maxSpawnPerFrame?: number;
|
|
2972
|
+
}
|
|
2973
|
+
type IGPUParticles3DOptions = IGPUParticles3DClosedFormOptions | IGPUParticles3DSpawnOptions;
|
|
2974
|
+
interface IEmitParticleRequest {
|
|
2975
|
+
readonly count?: number;
|
|
2976
|
+
readonly origin?: {
|
|
2977
|
+
readonly x: number;
|
|
2978
|
+
readonly y: number;
|
|
2979
|
+
readonly z: number;
|
|
2980
|
+
};
|
|
2981
|
+
readonly direction?: {
|
|
2982
|
+
readonly x: number;
|
|
2983
|
+
readonly y: number;
|
|
2984
|
+
readonly z: number;
|
|
2985
|
+
};
|
|
2986
|
+
readonly seed?: number;
|
|
2987
|
+
}
|
|
2988
|
+
interface IGPUParticles3DStats {
|
|
2989
|
+
/** Particles requested but not spawned (over `amount` or over `maxSpawnPerFrame`). */
|
|
2990
|
+
readonly clamped: number;
|
|
2991
|
+
/** Particles spawned. */
|
|
2992
|
+
readonly spawned: number;
|
|
2993
|
+
/** Live slots overwritten by the ring. `undefined` without the `lifetime` option, never `0`. */
|
|
2994
|
+
readonly recycledLive: number | undefined;
|
|
2118
2995
|
}
|
|
2119
2996
|
declare class GPUParticles3D extends Sprite implements IComputeDriven$1 {
|
|
2120
2997
|
#private;
|
|
@@ -2122,11 +2999,34 @@ declare class GPUParticles3D extends Sprite implements IComputeDriven$1 {
|
|
|
2122
2999
|
readonly buffers: IGPUParticles3DBuffers;
|
|
2123
3000
|
readonly processCadence: "render";
|
|
2124
3001
|
readonly warmupNodes: readonly ComputeNode[];
|
|
3002
|
+
readonly localCoords: boolean;
|
|
2125
3003
|
emitting: boolean;
|
|
3004
|
+
/** Cooperate with measured frame-budget shedding without changing particle storage. */
|
|
3005
|
+
readonly budget: IBudgetCandidate;
|
|
2126
3006
|
constructor(options: IGPUParticles3DOptions);
|
|
2127
3007
|
get released(): boolean;
|
|
3008
|
+
get stats(): IGPUParticles3DStats;
|
|
3009
|
+
/** Seconds outside view before culling; Infinity disables it at runtime. */
|
|
3010
|
+
get graceSeconds(): number;
|
|
3011
|
+
set graceSeconds(value: number);
|
|
2128
3012
|
attachRenderer(renderer: IRendererLike): void;
|
|
2129
|
-
|
|
3013
|
+
/** The override or newest landed local bounds; absent until a valid sample lands. */
|
|
3014
|
+
get measuredBounds(): Box3 | undefined;
|
|
3015
|
+
/** Simulation compute calls, excluding starts and bounds reduction. */
|
|
3016
|
+
get dispatches(): number;
|
|
3017
|
+
/** Current cull state and the number of state changes. */
|
|
3018
|
+
get cull(): {
|
|
3019
|
+
readonly state: "running" | "paused" | "cleared";
|
|
3020
|
+
readonly reason: "outside-view" | "over-budget" | undefined;
|
|
3021
|
+
readonly transitions: number;
|
|
3022
|
+
};
|
|
3023
|
+
process(renderer?: IRendererLike | undefined, camera?: Camera, _covered?: boolean, _view?: undefined, simulatedSeconds?: number): void;
|
|
3024
|
+
/**
|
|
3025
|
+
* Spawns `count` particles at `origin` (world space unless `localCoords`). Every call gets its own ring
|
|
3026
|
+
* slots, so a second burst never touches the first one's live particles. No readback.
|
|
3027
|
+
*/
|
|
3028
|
+
emitParticle(request?: IEmitParticleRequest): void;
|
|
3029
|
+
/** Reruns `start`. A spawn-driven emitter instead kills every particle and rewinds the ring. */
|
|
2130
3030
|
restart(): void;
|
|
2131
3031
|
detach(): void;
|
|
2132
3032
|
}
|
|
@@ -2188,6 +3088,154 @@ declare class FluidField2D extends Group {
|
|
|
2188
3088
|
detach(): void;
|
|
2189
3089
|
}
|
|
2190
3090
|
|
|
3091
|
+
type Vec3 = readonly [number, number, number];
|
|
3092
|
+
type Vec4 = readonly [number, number, number, number];
|
|
3093
|
+
declare const instancedArray: any;
|
|
3094
|
+
interface IFluidBounds {
|
|
3095
|
+
readonly min: Vec3;
|
|
3096
|
+
readonly max: Vec3;
|
|
3097
|
+
}
|
|
3098
|
+
/** An obstacle the water flows around. Boxes carry an xyzw quaternion; spheres have no orientation. */
|
|
3099
|
+
type IFluidCollider = {
|
|
3100
|
+
readonly kind: "sphere";
|
|
3101
|
+
readonly center: Vec3;
|
|
3102
|
+
readonly radius: number;
|
|
3103
|
+
} | {
|
|
3104
|
+
readonly kind: "box";
|
|
3105
|
+
readonly center: Vec3;
|
|
3106
|
+
readonly halfExtents: Vec3;
|
|
3107
|
+
readonly rotation?: Vec4;
|
|
3108
|
+
};
|
|
3109
|
+
interface IFluidParticlesOptions {
|
|
3110
|
+
/** Particle slots. The solver never holds more than this many live particles. */
|
|
3111
|
+
readonly capacity: number;
|
|
3112
|
+
/** Rest spacing in metres. The smoothing radius is twice this. */
|
|
3113
|
+
readonly spacing?: number;
|
|
3114
|
+
/** The container. Particles are projected back inside it every iteration. */
|
|
3115
|
+
readonly bounds?: IFluidBounds;
|
|
3116
|
+
/** Density-constraint iterations per fixed step, 0 to 8. */
|
|
3117
|
+
readonly iterations?: number;
|
|
3118
|
+
readonly viscosity?: number;
|
|
3119
|
+
readonly cohesion?: number;
|
|
3120
|
+
readonly vorticity?: number;
|
|
3121
|
+
readonly gravity?: number;
|
|
3122
|
+
/** Vector speed limit in m/s. Prediction projects radius-sized segments; this is not swept CCD. */
|
|
3123
|
+
readonly maxSpeed?: number;
|
|
3124
|
+
readonly timeStep?: number;
|
|
3125
|
+
/** Colliders updated per step through `setColliders`. */
|
|
3126
|
+
readonly maxColliders?: number;
|
|
3127
|
+
/** Queued `fill`/`emit` calls consumed per step. Extra calls return `false`. */
|
|
3128
|
+
readonly maxSpawns?: number;
|
|
3129
|
+
/** Voxel edge of the density volume, in metres. Defaults to half the spacing. */
|
|
3130
|
+
readonly voxelSize?: number;
|
|
3131
|
+
/** Fixed steps between GPU-to-CPU copies of stats and column heights. */
|
|
3132
|
+
readonly readbackEvery?: number;
|
|
3133
|
+
/** Extra acceleration (m/s²) added to every particle, from the game's own TSL. */
|
|
3134
|
+
readonly force?: (position: Node$1<"vec3">, velocity: Node$1<"vec3">, time: Node$1<"float">) => Node$1;
|
|
3135
|
+
}
|
|
3136
|
+
interface IFluidParticlesStats {
|
|
3137
|
+
readonly count: number;
|
|
3138
|
+
/** Mean of `max(0, density - 1)` over live particles; 0 is incompressible. */
|
|
3139
|
+
readonly meanCompression: number;
|
|
3140
|
+
readonly maxSpeed: number;
|
|
3141
|
+
readonly min: Vec3;
|
|
3142
|
+
readonly max: Vec3;
|
|
3143
|
+
/** Fixed steps between the GPU state these numbers describe and now. */
|
|
3144
|
+
readonly staleFrames: number;
|
|
3145
|
+
}
|
|
3146
|
+
/**
|
|
3147
|
+
* Simulate liquid as particles on the GPU and expose the data, never the look.
|
|
3148
|
+
*
|
|
3149
|
+
* It is a Position Based Fluids solver (density constraints, XSPH viscosity, cohesion, vorticity
|
|
3150
|
+
* confinement) whose passes run as compute kernels every fixed step. Nothing is drawn: `positions`
|
|
3151
|
+
* and `velocities` are storage nodes (`.w` of `positions` is the live flag, `.w` of `velocities`
|
|
3152
|
+
* is a 0..1 foam hint), `density` is a 3D texture of smoothed particle density a game raymarches
|
|
3153
|
+
* or thresholds, and `sample(x, z)` is the free-surface height a `Buoyancy3D` consumes.
|
|
3154
|
+
* Appearance — refraction, absorption, foam, spray — stays in the game's `src/render/` code.
|
|
3155
|
+
* @situation pour, splash, or dam-break water that fills a container and flows around obstacles
|
|
3156
|
+
* @situation simulate water or another liquid as particles in a fluid simulation
|
|
3157
|
+
* @situation drop a ball or box into liquid and let it displace and float on the water
|
|
3158
|
+
* @situation emit a stream or waterfall of particle fluid and drain it somewhere else
|
|
3159
|
+
* @situation sample particle-fluid density or surface height in a game-owned render node
|
|
3160
|
+
* @constraint add the fluid through `ctx.add` so renderer attachment, fixed-step dispatch, and release are automatic
|
|
3161
|
+
* @constraint a renderer without WebGPU compute throws a named error at attach; it never draws nothing
|
|
3162
|
+
* @constraint `emit` recycles the oldest slot once `capacity` slots have been used; `fill` stops at capacity
|
|
3163
|
+
* @constraint `sample` and `stats` read a throttled GPU copy and report `staleFrames`; they are never live
|
|
3164
|
+
* @override iterations, viscosity, cohesion, vorticity, gravity and maxSpeed tune the solver without changing its pass order
|
|
3165
|
+
* @example const water = new FluidParticles3D({ capacity: 6000 });
|
|
3166
|
+
* ctx.add(water);
|
|
3167
|
+
* water.fill([-2.8, 0.1, -1.5], [-0.6, 3, 1.5]);
|
|
3168
|
+
*/
|
|
3169
|
+
declare class FluidParticles3D extends Group {
|
|
3170
|
+
#private;
|
|
3171
|
+
readonly capacity: number;
|
|
3172
|
+
readonly spacing: number;
|
|
3173
|
+
readonly bounds: IFluidBounds;
|
|
3174
|
+
readonly iterations: number;
|
|
3175
|
+
readonly maxSpeed: number;
|
|
3176
|
+
readonly timeStep: number;
|
|
3177
|
+
readonly maxColliders: number;
|
|
3178
|
+
readonly maxSpawns: number;
|
|
3179
|
+
readonly processCadence: "fixed";
|
|
3180
|
+
readonly warmupNodes: readonly ComputeNode[];
|
|
3181
|
+
/** vec4 per slot: xyz position, w = 1 live / 0 free. */
|
|
3182
|
+
readonly positions: ReturnType<typeof instancedArray>;
|
|
3183
|
+
/** vec4 per slot: xyz velocity, w = foam 0..1. */
|
|
3184
|
+
readonly velocities: ReturnType<typeof instancedArray>;
|
|
3185
|
+
/** Smoothed particle density, ~1 inside water; sample it with `texture3D`. */
|
|
3186
|
+
readonly density: Storage3DTexture;
|
|
3187
|
+
/** Voxel counts of `density`. */
|
|
3188
|
+
readonly volumeSize: Vec3;
|
|
3189
|
+
/** World-space corner of voxel (0,0,0) and the edge length of one voxel. */
|
|
3190
|
+
readonly volumeOrigin: Vec3;
|
|
3191
|
+
readonly voxelSize: number;
|
|
3192
|
+
constructor(options: IFluidParticlesOptions);
|
|
3193
|
+
get released(): boolean;
|
|
3194
|
+
/** Slots handed out so far; never above `capacity`. */
|
|
3195
|
+
get used(): number;
|
|
3196
|
+
get steps(): number;
|
|
3197
|
+
get viscosity(): number;
|
|
3198
|
+
set viscosity(value: number);
|
|
3199
|
+
get cohesion(): number;
|
|
3200
|
+
set cohesion(value: number);
|
|
3201
|
+
get vorticity(): number;
|
|
3202
|
+
set vorticity(value: number);
|
|
3203
|
+
get gravity(): number;
|
|
3204
|
+
set gravity(value: number);
|
|
3205
|
+
attachRenderer(renderer: IRendererLike): void;
|
|
3206
|
+
/**
|
|
3207
|
+
* Place a lattice of particles in `[min, max]`, one per `spacing`, and return how many fit.
|
|
3208
|
+
* Particles never wrap: a full solver places none.
|
|
3209
|
+
*/
|
|
3210
|
+
fill(min: Vec3, max: Vec3, velocity?: Vec3): number;
|
|
3211
|
+
/** Spawn one particle. Once every slot has been used the oldest slot is recycled. */
|
|
3212
|
+
emit(position: Vec3, velocity?: Vec3): boolean;
|
|
3213
|
+
/** Free every live particle inside the box on the next step. */
|
|
3214
|
+
drain(min: Vec3, max: Vec3): boolean;
|
|
3215
|
+
/** Push particles within `radius` of `point` outward and up, strongest at the centre. */
|
|
3216
|
+
stir(point: Vec3, strength: number, radius: number): boolean;
|
|
3217
|
+
/** Replace the colliders. Call it every fixed step with the bodies' current transforms. */
|
|
3218
|
+
setColliders(colliders: readonly IFluidCollider[]): void;
|
|
3219
|
+
/**
|
|
3220
|
+
* Free-surface height near `(x, z)`, box-filtered over open columns of the newest landed GPU
|
|
3221
|
+
* copy; `bounds.min.y` where no water is near or nothing has landed yet. Shaped for `Buoyancy3D`'s `surface`.
|
|
3222
|
+
*/
|
|
3223
|
+
sample(x: number, z: number, _time?: number): {
|
|
3224
|
+
readonly height: number;
|
|
3225
|
+
};
|
|
3226
|
+
/** Surface height at `(x, z)`; see {@link sample}. */
|
|
3227
|
+
heightAt(x: number, z: number): number;
|
|
3228
|
+
/**
|
|
3229
|
+
* Fixed steps between the GPU state the newest copy holds and now; grows until the first copy
|
|
3230
|
+
* lands. `sample` and `heightAt` read the same copy, so this is their age too.
|
|
3231
|
+
*/
|
|
3232
|
+
get staleFrames(): number;
|
|
3233
|
+
/** Counts and extremes from the newest landed GPU copy, or `undefined` before one lands. */
|
|
3234
|
+
get stats(): IFluidParticlesStats | undefined;
|
|
3235
|
+
process(renderer?: IRendererLike | undefined): void;
|
|
3236
|
+
detach(): void;
|
|
3237
|
+
}
|
|
3238
|
+
|
|
2191
3239
|
/**
|
|
2192
3240
|
* A disturbance that propagates. `WaveField` in this same package evaluates a fixed analytic
|
|
2193
3241
|
* swell: it is the sea a game always has, and nothing a game does changes it. This is the other
|
|
@@ -2399,20 +3447,13 @@ interface IWaterReflectionOptions {
|
|
|
2399
3447
|
/** Whether this surface may appear in other reflectors' passes. Off is one pass; on is n². */
|
|
2400
3448
|
readonly bounces?: boolean;
|
|
2401
3449
|
/**
|
|
2402
|
-
*
|
|
2403
|
-
*
|
|
2404
|
-
*
|
|
2405
|
-
*
|
|
2406
|
-
* This is how much *world* the second pass costs, and on a crowded scene it is the whole bill.
|
|
2407
|
-
* The mirrored pass is a second draw of everything, so a frame with sixty-eight aircraft in it
|
|
2408
|
-
* pays for sixty-eight aircraft twice — once where the player can see them and once in the water,
|
|
2409
|
-
* where they are a few pixels and half of them are behind the camera anyway. Put the big
|
|
2410
|
-
* silhouettes a player actually reads in the water on their own layer and name it here.
|
|
2411
|
-
*
|
|
2412
|
-
* The mask decides what appears in the mirror, so the game owns it: this only carries the number
|
|
2413
|
-
* through to the pass, and a game that omits it gets the whole world reflected as before.
|
|
3450
|
+
* Explicit Three Layers mask. Wins over automatic selection, including `1` (all layer-0 props).
|
|
3451
|
+
* Omit to reflect terrain-sized surfaces and large non-instanced shadow casters. Instanced and
|
|
3452
|
+
* skinned props are excluded automatically; sky/background and lighting remain available.
|
|
2414
3453
|
*/
|
|
2415
3454
|
readonly layers?: number;
|
|
3455
|
+
/** Minimum world-space extent for automatic terrain/casters, in metres. Default 10. */
|
|
3456
|
+
readonly minSize?: number;
|
|
2416
3457
|
/**
|
|
2417
3458
|
* How often the mirrored pass redraws, in presented frames.
|
|
2418
3459
|
*
|
|
@@ -2491,7 +3532,7 @@ declare class WaterSurface3D {
|
|
|
2491
3532
|
* cannot inspect is a reflection you cannot cost. Undefined when this surface has no reflection.
|
|
2492
3533
|
*/
|
|
2493
3534
|
reflectionCameraFor(camera: Camera): Camera | undefined;
|
|
2494
|
-
/**
|
|
3535
|
+
/** Explicit mask supplied by the game. Undefined means automatic terrain/large-caster selection. */
|
|
2495
3536
|
readonly reflectionLayers: number | undefined;
|
|
2496
3537
|
/** How often the mirrored pass redraws, in presented frames. `1` is every frame, the default. */
|
|
2497
3538
|
readonly reflectionRefreshInterval: number;
|
|
@@ -2938,21 +3979,6 @@ declare function measureThreePose(object: Object3D, options?: IMeasureThreePoseO
|
|
|
2938
3979
|
*/
|
|
2939
3980
|
declare function posedBounds(root: Object3D, meshes?: readonly Object3D[]): IThreePoseBounds;
|
|
2940
3981
|
|
|
2941
|
-
type PlatformRuntime = "web" | "native";
|
|
2942
|
-
type PlatformOS = "android" | "ios" | "linux" | "macos" | "windows" | "unknown";
|
|
2943
|
-
type PlatformFormFactor = "mobile" | "desktop" | "unknown";
|
|
2944
|
-
interface IPlatformInfo {
|
|
2945
|
-
readonly runtime: PlatformRuntime;
|
|
2946
|
-
readonly os: PlatformOS;
|
|
2947
|
-
readonly formFactor: PlatformFormFactor;
|
|
2948
|
-
readonly maxTouchPoints: number;
|
|
2949
|
-
}
|
|
2950
|
-
declare function getPlatform(): Readonly<IPlatformInfo>;
|
|
2951
|
-
declare function isWeb(): boolean;
|
|
2952
|
-
declare function isNative(): boolean;
|
|
2953
|
-
declare function isMobile(): boolean;
|
|
2954
|
-
declare function isTouchscreenAvailable(): boolean;
|
|
2955
|
-
|
|
2956
3982
|
type ReplayPointer = readonly [number, number, number, number, number];
|
|
2957
3983
|
interface IReplayRecordingSample {
|
|
2958
3984
|
readonly keys: readonly string[];
|
|
@@ -3210,6 +4236,6 @@ declare function boneLengthDeviations(root: Object3D, bind: IBoneLengthSnapshot,
|
|
|
3210
4236
|
* unavoidable here — core is bundled for browsers and cannot read `package.json` at runtime — so
|
|
3211
4237
|
* the spec now asserts this equals the manifest instead of asserting a number somebody typed.
|
|
3212
4238
|
*/
|
|
3213
|
-
declare const version = "0.3.
|
|
4239
|
+
declare const version = "0.3.5";
|
|
3214
4240
|
|
|
3215
|
-
export { ATLAS_PADDING, ATMOSPHERE_LUT_RESOLUTIONS, AnimationPlayer, Atmosphere, type AtmosphereDirection, AtmosphereLuts, type AtmosphereRgb, Billboard3D, type BillboardLockAxis, CameraShake, type CameraShakeCurve, ClusteredBatch, ClusteredMesh, FlightModel, FluidField2D, FramePassKind, GPUParticles3D, GPUSceneBVH, type GPUSceneBVHTraceFunction, GroundSnap, type IAddInSlicesOptions, type IAddInSlicesProgress, type IAddInSlicesReport, type IAircraftAirframe, type IAnimationPlayOptions, type IAnimationPlayerOptions, type IAtmosphereLutResolution, type IAtmosphereLutResolutions, type IAtmosphereOptions, type IAtmosphereParameterPatch, type IAtmosphereParameters, type IAtmosphereScenePass, type IBillboard3DOptions, type IBoneContactReport, type IBoneLengthDeviation, type IBoneLengthDeviationReport, type IBoneLengthDeviationsOptions, type IBoneLengthSnapshot, type IBonePoseError, type ICameraShakeOffset, type ICameraShakeOptions, type IClipBindingReport, type IClipCoverageReport, type IClipPoseErrorOptions, type IClipPoseErrorReport, type IClipPoseSubject, type IClipTrackBinding, type IClusterTable, type IClusteredBatchBuildOptions, type IClusteredBatchOptions, type IClusteredMeshOptions, type IClusteredPlacement, IComputeDriven$1 as IComputeDriven, type IFlightAxes, type IFlightControls, type IFlightDeck, type IFlightEnvironment, type IFlightForces, type IFlightModelOptions, type IFlightModifiers, type IFlightQuaternion, type IFlightState, type IFlightVector3, type IFluidFieldOptions, type IFluidFieldSampler, type IFluidFieldVector2, IFrameBudgetWindow, IGPUReadbackSample, type IGPUSceneBVHMaterialGroup, type IGPUSceneBVHOptions, IGamePluginHooks, IGamePluginRuntime, type IGroundSnapOptions, type IInstancedBatchBuildOptions, type IInstancedBatchOptions, type IInstancedPlacement, type ILaunchFailure, type ILoadAllOptions, type ILoadAllProgress, type IMatrixWorldReport, type IMeasureThreePoseOptions, type IMergePart, type IMergePartsOptions, type INormaliseToMetresOptions, type IPathFollow3DOptions, type IPathFollow3DProjection, type IPathFollow3DSample, type
|
|
4241
|
+
export { ATLAS_PADDING, ATMOSPHERE_LUT_RESOLUTIONS, AnimationComposer, AnimationPlayer, Atmosphere, type AtmosphereDirection, AtmosphereLuts, type AtmosphereRgb, Billboard3D, type BillboardLockAxis, BlendSpace1D, BlendSpace2D, CameraShake, type CameraShakeCurve, ClusteredBatch, ClusteredMesh, Daylight, ENVIRONMENT_TOO_SMALL_MARKER, FlightModel, FluidField2D, FluidParticles3D, FramePassKind, GPUParticles3D, GPUSceneBVH, type GPUSceneBVHTraceFunction, GroundSnap, type IAddInSlicesOptions, type IAddInSlicesProgress, type IAddInSlicesReport, type IAircraftAirframe, type IAnimationComposerOptions, type IAnimationLayer, type IAnimationMask, type IAnimationMotionDelta, type IAnimationPlayOptions, type IAnimationPlayerOptions, type IAnimationRootMotionOptions, type IAtmosphereLutResolution, type IAtmosphereLutResolutions, type IAtmosphereOptions, type IAtmosphereParameterPatch, type IAtmosphereParameters, type IAtmosphereScenePass, type IBillboard3DOptions, type IBoneContactReport, type IBoneLengthDeviation, type IBoneLengthDeviationReport, type IBoneLengthDeviationsOptions, type IBoneLengthSnapshot, type IBonePoseError, type ICameraShakeOffset, type ICameraShakeOptions, type IClipBindingReport, type IClipCoverageReport, type IClipPoseErrorOptions, type IClipPoseErrorReport, type IClipPoseSubject, type IClipTrackBinding, type IClusterTable, type IClusteredBatchBuildOptions, type IClusteredBatchOptions, type IClusteredMeshOptions, type IClusteredPlacement, IComputeDriven$1 as IComputeDriven, type IDaylightOptions, type IEmitParticleRequest, type IFlightAxes, type IFlightControls, type IFlightDeck, type IFlightEnvironment, type IFlightForces, type IFlightModelOptions, type IFlightModifiers, type IFlightQuaternion, type IFlightState, type IFlightVector3, type IFluidBounds, type IFluidCollider, type IFluidFieldOptions, type IFluidFieldSampler, type IFluidFieldVector2, type IFluidParticlesOptions, type IFluidParticlesStats, IFrameBudgetWindow, type IGPUParticles3DOptions, type IGPUParticles3DRuntime, type IGPUParticles3DSpawnBuffers, type IGPUParticles3DSpawnRequest, type IGPUParticles3DStats, IGPUReadbackSample, type IGPUSceneBVHMaterialGroup, type IGPUSceneBVHOptions, IGamePluginHooks, IGamePluginRuntime, type IGroundSnapOptions, type IInstancedBatchBuildOptions, type IInstancedBatchOptions, type IInstancedPlacement, type ILaunchFailure, type ILoadAllOptions, type ILoadAllProgress, type IMatrixWorldReport, type IMeasureThreePoseOptions, type IMergeByMaterialOptions, type IMergePart, type IMergePartsOptions, type INormaliseToMetresOptions, type IPathFollow3DOptions, type IPathFollow3DProjection, type IPathFollow3DSample, type IProbeVolumeBakeProgress, type IProbeVolumeCoefficient, type IProbeVolumeObservation, type IProbeVolumeOptions, type IReplayOptions, type IReplayRecording, type IReplayRecordingSample, type IResolvedAtmosphereParameters, type IRippleFieldFlow, type IRippleFieldOptions, type ISceneShape, type ISceneWarning, type ISkeletalMesh3DOptions, type ISoftBody3DOptions, type ISoftBodyCollision, type ISolarPosition, type ISolarPositionInput, type ISpanProbeTarget, type ISpanSummary, type ISpanWindow, type ISpectralOceanCascade, type ISpectralOceanHeight, type ISpectralOceanOptions, type ISpriteAnimator3DOptions, type ISpriteFrame3D, type IStaticTransformCensus, type IStrideReport, type IThreePoseBounds, type IThreePoseMeasurement, type ITracerPool3DOptions, type ITracerSpawnOptions, type IUnlitFoliageWarning, type IValidationReport, type IVirtualShadowOptions, type IVirtualShadowStats, type IWaterReflectionOptions, type IWaterSurfaceOptions, type IWaveFieldDomainWarp, type IWaveFieldGraphOptions, type IWaveFieldOptions, type IWaveFieldSample, type IWaveFieldWave, InstancedBatch, LUT_RESOLUTIONS, type LaunchFailureKind, type MatrixWorldMode, MatrixWorldPass, NEUTRAL_FLIGHT_MODIFIERS, type NormaliseAxis, OPACITY_IGNORED_MARKER, PROBE_VOLUME_MARKER, PathFollow3D, ProbeVolume, type ProbeVolumeDensity, RENDERLIST_VALIDATE_FLAG, RENDERLIST_VALIDATE_MARKER, type Recording, RenderListValidator, type ReplayPointer, RippleField, SCENE_WARNING_MARKER, SPANS, SPANS_FLAG, SPANS_MARKER, SPAN_COUNT, SPAN_NAMES, STATIC_TRANSFORM_MARKER, SkeletalMesh3D, SoftBody3D, type SpanId, SpanRecorder, SpectralOcean, SpriteAnimator3D, type SpritePlaybackMode, type ThreePoseQuaternion, type ThreePoseVector, TracerPool3D, UNLIT_FOLIAGE_FIX, UNLIT_FOLIAGE_MARKER, VIRTUAL_SHADOW_CASTER_LAYER, VIRTUAL_SHADOW_MARKER, VIRTUAL_SHADOW_MOVER_LAYER, VIRTUAL_SHADOW_WIDE_CASTER_LAYER, VirtualShadowNode, WaterSurface3D, type WaveDirection, WaveField, addInSlices, addSpan, aerodynamicCoefficients, airDensity, aircraftMass, alwaysRender, attachToBone, attitudeAxes, beginSpan, boneContact, boneLengthDeviations, boneLengths, bvhIntersectFirstHit, clipBoneCoverage, clipPoseError, clipTrackBindings, createReplayDriver, debugFlag, describeSceneShape, describeSceneWarning, directionFromSolarPosition, directionalTransmittance, displayPeriodMs, endSpan, exposeDebug, formatSceneWarning, formatSpansWindow, formatUnlitFoliageWarning, formatValidationReport, gearClearance, installSpanProbes, invalidateStatic, isStatic, loadAll, markStatic, measureThreePose, mergeByMaterial, mergeParts, normaliseToMetres, onLaunchFailure, parseReplayRecording, posedBounds, rayStruct, readProbeVolumeObservation, readVirtualShadowMarker, refreshStaticTransforms, renderListValidationRequested, renderTrapAudit, replay, resetStaticTransforms, resolveAtmosphereLutResolutions, resolveAtmosphereParameters, sceneWarning, setAttitude, setSpanRecorder, skeletonBones, softCircleDataTexture, solarPosition, solarPositionAt, spanNow, spanRecorder, spansRequested, staticTransformCensus, unlitFoliageWarning, unmarkStatic, updateAtmosphereParameters, updateClusteredMeshes, validateWorldMatrices, version, zenithTransmittance };
|