@threenative/core 0.3.4 → 0.3.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (176) hide show
  1. package/capabilities.json +1505 -79
  2. package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
  3. package/dist/{canvas-layer-DDmC_VVF.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
  4. package/dist/{game-CljaDv4D.d.ts → game-Jz4Fdoeb.d.ts} +114 -11
  5. package/dist/hot.d.ts +4 -4
  6. package/dist/index.d.ts +712 -118
  7. package/dist/index.js +12437 -4955
  8. package/dist/{gpu-readback-CqJEfWNQ.d.ts → model-lod-BDAUYgsS.d.ts} +80 -5
  9. package/dist/playtest.d.ts +6 -10
  10. package/dist/playtest.js +57 -24
  11. package/dist/react-css.d.ts +62 -0
  12. package/dist/react-css.js +591 -0
  13. package/dist/react.d.ts +2 -2
  14. package/dist/{renderer-CfsS2hxi.d.ts → renderer-9yEo9hPa.d.ts} +489 -22
  15. package/dist/terrain-jobs-worker.d.ts +2 -0
  16. package/dist/terrain-jobs-worker.js +130 -0
  17. package/dist/ui-layer.js +59 -8
  18. package/dist/world.d.ts +766 -73
  19. package/dist/world.js +9307 -3543
  20. package/gpl/recipes/export_world.py +18 -1
  21. package/mcp/blender-server.mjs +7 -4
  22. package/mcp/blender.mjs +3 -4
  23. package/mcp/engine-server.mjs +2 -2
  24. package/mcp/servers.mjs +4 -4
  25. package/package.json +15 -9
  26. package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
  27. package/patches/three@0.185.1.patch +6594 -700
  28. package/scripts/apply-three-patch.mjs +62 -4
  29. package/src/animation-blend.ts +264 -0
  30. package/src/animation-composition.ts +362 -0
  31. package/src/animation-layers.ts +260 -0
  32. package/src/animation-root-motion.ts +283 -0
  33. package/src/animation.ts +896 -0
  34. package/src/assets.ts +1303 -0
  35. package/src/atmosphere/index.ts +335 -0
  36. package/src/atmosphere/luts.ts +298 -0
  37. package/src/atmosphere/params.ts +323 -0
  38. package/src/audio.ts +912 -0
  39. package/src/billboard.ts +124 -0
  40. package/src/bone-lengths.ts +157 -0
  41. package/src/camera-shake.ts +116 -0
  42. package/src/canvas-layer.ts +47 -0
  43. package/src/clip-audit.ts +401 -0
  44. package/src/clustered-batch.ts +492 -0
  45. package/src/clustered-mesh.ts +638 -0
  46. package/src/compute-driven.ts +176 -0
  47. package/src/compute-timing.ts +318 -0
  48. package/src/config.ts +593 -0
  49. package/src/debug.ts +82 -0
  50. package/src/engine-render-hook.ts +25 -0
  51. package/src/entities.ts +79 -0
  52. package/src/entity-snapshot.ts +53 -0
  53. package/src/flight.ts +683 -0
  54. package/src/fluid-field.ts +748 -0
  55. package/src/fluid-particles.ts +1253 -0
  56. package/src/frame-budget.ts +1368 -0
  57. package/src/game.ts +2408 -0
  58. package/src/geometry-capture.ts +1098 -0
  59. package/src/gpu-class.ts +160 -0
  60. package/src/gpu-frame-observation.ts +424 -0
  61. package/src/gpu-readback.ts +143 -0
  62. package/src/gpu-scene-bvh.ts +464 -0
  63. package/src/grounding.ts +100 -0
  64. package/src/hot.ts +161 -0
  65. package/src/import-meta.d.ts +13 -0
  66. package/src/index.ts +1536 -0
  67. package/src/input.ts +690 -0
  68. package/src/instanced-batch-lod.ts +283 -0
  69. package/src/instanced-batch.ts +274 -0
  70. package/src/interpolation.ts +129 -0
  71. package/src/launch-diagnostics.ts +161 -0
  72. package/src/loop.ts +574 -0
  73. package/src/matrix-world.ts +245 -0
  74. package/src/merge-parts.ts +812 -0
  75. package/src/model-lod.ts +1315 -0
  76. package/src/net-protocol.ts +333 -0
  77. package/src/net-session.ts +477 -0
  78. package/src/net.ts +80 -0
  79. package/src/ocean/fft.ts +72 -0
  80. package/src/ocean/spectral.ts +728 -0
  81. package/src/particle-significance.ts +102 -0
  82. package/src/particles.ts +648 -0
  83. package/src/path-follow.ts +175 -0
  84. package/src/picking.ts +250 -0
  85. package/src/pipeline-census.ts +1566 -0
  86. package/src/platform.ts +210 -0
  87. package/src/playtest.ts +850 -0
  88. package/src/pointer-events.ts +411 -0
  89. package/src/pose-measure.ts +435 -0
  90. package/src/profiling/FrameCounters.ts +231 -0
  91. package/src/profiling/Spans.ts +548 -0
  92. package/src/profiling/opacity-convention.ts +21 -0
  93. package/src/profiling/render-list-validate.ts +175 -0
  94. package/src/profiling/render-trap-audit.ts +84 -0
  95. package/src/profiling/scene-warning.ts +190 -0
  96. package/src/profiling/span-probes.ts +191 -0
  97. package/src/profiling/unlit-foliage-warning.ts +149 -0
  98. package/src/projection-apply.ts +1529 -0
  99. package/src/projection-marker.ts +142 -0
  100. package/src/projection-plan.ts +1258 -0
  101. package/src/projection-skinned.ts +419 -0
  102. package/src/projection-stability.ts +409 -0
  103. package/src/projection-uniform.ts +328 -0
  104. package/src/random.ts +41 -0
  105. package/src/react-css.ts +604 -0
  106. package/src/react-glyphs.ts +114 -0
  107. package/src/react-host.ts +576 -0
  108. package/src/react-layout.ts +265 -0
  109. package/src/react.ts +60 -0
  110. package/src/render/alpha-antialiasing.ts +159 -0
  111. package/src/render/batched-velocity.ts +126 -0
  112. package/src/render/chain.ts +1021 -0
  113. package/src/render/daylight.ts +189 -0
  114. package/src/render/depth-pyramid.ts +596 -0
  115. package/src/render/foliage-alpha.ts +166 -0
  116. package/src/render/material-key.ts +60 -0
  117. package/src/render/mesh-pool.ts +144 -0
  118. package/src/render/probe-volume.ts +1668 -0
  119. package/src/render/resolution-subrect.ts +253 -0
  120. package/src/render/velocity.ts +442 -0
  121. package/src/render/virtual-shadow-pages.ts +827 -0
  122. package/src/render/virtual-shadow-partial.ts +174 -0
  123. package/src/render/virtual-shadow.ts +3330 -0
  124. package/src/render/world-impostor-surface.ts +722 -0
  125. package/src/render/world-impostor.ts +558 -0
  126. package/src/render-camera-cull.ts +441 -0
  127. package/src/render-pass-budget.ts +501 -0
  128. package/src/renderProjection.ts +758 -0
  129. package/src/renderer-config.ts +127 -0
  130. package/src/renderer.ts +1847 -0
  131. package/src/replay-protocol.ts +85 -0
  132. package/src/replay.ts +205 -0
  133. package/src/resolution-scaler.ts +819 -0
  134. package/src/rig-preparation.ts +271 -0
  135. package/src/ripple-field.ts +432 -0
  136. package/src/scale.ts +109 -0
  137. package/src/scene.ts +239 -0
  138. package/src/schedule.ts +155 -0
  139. package/src/skeletal-mesh.ts +61 -0
  140. package/src/skeleton.ts +100 -0
  141. package/src/snow-field.ts +744 -0
  142. package/src/softbody-topology.ts +269 -0
  143. package/src/softbody.ts +516 -0
  144. package/src/sprite-animator.ts +222 -0
  145. package/src/startup-readiness.ts +386 -0
  146. package/src/state.ts +66 -0
  147. package/src/static-transform.ts +274 -0
  148. package/src/storage-buffer.ts +253 -0
  149. package/src/streaming.ts +308 -0
  150. package/src/target-fps.ts +92 -0
  151. package/src/terrain-jobs-worker.ts +17 -0
  152. package/src/terrain-jobs.ts +353 -0
  153. package/src/textures.ts +39 -0
  154. package/src/tracers.ts +237 -0
  155. package/src/ui-bridge.ts +368 -0
  156. package/src/ui-hit-regions.ts +380 -0
  157. package/src/ui-layer.ts +83 -0
  158. package/src/ui-state.ts +220 -0
  159. package/src/version.ts +2 -0
  160. package/src/viewport.ts +253 -0
  161. package/src/warmup.ts +1357 -0
  162. package/src/water-surface.ts +384 -0
  163. package/src/wave-field.ts +524 -0
  164. package/src/world-capabilities.ts +131 -0
  165. package/src/world-cell-proxy.ts +392 -0
  166. package/src/world-cells.ts +10564 -0
  167. package/src/world-gpu-scene.ts +3354 -0
  168. package/src/world-heightmap.ts +82 -0
  169. package/src/world-package.ts +469 -0
  170. package/src/world-passes.ts +582 -0
  171. package/src/world-region.ts +17 -0
  172. package/src/world-terrain-splat.ts +564 -0
  173. package/src/world-tiles.ts +3826 -0
  174. package/src/world-topology.ts +370 -0
  175. package/src/world-validate.ts +48 -0
  176. package/src/world.ts +805 -0
@@ -0,0 +1,124 @@
1
+ import { type Camera, Matrix4, type Object3D, Quaternion, Vector3 as Vec3 } from "three";
2
+
3
+ export type BillboardLockAxis = "x" | "y" | "z";
4
+
5
+ export interface IBillboard3DOptions {
6
+ /** Camera whose view direction or position the object follows. */
7
+ readonly camera: Camera;
8
+ /** Restrict the facing rotation to one world axis, for example `"y"` for a tree. */
9
+ readonly lockAxis?: BillboardLockAxis;
10
+ }
11
+
12
+ const EPSILON = 1e-12;
13
+
14
+ /**
15
+ * Orient one game-owned object toward a camera without owning its geometry or surface.
16
+ *
17
+ * The object is updated only when its owner calls {@link update}; there is no scene-wide registry
18
+ * or per-frame traversal. Perspective cameras face from the object's world position toward the
19
+ * camera, while orthographic cameras use their parallel view direction. The final world rotation
20
+ * is converted back into the object's local space, so a rotated parent remains correct.
21
+ */
22
+ export class Billboard3D {
23
+ readonly object: Object3D;
24
+ readonly camera: Camera;
25
+ readonly lockAxis: BillboardLockAxis | undefined;
26
+ readonly #cameraPosition = new Vec3();
27
+ readonly #cameraQuaternion = new Quaternion();
28
+ readonly #direction = new Vec3();
29
+ readonly #objectPosition = new Vec3();
30
+ readonly #objectQuaternion = new Quaternion();
31
+ readonly #parentQuaternion = new Quaternion();
32
+ readonly #screenUp = new Vec3();
33
+ readonly #screenRight = new Vec3();
34
+ readonly #basis = new Matrix4();
35
+
36
+ constructor(object: Object3D, options: IBillboard3DOptions) {
37
+ if (object === undefined || object === null)
38
+ throw new Error("Billboard3D.object must be a Three.js object.");
39
+ if (options === undefined || options === null || options.camera === undefined)
40
+ throw new Error("Billboard3D.camera is required.");
41
+ if (
42
+ options.lockAxis !== undefined &&
43
+ options.lockAxis !== "x" &&
44
+ options.lockAxis !== "y" &&
45
+ options.lockAxis !== "z"
46
+ )
47
+ throw new Error("Billboard3D.lockAxis must be 'x', 'y', or 'z'.");
48
+ this.object = object;
49
+ this.camera = options.camera;
50
+ this.lockAxis = options.lockAxis;
51
+ }
52
+
53
+ /** Apply the current camera pose to the object and return this helper for fluent setup. */
54
+ update(camera: Camera = this.camera): this {
55
+ if (camera === undefined || camera === null) throw new Error("Billboard3D.camera is required.");
56
+ this.object.updateWorldMatrix(true, false);
57
+ camera.updateWorldMatrix(true, false);
58
+ this.object.getWorldPosition(this.#objectPosition);
59
+ camera.getWorldQuaternion(this.#cameraQuaternion);
60
+
61
+ if (camera.type === "OrthographicCamera") {
62
+ this.#direction.set(0, 0, -1).applyQuaternion(this.#cameraQuaternion).negate();
63
+ } else {
64
+ camera.getWorldPosition(this.#cameraPosition);
65
+ this.#direction.subVectors(this.#cameraPosition, this.#objectPosition);
66
+ if (this.#direction.lengthSq() <= EPSILON)
67
+ this.#direction.set(0, 0, -1).applyQuaternion(this.#cameraQuaternion).negate();
68
+ }
69
+ if (this.#direction.lengthSq() <= EPSILON) this.#direction.set(0, 0, 1);
70
+ this.#lockDirection();
71
+ this.#direction.normalize();
72
+ if (this.lockAxis === undefined) {
73
+ this.#setUnrestrictedOrientation();
74
+ } else {
75
+ this.#objectPosition.set(0, 0, 1);
76
+ this.#objectQuaternion.setFromUnitVectors(this.#objectPosition, this.#direction);
77
+ }
78
+
79
+ const parent = this.object.parent;
80
+ if (parent === null) {
81
+ this.object.quaternion.copy(this.#objectQuaternion);
82
+ return this;
83
+ }
84
+ parent.updateWorldMatrix(true, false);
85
+ parent.getWorldQuaternion(this.#parentQuaternion);
86
+ this.object.quaternion.copy(this.#parentQuaternion).invert().multiply(this.#objectQuaternion);
87
+ return this;
88
+ }
89
+
90
+ #setUnrestrictedOrientation(): void {
91
+ this.#screenUp
92
+ .set(0, 1, 0)
93
+ .applyQuaternion(this.#cameraQuaternion)
94
+ .projectOnPlane(this.#direction);
95
+ if (this.#screenUp.lengthSq() <= EPSILON) {
96
+ this.#screenUp
97
+ .set(1, 0, 0)
98
+ .applyQuaternion(this.#cameraQuaternion)
99
+ .projectOnPlane(this.#direction);
100
+ }
101
+ if (this.#screenUp.lengthSq() <= EPSILON) {
102
+ this.#screenUp.set(0, 1, 0);
103
+ if (Math.abs(this.#screenUp.dot(this.#direction)) >= 1 - EPSILON) this.#screenUp.set(1, 0, 0);
104
+ this.#screenUp.projectOnPlane(this.#direction);
105
+ }
106
+ this.#screenUp.normalize();
107
+ this.#screenRight.crossVectors(this.#screenUp, this.#direction).normalize();
108
+ this.#basis.makeBasis(this.#screenRight, this.#screenUp, this.#direction);
109
+ this.#objectQuaternion.setFromRotationMatrix(this.#basis);
110
+ }
111
+
112
+ #lockDirection(): void {
113
+ if (this.lockAxis === undefined) return;
114
+ if (this.lockAxis === "x") this.#direction.x = 0;
115
+ if (this.lockAxis === "y") this.#direction.y = 0;
116
+ if (this.lockAxis === "z") this.#direction.z = 0;
117
+ if (this.#direction.lengthSq() > EPSILON) return;
118
+
119
+ // A camera on the locked axis has no unique heading. Keep a stable valid heading in the
120
+ // remaining plane rather than producing NaNs or allowing a one-frame roll.
121
+ if (this.lockAxis === "z") this.#direction.set(1, 0, 0);
122
+ else this.#direction.set(0, 0, 1);
123
+ }
124
+ }
@@ -0,0 +1,157 @@
1
+ import { type Bone, type Object3D, Vector3 } from "three";
2
+ import { bonesIn } from "./skeleton.js";
3
+
4
+ /**
5
+ * One rig's parent→child bone distances, captured at one moment.
6
+ *
7
+ * A rigid skeleton preserves every parent→child distance under any pose — that is what makes
8
+ * bone length the one number that names a broken pose without a screenshot (PRD-324).
9
+ */
10
+ export interface IBoneLengthSnapshot {
11
+ readonly bones: number;
12
+ /** Bone name → world distance to its parent bone, in metres. Bones without a bone parent are absent. */
13
+ readonly lengths: Readonly<Record<string, number>>;
14
+ }
15
+
16
+ /** One bone whose parent→child distance changed between the snapshot and now. */
17
+ export interface IBoneLengthDeviation {
18
+ readonly bone: string;
19
+ /** The distance at the snapshot, in metres. */
20
+ readonly bindLength: number;
21
+ /** The distance now, in metres. */
22
+ readonly posedLength: number;
23
+ /** `posedLength / bindLength`; `Infinity` when the bind distance was zero. */
24
+ readonly ratio: number;
25
+ /** `|posedLength − bindLength|`, in metres. */
26
+ readonly delta: number;
27
+ }
28
+
29
+ export interface IBoneLengthDeviationReport {
30
+ readonly bones: number;
31
+ /** Bones actually compared: named in both the snapshot and now. */
32
+ readonly compared: number;
33
+ /** The largest relative change across compared bones. Zero for a rigid pose. */
34
+ readonly maxDeviation: number;
35
+ /** The worst deviating bone, or `null` when the pose is rigid. */
36
+ readonly worst: IBoneLengthDeviation | null;
37
+ /** Every bone past `tolerance`, worst first. */
38
+ readonly deviations: readonly IBoneLengthDeviation[];
39
+ /** True when no bone moved past `tolerance` relative to its bind distance. */
40
+ readonly rigid: boolean;
41
+ }
42
+
43
+ export interface IBoneLengthDeviationsOptions {
44
+ /**
45
+ * Allowed relative change per bone before it is named. Default `0.01` — one per cent of its
46
+ * own bind length, which float noise sits far below and a pose defect sits far above.
47
+ */
48
+ readonly tolerance?: number;
49
+ }
50
+
51
+ /** Relative changes below this are float noise even for the shortest bone. */
52
+ const ABSOLUTE_FLOOR = 1e-9;
53
+
54
+ function boneLengthsOf(root: Object3D): Map<string, number> {
55
+ const bones = bonesIn(root);
56
+ if (bones.length === 0) {
57
+ throw new Error(`boneLengths: '${root.name || root.type}' has no bones.`);
58
+ }
59
+ root.updateMatrixWorld(true);
60
+ const withBoneParent = new Set<Bone>();
61
+ for (const bone of bones) {
62
+ if (bone.parent !== null && (bone.parent as Bone).isBone === true) withBoneParent.add(bone);
63
+ }
64
+ const lengths = new Map<string, number>();
65
+ const child = new Vector3();
66
+ const parent = new Vector3();
67
+ for (const bone of withBoneParent) {
68
+ child.setFromMatrixPosition(bone.matrixWorld);
69
+ parent.setFromMatrixPosition((bone.parent as Bone).matrixWorld);
70
+ lengths.set(bone.name, child.distanceTo(parent));
71
+ }
72
+ return lengths;
73
+ }
74
+
75
+ /**
76
+ * Measure every parent→child bone distance, in world space, as the rig stands right now.
77
+ *
78
+ * World distances, so a uniform ancestor scale is part of the number: capture the baseline and
79
+ * the comparison under the same ancestor transform (in the usual shape, both after the rig's
80
+ * normalisation) and the scale cancels in the comparison.
81
+ */
82
+ export function boneLengths(root: Object3D): IBoneLengthSnapshot {
83
+ const lengths = boneLengthsOf(root);
84
+ return {
85
+ bones: bonesIn(root).length,
86
+ lengths: Object.fromEntries(lengths),
87
+ };
88
+ }
89
+
90
+ /**
91
+ * Compare a rig's parent→child bone distances now against a captured snapshot.
92
+ *
93
+ * A rigid skeleton preserves every parent→child distance under any pose, so any named bone is
94
+ * a defect with an address: something moved a bone away from its parent — a position or scale
95
+ * track in the wrong space, a bind mismatch, a clipped hierarchy — and no screenshot needs to
96
+ * be squinted at to say which one (PRD-324).
97
+ */
98
+ export function boneLengthDeviations(
99
+ root: Object3D,
100
+ bind: IBoneLengthSnapshot,
101
+ options: IBoneLengthDeviationsOptions = {},
102
+ ): IBoneLengthDeviationReport {
103
+ const tolerance = options.tolerance ?? 0.01;
104
+ if (!Number.isFinite(tolerance) || tolerance < 0) {
105
+ throw new Error(
106
+ `boneLengthDeviations: tolerance must be a finite non-negative number, received ${tolerance}.`,
107
+ );
108
+ }
109
+ root.updateMatrixWorld(true);
110
+ const now = boneLengthsOf(root);
111
+
112
+ const bones = bonesIn(root).length;
113
+ const deviations: IBoneLengthDeviation[] = [];
114
+ let compared = 0;
115
+ let maxDeviation = 0;
116
+ for (const [bone, posedLength] of now) {
117
+ const bindLength = bind.lengths[bone];
118
+ if (bindLength === undefined) {
119
+ throw new Error(
120
+ `boneLengthDeviations: bone '${bone}' has no snapshot length; capture the baseline from the same rig.`,
121
+ );
122
+ }
123
+ compared += 1;
124
+ const delta = Math.abs(posedLength - bindLength);
125
+ const relative = Math.max(delta / Math.max(bindLength, ABSOLUTE_FLOOR), delta);
126
+ maxDeviation = Math.max(maxDeviation, relative);
127
+ if (relative > tolerance) {
128
+ deviations.push({
129
+ bone,
130
+ bindLength,
131
+ posedLength,
132
+ ratio: bindLength > 0 ? posedLength / bindLength : Number.POSITIVE_INFINITY,
133
+ delta,
134
+ });
135
+ }
136
+ }
137
+ for (const bone of Object.keys(bind.lengths)) {
138
+ if (!now.has(bone)) {
139
+ throw new Error(
140
+ `boneLengthDeviations: snapshot bone '${bone}' is not under the root any more; capture the baseline from the same rig.`,
141
+ );
142
+ }
143
+ }
144
+ deviations.sort((left, right) => {
145
+ const leftRelative = left.delta / Math.max(left.bindLength, ABSOLUTE_FLOOR);
146
+ const rightRelative = right.delta / Math.max(right.bindLength, ABSOLUTE_FLOOR);
147
+ return rightRelative - leftRelative;
148
+ });
149
+ return {
150
+ bones,
151
+ compared,
152
+ maxDeviation,
153
+ worst: deviations[0] ?? null,
154
+ deviations,
155
+ rigid: deviations.length === 0,
156
+ };
157
+ }
@@ -0,0 +1,116 @@
1
+ import { Vector3 } from "three";
2
+
3
+ export type CameraShakeCurve = (phase: number) => number;
4
+
5
+ export interface ICameraShakeOptions {
6
+ /** Position amplitude in world metres, supplied by the game. */
7
+ readonly amplitude: Vector3;
8
+ /** Rotation amplitude in radians around x/y/z, supplied by the game. */
9
+ readonly rotationAmplitude: Vector3;
10
+ /** Curve cycles per second, supplied by the game. */
11
+ readonly frequency: number;
12
+ /** Exponential envelope decay per second, supplied by the game. */
13
+ readonly decay: number;
14
+ /** Game-authored waveform sampled at `elapsed * frequency * 2π`. */
15
+ readonly curve: CameraShakeCurve;
16
+ }
17
+
18
+ export interface ICameraShakeOffset {
19
+ readonly position: Vector3;
20
+ readonly rotation: Vector3;
21
+ }
22
+
23
+ /**
24
+ * Produce a transient camera offset without owning or mutating a camera.
25
+ *
26
+ * The caller supplies the amplitudes, frequency, decay and waveform. {@link update} evaluates the
27
+ * waveform against the caller's fixed-step delta and returns a reusable position/rotation offset;
28
+ * a template can compose it after its own camera rig and damping.
29
+ */
30
+ export class CameraShake {
31
+ readonly amplitude: Vector3;
32
+ readonly rotationAmplitude: Vector3;
33
+ readonly frequency: number;
34
+ readonly decay: number;
35
+ readonly curve: CameraShakeCurve;
36
+ readonly offset: ICameraShakeOffset = {
37
+ position: new Vector3(),
38
+ rotation: new Vector3(),
39
+ };
40
+ #active = false;
41
+ #elapsed = 0;
42
+
43
+ constructor(options: ICameraShakeOptions) {
44
+ if (options === undefined || options === null || options.amplitude === undefined)
45
+ throw new Error("CameraShake.amplitude is required.");
46
+ if (options.rotationAmplitude === undefined)
47
+ throw new Error("CameraShake.rotationAmplitude is required.");
48
+ validateVector(options.amplitude, "CameraShake.amplitude");
49
+ validateVector(options.rotationAmplitude, "CameraShake.rotationAmplitude");
50
+ if (!Number.isFinite(options.frequency) || options.frequency <= 0)
51
+ throw new Error("CameraShake.frequency must be positive and finite.");
52
+ if (!Number.isFinite(options.decay) || options.decay <= 0)
53
+ throw new Error("CameraShake.decay must be positive and finite.");
54
+ if (typeof options.curve !== "function") throw new Error("CameraShake.curve is required.");
55
+ this.amplitude = options.amplitude.clone();
56
+ this.rotationAmplitude = options.rotationAmplitude.clone();
57
+ this.frequency = options.frequency;
58
+ this.decay = options.decay;
59
+ this.curve = options.curve;
60
+ }
61
+
62
+ get active(): boolean {
63
+ return this.#active;
64
+ }
65
+
66
+ get elapsed(): number {
67
+ return this.#elapsed;
68
+ }
69
+
70
+ /** Start or restart the authored shake waveform. */
71
+ trigger(): this {
72
+ this.#elapsed = 0;
73
+ this.#active = true;
74
+ this.#clearOffset();
75
+ return this;
76
+ }
77
+
78
+ /** Stop the effect and clear the offset. */
79
+ stop(): this {
80
+ this.#active = false;
81
+ this.#elapsed = 0;
82
+ this.#clearOffset();
83
+ return this;
84
+ }
85
+
86
+ /** Evaluate the current offset and advance by one caller-supplied fixed-step delta. */
87
+ update(dt: number): ICameraShakeOffset {
88
+ if (!Number.isFinite(dt) || dt < 0)
89
+ throw new Error("CameraShake.update delta must be finite and non-negative.");
90
+ if (!this.#active) {
91
+ this.#clearOffset();
92
+ return this.offset;
93
+ }
94
+
95
+ const envelope = Math.exp(-this.decay * this.#elapsed);
96
+ const phase = this.#elapsed * this.frequency * Math.PI * 2;
97
+ const sample = this.curve(phase);
98
+ if (!Number.isFinite(sample)) throw new Error("CameraShake.curve must return a finite number.");
99
+ this.offset.position.copy(this.amplitude).multiplyScalar(sample * envelope);
100
+ this.offset.rotation.copy(this.rotationAmplitude).multiplyScalar(sample * envelope);
101
+ this.#elapsed += dt;
102
+ if (!Number.isFinite(this.#elapsed)) throw new Error("CameraShake elapsed time overflowed.");
103
+ if (Math.exp(-this.decay * this.#elapsed) <= Number.EPSILON) this.#active = false;
104
+ return this.offset;
105
+ }
106
+
107
+ #clearOffset(): void {
108
+ this.offset.position.set(0, 0, 0);
109
+ this.offset.rotation.set(0, 0, 0);
110
+ }
111
+ }
112
+
113
+ function validateVector(value: Vector3 | null | undefined, name: string): void {
114
+ if (value === undefined || value === null || ![value.x, value.y, value.z].every(Number.isFinite))
115
+ throw new Error(`${name} must contain finite components.`);
116
+ }
@@ -0,0 +1,47 @@
1
+ import { OrthographicCamera, Scene } from "three";
2
+ import type { IViewportSize, Viewport } from "./viewport.js";
3
+
4
+ /** A Godot-shaped render surface that is independent of the world camera and post pipeline. */
5
+ export class CanvasLayer {
6
+ readonly scene = new Scene();
7
+ readonly camera = new OrthographicCamera();
8
+ /** Declares that this layer covers the framebuffer, allowing the world pass to be skipped. */
9
+ opaque = false;
10
+ /** Keep preparing/drawing the world behind an opaque loading cover, including scene changes. */
11
+ keepWorldRendering = false;
12
+ /** Allow first-use world draws during startup; render-cadence admission runs independently. */
13
+ renderWorldDuringStartup = true;
14
+ #stopResize: () => void;
15
+ #resizeListeners = new Set<(size: IViewportSize) => void>();
16
+
17
+ constructor(viewport: Pick<Viewport, "onResize" | "size">) {
18
+ this.camera.position.z = 1;
19
+ this.#resize(viewport.size);
20
+ this.#stopResize = viewport.onResize(this.#resize);
21
+ }
22
+
23
+ dispose(): void {
24
+ this.#stopResize();
25
+ this.#stopResize = () => undefined;
26
+ this.#resizeListeners.clear();
27
+ this.scene.clear();
28
+ }
29
+
30
+ /** Subscribe to drawable-size changes after this layer has updated its camera. */
31
+ onResize(handler: (size: IViewportSize) => void): () => void {
32
+ this.#resizeListeners.add(handler);
33
+ return () => this.#resizeListeners.delete(handler);
34
+ }
35
+
36
+ #resize = ({ height, width }: IViewportSize): void => {
37
+ this.camera.left = -width / 2;
38
+ this.camera.right = width / 2;
39
+ this.camera.top = height / 2;
40
+ this.camera.bottom = -height / 2;
41
+ this.camera.near = 0;
42
+ this.camera.far = 2;
43
+ this.camera.updateProjectionMatrix();
44
+ for (const listener of this.#resizeListeners)
45
+ listener({ height, width, aspect: width / height });
46
+ };
47
+ }