@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,124 @@
1
+ /**
2
+ * Mesh layer - procedural primitives (sphere / ring / spike / quad) with
3
+ * animated material params, optional fan-out instancing, and an animated
4
+ * scale/opacity/color stack driven by keyframes + sin pulses.
5
+ *
6
+ * Unlit `MeshBasicMaterial`s, so the same objects draw under WebGLRenderer
7
+ * and WebGPURenderer. The PlayCanvas build drew these with a
8
+ * StandardMaterial whose only contribution was its emissive colour; that is
9
+ * the basic material's colour here.
10
+ */
11
+ import { BufferGeometry, Mesh, MeshBasicMaterial } from 'three';
12
+ import type { Object3D } from 'three';
13
+ import type { CurvePoint, ColorCurvePoint, VfxLayerBase } from '../data-types';
14
+ import type { VfxLayerBuildContext, VfxLayerInstance, VfxLayerRenderer } from '../layer-renderer';
15
+ /** @group Effects */
16
+ export type MeshShape = 'sphere' | 'ring' | 'spike' | 'quad';
17
+ /** @group Effects */
18
+ export type InstancePattern = 'single' | 'uniform-sphere' | 'uniform-circle' | 'custom';
19
+ /**
20
+ * Fan one mesh layer out into several copies, each pointed along a direction.
21
+ *
22
+ * @group Effects
23
+ */
24
+ export interface VfxMeshInstancing {
25
+ pattern: InstancePattern;
26
+ count: number;
27
+ customDirections?: [number, number, number][];
28
+ }
29
+ /**
30
+ * `1 + amplitude * sin(elapsed * frequency * 2π + offset)`, multiplied in.
31
+ *
32
+ * @group Effects
33
+ */
34
+ export interface VfxSinPulse {
35
+ amplitude: number;
36
+ frequency: number;
37
+ offset?: number;
38
+ }
39
+ /**
40
+ * A procedural mesh primitive with keyframed scale, opacity and colour.
41
+ *
42
+ * @group Effects
43
+ */
44
+ export interface VfxMeshLayer extends VfxLayerBase {
45
+ type: 'mesh';
46
+ shape: MeshShape;
47
+ radius?: number;
48
+ innerRatio?: number;
49
+ segments?: number;
50
+ width?: number;
51
+ length?: number;
52
+ color: [number, number, number];
53
+ emissiveIntensity: number;
54
+ opacity: number;
55
+ blendMode: 'additive' | 'alpha';
56
+ depthTest: boolean;
57
+ depthWrite: boolean;
58
+ cullFace: boolean;
59
+ positionOffset: [number, number, number];
60
+ rotation: [number, number, number];
61
+ scale: number;
62
+ scaleKeys?: CurvePoint[];
63
+ opacityKeys?: CurvePoint[];
64
+ rotationSpeed?: [number, number, number];
65
+ colorKeys?: ColorCurvePoint[];
66
+ extensionKeys?: CurvePoint[];
67
+ scalePulse?: VfxSinPulse;
68
+ opacityPulse?: VfxSinPulse;
69
+ instancing?: VfxMeshInstancing;
70
+ }
71
+ /**
72
+ * Unit UV-sphere (radius 1).
73
+ *
74
+ * @group Effects
75
+ */
76
+ export declare function buildVfxSphereMesh(lat?: number, lon?: number): BufferGeometry;
77
+ /**
78
+ * Flat annular ring in the XZ plane. Outer radius 1, inner = innerRatio.
79
+ *
80
+ * @group Effects
81
+ */
82
+ export declare function buildVfxRingMesh(innerRatio?: number, segments?: number): BufferGeometry;
83
+ /**
84
+ * Diamond spike pointing along +Z in [0, 1].
85
+ *
86
+ * @group Effects
87
+ */
88
+ export declare function buildVfxSpikeMesh(): BufferGeometry;
89
+ /**
90
+ * Unit billboard quad in the XY plane, centred at the origin, size 1x1, with UVs.
91
+ *
92
+ * @group Effects
93
+ */
94
+ export declare function buildVfxQuadMesh(): BufferGeometry;
95
+ /**
96
+ * One geometry per `shape + innerRatio + segments`, shared by every effect
97
+ * that asks for it. Exported so consumers adding their own mesh-backed
98
+ * renderers can share the same buffers. The cache owns these: do not
99
+ * dispose them.
100
+ *
101
+ * @group Effects
102
+ */
103
+ export declare function getVfxMesh(shape: MeshShape, opts?: {
104
+ innerRatio?: number;
105
+ segments?: number;
106
+ }): BufferGeometry;
107
+ /**
108
+ * Renders `mesh` layers.
109
+ *
110
+ * @group Effects
111
+ */
112
+ export declare class MeshLayerRenderer implements VfxLayerRenderer<VfxMeshLayer> {
113
+ readonly type = "mesh";
114
+ build(layer: VfxMeshLayer, ctx: VfxLayerBuildContext): VfxLayerInstance;
115
+ }
116
+ /**
117
+ * Build a single trail "puff" (one mesh primitive + material). The trail is
118
+ * owned by `JsonVfxInstance`, not a layer renderer, but uses the same mesh
119
+ * cache + material construction as the mesh layer renderer.
120
+ */
121
+ export declare function buildVfxTrailMesh(parent: Object3D, shape: MeshShape, color: [number, number, number], emissiveIntensity: number, blendMode: 'additive' | 'alpha', radius: number, name: string): {
122
+ mesh: Mesh;
123
+ mat: MeshBasicMaterial;
124
+ };
@@ -0,0 +1,90 @@
1
+ /**
2
+ * Particle layer - billboard particles with the PlayCanvas build's JSON
3
+ * schema and its particle system's behaviour.
4
+ *
5
+ * The PlayCanvas build handed these layers to PlayCanvas's own
6
+ * `ParticleSystemComponent`, so the effect data was tuned against that
7
+ * emitter: its spawn timing (`rate` is seconds between spawns), its
8
+ * smoothstep-interpolated graphs sampled at 32 points, its default soft-dot
9
+ * texture and its blending. This file reproduces that emitter on the CPU -
10
+ * the numbers below follow its GPU path, which is the one that ran on WebGL2
11
+ * and WebGPU - and draws the result as one unlit mesh of camera-facing quads,
12
+ * so the same code renders under both three.js renderers.
13
+ *
14
+ * Not reproduced: `depthSoftening` (needs a scene depth texture), and
15
+ * `gravity`, which the PlayCanvas emitter never read either.
16
+ */
17
+ import { Object3D } from 'three';
18
+ import type { Vec3Like } from '../../../presets/camera/camera-preset';
19
+ import type { Scene } from '../../../scene';
20
+ import type { CurvePoint, ColorCurvePoint, VfxLayerBase } from '../data-types';
21
+ import type { VfxLayerBuildContext, VfxLayerInstance, VfxLayerRenderer, VfxLayerUpdateContext } from '../layer-renderer';
22
+ /**
23
+ * Particle emitter settings, named as PlayCanvas's particle system names them.
24
+ *
25
+ * @group Effects
26
+ */
27
+ export interface VfxParticleLayer extends VfxLayerBase {
28
+ type: 'particle';
29
+ numParticles: number;
30
+ lifetime: number;
31
+ /** Seconds between spawns (a random pick between `rate` and `rate2` per particle). */
32
+ rate: number;
33
+ rate2?: number;
34
+ emitterShape: 'box' | 'sphere';
35
+ emitterRadius?: number;
36
+ emitterExtents?: [number, number, number];
37
+ localVelocity?: [number, number, number];
38
+ localVelocity2?: [number, number, number];
39
+ velocity?: [number, number, number];
40
+ velocity2?: [number, number, number];
41
+ initialVelocity?: number;
42
+ /** Not applied: PlayCanvas's particle system has no gravity, so effect data never relied on it. */
43
+ gravity?: [number, number, number];
44
+ startAngle?: number;
45
+ startAngle2?: number;
46
+ scaleGraph?: CurvePoint[];
47
+ colorGraph?: ColorCurvePoint[];
48
+ alphaGraph?: CurvePoint[];
49
+ rotationSpeedGraph?: CurvePoint[];
50
+ radialSpeedGraph?: CurvePoint[];
51
+ radialSpeedGraph2?: CurvePoint[];
52
+ blendType: 'additive' | 'alpha';
53
+ depthWrite: boolean;
54
+ /** Not applied: soft particles need a scene depth texture. */
55
+ depthSoftening?: number;
56
+ loop: boolean;
57
+ preWarm: boolean;
58
+ stretch?: number;
59
+ alignToMotion?: boolean;
60
+ localSpace?: boolean;
61
+ positionOffset?: [number, number, number];
62
+ }
63
+ declare class ParticleLayerInstance implements VfxLayerInstance {
64
+ private readonly _scene;
65
+ private readonly _node;
66
+ private readonly _mesh;
67
+ private readonly _layer;
68
+ private readonly _emitter;
69
+ private readonly _offPreRender;
70
+ constructor(scene: Scene, node: Object3D, layer: VfxParticleLayer);
71
+ spawn(_pos: Vec3Like): void;
72
+ update(ctx: VfxLayerUpdateContext): void;
73
+ reset(): void;
74
+ dispose(): void;
75
+ /** Editor pause/resume escape hatch. Surfaced through JsonVfxInstance. */
76
+ setPaused(paused: boolean): void;
77
+ private _writeVertices;
78
+ }
79
+ /**
80
+ * Renders `particle` layers.
81
+ *
82
+ * @group Effects
83
+ */
84
+ export declare class ParticleLayerRenderer implements VfxLayerRenderer<VfxParticleLayer> {
85
+ readonly type = "particle";
86
+ build(layer: VfxParticleLayer, ctx: VfxLayerBuildContext): VfxLayerInstance;
87
+ }
88
+ /** Type guard for the prefab's editor escape hatch `setParticlesPaused`. */
89
+ export declare function isParticleLayerInstance(inst: VfxLayerInstance): inst is ParticleLayerInstance;
90
+ export {};
@@ -0,0 +1,130 @@
1
+ /**
2
+ * Generic data-driven shader layer.
3
+ *
4
+ * Unlike the other layer types, this one carries its shader code *in the
5
+ * layer JSON*. That makes it the substrate for fully data-driven VFX: a tool
6
+ * authors a fragment shader per effect and it renders without any new
7
+ * TypeScript - the program is just serialized data.
8
+ *
9
+ * The renderer supplies:
10
+ * - one of three meshes (`billboard` camera-facing quad, flat `quad`, `sphere`)
11
+ * - a default vertex stage per geometry, so most effects only need a
12
+ * fragment shader
13
+ * - standard uniforms every frame: uProgress (0..1 lifecycle), uTime
14
+ * (seconds), uDuration, uOpacity, plus any custom uniforms declared in
15
+ * `layer.uniforms`
16
+ *
17
+ * Under WebGLRenderer the layer runs `fragmentGLSL` (and `vertexGLSL`):
18
+ * GLSL ES 1.00 as the PlayCanvas build takes it (attribute / varying /
19
+ * gl_FragColor, PlayCanvas's `vertex_*` attribute and `matrix_*` uniform
20
+ * names), so shaders authored for that build run unchanged. Under
21
+ * WebGPURenderer it runs `fragmentWGSL`, a WGSL function whose parameters
22
+ * are picked by name from the same inputs; that needs the
23
+ * `@viggle/splat-engine-three/webgpu` entry point. A layer without the code
24
+ * for the renderer drawing it is skipped with a warning.
25
+ *
26
+ * The fragment output is written as-is, with no colour-space conversion -
27
+ * the PlayCanvas build's ShaderMaterial behaviour.
28
+ */
29
+ import { Mesh } from 'three';
30
+ import type { BufferGeometry, Camera, Material } from 'three';
31
+ import type { CurvePoint, VfxLayerBase } from '../data-types';
32
+ import type { VfxLayerBuildContext, VfxLayerInstance, VfxLayerRenderer } from '../layer-renderer';
33
+ /** @group Effects */
34
+ export type VfxShaderGeometry = 'billboard' | 'quad' | 'sphere';
35
+ /**
36
+ * A custom uniform: float | vec2 | vec3 | vec4.
37
+ *
38
+ * @group Effects
39
+ */
40
+ export interface VfxShaderUniform {
41
+ value: number | number[];
42
+ }
43
+ /**
44
+ * A mesh drawn with shader code carried in the layer data.
45
+ *
46
+ * @group Effects
47
+ */
48
+ export interface VfxShaderLayer extends VfxLayerBase {
49
+ type: 'shader';
50
+ /** Mesh the shader draws on. billboard = camera-facing quad. */
51
+ geometry: VfxShaderGeometry;
52
+ /** GLSL ES 1.00 fragment shader, used under WebGLRenderer. */
53
+ fragmentGLSL?: string;
54
+ /** Optional GLSL ES 1.00 vertex shader. Defaults to the per-geometry one. */
55
+ vertexGLSL?: string;
56
+ /**
57
+ * WGSL fragment function, used under WebGPURenderer. Its parameters are
58
+ * filled by name from `vUv: vec2f`, `vLocalPos`, `vWorldPos`,
59
+ * `vNormal: vec3f`, `uTime`, `uProgress`, `uDuration`, `uOpacity: f32` and
60
+ * the custom uniforms; it returns the `vec4f` colour. See
61
+ * {@link DEFAULT_SHADER_FRAGMENT_WGSL}.
62
+ */
63
+ fragmentWGSL?: string;
64
+ /** Custom uniforms, keyed by shader name (must be declared in the shader). */
65
+ uniforms?: Record<string, VfxShaderUniform>;
66
+ /** Global opacity multiplier exposed to the shader as `uOpacity`. */
67
+ opacity: number;
68
+ opacityKeys?: CurvePoint[];
69
+ scaleKeys?: CurvePoint[];
70
+ blendMode: 'additive' | 'alpha';
71
+ depthTest: boolean;
72
+ depthWrite: boolean;
73
+ /** false → double-sided, recommended for transparent FX. */
74
+ cullFace: boolean;
75
+ scale: number;
76
+ positionOffset: [number, number, number];
77
+ rotation: [number, number, number];
78
+ }
79
+ /**
80
+ * Starter fragment shader (soft additive radial glow on a billboard that fades
81
+ * out over the layer lifetime). Exported so editors/generators can seed a new
82
+ * shader layer and use it as a canonical example.
83
+ *
84
+ * @group Effects
85
+ */
86
+ export declare const DEFAULT_SHADER_FRAGMENT = "precision highp float;\nvarying vec2 vUv;\nuniform float uProgress; // 0..1 over the layer's lifetime\nuniform float uOpacity; // multiply final alpha by this\nuniform vec3 uColor; // custom uniform (see \"uniforms\" below)\nvoid main() {\n vec2 p = vUv * 2.0 - 1.0; // -1..1\n float d = length(p);\n float glow = pow(smoothstep(1.0, 0.0, d), 2.0);\n float fade = 1.0 - uProgress; // fade out as the effect ends\n float alpha = glow * fade * uOpacity;\n gl_FragColor = vec4(uColor * glow * 3.0, alpha);\n}";
87
+ /**
88
+ * {@link DEFAULT_SHADER_FRAGMENT} as the WGSL function `fragmentWGSL` takes.
89
+ *
90
+ * @group Effects
91
+ */
92
+ export declare const DEFAULT_SHADER_FRAGMENT_WGSL = "fn main(vUv: vec2f, uProgress: f32, uOpacity: f32, uColor: vec3f) -> vec4f {\n let p = vUv * 2.0 - 1.0;\n let d = length(p);\n let glow = pow(1.0 - smoothstep(0.0, 1.0, d), 2.0);\n let fade = 1.0 - uProgress;\n let alpha = glow * fade * uOpacity;\n return vec4f(uColor * glow * 3.0, alpha);\n}";
93
+ /** The mesh a shader layer draws on, from the shared cache. */
94
+ export declare function shaderLayerGeometry(geometry: VfxShaderGeometry): BufferGeometry;
95
+ /**
96
+ * Compile a shader layer's GLSL on `renderer`'s WebGL context. Returns a
97
+ * human-readable error, or null when both stages compile - and null on any
98
+ * renderer that is not a `WebGLRenderer`, where nothing is checked.
99
+ *
100
+ * @group Effects
101
+ */
102
+ export declare function validateShaderGLSL(renderer: unknown, vs: string, fs: string): string | null;
103
+ /**
104
+ * A shader layer's material and how to feed it uniforms.
105
+ * @internal
106
+ */
107
+ export interface ShaderLayerMaterial {
108
+ readonly material: Material;
109
+ /** Set a standard (`uTime`, …) or custom uniform. */
110
+ set(name: string, value: number | readonly number[]): void;
111
+ /** Per-draw camera state. */
112
+ beforeRender(renderer: unknown, mesh: Mesh, camera: Camera): void;
113
+ }
114
+ /** @internal */
115
+ export type ShaderLayerMaterialFactory = (layer: VfxShaderLayer, geometry: VfxShaderGeometry) => ShaderLayerMaterial;
116
+ /**
117
+ * Make the WGSL path available. Called by the
118
+ * `@viggle/splat-engine-three/webgpu` entry point.
119
+ * @internal
120
+ */
121
+ export declare function registerShaderLayerWebGPU(factory: ShaderLayerMaterialFactory): void;
122
+ /**
123
+ * Renders `shader` layers.
124
+ *
125
+ * @group Effects
126
+ */
127
+ export declare class ShaderLayerRenderer implements VfxLayerRenderer<VfxShaderLayer> {
128
+ readonly type = "shader";
129
+ build(layer: VfxShaderLayer, ctx: VfxLayerBuildContext): VfxLayerInstance;
130
+ }
@@ -0,0 +1,40 @@
1
+ /**
2
+ * Shared helpers used by layer renderers - curve evaluation, Euler and
3
+ * blending conventions. Both the engine's own renderers and consumer
4
+ * renderers (via the public `VfxLayerRenderer` surface) can use these.
5
+ */
6
+ import { Color, Quaternion, Vector3 } from 'three';
7
+ import type { Material } from 'three';
8
+ import type { CurvePoint, ColorCurvePoint } from '../data-types';
9
+ export declare function lerpCurve(keys: CurvePoint[] | undefined, t: number): number;
10
+ /** Writes the curve's RGB at `t` into `out`; leaves it untouched for an empty curve. */
11
+ export declare function lerpColorCurve(keys: ColorCurvePoint[] | undefined, t: number, out: {
12
+ r: number;
13
+ g: number;
14
+ b: number;
15
+ }): void;
16
+ /**
17
+ * Euler angles in degrees, in the PlayCanvas build's convention (the one its
18
+ * effect data was authored against): three.js order 'ZYX' reproduces it.
19
+ */
20
+ export declare function quatFromEulerDeg(xDeg: number, yDeg: number, zDeg: number, out: Quaternion): Quaternion;
21
+ /** Rotation whose +Z axis points along `dir`, its up as close to world +Y as it can be. */
22
+ export declare function quatFromForward(dir: Vector3, out?: Quaternion): Quaternion;
23
+ /**
24
+ * Emissive colour as the PlayCanvas build's StandardMaterial treats it:
25
+ * authored in sRGB and scaled by the intensity, so `[1, 0.5, 0] x 2` draws
26
+ * as the clamped sRGB value `[1, 1, 0]`.
27
+ */
28
+ export declare function setEmissive(out: Color, rgb: readonly number[], intensity: number): Color;
29
+ /**
30
+ * The PlayCanvas build's blend modes. Its additive is `ONE, ONE`: alpha
31
+ * (and so `opacity`) does not dim an additive layer, only its colour does.
32
+ * That is how the effect data was tuned, so it is kept.
33
+ */
34
+ export declare function applyBlend(material: Material, additive: boolean): void;
35
+ /**
36
+ * Face culling as the layer data states it. Double-sided transparent
37
+ * materials draw in one pass, as PlayCanvas does, rather than three.js's
38
+ * back-then-front two.
39
+ */
40
+ export declare function applyCull(material: Material, cullBack: boolean): void;
@@ -0,0 +1,45 @@
1
+ /**
2
+ * Sprite layer - animated spritesheet on a quad. Frames advance based on
3
+ * progress through the layer's duration; can either billboard to the camera
4
+ * or stay in world rotation.
5
+ */
6
+ import type { CurvePoint, VfxLayerBase } from '../data-types';
7
+ import type { VfxLayerBuildContext, VfxLayerInstance, VfxLayerRenderer } from '../layer-renderer';
8
+ /**
9
+ * An animated spritesheet on a quad.
10
+ *
11
+ * @group Effects
12
+ */
13
+ export interface VfxSpriteLayer extends VfxLayerBase {
14
+ type: 'sprite';
15
+ /** Path to the spritesheet image, passed through the stage's `resolveUrl`. */
16
+ spriteSheet: string;
17
+ cols: number;
18
+ rows: number;
19
+ /** Total frame count (defaults to cols * rows). */
20
+ frameCount?: number;
21
+ fps: number;
22
+ loop?: boolean;
23
+ orientation: 'billboard' | 'world';
24
+ color: [number, number, number];
25
+ emissiveIntensity: number;
26
+ opacity: number;
27
+ blendMode: 'additive' | 'alpha';
28
+ depthTest: boolean;
29
+ depthWrite: boolean;
30
+ cullFace: boolean;
31
+ positionOffset: [number, number, number];
32
+ rotation: [number, number, number];
33
+ scale: number;
34
+ opacityKeys?: CurvePoint[];
35
+ scaleKeys?: CurvePoint[];
36
+ }
37
+ /**
38
+ * Renders `sprite` layers.
39
+ *
40
+ * @group Effects
41
+ */
42
+ export declare class SpriteLayerRenderer implements VfxLayerRenderer<VfxSpriteLayer> {
43
+ readonly type = "sprite";
44
+ build(layer: VfxSpriteLayer, ctx: VfxLayerBuildContext): VfxLayerInstance;
45
+ }
@@ -0,0 +1,51 @@
1
+ import type { Object3D } from 'three';
2
+ import type { Vec3Like } from '../../presets/camera/camera-preset';
3
+ import type { Scene } from '../../scene';
4
+ import type { IVfxPrefab } from './prefab';
5
+ /**
6
+ * Per-spawn knobs forwarded to the underlying {@link IVfxInstance}.
7
+ *
8
+ * @group Effects
9
+ */
10
+ export interface VfxSpawnOptions {
11
+ /** Uniform scale multiplier applied via {@link IVfxInstance.setScale}. */
12
+ scale?: number;
13
+ /** RGB tint (0..1). Ignored if the prefab doesn't implement `setColor`. */
14
+ color?: [number, number, number];
15
+ /** Position offset added to the spawn position. */
16
+ offset?: {
17
+ x?: number;
18
+ y?: number;
19
+ z?: number;
20
+ };
21
+ /** Euler rotation (degrees) for the effect root. Ignored if the prefab
22
+ * doesn't implement `setRotation`. Use to aim directional effects (slash
23
+ * arcs, cones) at a target. */
24
+ rotation?: {
25
+ x?: number;
26
+ y?: number;
27
+ z?: number;
28
+ };
29
+ }
30
+ /**
31
+ * Generic ring-buffer pool for VFX. Contains zero VFX-specific code - the
32
+ * pool only knows how to call the {@link IVfxInstance} lifecycle. Prefab
33
+ * choice (particles, mesh flashes, etc.) is supplied at construction.
34
+ *
35
+ * @group Effects
36
+ */
37
+ export declare class VfxPool {
38
+ private readonly _entries;
39
+ private readonly _prefab;
40
+ private readonly _scratchPos;
41
+ constructor(prefab: IVfxPrefab, scene: Scene, root: Object3D, size: number);
42
+ /**
43
+ * Activate an effect at `pos`. If no free slot exists, the oldest slot
44
+ * (index 0) is force-recycled.
45
+ */
46
+ spawn(pos: Vec3Like, opts?: VfxSpawnOptions): void;
47
+ /** Advance all active effects. Call once per frame. */
48
+ update(dt: number): void;
49
+ /** Dispose all instances and the prefab's shared GPU resources. */
50
+ destroy(): void;
51
+ }
@@ -0,0 +1,48 @@
1
+ import type { Object3D } from 'three';
2
+ import type { Vec3Like } from '../../presets/camera/camera-preset';
3
+ import type { Scene } from '../../scene';
4
+ /**
5
+ * One recycled VFX instance managed by {@link VfxPool}.
6
+ *
7
+ * Lifecycle:
8
+ * - `create` (by the prefab) → objects + GPU resources allocated, kept hidden.
9
+ * - `spawn(pos)` → shown at `pos`, age timer reset.
10
+ * - `update(dt)` each frame → animate; return `true` once the effect has
11
+ * finished playing so the pool can recycle the slot.
12
+ * - `reset()` → hide and return to dormant. Called by the pool both when
13
+ * recycling a finished effect and when force-recycling the oldest slot.
14
+ * - `dispose()` → remove the objects and free what the instance owns.
15
+ *
16
+ * Positions are any `{ x, y, z }` - a `THREE.Vector3` or a plain object - in
17
+ * the space of the parent the prefab was created under (the scene's
18
+ * `contentRoot` for {@link VfxStage}, which is world space).
19
+ *
20
+ * @group Effects
21
+ */
22
+ export interface IVfxInstance {
23
+ spawn(pos: Vec3Like): void;
24
+ update(dt: number): boolean;
25
+ reset(): void;
26
+ dispose(): void;
27
+ setScale(s: number): void;
28
+ /** Optional RGB tint (0..1). Implementations may ignore. */
29
+ setColor?(rgb: [number, number, number]): void;
30
+ /** Move an active instance to a new position. Optional - implementations
31
+ * like fire-and-forget bursts may ignore. */
32
+ moveTo?(pos: Vec3Like): void;
33
+ /** Apply Euler rotation (degrees, the PlayCanvas build's convention) to
34
+ * the effect root. Optional - fire-and-forget instances that don't care
35
+ * about orientation can omit this. */
36
+ setRotation?(xDeg: number, yDeg: number, zDeg: number): void;
37
+ }
38
+ /**
39
+ * Factory for one kind of VFX instance, consumed by {@link VfxPool}.
40
+ *
41
+ * @group Effects
42
+ */
43
+ export interface IVfxPrefab {
44
+ /** Build one dormant instance under `parent`. `scene` supplies the renderer and camera. */
45
+ create(scene: Scene, parent: Object3D): IVfxInstance;
46
+ /** Release shared GPU resources (mesh, texture, …). Called once per pool. */
47
+ dispose?(): void;
48
+ }
@@ -0,0 +1,17 @@
1
+ import type { VfxDataFile } from './data-types';
2
+ import type { VfxStage } from './stage';
3
+ /**
4
+ * Compile the shaders of every effect in `dataFile` before the player can
5
+ * see one, so the first spawn during gameplay does not stall a frame while
6
+ * the renderer builds its program.
7
+ *
8
+ * Each effect is spawned once at the origin, the renderer compiles the
9
+ * scene (`compileAsync`, on WebGL and WebGPU alike), and the instances are
10
+ * taken out of the scene and kept by the stage until {@link VfxStage.destroy}: three.js frees
11
+ * a program as soon as no material uses it, so disposing them here would
12
+ * throw the compiled programs away again. Prefabs the game builds later hit
13
+ * that cache. Run it behind a loading screen.
14
+ *
15
+ * @group Effects
16
+ */
17
+ export declare function prewarmJsonVfxPrefabs(stage: VfxStage, dataFile: VfxDataFile, resolveUrl?: (path: string) => string): Promise<void>;
@@ -0,0 +1,115 @@
1
+ import type { Object3D, WebGLRenderer } from 'three';
2
+ import type { Vec3Like } from '../../presets/camera/camera-preset';
3
+ import type { Scene } from '../../scene';
4
+ import type { VfxSpawnOptions } from './pool';
5
+ import type { IVfxPrefab, IVfxInstance } from './prefab';
6
+ import { JsonVfxPrefab } from './json-vfx-prefab';
7
+ import type { VfxEffectData } from './data-types';
8
+ import type { VfxLayerRegistry } from './layer-renderer';
9
+ /**
10
+ * Optional construction extras the editor + cutscene flows need.
11
+ *
12
+ * @group Effects
13
+ */
14
+ export interface VfxStageOptions {
15
+ /**
16
+ * `renderOrder` for every effect mesh. three.js draws transparent objects
17
+ * by `renderOrder` first, then by distance, so a value above the
18
+ * characters' (0) keeps effects over them - what the PlayCanvas build got
19
+ * by drawing effects on a later layer. Omitted = three.js's default (0).
20
+ */
21
+ renderOrder?: number;
22
+ /**
23
+ * The PlayCanvas build's name for {@link renderOrder}: a layer drawn
24
+ * later. Used as the `renderOrder` when that is not set.
25
+ */
26
+ layerId?: number;
27
+ /** URL resolver for asset paths inside VfxEffectData (e.g. sprite textures).
28
+ * Identity when omitted - editor previews pass already-resolved URLs through. */
29
+ resolveUrl?: (path: string) => string;
30
+ /**
31
+ * Layer-type → renderer registry. Defaults to `defaultLayerRegistry()`
32
+ * (particle + mesh + sprite + shader). Consumers extend it with their own
33
+ * stylized renderers (cloud, shield, lightning, …) by registering them on
34
+ * a fresh registry and passing it here.
35
+ */
36
+ registry?: VfxLayerRegistry;
37
+ }
38
+ /**
39
+ * VFX render host for one scene. Effects are added under the scene's
40
+ * `contentRoot` and draw with its renderer, WebGL or WebGPU alike.
41
+ *
42
+ * Two paths for spawning effects - pick by use case:
43
+ *
44
+ * - Gameplay (fire-and-forget, pool-backed):
45
+ * stage.register('punch_hit', prefab, 8);
46
+ * stage.play('punch_hit', pos); // recycled instance, you don't keep a handle
47
+ *
48
+ * - Editor / cutscene (long-lived handle you control):
49
+ * const prefab = stage.buildPrefab(jsonData);
50
+ * const instance = stage.spawn(prefab);
51
+ * instance.spawn(pos); instance.update(dt); instance.dispose();
52
+ *
53
+ * The two paths share the IVfxPrefab/IVfxInstance contracts; only the
54
+ * lifecycle differs. Don't retain handles from `play` - the pool reserves
55
+ * the right to recycle.
56
+ *
57
+ * Particle layers face the camera in the scene's `'preRender'` step, so draw
58
+ * through the scene's own loop ({@link Scene.start}, `tick` or `render`).
59
+ *
60
+ * @example
61
+ * ```ts
62
+ * const vfx = new VfxStage(scene, { renderOrder: 1 });
63
+ * vfx.register('boom', vfx.buildPrefab(explosionJson), 8);
64
+ * scene.on('update', (dt) => vfx.update(dt));
65
+ * vfx.play('boom', { x: 0, y: 1, z: 0 }, { scale: 1.5 });
66
+ * ```
67
+ *
68
+ * @group Effects
69
+ */
70
+ export declare class VfxStage {
71
+ private readonly _scene;
72
+ private readonly _pools;
73
+ private readonly _resolveUrl?;
74
+ private readonly _renderOrder?;
75
+ private readonly _registry;
76
+ constructor(scene: Scene, opts?: VfxStageOptions);
77
+ /** The scene effects draw in. */
78
+ get scene(): Scene;
79
+ /** The renderer effects draw with. */
80
+ get renderer(): WebGLRenderer;
81
+ /** Parent of every effect this stage creates. */
82
+ get contentRoot(): Object3D;
83
+ get renderOrder(): number | undefined;
84
+ get registry(): VfxLayerRegistry;
85
+ /** Register a prefab under `name`. Allocates a pool of `poolSize` instances
86
+ * eagerly so first-spawn doesn't pay the allocation cost. Re-registering
87
+ * the same name disposes the previous pool. */
88
+ register(name: string, prefab: IVfxPrefab, poolSize?: number): void;
89
+ /** Fire one shot of a registered prefab at `pos`. Returns false if no
90
+ * prefab is registered under that name. Caller doesn't keep a handle -
91
+ * the pool reuses the slot when the effect finishes. */
92
+ play(name: string, pos: Vec3Like, opts?: VfxSpawnOptions): boolean;
93
+ /** Compile JSON layer data into a runnable prefab. Uses the stage's
94
+ * registry + resolveUrl + renderOrder defaults. The returned prefab can be
95
+ * passed to `spawn` (handle path) or `register` (pool path) interchangeably. */
96
+ buildPrefab(data: VfxEffectData): JsonVfxPrefab;
97
+ /** Create one instance you own. Returns the live handle - drive it with
98
+ * spawn(pos) / update(dt) / dispose() yourself. Bypasses the pool. */
99
+ spawn(prefab: IVfxPrefab): IVfxInstance;
100
+ /** Tick every registered pool. Drive this from your scene's update loop.
101
+ * Handle-instances (from `spawn`) are NOT ticked here - caller owns the
102
+ * update loop for those. */
103
+ update(dt: number): void;
104
+ /** Dispose every registered pool, and what {@link prewarmJsonVfxPrefabs}
105
+ * kept warm. Does NOT dispose handle-instances - caller is responsible
106
+ * for those. */
107
+ destroy(): void;
108
+ /**
109
+ * Hold hidden instances until {@link destroy}, so the shader programs they
110
+ * compiled stay cached: three.js frees a program once no material uses it.
111
+ * @internal
112
+ */
113
+ keepWarm(instances: IVfxInstance[]): void;
114
+ private readonly _warm;
115
+ }
@@ -0,0 +1,2 @@
1
+ /** @internal */
2
+ export declare function registerVfxWebGPU(): void;
@@ -0,0 +1,2 @@
1
+ /** @internal */
2
+ export declare function registerEffectsWebGPU(): void;