@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.
- package/CHANGELOG.md +58 -0
- package/README.md +158 -20
- package/dist/chunks/chunk-2GKWT24B.js +23182 -0
- package/dist/chunks/chunk-2GKWT24B.js.map +7 -0
- package/dist/index.js +235 -3
- package/dist/types/anim/animation-conversion.d.ts +2 -2
- package/dist/types/anim/keyframe-splines.d.ts +17 -41
- package/dist/types/animation.d.ts +84 -28
- package/dist/types/armature.d.ts +280 -2
- package/dist/types/character.d.ts +120 -2
- package/dist/types/effects/index.d.ts +12 -0
- package/dist/types/effects/outlines/outline-effect.d.ts +98 -0
- package/dist/types/effects/outlines/outline-shaders.d.ts +14 -0
- package/dist/types/effects/pixelart/pixelart-effect.d.ts +152 -0
- package/dist/types/effects/pixelart/pixelart-shaders.d.ts +31 -0
- package/dist/types/effects/postfx/base-capturing-pass.d.ts +109 -0
- package/dist/types/effects/postfx/camera-frame.d.ts +103 -0
- package/dist/types/effects/postfx/frame-renderer.d.ts +32 -0
- package/dist/types/effects/postfx/frame-shaders.d.ts +19 -0
- package/dist/types/effects/postfx/mask.d.ts +44 -0
- package/dist/types/effects/postfx/postfx.d.ts +144 -0
- package/dist/types/effects/postfx/program.d.ts +74 -0
- package/dist/types/effects/postfx/uniforms.d.ts +24 -0
- package/dist/types/effects/postfx/webgl-program.d.ts +6 -0
- package/dist/types/effects/postfx/webgpu-program.d.ts +3 -0
- package/dist/types/effects/vfx/data-types.d.ts +100 -0
- package/dist/types/effects/vfx/index.d.ts +37 -0
- package/dist/types/effects/vfx/json-vfx-prefab.d.ts +94 -0
- package/dist/types/effects/vfx/layer-renderer.d.ts +118 -0
- package/dist/types/effects/vfx/layers/mesh.d.ts +124 -0
- package/dist/types/effects/vfx/layers/particle.d.ts +90 -0
- package/dist/types/effects/vfx/layers/shader.d.ts +130 -0
- package/dist/types/effects/vfx/layers/shared.d.ts +40 -0
- package/dist/types/effects/vfx/layers/sprite.d.ts +45 -0
- package/dist/types/effects/vfx/pool.d.ts +51 -0
- package/dist/types/effects/vfx/prefab.d.ts +48 -0
- package/dist/types/effects/vfx/prewarm.d.ts +17 -0
- package/dist/types/effects/vfx/stage.d.ts +115 -0
- package/dist/types/effects/vfx/webgpu-register.d.ts +2 -0
- package/dist/types/effects/webgpu-register.d.ts +2 -0
- package/dist/types/engine.d.ts +18 -0
- package/dist/types/environment.d.ts +96 -8
- package/dist/types/index.d.ts +35 -6
- package/dist/types/loader/animation/animation-glb.d.ts +4 -4
- package/dist/types/loader/character/load.d.ts +6 -1
- package/dist/types/loader/environment/lod-bundle.d.ts +123 -0
- package/dist/types/loader/environment/spz-decode.d.ts +88 -0
- package/dist/types/loader/environment/spz.d.ts +28 -0
- package/dist/types/loader/shared/asset-fetch.d.ts +11 -0
- package/dist/types/loader/shared/asset-loader.d.ts +86 -0
- package/dist/types/loader/shared/bin-cache.d.ts +41 -14
- package/dist/types/loader/shared/decode-worker.d.ts +27 -0
- package/dist/types/loader/shared/glb.d.ts +30 -0
- package/dist/types/loader/shared/inflate.d.ts +9 -0
- package/dist/types/loader/shared/pack-splats-task.d.ts +17 -0
- package/dist/types/loader/shared/sog-decode.d.ts +81 -0
- package/dist/types/loader/shared/sog.d.ts +17 -0
- package/dist/types/math.d.ts +198 -13
- package/dist/types/physics/ammo.d.ts +217 -0
- package/dist/types/physics/index.d.ts +11 -0
- package/dist/types/physics/joints.d.ts +206 -0
- package/dist/types/physics/physics-world.d.ts +194 -0
- package/dist/types/physics/rigid-body.d.ts +361 -0
- package/dist/types/presets/camera/camera-preset.d.ts +43 -0
- package/dist/types/presets/camera/third-person-camera.d.ts +63 -0
- package/dist/types/presets/character/body-shape.d.ts +109 -0
- package/dist/types/presets/character/character-reveal.d.ts +90 -0
- package/dist/types/presets/character/socket-loadout.d.ts +61 -0
- package/dist/types/presets/index.d.ts +13 -0
- package/dist/types/presets/vfx/mesh-flash.d.ts +51 -0
- package/dist/types/presets/visual/bone-overlay.d.ts +57 -0
- package/dist/types/proxy/environment-input.d.ts +30 -0
- package/dist/types/proxy/environment-source.d.ts +39 -0
- package/dist/types/proxy/proxy-debug.d.ts +106 -0
- package/dist/types/proxy/splat-source.d.ts +42 -0
- package/dist/types/proxy/voxelizer.d.ts +383 -0
- package/dist/types/relight/backend.d.ts +101 -0
- package/dist/types/relight/index.d.ts +6 -0
- package/dist/types/relight/relight-pass.d.ts +367 -0
- package/dist/types/relight/relight-placeholder.d.ts +2 -0
- package/dist/types/relight/relight-shaders.d.ts +4 -0
- package/dist/types/relight/shadow-bias.d.ts +26 -0
- package/dist/types/relight/splat-relight.d.ts +760 -0
- package/dist/types/relight/webgl-backend.d.ts +3 -0
- package/dist/types/relight/webgpu/backend.d.ts +3 -0
- package/dist/types/relight/webgpu-register.d.ts +2 -0
- package/dist/types/scene.d.ts +291 -0
- package/dist/types/skeletal/animation-player.d.ts +31 -3
- package/dist/types/skeletal/body-parts.d.ts +55 -0
- package/dist/types/skeletal/ragdoll-config.d.ts +115 -0
- package/dist/types/skeletal/ragdoll.d.ts +283 -0
- package/dist/types/skeletal/skeleton.d.ts +9 -2
- package/dist/types/splat/backend.d.ts +2 -0
- package/dist/types/splat/color-modifier.d.ts +78 -0
- package/dist/types/splat/cut-groups.d.ts +27 -0
- package/dist/types/splat/relight-binding.d.ts +39 -0
- package/dist/types/splat/reveal-bake.d.ts +43 -0
- package/dist/types/splat/reveal-look.d.ts +64 -0
- package/dist/types/splat/splat-mesh.d.ts +1 -0
- package/dist/types/splat/splat.d.ts +154 -0
- package/dist/types/splat/webgl/shaders.d.ts +5 -1
- package/dist/types/splat/webgl/splat-mesh.d.ts +4 -0
- package/dist/types/splat/webgpu/radix-sort.d.ts +3 -0
- package/dist/types/splat/webgpu/splat-mesh.d.ts +23 -0
- package/dist/types/three/splat-character.d.ts +28 -0
- package/dist/types/three/spz-loader.d.ts +35 -0
- package/dist/types/types.d.ts +6 -0
- package/dist/webgpu.js +1137 -154
- package/dist/webgpu.js.map +4 -4
- package/package.json +6 -2
- package/dist/chunks/chunk-WN5WBKM4.js +0 -8606
- 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,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;
|