@threenative/core 0.3.11 → 0.3.13

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 (236) hide show
  1. package/README.md +1 -1
  2. package/capabilities.json +1988 -204
  3. package/dist/{assets-YUbXa3-Y.d.ts → assets-CfMKnOsK.d.ts} +78 -1
  4. package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
  5. package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-G7ttVy7y.d.ts} +1 -1
  6. package/dist/chunk-4SRAQFTU.js +133 -0
  7. package/dist/chunk-CFGTPFUH.js +231 -0
  8. package/dist/chunk-DIPIJICH.js +8916 -0
  9. package/dist/chunk-EEABDLUC.js +2237 -0
  10. package/dist/chunk-EFWZWLPY.js +1895 -0
  11. package/dist/chunk-GXY7B3JG.js +46 -0
  12. package/dist/chunk-GYUZJQ7U.js +280 -0
  13. package/dist/chunk-H4J6IAJE.js +504 -0
  14. package/dist/chunk-KIRUKTBQ.js +187 -0
  15. package/dist/chunk-QWJEMUUT.js +94 -0
  16. package/dist/chunk-SV4QVUTQ.js +31 -0
  17. package/dist/chunk-U4YHUKKL.js +615 -0
  18. package/dist/chunk-VP43GIWW.js +18 -0
  19. package/dist/chunk-XDTZ4QMO.js +160 -0
  20. package/dist/default-tone-mapping-GgKPTiBP.d.ts +4 -0
  21. package/dist/{game-DzMcitDO.d.ts → game-k8K3hZai.d.ts} +85 -9
  22. package/dist/hot.d.ts +5 -4
  23. package/dist/hot.js +5 -52
  24. package/dist/index.d.ts +633 -1351
  25. package/dist/index.js +12873 -23068
  26. package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-DPTzeCcD.d.ts} +35 -3
  27. package/dist/playtest.d.ts +5 -4
  28. package/dist/playtest.js +25 -75
  29. package/dist/quality-BYqKGAwo.d.ts +868 -0
  30. package/dist/react-css.js +1 -215
  31. package/dist/react.d.ts +3 -2
  32. package/dist/render-environment.d.ts +170 -0
  33. package/dist/render-environment.js +352 -0
  34. package/dist/{renderer-rZm0hVqq.d.ts → renderer-BtOSseYf.d.ts} +42 -35
  35. package/dist/spells/index.d.ts +643 -0
  36. package/dist/spells/index.js +1558 -0
  37. package/dist/spells/ultra/index.d.ts +1600 -0
  38. package/dist/spells/ultra/index.js +6804 -0
  39. package/dist/terrain-jobs-worker.js +1 -123
  40. package/dist/two-sided-foliage-W523J3UM.js +1 -0
  41. package/dist/ui-layer.js +6 -384
  42. package/dist/worker.js +13 -43
  43. package/dist/world.d.ts +988 -268
  44. package/dist/world.js +17464 -18290
  45. package/mcp/animation-server.mjs +1 -1
  46. package/mcp/animation.mjs +2 -3
  47. package/mcp/engine-server.mjs +245 -52
  48. package/mcp/servers.mjs +10 -3
  49. package/mcp/terrain.mjs +8 -0
  50. package/package.json +19 -7
  51. package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
  52. package/patches/three@0.187.0.patch +2004 -407
  53. package/src/animation-batch.ts +193 -0
  54. package/src/animation-layers.ts +7 -3
  55. package/src/animation.ts +209 -29
  56. package/src/asset-cache.ts +3 -3
  57. package/src/asset-memo.ts +202 -0
  58. package/src/assets.ts +437 -125
  59. package/src/auto-batch.ts +190 -44
  60. package/src/card-lod.ts +152 -0
  61. package/src/compressed-texture-preparation.ts +1008 -0
  62. package/src/compute-driven.ts +1 -1
  63. package/src/config.ts +8 -0
  64. package/src/debug.ts +103 -22
  65. package/src/dev-global.ts +54 -0
  66. package/src/engine-hooks.ts +37 -0
  67. package/src/frame-budget.ts +50 -23
  68. package/src/game-boot-phase.ts +269 -0
  69. package/src/game-dev-tools.ts +86 -0
  70. package/src/game-frame-loop.ts +958 -0
  71. package/src/game-renderer-metrics.ts +77 -0
  72. package/src/game-startup.ts +1076 -0
  73. package/src/game-ui.ts +84 -0
  74. package/src/game-validate.ts +70 -0
  75. package/src/game.ts +198 -2264
  76. package/src/gamepad-mappings.ts +269 -0
  77. package/src/generated/console-markers.ts +13 -0
  78. package/src/geometry-capture.ts +28 -4
  79. package/src/gpu-readings.ts +98 -0
  80. package/src/gpu-scene-bvh.ts +149 -36
  81. package/src/hot.ts +4 -7
  82. package/src/index.ts +141 -9
  83. package/src/input.ts +237 -25
  84. package/src/instanced-batch-lod.ts +3 -8
  85. package/src/interpolation.ts +171 -40
  86. package/src/launch-diagnostics.ts +22 -12
  87. package/src/look/ao-admission.ts +25 -0
  88. package/src/look/auto-exposure.ts +5 -16
  89. package/src/look/default-tone-mapping.ts +41 -5
  90. package/src/look/filmic-tone-mapping.ts +15 -13
  91. package/src/look/local-exposure.ts +2 -7
  92. package/src/look/look-diagnostics.ts +3 -3
  93. package/src/look/quad-pass.ts +21 -0
  94. package/src/look/quality.ts +14 -5
  95. package/src/look/unreal-bloom.ts +4 -13
  96. package/src/look/world-environment.ts +113 -103
  97. package/src/loop.ts +29 -0
  98. package/src/merge-parts.ts +20 -24
  99. package/src/model-lod.ts +139 -17
  100. package/src/particle-kinds.ts +515 -0
  101. package/src/particle-significance.ts +12 -0
  102. package/src/particles.ts +19 -10
  103. package/src/picking.ts +17 -3
  104. package/src/platform.ts +23 -4
  105. package/src/playtest.ts +27 -1
  106. package/src/profiling/FrameStages.ts +5 -6
  107. package/src/profiling/Spans.ts +3 -17
  108. package/src/profiling/debug-telemetry.ts +2 -6
  109. package/src/profiling/render-list-validate.ts +6 -15
  110. package/src/projection-apply.ts +4 -1
  111. package/src/projection-marker.ts +2 -1
  112. package/src/projection-plan.ts +9 -6
  113. package/src/quiet-markers.ts +3 -10
  114. package/src/render/cpu-bvh.ts +100 -0
  115. package/src/render/depth-pyramid.ts +6 -14
  116. package/src/render/environment/environmentContribution.ts +202 -0
  117. package/src/render/environment/environmentRadiance.ts +44 -0
  118. package/src/render/environment/environmentSampleCache.ts +56 -0
  119. package/src/render/environment/environmentSampling.ts +201 -0
  120. package/src/render/environment/environmentSnapshot.ts +71 -0
  121. package/src/render/environment/gate.ts +57 -0
  122. package/src/render/mesh-pool.ts +4 -20
  123. package/src/render/probe-trace.ts +872 -0
  124. package/src/render/probe-volume.ts +780 -34
  125. package/src/render/radiance-cache.ts +17 -0
  126. package/src/render/resolution-subrect.ts +2 -0
  127. package/src/render/rough-diffuse.ts +46 -12
  128. package/src/render/soft-shadow.ts +27 -12
  129. package/src/render/virtual-shadow-adaptive.ts +55 -0
  130. package/src/render/virtual-shadow-casters.ts +175 -0
  131. package/src/render/virtual-shadow-layers.ts +76 -0
  132. package/src/render/virtual-shadow-level.ts +224 -0
  133. package/src/render/virtual-shadow-markers.ts +193 -0
  134. package/src/render/virtual-shadow-options.ts +370 -0
  135. package/src/render/virtual-shadow-pages.ts +5 -0
  136. package/src/render/virtual-shadow-partial.ts +13 -0
  137. package/src/render/virtual-shadow.ts +231 -1008
  138. package/src/render/world-impostor-surface.ts +402 -40
  139. package/src/render/world-impostor.ts +5 -2
  140. package/src/render-camera-cull.ts +98 -3
  141. package/src/render-environment.ts +41 -0
  142. package/src/render-pass-budget.ts +34 -7
  143. package/src/renderProjection.ts +22 -0
  144. package/src/renderer-config.ts +36 -0
  145. package/src/renderer-facts.ts +37 -0
  146. package/src/renderer.ts +144 -65
  147. package/src/resolution-scaler.ts +3 -2
  148. package/src/scene-entry-inspectors.ts +61 -0
  149. package/src/snow-field.ts +2 -1
  150. package/src/spells/cast-pool.ts +361 -0
  151. package/src/spells/index.ts +177 -0
  152. package/src/spells/mechanisms.ts +295 -0
  153. package/src/spells/reaction-field.ts +415 -0
  154. package/src/spells/spell-lights.ts +139 -0
  155. package/src/spells/spell-world.ts +187 -0
  156. package/src/spells/spell.ts +397 -0
  157. package/src/spells/spells.ts +283 -0
  158. package/src/spells/ultra/engine/camera.ts +184 -0
  159. package/src/spells/ultra/engine/quality.ts +96 -0
  160. package/src/spells/ultra/index.ts +52 -0
  161. package/src/spells/ultra/main.ts +305 -0
  162. package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
  163. package/src/spells/ultra/spells/cast.ts +233 -0
  164. package/src/spells/ultra/spells/fire.ts +1267 -0
  165. package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
  166. package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
  167. package/src/spells/ultra/vfx/FxTarget.ts +61 -0
  168. package/src/spells/ultra/vfx/GroundField.ts +1399 -0
  169. package/src/spells/ultra/vfx/Particles.ts +1475 -0
  170. package/src/spells/ultra/vfx/Ribbons.ts +645 -0
  171. package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
  172. package/src/spells/ultra/vfx/Volumes.ts +489 -0
  173. package/src/spells/ultra/vfx/common.ts +1195 -0
  174. package/src/spells/ultra/vfx/noise.ts +441 -0
  175. package/src/startup-offscreen-bytes.ts +78 -0
  176. package/src/startup-readiness.ts +128 -34
  177. package/src/static-transform.ts +25 -19
  178. package/src/streamed-textures.ts +112 -0
  179. package/src/streaming.ts +68 -4
  180. package/src/texture-streaming.ts +331 -0
  181. package/src/version.ts +1 -1
  182. package/src/warmup.ts +56 -8
  183. package/src/water-surface.ts +9 -3
  184. package/src/worker.ts +12 -2
  185. package/src/world-bundle-safety.ts +446 -0
  186. package/src/world-cell-batches.ts +1178 -0
  187. package/src/world-cell-chunks.ts +1128 -0
  188. package/src/world-cell-data.ts +995 -0
  189. package/src/world-cell-impostors.ts +1461 -0
  190. package/src/world-cell-lod-bias.ts +151 -0
  191. package/src/world-cell-models.ts +1074 -0
  192. package/src/world-cell-options.ts +177 -0
  193. package/src/world-cell-placements.ts +798 -0
  194. package/src/world-cell-prewarm.ts +592 -0
  195. package/src/world-cell-readiness.ts +357 -0
  196. package/src/world-cell-records.ts +401 -0
  197. package/src/world-cell-render-bundles.ts +459 -0
  198. package/src/world-cell-render-gpu-dress.ts +710 -0
  199. package/src/world-cell-render-main-cull.ts +540 -0
  200. package/src/world-cell-render-shadow-claims.ts +198 -0
  201. package/src/world-cell-render-util.ts +259 -0
  202. package/src/world-cell-render.ts +1501 -0
  203. package/src/world-cell-residency.ts +754 -0
  204. package/src/world-cell-stale.ts +238 -0
  205. package/src/world-cells.ts +1335 -10418
  206. package/src/world-chunk-shadow.ts +308 -0
  207. package/src/world-collar.ts +315 -0
  208. package/src/world-gpu-flags.ts +131 -0
  209. package/src/world-gpu-readback.ts +881 -0
  210. package/src/world-gpu-reference.ts +524 -0
  211. package/src/world-gpu-scene.ts +256 -2286
  212. package/src/world-gpu-shadow.ts +203 -0
  213. package/src/world-gpu-types.ts +409 -0
  214. package/src/world-gpu-validation.ts +518 -0
  215. package/src/world-heightfield.ts +802 -0
  216. package/src/world-load-limiter.ts +111 -0
  217. package/src/world-model-sections.ts +80 -0
  218. package/src/world-noise.ts +241 -0
  219. package/src/world-package.ts +42 -0
  220. package/src/world-region.ts +1 -1
  221. package/src/world-river-ribbon.ts +282 -0
  222. package/src/world-root-frame.ts +39 -0
  223. package/src/world-shore-field.ts +91 -0
  224. package/src/world-static-pose.ts +163 -0
  225. package/src/world-surface-sampler.ts +48 -0
  226. package/src/world-terrain-splat.ts +361 -153
  227. package/src/world-tile-budget.ts +249 -0
  228. package/src/world-tile-geometry.ts +469 -0
  229. package/src/world-tile-lod.ts +408 -0
  230. package/src/world-tile-observation.ts +566 -0
  231. package/src/world-tile-stitch.ts +166 -0
  232. package/src/world-tiles.ts +247 -1755
  233. package/src/world-validate.ts +6 -14
  234. package/src/world-warm.ts +51 -0
  235. package/src/world-water-bodies.ts +359 -0
  236. package/src/world.ts +48 -741
@@ -0,0 +1,139 @@
1
+ /**
2
+ * The lights a spell throws, without the light count ever moving.
3
+ *
4
+ * A point light added at cast time is a shader recompile and a lighting-state change in the middle
5
+ * of a fight. This pool creates its lights once, parks every one of them at zero intensity, and
6
+ * hands them out for the duration of an impact. A cast therefore changes what the lights do and
7
+ * never what they are. Niagara submits spell-sized lights as plain simple lights for the same
8
+ * reason (UE 5.8.3: Engine/Plugins/FX/Niagara/Source/Niagara/Private/NiagaraRendererLights.cpp:100,
9
+ * :201).
10
+ */
11
+
12
+ import { type Color, type Object3D, PointLight } from "three";
13
+
14
+ export interface ISpellLightsOptions {
15
+ /** Where the lights are added. A scene, or any object that outlives the casts. */
16
+ readonly parent: Object3D;
17
+ /** Lights in the pool. Defaults to 4: a charge glow, an impact flash, and two in flight. */
18
+ readonly count?: number;
19
+ /** Lights are cheaper than shadows for a flash; a spell never casts one. */
20
+ readonly shadows?: boolean;
21
+ }
22
+
23
+ interface ISlotState {
24
+ /** Seconds left on the current flash. */
25
+ remaining: number;
26
+ /** Seconds the current flash was asked for. */
27
+ duration: number;
28
+ /** Intensity the current flash started at. */
29
+ peak: number;
30
+ }
31
+
32
+ /** One light, and the game-owned look it was given. */
33
+ export interface ISpellLightFlash {
34
+ /** World position of the flash. */
35
+ readonly x: number;
36
+ readonly y: number;
37
+ readonly z: number;
38
+ readonly color: Color;
39
+ /** Peak intensity in candela. */
40
+ readonly intensity: number;
41
+ /** Metres the light reaches. */
42
+ readonly range: number;
43
+ /** Seconds the flash takes to decay to zero. */
44
+ readonly seconds: number;
45
+ }
46
+
47
+ const finite = (value: number, label: string): number => {
48
+ if (!Number.isFinite(value)) throw new TypeError(`${label} must be finite`);
49
+ return value;
50
+ };
51
+
52
+ /**
53
+ * A fixed pool of spell lights.
54
+ *
55
+ * `flash` returns false when every light is busy: a spell reports that and carries on without
56
+ * one rather than growing the pool. Intensity decays linearly to zero, which reads as a flash
57
+ * rather than a lamp fading, and Update runs on the same fixed delta as the casts.
58
+ */
59
+ export class SpellLights {
60
+ readonly lights: readonly PointLight[];
61
+ readonly #slots: ISlotState[];
62
+
63
+ constructor(options: ISpellLightsOptions) {
64
+ if (options.parent === undefined || options.parent === null)
65
+ throw new Error("SpellLights.parent is required.");
66
+ const count = options.count ?? 4;
67
+ if (!Number.isInteger(count) || count < 1 || count > 32)
68
+ throw new RangeError("SpellLights.count must be an integer in 1..32");
69
+ this.lights = Array.from({ length: count }, (_, index) => {
70
+ const light = new PointLight(0xffffff, 0, 10, 2);
71
+ light.name = `spell-light-${index}`;
72
+ light.intensity = 0;
73
+ light.castShadow = options.shadows ?? false;
74
+ // Never toggle `visible`: Three.js drops an invisible object before it collects lights, so the
75
+ // frame would see a different light count and recompile. A dark light is intensity 0.
76
+ options.parent.add(light);
77
+ return light;
78
+ });
79
+ this.#slots = this.lights.map(() => ({ duration: 1, peak: 0, remaining: 0 }));
80
+ }
81
+
82
+ /** True while at least one light is lit, so a game can skip its own light bookkeeping. */
83
+ get active(): boolean {
84
+ return this.#slots.some((slot) => slot.remaining > 0);
85
+ }
86
+
87
+ /** The light this flash took, or undefined when the pool was full. */
88
+ flash(request: ISpellLightFlash): PointLight | undefined {
89
+ const seconds = finite(request.seconds, "flash.seconds");
90
+ if (seconds <= 0) throw new RangeError("flash.seconds must be positive");
91
+ // Validate before a slot is claimed: a throw must not leave a light marked busy.
92
+ const intensity = finite(request.intensity, "flash.intensity");
93
+ const range = finite(request.range, "flash.range");
94
+ const x = finite(request.x, "flash.x");
95
+ const y = finite(request.y, "flash.y");
96
+ const z = finite(request.z, "flash.z");
97
+ const index = this.#slots.findIndex((slot) => slot.remaining <= 0);
98
+ if (index < 0) return undefined;
99
+ const light = this.lights[index] as PointLight;
100
+ const slot = this.#slots[index] as ISlotState;
101
+ slot.peak = Math.max(0, intensity);
102
+ slot.duration = seconds;
103
+ slot.remaining = seconds;
104
+ light.position.set(x, y, z);
105
+ light.color.copy(request.color);
106
+ light.distance = Math.max(0, range);
107
+ light.intensity = slot.peak;
108
+ return light;
109
+ }
110
+
111
+ /** Put every light out now, without waiting for its decay. */
112
+ clear(): void {
113
+ for (let index = 0; index < this.#slots.length; index++) {
114
+ const slot = this.#slots[index] as ISlotState;
115
+ slot.remaining = 0;
116
+ slot.peak = 0;
117
+ (this.lights[index] as PointLight).intensity = 0;
118
+ }
119
+ }
120
+
121
+ update(dt: number): void {
122
+ if (!Number.isFinite(dt) || dt < 0)
123
+ throw new RangeError("SpellLights.update delta must be finite and non-negative");
124
+ // Indexed loops: this runs every frame and allocating an entry iterator per light is waste.
125
+ for (let index = 0; index < this.#slots.length; index++) {
126
+ const slot = this.#slots[index] as ISlotState;
127
+ if (slot.remaining <= 0) continue;
128
+ const light = this.lights[index] as PointLight;
129
+ slot.remaining -= dt;
130
+ if (slot.remaining <= 0) {
131
+ slot.remaining = 0;
132
+ slot.peak = 0;
133
+ light.intensity = 0;
134
+ continue;
135
+ }
136
+ light.intensity = slot.peak * (slot.remaining / slot.duration);
137
+ }
138
+ }
139
+ }
@@ -0,0 +1,187 @@
1
+ /**
2
+ * The world a spell lands in.
3
+ *
4
+ * A spell that reads `scene`, `camera` and a floor function directly has to be rewritten for every
5
+ * game, and the upstream files show what happens when it is: 34 of them read the arena SDF, so the
6
+ * arena is load-bearing and a game cannot replace it. Everything a spell needs therefore arrives
7
+ * through here — the scene to add its pooled objects to, the floor to land on, the light pool that
8
+ * never changes size, the surface field it paints, one shake and one flash limiter.
9
+ *
10
+ * Damage, mana, cooldowns and who the target actually is stay in the game. `SpellWorld` knows
11
+ * nothing about them, and a game that wants a spell to hurt something reads the cast's `to` point
12
+ * from its own update and decides.
13
+ */
14
+
15
+ import { type Camera, Color, type Object3D, type Scene, Vector3 } from "three";
16
+ import { CameraShake, type CameraShakeCurve, type ICameraShakeOptions } from "../camera-shake.js";
17
+ import type { ICastEnvironment } from "./cast-pool.js";
18
+ import { type IReactionFieldOptions, ReactionField } from "./reaction-field.js";
19
+ import { SpellLights } from "./spell-lights.js";
20
+
21
+ export interface ISpellWorldShakeOptions {
22
+ /** Metres. Defaults to 0.12, which reads as a thump and not as a broken camera. */
23
+ readonly amplitude?: number;
24
+ /** Radians. Defaults to 0.012. */
25
+ readonly rotationAmplitude?: number;
26
+ /** Cycles per second. Defaults to 11. */
27
+ readonly frequency?: number;
28
+ /** Exponential decay per second. Defaults to 5. */
29
+ readonly decay?: number;
30
+ readonly curve?: CameraShakeCurve;
31
+ }
32
+
33
+ export interface ISpellWorldOptions {
34
+ /** Where every pooled object is added. The game owns it, and it outlives every cast. */
35
+ readonly scene: Scene;
36
+ /** The camera a spell may read for billboarding. Optional: most spells never look at it. */
37
+ readonly camera?: Camera;
38
+ /** Floor height under a point in metres. A spell lands here instead of at y = 0. */
39
+ readonly groundAt?: (x: number, z: number) => number;
40
+ /** Cast records. Defaults to 16. */
41
+ readonly castSlots?: number;
42
+ /** Lights in the pool. Defaults to 4. */
43
+ readonly lightCount?: number;
44
+ /** Surface field. Defaults to 96 cells over 120 m. `false` skips it and saves the float arrays. */
45
+ readonly reaction?: IReactionFieldOptions | false;
46
+ /**
47
+ * Keep every spell to at most three flashes per second (WCAG 2.3.1). Defaults to false, which is
48
+ * the upstream behaviour; a game with an accessibility setting turns it on.
49
+ */
50
+ readonly reducedFlashes?: boolean;
51
+ /** Spells that shake the camera. `false` gives them nothing to shake. */
52
+ readonly shake?: ISpellWorldShakeOptions | false;
53
+ /**
54
+ * Parent an object a spell built. A `GPUParticles3D` also needs a renderer before it can emit, and
55
+ * only the game knows its own context: pass the game context's `add`, which parents *and* attaches.
56
+ * The default parents to `scene`, which is enough for a test and not enough to draw.
57
+ */
58
+ readonly add?: (object: Object3D) => void;
59
+ }
60
+
61
+ /** The stock shake: one thump, gone in about a fifth of a second. */
62
+ const DEFAULT_SHAKE: Required<Omit<ISpellWorldShakeOptions, "curve">> = {
63
+ amplitude: 0.12,
64
+ decay: 5,
65
+ frequency: 11,
66
+ rotationAmplitude: 0.012,
67
+ };
68
+
69
+ const DEFAULT_CURVE: CameraShakeCurve = (phase) => Math.sin(phase) * Math.cos(phase * 1.7);
70
+
71
+ /**
72
+ * Everything a spell is allowed to touch.
73
+ *
74
+ * One instance per game. `update` advances the light decay, the surface field and the shake; the
75
+ * casts themselves live in a `CastPool` the game steps itself, so a paused game can stop casting
76
+ * without also freezing a scorch that is still fading.
77
+ */
78
+ export class SpellWorld implements ICastEnvironment {
79
+ readonly scene: Scene;
80
+ readonly camera: Camera | undefined;
81
+ readonly groundAt: ((x: number, z: number) => number) | undefined;
82
+ readonly castSlots: number;
83
+ readonly lights: SpellLights;
84
+ readonly reaction: ReactionField | undefined;
85
+ readonly shake: CameraShake | undefined;
86
+ readonly reducedFlashes: boolean;
87
+ /** Where a spell with no `from` starts: the caster's hand, in world metres. */
88
+ readonly focus = new Vector3();
89
+ /** Parent a spell's pooled object. See `ISpellWorldOptions.add`. */
90
+ readonly add: (object: Object3D) => void;
91
+ /** Everything a spell has parented through `add`, in creation order. */
92
+ readonly objects: Object3D[] = [];
93
+ /** Seconds since the world was created. */
94
+ time = 0;
95
+ /** Flashes the limiter refused, so a game can see its own accessibility setting working. */
96
+ suppressedFlashes = 0;
97
+
98
+ /** Millisecond stamps of the flashes that were allowed, newest last, at most `FLASH_WINDOW`. */
99
+ #flashes: number[] = [];
100
+
101
+ constructor(options: ISpellWorldOptions) {
102
+ if (options.scene === undefined || options.scene === null)
103
+ throw new Error("SpellWorld.scene is required.");
104
+ this.scene = options.scene;
105
+ this.camera = options.camera;
106
+ this.groundAt = options.groundAt;
107
+ this.castSlots = options.castSlots ?? 16;
108
+ this.add = (object: Object3D) => {
109
+ if (this.objects.includes(object)) return;
110
+ this.objects.push(object);
111
+ if (options.add === undefined) options.scene.add(object);
112
+ else options.add(object);
113
+ };
114
+ this.reducedFlashes = options.reducedFlashes ?? false;
115
+ this.lights = new SpellLights({ count: options.lightCount ?? 4, parent: options.scene });
116
+ this.reaction =
117
+ options.reaction === false ? undefined : new ReactionField(options.reaction ?? {});
118
+ if (options.shake === false) this.shake = undefined;
119
+ else {
120
+ const shake = options.shake ?? {};
121
+ const amplitude = shake.amplitude ?? DEFAULT_SHAKE.amplitude;
122
+ const rotationAmplitude = shake.rotationAmplitude ?? DEFAULT_SHAKE.rotationAmplitude;
123
+ const settings: ICameraShakeOptions = {
124
+ amplitude: new Vector3(amplitude, amplitude * 0.6, amplitude),
125
+ curve: shake.curve ?? DEFAULT_CURVE,
126
+ decay: shake.decay ?? DEFAULT_SHAKE.decay,
127
+ frequency: shake.frequency ?? DEFAULT_SHAKE.frequency,
128
+ rotationAmplitude: new Vector3(
129
+ rotationAmplitude,
130
+ rotationAmplitude,
131
+ rotationAmplitude * 0.5,
132
+ ),
133
+ };
134
+ this.shake = new CameraShake(settings);
135
+ }
136
+ }
137
+
138
+ /**
139
+ * Ask the limiter whether a flash may be shown.
140
+ *
141
+ * With reduced flashes on, a fourth flash inside one second is refused and the spell draws its
142
+ * impact without one. Returning a boolean rather than quietly dimming keeps the spell honest:
143
+ * the spell still happens, the flash does not.
144
+ */
145
+ flash(): boolean {
146
+ if (!this.reducedFlashes) return true;
147
+ const now = this.time * 1000;
148
+ this.#flashes = this.#flashes.filter((at) => now - at < 1000);
149
+ if (this.#flashes.length >= FLASH_PER_SECOND) {
150
+ this.suppressedFlashes += 1;
151
+ return false;
152
+ }
153
+ this.#flashes.push(now);
154
+ return true;
155
+ }
156
+
157
+ /** Surface height of the floor under a point, or 0 when the game supplied none. */
158
+ floorAt(x: number, z: number): number {
159
+ return this.groundAt?.(x, z) ?? 0;
160
+ }
161
+
162
+ update(dt: number): void {
163
+ if (!Number.isFinite(dt) || dt < 0)
164
+ throw new RangeError("SpellWorld.update delta must be finite and non-negative");
165
+ this.time += dt;
166
+ this.lights.update(dt);
167
+ this.reaction?.update(dt);
168
+ this.shake?.update(dt);
169
+ }
170
+
171
+ /** Put out every light, clear the floor and stop the shake, keeping every pool warm. */
172
+ clear(): void {
173
+ this.lights.clear();
174
+ this.reaction?.clear();
175
+ this.shake?.stop();
176
+ this.#flashes = [];
177
+ this.suppressedFlashes = 0;
178
+ }
179
+ }
180
+
181
+ /** WCAG 2.3.1: no more than three flashes in any one-second window. */
182
+ const FLASH_PER_SECOND = 3;
183
+
184
+ /** A colour the spell factories share, so a stock look and an override read the same. */
185
+ export function color(value: string | Color): Color {
186
+ return value instanceof Color ? value : new Color(value);
187
+ }