@viggle/splat-engine-three 0.1.1 → 0.3.0

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 (112) hide show
  1. package/CHANGELOG.md +58 -0
  2. package/README.md +158 -20
  3. package/dist/chunks/chunk-2GKWT24B.js +23182 -0
  4. package/dist/chunks/chunk-2GKWT24B.js.map +7 -0
  5. package/dist/index.js +235 -3
  6. package/dist/types/anim/animation-conversion.d.ts +2 -2
  7. package/dist/types/anim/keyframe-splines.d.ts +17 -41
  8. package/dist/types/animation.d.ts +84 -28
  9. package/dist/types/armature.d.ts +280 -2
  10. package/dist/types/character.d.ts +120 -2
  11. package/dist/types/effects/index.d.ts +12 -0
  12. package/dist/types/effects/outlines/outline-effect.d.ts +98 -0
  13. package/dist/types/effects/outlines/outline-shaders.d.ts +14 -0
  14. package/dist/types/effects/pixelart/pixelart-effect.d.ts +152 -0
  15. package/dist/types/effects/pixelart/pixelart-shaders.d.ts +31 -0
  16. package/dist/types/effects/postfx/base-capturing-pass.d.ts +109 -0
  17. package/dist/types/effects/postfx/camera-frame.d.ts +103 -0
  18. package/dist/types/effects/postfx/frame-renderer.d.ts +32 -0
  19. package/dist/types/effects/postfx/frame-shaders.d.ts +19 -0
  20. package/dist/types/effects/postfx/mask.d.ts +44 -0
  21. package/dist/types/effects/postfx/postfx.d.ts +144 -0
  22. package/dist/types/effects/postfx/program.d.ts +74 -0
  23. package/dist/types/effects/postfx/uniforms.d.ts +24 -0
  24. package/dist/types/effects/postfx/webgl-program.d.ts +6 -0
  25. package/dist/types/effects/postfx/webgpu-program.d.ts +3 -0
  26. package/dist/types/effects/vfx/data-types.d.ts +100 -0
  27. package/dist/types/effects/vfx/index.d.ts +37 -0
  28. package/dist/types/effects/vfx/json-vfx-prefab.d.ts +94 -0
  29. package/dist/types/effects/vfx/layer-renderer.d.ts +118 -0
  30. package/dist/types/effects/vfx/layers/mesh.d.ts +124 -0
  31. package/dist/types/effects/vfx/layers/particle.d.ts +90 -0
  32. package/dist/types/effects/vfx/layers/shader.d.ts +130 -0
  33. package/dist/types/effects/vfx/layers/shared.d.ts +40 -0
  34. package/dist/types/effects/vfx/layers/sprite.d.ts +45 -0
  35. package/dist/types/effects/vfx/pool.d.ts +51 -0
  36. package/dist/types/effects/vfx/prefab.d.ts +48 -0
  37. package/dist/types/effects/vfx/prewarm.d.ts +17 -0
  38. package/dist/types/effects/vfx/stage.d.ts +115 -0
  39. package/dist/types/effects/vfx/webgpu-register.d.ts +2 -0
  40. package/dist/types/effects/webgpu-register.d.ts +2 -0
  41. package/dist/types/engine.d.ts +18 -0
  42. package/dist/types/environment.d.ts +96 -8
  43. package/dist/types/index.d.ts +35 -6
  44. package/dist/types/loader/animation/animation-glb.d.ts +4 -4
  45. package/dist/types/loader/character/load.d.ts +6 -1
  46. package/dist/types/loader/environment/lod-bundle.d.ts +123 -0
  47. package/dist/types/loader/environment/spz-decode.d.ts +88 -0
  48. package/dist/types/loader/environment/spz.d.ts +28 -0
  49. package/dist/types/loader/shared/asset-fetch.d.ts +11 -0
  50. package/dist/types/loader/shared/asset-loader.d.ts +86 -0
  51. package/dist/types/loader/shared/bin-cache.d.ts +41 -14
  52. package/dist/types/loader/shared/decode-worker.d.ts +27 -0
  53. package/dist/types/loader/shared/glb.d.ts +30 -0
  54. package/dist/types/loader/shared/inflate.d.ts +9 -0
  55. package/dist/types/loader/shared/pack-splats-task.d.ts +17 -0
  56. package/dist/types/loader/shared/sog-decode.d.ts +81 -0
  57. package/dist/types/loader/shared/sog.d.ts +17 -0
  58. package/dist/types/math.d.ts +198 -13
  59. package/dist/types/physics/ammo.d.ts +217 -0
  60. package/dist/types/physics/index.d.ts +11 -0
  61. package/dist/types/physics/joints.d.ts +206 -0
  62. package/dist/types/physics/physics-world.d.ts +194 -0
  63. package/dist/types/physics/rigid-body.d.ts +361 -0
  64. package/dist/types/presets/camera/camera-preset.d.ts +43 -0
  65. package/dist/types/presets/camera/third-person-camera.d.ts +63 -0
  66. package/dist/types/presets/character/body-shape.d.ts +109 -0
  67. package/dist/types/presets/character/character-reveal.d.ts +90 -0
  68. package/dist/types/presets/character/socket-loadout.d.ts +61 -0
  69. package/dist/types/presets/index.d.ts +13 -0
  70. package/dist/types/presets/vfx/mesh-flash.d.ts +51 -0
  71. package/dist/types/presets/visual/bone-overlay.d.ts +57 -0
  72. package/dist/types/proxy/environment-input.d.ts +30 -0
  73. package/dist/types/proxy/environment-source.d.ts +39 -0
  74. package/dist/types/proxy/proxy-debug.d.ts +106 -0
  75. package/dist/types/proxy/splat-source.d.ts +42 -0
  76. package/dist/types/proxy/voxelizer.d.ts +383 -0
  77. package/dist/types/relight/backend.d.ts +101 -0
  78. package/dist/types/relight/index.d.ts +6 -0
  79. package/dist/types/relight/relight-pass.d.ts +367 -0
  80. package/dist/types/relight/relight-placeholder.d.ts +2 -0
  81. package/dist/types/relight/relight-shaders.d.ts +4 -0
  82. package/dist/types/relight/shadow-bias.d.ts +26 -0
  83. package/dist/types/relight/splat-relight.d.ts +760 -0
  84. package/dist/types/relight/webgl-backend.d.ts +3 -0
  85. package/dist/types/relight/webgpu/backend.d.ts +3 -0
  86. package/dist/types/relight/webgpu-register.d.ts +2 -0
  87. package/dist/types/scene.d.ts +291 -0
  88. package/dist/types/skeletal/animation-player.d.ts +31 -3
  89. package/dist/types/skeletal/body-parts.d.ts +55 -0
  90. package/dist/types/skeletal/ragdoll-config.d.ts +115 -0
  91. package/dist/types/skeletal/ragdoll.d.ts +283 -0
  92. package/dist/types/skeletal/skeleton.d.ts +9 -2
  93. package/dist/types/splat/backend.d.ts +2 -0
  94. package/dist/types/splat/color-modifier.d.ts +78 -0
  95. package/dist/types/splat/cut-groups.d.ts +27 -0
  96. package/dist/types/splat/relight-binding.d.ts +39 -0
  97. package/dist/types/splat/reveal-bake.d.ts +43 -0
  98. package/dist/types/splat/reveal-look.d.ts +64 -0
  99. package/dist/types/splat/splat-mesh.d.ts +1 -0
  100. package/dist/types/splat/splat.d.ts +154 -0
  101. package/dist/types/splat/webgl/shaders.d.ts +5 -1
  102. package/dist/types/splat/webgl/splat-mesh.d.ts +4 -0
  103. package/dist/types/splat/webgpu/radix-sort.d.ts +3 -0
  104. package/dist/types/splat/webgpu/splat-mesh.d.ts +23 -0
  105. package/dist/types/three/splat-character.d.ts +28 -0
  106. package/dist/types/three/spz-loader.d.ts +35 -0
  107. package/dist/types/types.d.ts +6 -0
  108. package/dist/webgpu.js +1137 -154
  109. package/dist/webgpu.js.map +4 -4
  110. package/package.json +6 -2
  111. package/dist/chunks/chunk-WN5WBKM4.js +0 -8606
  112. package/dist/chunks/chunk-WN5WBKM4.js.map +0 -7
@@ -0,0 +1,144 @@
1
+ import type { RenderTarget, WebGLRenderer } from 'three';
2
+ import type { Scene } from '../../scene';
3
+ import { CameraFrame } from './camera-frame';
4
+ /**
5
+ * A post-process effect {@link PostFX} runs. The three.js counterpart of the
6
+ * PlayCanvas build's `PostFXPass`, with the same lifecycle names so a pass
7
+ * ported from there keeps its overrides.
8
+ *
9
+ * A *capturing* pass reads the full picture the stage before it produced and
10
+ * writes a new one: the first capturing pass reads the scene as the
11
+ * {@link CameraFrame} composed it, each later one the output of the one
12
+ * before, and the last writes the canvas. A non-capturing pass draws nothing;
13
+ * it changes the frame's settings in {@link install} and puts them back in
14
+ * {@link uninstall}.
15
+ *
16
+ * Lifecycle: {@link configureFrame} once when added, then {@link install};
17
+ * {@link render} every frame (capturing passes); {@link uninstall} when
18
+ * removed. Render targets are PostFX's, handed over per frame in a
19
+ * {@link PostFXRenderContext}, so a pass has nothing to reallocate on resize.
20
+ *
21
+ * @group PostFX
22
+ */
23
+ export interface PostFXPass {
24
+ /** True for a pass that reads the picture so far and writes a new one. */
25
+ readonly capturesScene?: boolean;
26
+ /** Request frame features before {@link install}. Runs once, when the pass is added. */
27
+ configureFrame?(scene: Scene, config: PostFXFrameConfig): void;
28
+ /**
29
+ * First capturing pass only: the size of the target the frame composes the
30
+ * scene into, given the canvas size. The scene itself renders at that size
31
+ * times `rendering.renderTargetScale`. Default: the canvas size.
32
+ */
33
+ getSceneCaptureSize?(width: number, height: number): {
34
+ width: number;
35
+ height: number;
36
+ };
37
+ /** Set the pass up. `ctx.frame` is live here for passes that tune it. */
38
+ install(scene: Scene, ctx: PostFXInstallContext): void;
39
+ /** Undo {@link install}. The pass may be installed again afterwards. */
40
+ uninstall(scene: Scene): void;
41
+ /** Capturing passes: draw `ctx.inputTarget` into `ctx.outputTarget`. */
42
+ render?(ctx: PostFXRenderContext): void;
43
+ }
44
+ /**
45
+ * What {@link PostFXPass.install} receives.
46
+ *
47
+ * @group PostFX
48
+ */
49
+ export interface PostFXInstallContext {
50
+ /** The scene's frame; null unless the app or a pass ({@link PostFXFrameConfig}) asked for one. */
51
+ frame: CameraFrame | null;
52
+ }
53
+ /**
54
+ * What a capturing pass's {@link PostFXPass.render} receives each frame.
55
+ *
56
+ * @group PostFX
57
+ */
58
+ export interface PostFXRenderContext {
59
+ /** The scene's renderer, a `THREE.WebGLRenderer` or a `WebGPURenderer`. */
60
+ readonly renderer: WebGLRenderer;
61
+ /** The scene's frame, or null. */
62
+ readonly frame: CameraFrame | null;
63
+ /** The picture so far: 8-bit display colour. Its size is the capture size for the first pass, the canvas's after. */
64
+ readonly inputTarget: RenderTarget;
65
+ /** Where to write: another 8-bit target, or `null` for the canvas. */
66
+ readonly outputTarget: RenderTarget | null;
67
+ /** Size of the output in pixels. */
68
+ readonly width: number;
69
+ readonly height: number;
70
+ }
71
+ /**
72
+ * Frame features a pass asks for in {@link PostFXPass.configureFrame}. Either
73
+ * one realizes the scene's {@link CameraFrame}, as in the PlayCanvas build;
74
+ * both stay set once set.
75
+ *
76
+ * @group PostFX
77
+ */
78
+ export interface PostFXFrameConfig {
79
+ /** Kept for PlayCanvas parity, where it asks for a scene depth prepass: here it realizes the frame. */
80
+ sceneDepthMap?: boolean;
81
+ /** Realize the frame, for a pass that relies on its tone mapping, bloom, grading or vignette. */
82
+ requireFrame?: boolean;
83
+ }
84
+ /**
85
+ * Something drawn over the scene before the frame composes it, such as an
86
+ * outline. Unlike a pass, an overlay alone keeps the scene on the direct path.
87
+ * @internal
88
+ */
89
+ export interface PostFXOverlay {
90
+ /** Draw over the scene in `target` (`null`: the canvas), `width` x `height` pixels. */
91
+ renderOverlay(target: RenderTarget | null, width: number, height: number): void;
92
+ }
93
+ /**
94
+ * Post-processing for a {@link Scene}: the scene's {@link CameraFrame} and a
95
+ * chain of {@link PostFXPass}es between the scene render and the canvas.
96
+ * Always present as `scene.postfx`. Empty, it costs nothing: the scene
97
+ * renders straight to the canvas.
98
+ *
99
+ * ```ts
100
+ * const pixelart = scene.postfx.add(new PixelartEffect({ scale: 3 }));
101
+ * const film = scene.postfx.add(new FilmPass()); // chains after pixelart
102
+ * ```
103
+ *
104
+ * @group PostFX
105
+ */
106
+ export declare class PostFX {
107
+ private readonly _scene;
108
+ private readonly _passes;
109
+ private readonly _config;
110
+ private readonly _overlays;
111
+ private _frameRenderer;
112
+ private _capture;
113
+ private readonly _chain;
114
+ private _width;
115
+ private _height;
116
+ constructor(scene: Scene);
117
+ /** The camera's built-in effects, once {@link getOrCreateCameraFrame} has created them. */
118
+ cameraFrame: CameraFrame | null;
119
+ /** Whether anything sits between the scene render and the canvas. */
120
+ get active(): boolean;
121
+ /** The passes, in the order they run. */
122
+ get passes(): readonly PostFXPass[];
123
+ /** The scene camera's {@link CameraFrame}, created on first call. */
124
+ getOrCreateCameraFrame(): CameraFrame;
125
+ /** Drop the {@link CameraFrame}, and every effect it applied. */
126
+ destroyCameraFrame(): void;
127
+ /** Add a pass at the end of the chain. Returns it, for keeping a handle. */
128
+ add<T extends PostFXPass>(pass: T): T;
129
+ /** Take a pass out of the chain. No-op when it is not in it. */
130
+ remove(pass: PostFXPass): void;
131
+ /** Whether `pass` is in the chain. */
132
+ has(pass: PostFXPass): boolean;
133
+ /** @internal */
134
+ addOverlay(overlay: PostFXOverlay): void;
135
+ /** @internal */
136
+ removeOverlay(overlay: PostFXOverlay): void;
137
+ /** Draw one frame: the scene, then every pass. Called by the scene's loop. @internal */
138
+ render(): void;
139
+ /** The drawing buffer changed size. Called by the scene. @internal */
140
+ resize(width: number, height: number): void;
141
+ /** Tear everything down. Called by {@link Scene.destroy}. @internal */
142
+ destroyAll(): void;
143
+ private _releaseIfIdle;
144
+ }
@@ -0,0 +1,74 @@
1
+ import { RenderTarget } from 'three';
2
+ import type { WebGLRenderer } from 'three';
3
+ import type { PostFXUniformValue } from './uniforms';
4
+ /**
5
+ * How a fullscreen shader's output lands on its target.
6
+ * @internal
7
+ */
8
+ export type PostFXBlend = 'none' | 'alpha' | 'add';
9
+ /**
10
+ * A fullscreen fragment shader, written once per shading language in the
11
+ * dialect PlayCanvas's `QuadRender` takes, so a pass ported from the
12
+ * PlayCanvas build keeps its source:
13
+ *
14
+ * - GLSL: `uniform` declarations, `gl_FragCoord`, `gl_FragColor`,
15
+ * `texelFetch` / `texture2D`, and `varying vec2 vUv0` (0..1, y up).
16
+ * - WGSL: `var name: texture_2d<f32>;` and `var nameSampler: sampler;` for
17
+ * textures, `uniform name: type;` read as `uniform.name`, and
18
+ * `fn fragmentMain(input: FragmentInput) -> FragmentOutput` with
19
+ * `input.position` (pixel coordinates, y down) and `output.color`. On top
20
+ * of PlayCanvas's: `input.vUv0` (0..1, y up) and `input.texUv`, the
21
+ * coordinate that samples a full-target texture the right way up.
22
+ *
23
+ * @internal
24
+ */
25
+ export interface PostFXShaderSource {
26
+ /** Cache and debug name. */
27
+ name: string;
28
+ glsl: string;
29
+ wgsl: string;
30
+ blend?: PostFXBlend;
31
+ }
32
+ /**
33
+ * A compiled {@link PostFXShaderSource}, drawn as one fullscreen triangle.
34
+ * @internal
35
+ */
36
+ export interface PostFXProgram {
37
+ /** Set a uniform the source declares. Unknown names are ignored, as PlayCanvas's scope does. */
38
+ set(name: string, value: PostFXUniformValue): void;
39
+ /** Draw into `target` (`null`: the canvas), over what it holds. */
40
+ draw(target: RenderTarget | null): void;
41
+ dispose(): void;
42
+ }
43
+ /**
44
+ * Compiles {@link PostFXShaderSource}s for one kind of renderer.
45
+ * @internal
46
+ */
47
+ export interface PostFXBackend {
48
+ createProgram(renderer: WebGLRenderer, source: PostFXShaderSource): PostFXProgram;
49
+ }
50
+ /**
51
+ * Make post-processing available under `WebGPURenderer`. Called by the
52
+ * `@viggle/splat-engine-three/webgpu` entry point.
53
+ * @internal
54
+ */
55
+ export declare function registerPostFXWebGPUBackend(backend: PostFXBackend): void;
56
+ /** @internal */
57
+ export declare function postFXBackendFor(renderer: WebGLRenderer): PostFXBackend;
58
+ /**
59
+ * What a post-process target stores. `'hdr'` is linear half-float, what the
60
+ * scene renders into; `'ldr'` is 8-bit display-referred colour, what the
61
+ * passes after the frame's compose hand each other.
62
+ * @internal
63
+ */
64
+ export interface PostFXTargetOptions {
65
+ format: 'hdr' | 'ldr';
66
+ depth?: boolean;
67
+ samples?: number;
68
+ }
69
+ /**
70
+ * Keep `current` at `width` x `height` with `samples`, replacing it when the
71
+ * sample count changed (three.js cannot change that in place).
72
+ * @internal
73
+ */
74
+ export declare function ensurePostFXTarget(renderer: WebGLRenderer, current: RenderTarget | null, width: number, height: number, opts: PostFXTargetOptions): RenderTarget;
@@ -0,0 +1,24 @@
1
+ import { Vector2, Vector3, Vector4 } from 'three';
2
+ import type { Texture } from 'three';
3
+ /**
4
+ * A value a post-process shader uniform takes: a number, a 2-4 component
5
+ * vector (as a three.js vector or an array), or a texture.
6
+ *
7
+ * @group PostFX
8
+ */
9
+ export type PostFXUniformValue = number | ArrayLike<number> | Vector2 | Vector3 | Vector4 | Texture | null;
10
+ /**
11
+ * Store `value` in a uniform holder, keeping the holder's vector instance:
12
+ * a WebGPU uniform node is bound to it.
13
+ * @internal
14
+ */
15
+ export declare function assignUniform(holder: {
16
+ value: unknown;
17
+ }, value: PostFXUniformValue): void;
18
+ /** The uniforms a shader source declares, by name, with their declared type. @internal */
19
+ export interface DeclaredUniform {
20
+ name: string;
21
+ type: 'float' | 'int' | 'vec2' | 'vec3' | 'vec4' | 'texture' | 'sampler';
22
+ }
23
+ /** A zeroed holder value for a uniform of `type`. @internal */
24
+ export declare function initialUniformValue(type: DeclaredUniform['type']): unknown;
@@ -0,0 +1,6 @@
1
+ import type { PostFXBackend } from './program';
2
+ import { type DeclaredUniform } from './uniforms';
3
+ /** The uniforms a PlayCanvas-dialect GLSL fragment declares. @internal */
4
+ export declare function glslUniforms(source: string): DeclaredUniform[];
5
+ /** Post-process programs for `THREE.WebGLRenderer`. @internal */
6
+ export declare const webglPostFXBackend: PostFXBackend;
@@ -0,0 +1,3 @@
1
+ import type { PostFXBackend } from './program';
2
+ /** Post-process programs for `WebGPURenderer`. @internal */
3
+ export declare const webgpuPostFXBackend: PostFXBackend;
@@ -0,0 +1,100 @@
1
+ /**
2
+ * VFX data types - JSON-serializable definitions for data-driven VFX.
3
+ *
4
+ * Each VFX effect consists of one or more layers. The engine ships four
5
+ * built-in layer types (declared via `VfxLayerTypeMap` below):
6
+ * - "particle" - CPU-simulated billboard particles
7
+ * - "mesh" - Procedural mesh primitive (sphere/ring/spike/quad)
8
+ * - "sprite" - Animated spritesheet on a quad
9
+ * - "shader" - A quad / billboard / sphere drawn with shader code from the data
10
+ *
11
+ * The schema is the PlayCanvas build's, unchanged, so effect JSON authored
12
+ * for it loads here as-is.
13
+ *
14
+ * Consumers extend the layer union by registering more renderers with
15
+ * `VfxLayerRegistry` AND declaration-merging their layer types into
16
+ * `VfxLayerTypeMap`.
17
+ */
18
+ import type { VfxParticleLayer } from './layers/particle';
19
+ import type { VfxMeshLayer, MeshShape } from './layers/mesh';
20
+ import type { VfxSpriteLayer } from './layers/sprite';
21
+ import type { VfxShaderLayer } from './layers/shader';
22
+ /**
23
+ * [normalizedTime, value] - time is 0..1 over the layer's duration.
24
+ *
25
+ * @group Effects
26
+ */
27
+ export type CurvePoint = [number, number];
28
+ /**
29
+ * [normalizedTime, r, g, b] - RGB 0..1
30
+ *
31
+ * @group Effects
32
+ */
33
+ export type ColorCurvePoint = [number, number, number, number];
34
+ /**
35
+ * Fields every layer type has.
36
+ *
37
+ * @group Effects
38
+ */
39
+ export interface VfxLayerBase {
40
+ id: string;
41
+ name: string;
42
+ enabled: boolean;
43
+ startDelay: number;
44
+ duration: number;
45
+ }
46
+ /**
47
+ * Map of `layer.type` → concrete layer interface. The engine seeds the
48
+ * built-in types; consumers extend this via declaration merging so
49
+ * `VfxLayer` widens to include their custom layer types:
50
+ *
51
+ * ```ts
52
+ * import type { VfxCloudLayer } from './renderers/cloud';
53
+ * declare module '@viggle/splat-engine-three' {
54
+ * interface VfxLayerTypeMap { cloud: VfxCloudLayer; }
55
+ * }
56
+ * ```
57
+ *
58
+ * @group Effects
59
+ */
60
+ export interface VfxLayerTypeMap {
61
+ particle: VfxParticleLayer;
62
+ mesh: VfxMeshLayer;
63
+ sprite: VfxSpriteLayer;
64
+ /** Generic data-driven shader layer (see `layers/shader.ts`). */
65
+ shader: VfxShaderLayer;
66
+ }
67
+ /** @group Effects */
68
+ export type VfxLayer = VfxLayerTypeMap[keyof VfxLayerTypeMap];
69
+ /**
70
+ * A trail of fading puffs left along the effect root's path.
71
+ *
72
+ * @group Effects
73
+ */
74
+ export interface VfxTrailConfig {
75
+ count: number;
76
+ sampleInterval: number;
77
+ shape: MeshShape;
78
+ radius: number;
79
+ color: [number, number, number];
80
+ emissiveIntensity: number;
81
+ maxOpacity: number;
82
+ shrinkFactor: number;
83
+ blendMode: 'additive' | 'alpha';
84
+ }
85
+ /**
86
+ * One effect: its layers, length, and optional spin and trail.
87
+ *
88
+ * @group Effects
89
+ */
90
+ export interface VfxEffectData {
91
+ name: string;
92
+ duration: number;
93
+ loop?: boolean;
94
+ /** Degrees per second about x, y, z, added to the root's aim. */
95
+ rootRotationSpeed?: [number, number, number];
96
+ trail?: VfxTrailConfig;
97
+ layers: VfxLayer[];
98
+ }
99
+ /** @group Effects */
100
+ export type VfxDataFile = Record<string, VfxEffectData>;
@@ -0,0 +1,37 @@
1
+ /**
2
+ * VFX runtime primitives - pool/stage abstractions plus the data-driven
3
+ * JSON prefab system that interprets {@link VfxEffectData} layers.
4
+ *
5
+ * Two ways to drive an effect, both built on the same {@link IVfxPrefab} /
6
+ * {@link IVfxInstance} contract:
7
+ *
8
+ * - **Gameplay (pool-backed, fire-and-forget):** register a prefab once with
9
+ * {@link VfxStage.register}, then trigger one-shots by name with
10
+ * {@link VfxStage.play}. The pool reuses slots once an effect finishes.
11
+ * - **Editor / cutscene (handle-controlled):** build a prefab from JSON via
12
+ * {@link VfxStage.buildPrefab}, instantiate one with {@link VfxStage.spawn},
13
+ * then drive it yourself.
14
+ *
15
+ * Layer types are plug-ins. The engine ships four generic renderers
16
+ * (`particle`, `mesh`, `sprite`, `shader`); consumers add stylized renderers
17
+ * (cloud, shield, …) by extending {@link VfxLayerRegistry} and merging their
18
+ * layer data interfaces into {@link VfxLayerTypeMap}.
19
+ */
20
+ export { VfxPool } from './pool';
21
+ export type { VfxSpawnOptions } from './pool';
22
+ export { VfxStage } from './stage';
23
+ export type { VfxStageOptions } from './stage';
24
+ export type { IVfxPrefab, IVfxInstance } from './prefab';
25
+ export { JsonVfxPrefab, JsonVfxInstance } from './json-vfx-prefab';
26
+ export { prewarmJsonVfxPrefabs } from './prewarm';
27
+ export { VfxLayerRegistry, defaultLayerRegistry, } from './layer-renderer';
28
+ export type { VfxLayerRenderer, VfxLayerInstance, VfxLayerBuildContext, VfxLayerUpdateContext, } from './layer-renderer';
29
+ export type { CurvePoint, ColorCurvePoint, VfxLayerBase, VfxLayerTypeMap, VfxLayer, VfxTrailConfig, VfxEffectData, VfxDataFile, } from './data-types';
30
+ export { ParticleLayerRenderer } from './layers/particle';
31
+ export type { VfxParticleLayer } from './layers/particle';
32
+ export { MeshLayerRenderer, getVfxMesh, buildVfxSphereMesh, buildVfxRingMesh, buildVfxSpikeMesh, buildVfxQuadMesh, } from './layers/mesh';
33
+ export type { VfxMeshLayer, MeshShape, InstancePattern, VfxMeshInstancing, VfxSinPulse, } from './layers/mesh';
34
+ export { SpriteLayerRenderer } from './layers/sprite';
35
+ export type { VfxSpriteLayer } from './layers/sprite';
36
+ export { ShaderLayerRenderer, validateShaderGLSL, DEFAULT_SHADER_FRAGMENT, DEFAULT_SHADER_FRAGMENT_WGSL, } from './layers/shader';
37
+ export type { VfxShaderLayer, VfxShaderUniform, VfxShaderGeometry, } from './layers/shader';
@@ -0,0 +1,94 @@
1
+ /**
2
+ * JsonVfxPrefab - generic JSON-walker that turns a `VfxEffectData` into a
3
+ * runnable VFX. Knows nothing about specific layer types: looks each layer's
4
+ * `type` up in a `VfxLayerRegistry` and delegates construction + per-frame
5
+ * tick to the matched `VfxLayerRenderer`.
6
+ *
7
+ * Owns:
8
+ * - The root object and its rotation animation (`rootRotationSpeed`).
9
+ * - Shared time math: `elapsed`, `loop`, per-layer `startDelay` + duration
10
+ * resolution. Renderers receive a clean `VfxLayerUpdateContext`.
11
+ * - Optional position trail (puffs sampled from the root's path).
12
+ *
13
+ * Implements the `IVfxPrefab` / `IVfxInstance` contracts so it plugs into
14
+ * `VfxPool` (gameplay path) and `VfxStage.spawn` (editor path) unchanged.
15
+ */
16
+ import { Group } from 'three';
17
+ import type { Mesh, MeshBasicMaterial, Object3D } from 'three';
18
+ import type { Vec3Like } from '../../presets/camera/camera-preset';
19
+ import type { Scene } from '../../scene';
20
+ import type { IVfxInstance, IVfxPrefab } from './prefab';
21
+ import type { VfxEffectData, VfxLayer, VfxTrailConfig } from './data-types';
22
+ import type { VfxLayerInstance, VfxLayerRegistry } from './layer-renderer';
23
+ interface LayerSlot {
24
+ layer: VfxLayer;
25
+ instance: VfxLayerInstance;
26
+ /** Resolved layer duration: `layer.duration > 0 ? layer.duration : effectDuration`. */
27
+ duration: number;
28
+ }
29
+ /**
30
+ * One live effect built by {@link JsonVfxPrefab}.
31
+ *
32
+ * @group Effects
33
+ */
34
+ export declare class JsonVfxInstance implements IVfxInstance {
35
+ private readonly _root;
36
+ private readonly _slots;
37
+ private readonly _duration;
38
+ private readonly _loop;
39
+ private readonly _rootRotSpeed;
40
+ private readonly _trailMeshes;
41
+ private readonly _trailMaterials;
42
+ private readonly _trailBuf;
43
+ private readonly _trailConfig;
44
+ private _trailHead;
45
+ private _trailTimer;
46
+ private _elapsed;
47
+ private _alive;
48
+ private _scale;
49
+ /** Base Euler (degrees) from the last `setRotation`, used to aim
50
+ * directional effects (e.g. a slash arc at its target). The root's
51
+ * rotation each frame is this base plus any `rootRotSpeed` spin, so a
52
+ * spinning effect still respects its spawn-time aim. */
53
+ private readonly _baseEuler;
54
+ /** @internal Built by {@link JsonVfxPrefab.create}. */
55
+ constructor(root: Group, slots: LayerSlot[], duration: number, loop: boolean, rootRotSpeed?: [number, number, number], trailMeshes?: Mesh[], trailMaterials?: MeshBasicMaterial[], trailConfig?: VfxTrailConfig);
56
+ /** The effect's root object: move, parent or inspect it like any other. */
57
+ get object3D(): Object3D;
58
+ spawn(pos: Vec3Like): void;
59
+ update(dt: number): boolean;
60
+ reset(): void;
61
+ moveTo(pos: Vec3Like): void;
62
+ setScale(s: number): void;
63
+ /** Aim the effect root: Euler in degrees. Stored as the base orientation;
64
+ * `rootRotSpeed` spin (if any) is layered on top each frame. Call
65
+ * before/at spawn - the next `_applyRootRotation` picks it up. */
66
+ setRotation(xDeg: number, yDeg: number, zDeg: number): void;
67
+ /** Write the root's rotation as base aim + spin at `time` seconds. */
68
+ private _applyRootRotation;
69
+ /** Jump to an absolute time and evaluate all layers (for editor scrubbing). */
70
+ seekTo(time: number): void;
71
+ get elapsed(): number;
72
+ get alive(): boolean;
73
+ /** Stop or resume particle layers (for editor pause). */
74
+ setParticlesPaused(paused: boolean): void;
75
+ dispose(): void;
76
+ private _tickAllLayers;
77
+ private _updateTrail;
78
+ }
79
+ /**
80
+ * Compiles one {@link VfxEffectData} into instances, through a
81
+ * {@link VfxLayerRegistry}. Usually built with {@link VfxStage.buildPrefab}.
82
+ *
83
+ * @group Effects
84
+ */
85
+ export declare class JsonVfxPrefab implements IVfxPrefab {
86
+ private readonly _data;
87
+ private readonly _registry;
88
+ private readonly _resolveUrl;
89
+ private readonly _renderOrder;
90
+ private _count;
91
+ constructor(data: VfxEffectData, registry: VfxLayerRegistry, resolveUrl?: (path: string) => string, renderOrder?: number);
92
+ create(scene: Scene, parent: Object3D): JsonVfxInstance;
93
+ }
94
+ export {};
@@ -0,0 +1,118 @@
1
+ /**
2
+ * Plug-in surface for VFX layer renderers.
3
+ *
4
+ * `JsonVfxPrefab` ships only mechanism - it walks `VfxEffectData.layers`,
5
+ * resolves each layer's `type` against a `VfxLayerRegistry`, and asks the
6
+ * matched renderer to build a `VfxLayerInstance`. The prefab owns the shared
7
+ * time accounting (startDelay, duration, loop, alive flag) and per-frame
8
+ * dispatch; the renderer owns everything specific to its layer type
9
+ * (geometry, materials, per-frame uniform updates).
10
+ *
11
+ * The engine ships four renderers: `ParticleLayerRenderer`,
12
+ * `MeshLayerRenderer`, `SpriteLayerRenderer` and `ShaderLayerRenderer`.
13
+ * Consumers register their own (stylized fire ribbons, clouds, shields, ...)
14
+ * and extend `VfxLayerTypeMap` via declaration merging so the union narrows
15
+ * correctly in user code.
16
+ */
17
+ import type { Object3D } from 'three';
18
+ import type { Vec3Like } from '../../presets/camera/camera-preset';
19
+ import type { Scene } from '../../scene';
20
+ import type { VfxLayerBase } from './data-types';
21
+ /**
22
+ * Context passed when building a layer instance.
23
+ *
24
+ * @group Effects
25
+ */
26
+ export interface VfxLayerBuildContext {
27
+ /** The scene the effect draws in: its renderer picks the material flavour, its camera faces billboards. */
28
+ scene: Scene;
29
+ /** Parent object all per-layer objects attach under (the effect root). */
30
+ parent: Object3D;
31
+ /**
32
+ * `renderOrder` for the effect's meshes; `undefined` leaves three.js's
33
+ * default. The prefab applies it to every mesh under the effect root after
34
+ * the renderer returns, so most renderers can ignore it.
35
+ */
36
+ renderOrder?: number;
37
+ /** Resolves asset paths (texture URLs etc.) found inside layer data. */
38
+ resolveUrl: (path: string) => string;
39
+ }
40
+ /**
41
+ * Per-frame update context for a single layer instance.
42
+ *
43
+ * @group Effects
44
+ */
45
+ export interface VfxLayerUpdateContext {
46
+ /**
47
+ * Layer-local time in seconds since spawn, already shifted by
48
+ * `layer.startDelay`. Negative when the layer hasn't started yet - most
49
+ * renderers should just hide themselves while `alive` is false.
50
+ */
51
+ t: number;
52
+ /** Frame delta in seconds. */
53
+ dt: number;
54
+ /** Wall-clock elapsed since spawn, ignoring `startDelay`. Useful for
55
+ * shader `uTime` uniforms that should run during the startDelay window. */
56
+ elapsed: number;
57
+ /**
58
+ * True while the layer is active - i.e. `t >= 0` AND (the effect loops OR
59
+ * `t <= layerDuration`). Renderers should hide their objects and skip
60
+ * uniform updates when this is false.
61
+ */
62
+ alive: boolean;
63
+ /** Resolved layer duration: `layer.duration > 0 ? layer.duration : effectDuration`. */
64
+ layerDuration: number;
65
+ /** Whether the parent effect loops. */
66
+ loop: boolean;
67
+ }
68
+ /**
69
+ * One runtime instance of a single layer. The prefab owns N of these.
70
+ *
71
+ * @group Effects
72
+ */
73
+ export interface VfxLayerInstance {
74
+ /** Show + activate at a position. Called on `JsonVfxInstance.spawn`. */
75
+ spawn(pos: Vec3Like): void;
76
+ /** Hide + return to dormant. Called by `JsonVfxInstance.reset` / before recycle. */
77
+ reset(): void;
78
+ /** Per-frame tick. See `VfxLayerUpdateContext` for time semantics. */
79
+ update(ctx: VfxLayerUpdateContext): void;
80
+ /** Free what the instance owns. Called on `JsonVfxInstance.dispose`. */
81
+ dispose(): void;
82
+ /** Optional: move the active instance to a new position. */
83
+ moveTo?(pos: Vec3Like): void;
84
+ /** Optional: set per-instance uniform scale. */
85
+ setScale?(s: number): void;
86
+ /** Optional: set per-instance color tint. */
87
+ setColor?(rgb: [number, number, number]): void;
88
+ }
89
+ /**
90
+ * Factory for one layer type, registered with the registry by name.
91
+ *
92
+ * @group Effects
93
+ */
94
+ export interface VfxLayerRenderer<L extends VfxLayerBase = VfxLayerBase> {
95
+ /** The discriminator string this renderer handles ('particle', 'cloud', ...). */
96
+ readonly type: string;
97
+ /** Build a runtime instance from one layer definition. */
98
+ build(layer: L, ctx: VfxLayerBuildContext): VfxLayerInstance;
99
+ }
100
+ /**
101
+ * Layer-type → renderer registry. Passed to `VfxStage` / `JsonVfxPrefab`.
102
+ *
103
+ * @group Effects
104
+ */
105
+ export declare class VfxLayerRegistry {
106
+ private readonly _renderers;
107
+ register<L extends VfxLayerBase>(renderer: VfxLayerRenderer<L>): this;
108
+ get(type: string): VfxLayerRenderer | undefined;
109
+ has(type: string): boolean;
110
+ }
111
+ /**
112
+ * Returns a registry pre-populated with the engine-default layer renderers
113
+ * (`particle`, `mesh`, `sprite`, `shader`). Consumers extend it with their
114
+ * own stylized renderers and pass the result to `VfxStage`.
115
+ *
116
+ * @group Effects
117
+ */
118
+ export declare function defaultLayerRegistry(): VfxLayerRegistry;