@viggle/splat-engine-three 0.1.1 → 0.2.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 +38 -0
  2. package/README.md +133 -20
  3. package/dist/chunks/chunk-BHNNSHJG.js +22298 -0
  4. package/dist/chunks/chunk-BHNNSHJG.js.map +7 -0
  5. package/dist/index.js +221 -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 +33 -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 +7 -0
  59. package/dist/types/physics/ammo.d.ts +210 -0
  60. package/dist/types/physics/index.d.ts +11 -0
  61. package/dist/types/physics/joints.d.ts +157 -0
  62. package/dist/types/physics/physics-world.d.ts +193 -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 +741 -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 +241 -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 +1123 -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,3 @@
1
+ import type { RelightBackend } from './backend';
2
+ /** The relight for `THREE.WebGLRenderer`. Registered by default. @internal */
3
+ export declare const webglRelightBackend: RelightBackend;
@@ -0,0 +1,3 @@
1
+ import type { RelightBackend } from '../backend';
2
+ /** The relight for `WebGPURenderer`. @internal */
3
+ export declare const webgpuRelightBackend: RelightBackend;
@@ -0,0 +1,2 @@
1
+ /** Make `SplatRelight` available under `WebGPURenderer`. @internal */
2
+ export declare function registerRelightWebGPU(): void;
@@ -0,0 +1,241 @@
1
+ import { AmbientLight, PerspectiveCamera, Scene as ThreeScene, WebGLRenderer } from 'three';
2
+ import { CameraFrame } from './effects/postfx/camera-frame';
3
+ import { PostFX } from './effects/postfx/postfx';
4
+ import { EngineDisposedError, SplatEngine } from './engine';
5
+ import { PhysicsWorld } from './physics/physics-world';
6
+ /**
7
+ * Graphics backend preference for {@link CreateSceneOptions.backend}.
8
+ *
9
+ * @group Scene
10
+ */
11
+ export type RenderBackend = 'webgl' | 'webgpu';
12
+ /**
13
+ * Options for {@link Scene.create}. Named and defaulted as in the PlayCanvas
14
+ * build's `Scene.create`, so a game's options carry over.
15
+ *
16
+ * @group Scene
17
+ */
18
+ export interface CreateSceneOptions {
19
+ /** Clear colour as normalized floats (0–1). Default `{r: 0.08, g: 0.08, b: 0.12, a: 1}`. An `a` below 1 makes the canvas see-through. */
20
+ bgColor?: {
21
+ r: number;
22
+ g: number;
23
+ b: number;
24
+ a: number;
25
+ };
26
+ /** Keep the drawing buffer after compositing, so the canvas can be read back. Default `false`. */
27
+ preserveDrawingBuffer?: boolean;
28
+ /** MSAA on the canvas. Default `false`. */
29
+ antialias?: boolean;
30
+ /**
31
+ * `'webgpu'` uses `WebGPURenderer`, and needs the
32
+ * `@viggle/splat-engine-three/webgpu` entry point to have been imported; a
33
+ * device without WebGPU falls back to WebGL. Default `'webgl'`.
34
+ */
35
+ backend?: RenderBackend;
36
+ /** Initial camera world position. Default `{x: 0, y: 1, z: 5}`. */
37
+ cameraPosition?: {
38
+ x: number;
39
+ y: number;
40
+ z: number;
41
+ };
42
+ /** Initial camera look-at target. Default `{x: 0, y: 0.5, z: 0}`. */
43
+ cameraTarget?: {
44
+ x: number;
45
+ y: number;
46
+ z: number;
47
+ };
48
+ /** Vertical field of view in degrees. Default `60`. */
49
+ fov?: number;
50
+ /** Near clip plane. Default `0.1`. */
51
+ near?: number;
52
+ /** Far clip plane. Default `100`. */
53
+ far?: number;
54
+ /** Ambient light for meshes (splats ignore it), 0–1. Default `0.55`. */
55
+ ambientLight?: number;
56
+ /** Tone-mapping exposure. Default `1`. */
57
+ exposure?: number;
58
+ /**
59
+ * Ammo-backed physics: rigid bodies on {@link Scene.physics}, and the
60
+ * engine's `Ragdoll`. The engine does not ship Ammo. Pass `true` when
61
+ * `globalThis.Ammo` is already set, or `{ loadAmmo }` to have the engine
62
+ * await your loader first. Default `false`.
63
+ */
64
+ physics?: boolean | {
65
+ loadAmmo: () => Promise<void>;
66
+ };
67
+ /**
68
+ * Cap on frames per second: frames that arrive sooner are skipped whole,
69
+ * update and render alike. Default: the display's own rate.
70
+ */
71
+ maxFps?: number;
72
+ /** Cap on the device pixel ratio of the drawing buffer. Default `1`. */
73
+ maxPixelRatio?: number;
74
+ /** GPU power preference. Default `'high-performance'`. */
75
+ powerPreference?: 'default' | 'high-performance' | 'low-power';
76
+ /**
77
+ * Discard splats smaller than this many pixels on screen, on every splat
78
+ * loaded into the scene. `true` is 2 px. Default off.
79
+ */
80
+ subPixelCull?: boolean | number;
81
+ /**
82
+ * {@link SplatEngine.legacyRootRotation} for this scene. Default `false`:
83
+ * GLB clips keep their root rotation, as in the PlayCanvas build 0.3.2.
84
+ */
85
+ legacyRootRotation?: boolean;
86
+ /** Kept for PlayCanvas parity; three.js always has a depth buffer. */
87
+ depth?: boolean;
88
+ /** Kept for PlayCanvas parity; the skeleton library always loads. */
89
+ loadSkeleton?: boolean;
90
+ }
91
+ /** Events {@link Scene.on} accepts. */
92
+ export type SceneEvent = 'update' | 'postUpdate' | 'preRender' | 'postRender';
93
+ type WebGPURendererFactory = (canvas: HTMLCanvasElement, opts: CreateSceneOptions) => Promise<unknown | null>;
94
+ /**
95
+ * Make `backend: 'webgpu'` available to {@link Scene.create}. Called by the
96
+ * `@viggle/splat-engine-three/webgpu` entry point.
97
+ * @internal
98
+ */
99
+ export declare function registerWebGPURendererFactory(factory: WebGPURendererFactory): void;
100
+ /**
101
+ * Everything a game needs to draw splats, in one object: a renderer on your
102
+ * canvas, a three.js scene and camera, the render loop, resizing, and the
103
+ * engine state ({@link SplatEngine}) characters and clips load into.
104
+ *
105
+ * The three.js counterpart of the PlayCanvas build's `Scene`. It IS a
106
+ * `SplatEngine`, so `Character.load(scene, …)` and
107
+ * `Animation.loadGlb(scene, …)` work as they do there. Where that build
108
+ * exposes PlayCanvas objects, this one exposes three.js ones:
109
+ *
110
+ * | PlayCanvas build | here |
111
+ * |-------------------------------|-------------------------------|
112
+ * | `scene.app` | {@link renderer}, {@link threeScene} |
113
+ * | `scene.cameraEntity` | {@link camera} |
114
+ * | `scene.graphicsDevice.setResolution(w, h)` | {@link setResolution} |
115
+ * | `scene.app.on('update', fn)` | {@link on}`('update', fn)` |
116
+ * | `entity.addComponent('rigidbody' / 'collision', …)` | {@link physics}`.addBody(object, { shape, … })` |
117
+ * | `entity.rigidbody` | {@link physics}`.getBody(object)` |
118
+ * | `app.systems.rigidbody.raycastFirst / gravity / dynamicsWorld` | {@link physics}`.raycastFirst / gravity / dynamicsWorld` |
119
+ *
120
+ * Applications that already own a renderer and a loop keep using
121
+ * {@link SplatEngine} directly; nothing here is required.
122
+ *
123
+ * ```ts
124
+ * const scene = await Scene.create(canvas, { fov: 70, bgColor: { r: 0.05, g: 0.06, b: 0.08, a: 1 } });
125
+ * const hero = await Character.load(scene, '/assets/hero.vsplat');
126
+ * await Animation.loadGlb(scene, '/assets/idle.glb', 'idle');
127
+ * hero.playAnimation('idle', { loop: true });
128
+ * scene.on('update', (dt) => { … });
129
+ * scene.start();
130
+ * ```
131
+ *
132
+ * @group Scene
133
+ */
134
+ export declare class Scene extends SplatEngine {
135
+ /** The canvas the renderer draws into. */
136
+ readonly canvas: HTMLCanvasElement;
137
+ /**
138
+ * The three.js renderer: a `THREE.WebGLRenderer`, or a `WebGPURenderer`
139
+ * when {@link backendName} is `'webgpu'`.
140
+ */
141
+ readonly renderer: WebGLRenderer;
142
+ /** Which backend {@link renderer} runs on. */
143
+ readonly backendName: RenderBackend;
144
+ /** The three.js scene everything is drawn from. {@link contentRoot} is in it. */
145
+ readonly threeScene: ThreeScene;
146
+ /** The scene camera. */
147
+ camera: PerspectiveCamera;
148
+ /** Ambient light for meshes added to {@link threeScene}. Splats are not lit by it. */
149
+ readonly ambientLight: AmbientLight;
150
+ /** The post-processing chain. Empty until an effect is added. */
151
+ readonly postfx: PostFX;
152
+ /** Rigid-body physics, when the scene was created with {@link CreateSceneOptions.physics}. */
153
+ readonly physics: PhysicsWorld | null;
154
+ /** True when the scene was created with a see-through background (`bgColor.a < 1`). */
155
+ readonly transparent: boolean;
156
+ /** Frames per second cap; `0` for none. Read every frame. */
157
+ maxFps: number;
158
+ private readonly _listeners;
159
+ private _running;
160
+ private _suspended;
161
+ private _lastTime;
162
+ private _lastFrameTime;
163
+ private _maxPixelRatio;
164
+ private _explicitSize;
165
+ private readonly _resizeObserver;
166
+ private readonly _clearDisplay;
167
+ private readonly _clearLinear;
168
+ private readonly _clearAlpha;
169
+ /** @internal Use {@link Scene.create}. */
170
+ constructor(canvas: HTMLCanvasElement, renderer: WebGLRenderer, backendName: RenderBackend, physics: PhysicsWorld | null, opts: CreateSceneOptions);
171
+ /**
172
+ * Create a renderer on `canvas` and return a ready scene. Call
173
+ * {@link start} to begin rendering.
174
+ */
175
+ static create(canvas: HTMLCanvasElement, opts?: CreateSceneOptions): Promise<Scene>;
176
+ private static _createWithPhysics;
177
+ /** Cap on the drawing buffer's device pixel ratio. */
178
+ get maxPixelRatio(): number;
179
+ set maxPixelRatio(ratio: number);
180
+ /** Drawing-buffer width in pixels. */
181
+ get width(): number;
182
+ /** Drawing-buffer height in pixels. */
183
+ get height(): number;
184
+ /**
185
+ * Set the drawing buffer to exactly `width` x `height` pixels, whatever the
186
+ * canvas's CSS size and the pixel ratio. Holds until {@link maxPixelRatio}
187
+ * is set again.
188
+ */
189
+ setResolution(width: number, height: number): void;
190
+ private _fitToCanvas;
191
+ private _applySize;
192
+ /**
193
+ * Run `fn` every frame. `'update'` runs after physics and the characters
194
+ * have advanced, `'postUpdate'` after every `'update'` listener,
195
+ * `'preRender'` / `'postRender'` around the draw. `dt` is in seconds.
196
+ * @returns A function that removes the listener.
197
+ */
198
+ on(event: SceneEvent, fn: (dt: number) => void): () => void;
199
+ /** Remove a listener added with {@link on}. */
200
+ off(event: SceneEvent, fn: (dt: number) => void): void;
201
+ /** Start the render loop. */
202
+ start(): void;
203
+ /** Stop the render loop. {@link start} resumes it. */
204
+ stop(): void;
205
+ /** Pause rendering while updates keep ticking; resuming draws again. */
206
+ setSuspended(suspended: boolean): void;
207
+ private _loop;
208
+ /**
209
+ * Advance and draw one frame by hand: physics, characters, the `'update'`
210
+ * listeners, then the render. The loop {@link start} runs calls this.
211
+ */
212
+ tick(dt: number): void;
213
+ /** Draw one frame with the current state, through the post-processing chain. */
214
+ render(dt?: number): void;
215
+ /**
216
+ * Switch the renderer's clear colour between the background as display
217
+ * colour (drawing to the canvas) and as a linear value (drawing into a
218
+ * {@link CameraFrame}'s target). @internal
219
+ */
220
+ useLinearClearColor(linear: boolean): void;
221
+ /** The camera's built-in tone mapping, bloom, grading and vignette, created on first call. */
222
+ getOrCreateCameraFrame(): CameraFrame;
223
+ /** The {@link CameraFrame}, or `null` before {@link getOrCreateCameraFrame}. */
224
+ get cameraFrame(): CameraFrame | null;
225
+ /** Drop the {@link CameraFrame} and its effects. */
226
+ destroyCameraFrame(): void;
227
+ /**
228
+ * Stop the loop, release the renderer and its context, and stop observing
229
+ * the canvas. Characters and environments are not destroyed for you.
230
+ */
231
+ destroy(): void;
232
+ }
233
+ /**
234
+ * Thrown when an asset finishes loading onto a scene that has already been
235
+ * destroyed. The same class as {@link EngineDisposedError}, under the
236
+ * PlayCanvas build's name.
237
+ *
238
+ * @group Scene
239
+ */
240
+ export declare const SceneDestroyedError: typeof EngineDisposedError;
241
+ export {};
@@ -1,5 +1,5 @@
1
1
  import type { Animation, AnimationEvent } from '../animation';
2
- import type { Pose } from './pose';
2
+ import { Pose } from './pose';
3
3
  import type { Skeleton } from './skeleton';
4
4
  /**
5
5
  * Resolves an animation by name and returns an already-filtered/converted
@@ -28,6 +28,10 @@ export interface CrossfadeOptions {
28
28
  * frame 0.
29
29
  */
30
30
  preserveTime?: boolean;
31
+ /** Keep the outgoing clip moving during the blend. Interrupted blends use the visible pose. */
32
+ continueSource?: boolean;
33
+ /** Ease the blend weight at both ends. Default is linear for existing callers. */
34
+ easing?: 'linear' | 'smoothstep';
31
35
  }
32
36
  /**
33
37
  * Callback fired when {@link AnimationPlayer.tick} crosses a frame that has
@@ -77,21 +81,31 @@ export declare class AnimationPlayer {
77
81
  private _crossfadeTime;
78
82
  private _crossfadeDuration;
79
83
  private readonly _snapshot;
84
+ private _outgoing;
85
+ private _easing;
86
+ private readonly _evalResult;
80
87
  private _lastTickFrame;
81
88
  private readonly _eventListeners;
82
89
  private readonly _tmpPos;
83
90
  private readonly _tmpRot;
84
91
  private readonly _tmpScale;
85
92
  private readonly _tmpSlerpRot;
93
+ private readonly _tmpKeyRot;
86
94
  private readonly _tmpToRot;
87
95
  private readonly _restIn;
88
96
  private readonly _restOut;
89
97
  private readonly _splineValues;
98
+ private _bones;
90
99
  constructor(opts: {
91
100
  skeleton: Skeleton;
92
101
  animationProvider: AnimationProvider;
93
102
  snapshotPose: Pose;
94
103
  });
104
+ /**
105
+ * The bones {@link evaluate} writes, or `null` (the default) for all. Clips
106
+ * convert keyframes for these bones only; the rest keep their last pose.
107
+ */
108
+ set bones(v: Int32Array | null);
95
109
  get isPlaying(): boolean;
96
110
  get isFinished(): boolean;
97
111
  get paused(): boolean;
@@ -135,6 +149,19 @@ export declare class AnimationPlayer {
135
149
  * mutating `currentPose` after the call returns.
136
150
  */
137
151
  crossfadeTo(name: string, currentPose: Pose, opts?: CrossfadeOptions): boolean;
152
+ /**
153
+ * Evaluate the active animation at an explicit `frameTime` into `outPose`,
154
+ * with no crossfade blending, and leave every scrap of playback state exactly
155
+ * as it was - current time, crossfade window, loop flag, event cursor.
156
+ *
157
+ * This is the read-only probe a caller needs to sweep a clip for precompute
158
+ * (foot heights, root paths, a loop-start pose) while it keeps playing.
159
+ * {@link AnimationPlayer.evaluate} cannot serve: it reads the live time and
160
+ * folds in whatever blend is in flight.
161
+ *
162
+ * Returns `false` when nothing is active or keyframes are not ready.
163
+ */
164
+ evaluateAt(frameTime: number, outPose: Pose): boolean;
138
165
  /**
139
166
  * Snap any active crossfade to its terminal state (alpha = 1, target pose
140
167
  * fully applied) on the next {@link AnimationPlayer.evaluate}. No-op if no
@@ -167,11 +194,12 @@ export declare class AnimationPlayer {
167
194
  *
168
195
  * Returns `blendToRestComplete: true` once on the tick a previously-
169
196
  * scheduled `stop(_, fade > 0)` reaches alpha 1 - the facade uses that to
170
- * snap pose to bind and reset rootMotion baseline.
197
+ * snap pose to bind and reset rootMotion baseline. The result object is
198
+ * reused by the next call; read it before evaluating again.
171
199
  *
172
200
  * Skip this call when the character is off-screen; `tick` keeps time
173
201
  * advancing in the meantime, so the next on-screen frame evaluates straight
174
- * to the correct pose with no visible pop.
202
+ * to the correct pose with no visible pop. Only {@link bones} are written.
175
203
  */
176
204
  evaluate(outPose: Pose): {
177
205
  blendToRestComplete: boolean;
@@ -0,0 +1,55 @@
1
+ /**
2
+ * Coarse body-part segmentation used by the damage / variant system.
3
+ *
4
+ * Each bone in the skeleton is classified into one of {@link BodyPart}.
5
+ * A {@link Splat} stores the dominant-bone group per gaussian; at runtime
6
+ * the variant-mask uniform decides per-group whether to render the splat
7
+ * from the "normal" cloud or the "damaged" cloud. The `DamageVariant`
8
+ * preset (`presets/character/damage-variant.ts`) is the system built on
9
+ * this: `DamageVariant.create` / `setBodyPartDamaged`.
10
+ *
11
+ * The enum values are stable group IDs used directly as texture coords on
12
+ * the variant-mask texture - do not renumber without updating shaders.
13
+ *
14
+ * @group Characters & Animation
15
+ */
16
+ export declare const BodyPart: {
17
+ readonly Torso: 0;
18
+ readonly Head: 1;
19
+ readonly LeftUpperArm: 2;
20
+ readonly LeftLowerArm: 3;
21
+ readonly LeftHand: 4;
22
+ readonly RightUpperArm: 5;
23
+ readonly RightLowerArm: 6;
24
+ readonly RightHand: 7;
25
+ readonly LeftUpperLeg: 8;
26
+ readonly LeftLowerLeg: 9;
27
+ readonly LeftFoot: 10;
28
+ readonly RightUpperLeg: 11;
29
+ readonly RightLowerLeg: 12;
30
+ readonly RightFoot: 13;
31
+ };
32
+ /** One of the {@link BodyPart} group IDs. */
33
+ export type BodyPart = (typeof BodyPart)[keyof typeof BodyPart];
34
+ /** Width of the per-character variant-mask texture (= max group ID + 1). */
35
+ export declare const NUM_BODY_PARTS = 14;
36
+ /**
37
+ * Classify a single bone name into a {@link BodyPart}. Pattern-based so it
38
+ * tolerates both the 86-bone std-male rig (clavicle_l, upperarm_l, ...) and
39
+ * the 441-bone rig (FACIAL_* in addition).
40
+ *
41
+ * Returns {@link BodyPart.Torso} for anything we can't confidently bucket
42
+ * (root, unknown auxiliary bones) - Torso is the safest fallback because the
43
+ * spine controls the largest contiguous splat region.
44
+ */
45
+ export declare function classifyBone(boneName: string): BodyPart;
46
+ /**
47
+ * Build a Uint8Array of length `boneNames.length` where entry `i` is the
48
+ * group ID for bone `i`. Cheap (single pass, regex-based) - call once per
49
+ * armature/splat-asset combination.
50
+ */
51
+ export declare function buildBoneToGroup(boneNames: readonly string[]): Uint8Array;
52
+ /** Human-readable label for a body part (debug overlays, UI). */
53
+ export declare function bodyPartLabel(p: BodyPart): string;
54
+ /** Iteration helper - all defined body parts in stable order. */
55
+ export declare const ALL_BODY_PARTS: readonly BodyPart[];
@@ -0,0 +1,115 @@
1
+ /**
2
+ * Describes how a humanoid (or other) rig becomes a set of physics
3
+ * bodies for ragdoll. Keyed by bone name.
4
+ *
5
+ * ## Assumed conventions
6
+ *
7
+ * The Ragdoll places each capsule body so that the body's local +Y
8
+ * axis points along the bone's bind-pose direction (i.e. toward
9
+ * `endBoneName`'s bind position). Authoring the config correctly
10
+ * therefore requires that the rig's bone hierarchy and bind pose be
11
+ * known - name lookup is done by string match against
12
+ * `Armature.boneNames`, which is supplied by `Scene.skeletonLibrary`.
13
+ *
14
+ * For UE-style humanoids (`pelvis`, `spine_NN`, `neck_NN`, `head`,
15
+ * `clavicle_l/r`, `upperarm_l/r`, `lowerarm_l/r`, `hand_l/r`,
16
+ * `thigh_l/r`, `calf_l/r`, `foot_l/r`) the bundled
17
+ * {@link DEFAULT_HUMANOID_RAGDOLL} works without modification. Other
18
+ * rigs (Maya joint orientation, custom skeletons, props) can supply a
19
+ * custom config; only the bone names need to differ.
20
+ *
21
+ * @group Ragdoll
22
+ */
23
+ export interface RagdollConfig {
24
+ bones: RagdollBoneDesc[];
25
+ }
26
+ /**
27
+ * One physics body in the ragdoll graph. Each body is a capsule attached to
28
+ * a bone; its axis points from the bone's bind-pose origin toward the
29
+ * bind-pose position of `endBoneName` (so its length is implicit in the
30
+ * rig). Terminal bodies (head, hand, foot) without a useful end bone in
31
+ * the config specify `length` directly.
32
+ *
33
+ * @group Ragdoll
34
+ */
35
+ export interface RagdollBoneDesc {
36
+ /** Bone the body is attached to. */
37
+ boneName: string;
38
+ /**
39
+ * Bone whose bind-pose position defines the capsule's distal end.
40
+ * Capsule length = ‖bindPos(endBoneName) − bindPos(boneName)‖.
41
+ * Omit and set {@link length} for terminal bodies (head, hand, foot)
42
+ * whose child bones don't represent the body's tip.
43
+ */
44
+ endBoneName?: string;
45
+ /** Capsule length override when {@link endBoneName} is absent. Meters. */
46
+ length?: number;
47
+ /** Capsule radius. Meters. */
48
+ radius: number;
49
+ /** Body mass. */
50
+ mass: number;
51
+ /** Parent body's `boneName`. `null` for the root body (pelvis). */
52
+ parent: string | null;
53
+ /**
54
+ * Joint to the parent body. `null` for the root body. The joint anchors
55
+ * sit at the proximal end of the child capsule (where the bone starts)
56
+ * and at the corresponding point on the parent body.
57
+ */
58
+ joint?: RagdollJointDesc | null;
59
+ }
60
+ /**
61
+ * Joint between a body and its parent. `coneTwist` is the right choice for
62
+ * shoulders, hips, neck, and the spine; `hinge` is for elbows and knees.
63
+ *
64
+ * @group Ragdoll
65
+ */
66
+ /**
67
+ * Shared fields across joint variants.
68
+ *
69
+ * @group Ragdoll
70
+ */
71
+ interface RagdollJointCommon {
72
+ /**
73
+ * When set, the joint detaches if its applied impulse in a single
74
+ * physics step exceeds this value (N·s). Triggers
75
+ * {@link Ragdoll.onLimbDetached} for the child bone and severs the
76
+ * skeletal subtree. Omit for an unbreakable joint.
77
+ *
78
+ * Tuning is rig-specific - start around 8–15 N·s for shoulders /
79
+ * hips on a humanoid; lower values detach more easily.
80
+ */
81
+ breakImpulse?: number;
82
+ }
83
+ export type RagdollJointDesc = (RagdollJointCommon & {
84
+ type: 'coneTwist';
85
+ /** Cone half-angle, radians. Default π/4. */
86
+ swingY?: number;
87
+ /** Cone half-angle, radians. Default π/4. */
88
+ swingZ?: number;
89
+ /** Twist half-angle, radians. Default π/6. */
90
+ twist?: number;
91
+ }) | (RagdollJointCommon & {
92
+ type: 'hinge';
93
+ /** Hinge axis in the child body's local space. `'x' | 'y' | 'z'`. */
94
+ axis: 'x' | 'y' | 'z';
95
+ /** Lower limit, radians. */
96
+ low: number;
97
+ /** Upper limit, radians. */
98
+ high: number;
99
+ });
100
+ /**
101
+ * A sensible default humanoid ragdoll for rigs that use the standard
102
+ * UE-style bone naming (`pelvis`, `spine_NN`, `neck_NN`, `head`,
103
+ * `clavicle_l/r`, `upperarm_l/r`, `lowerarm_l/r`, `hand_l/r`,
104
+ * `thigh_l/r`, `calf_l/r`, `foot_l/r`). Collapses the spine to a single
105
+ * torso body, ignores fingers, toes, and twist bones - 14 bodies total,
106
+ * enough for recognizable ragdoll motion without the cost of a per-bone
107
+ * body.
108
+ *
109
+ * Override per-character by passing a custom {@link RagdollConfig} to
110
+ * the {@link Ragdoll} constructor.
111
+ *
112
+ * @group Ragdoll
113
+ */
114
+ export declare const DEFAULT_HUMANOID_RAGDOLL: RagdollConfig;
115
+ export {};