@viggle/splat-engine-three 0.2.0 → 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/dist/index.js CHANGED
@@ -45,6 +45,7 @@ import {
45
45
  JsonVfxInstance,
46
46
  JsonVfxPrefab,
47
47
  LOWER_BODY_BONE_NAMES,
48
+ Mat4,
48
49
  MeshFlash,
49
50
  MeshLayerRenderer,
50
51
  NUM_BODY_PARTS,
@@ -55,6 +56,7 @@ import {
55
56
  PointLight,
56
57
  Pose,
57
58
  PostFX,
59
+ Quat,
58
60
  Ragdoll,
59
61
  RigidBody,
60
62
  Scene,
@@ -82,6 +84,7 @@ import {
82
84
  ThirdPersonCamera,
83
85
  UPPER_BODY_BONE_NAMES,
84
86
  VSplatLoader,
87
+ Vec3,
85
88
  VfxLayerRegistry,
86
89
  VfxPool,
87
90
  VfxStage,
@@ -90,6 +93,7 @@ import {
90
93
  bodyPartLabel,
91
94
  buildBoneToGroup,
92
95
  buildProxyMesh,
96
+ buildSourceBoneRemap,
93
97
  buildStretch,
94
98
  buildVfxQuadMesh,
95
99
  buildVfxRingMesh,
@@ -103,11 +107,13 @@ import {
103
107
  createConeTwistJoint,
104
108
  createGeneric6DofJoint,
105
109
  createHingeJoint,
110
+ createPointToPointJoint,
106
111
  decodeCharacterBundle,
107
112
  decodeSplatFile,
108
113
  decodeSpz,
109
114
  defaultLayerRegistry,
110
115
  defaultProxySettings,
116
+ evictExpired,
111
117
  extractSurface,
112
118
  getVfxMesh,
113
119
  indexAssetCache,
@@ -130,10 +136,11 @@ import {
130
136
  setAssetFetch,
131
137
  setBinFetch,
132
138
  setGlbLoader,
139
+ setPlayCanvasLightColor,
133
140
  setShareSplatResources,
134
141
  uninstallFetchInterceptor,
135
142
  validateShaderGLSL
136
- } from "./chunks/chunk-BHNNSHJG.js";
143
+ } from "./chunks/chunk-2GKWT24B.js";
137
144
  export {
138
145
  ALL_BODY_PARTS,
139
146
  Animation,
@@ -181,6 +188,7 @@ export {
181
188
  JsonVfxInstance,
182
189
  JsonVfxPrefab,
183
190
  LOWER_BODY_BONE_NAMES,
191
+ Mat4,
184
192
  MeshFlash,
185
193
  MeshLayerRenderer,
186
194
  NUM_BODY_PARTS,
@@ -191,6 +199,7 @@ export {
191
199
  PointLight,
192
200
  Pose,
193
201
  PostFX,
202
+ Quat,
194
203
  Ragdoll,
195
204
  RigidBody,
196
205
  Scene,
@@ -219,6 +228,7 @@ export {
219
228
  ThirdPersonCamera,
220
229
  UPPER_BODY_BONE_NAMES,
221
230
  VSplatLoader,
231
+ Vec3,
222
232
  VfxLayerRegistry,
223
233
  VfxPool,
224
234
  VfxStage,
@@ -227,6 +237,7 @@ export {
227
237
  bodyPartLabel,
228
238
  buildBoneToGroup,
229
239
  buildProxyMesh,
240
+ buildSourceBoneRemap,
230
241
  buildStretch,
231
242
  buildVfxQuadMesh,
232
243
  buildVfxRingMesh,
@@ -240,11 +251,13 @@ export {
240
251
  createConeTwistJoint,
241
252
  createGeneric6DofJoint,
242
253
  createHingeJoint,
254
+ createPointToPointJoint,
243
255
  decodeCharacterBundle,
244
256
  decodeSplatFile,
245
257
  decodeSpz,
246
258
  defaultLayerRegistry,
247
259
  defaultProxySettings,
260
+ evictExpired,
248
261
  extractSurface,
249
262
  getVfxMesh,
250
263
  indexAssetCache,
@@ -267,6 +280,7 @@ export {
267
280
  setAssetFetch,
268
281
  setBinFetch,
269
282
  setGlbLoader,
283
+ setPlayCanvasLightColor,
270
284
  setShareSplatResources,
271
285
  uninstallFetchInterceptor,
272
286
  validateShaderGLSL
@@ -5,7 +5,7 @@ export { Animation as SplatClip } from './animation';
5
5
  export { SplatEngine, EngineDisposedError } from './engine';
6
6
  export type { SceneLighting, SplatEngineOptions } from './engine';
7
7
  export { Scene, SceneDestroyedError } from './scene';
8
- export type { CreateSceneOptions, RenderBackend, SceneEvent } from './scene';
8
+ export type { CreateSceneOptions, RenderBackend, SceneEvent, SceneUpdateOrder } from './scene';
9
9
  export * from './effects';
10
10
  export * from './physics';
11
11
  export { Character } from './character';
@@ -15,6 +15,7 @@ export type { AnimationEvent, AnimationLoadOptions } from './animation';
15
15
  export { Armature } from './armature';
16
16
  export type { AnimLodPreset, PoseModifier, PoseProvider, RootMotionMode, RootOffsetProvider } from './armature';
17
17
  export { Pose } from './skeletal/pose';
18
+ export { Mat4, Quat, Vec3 } from './math';
18
19
  export { Environment } from './environment';
19
20
  export type { LoadEnvironmentOptions, LoadLodBundleOptions } from './environment';
20
21
  export { SplatSPZLoader } from './three/spz-loader';
@@ -46,7 +47,8 @@ export type { AnimEventCallback, CrossfadeOptions } from './skeletal/animation-p
46
47
  export { computeBoneStretch } from './skeletal/bone-stretch';
47
48
  export type { BoneScale, BoneScaleInput, BoneStretch } from './skeletal/bone-stretch';
48
49
  export { decodeCharacterBundle, loadCharacterBundle, loadCharacterBundleFromBytes } from './loader/character/load';
49
- export { cachedFetch, indexAssetCache, installFetchInterceptor, isCached, setBinFetch, uninstallFetchInterceptor, } from './loader/shared/bin-cache';
50
+ export { cachedFetch, evictExpired, indexAssetCache, installFetchInterceptor, isCached, setBinFetch, uninstallFetchInterceptor, } from './loader/shared/bin-cache';
51
+ export { buildSourceBoneRemap } from './splat/bone-binding';
50
52
  export { setAssetFetch } from './loader/shared/asset-fetch';
51
53
  export type { AssetFetch } from './loader/shared/asset-fetch';
52
54
  export type { CharacterBundle } from './loader/character/load';
@@ -60,7 +62,7 @@ export * from './presets';
60
62
  export { BodyPart, NUM_BODY_PARTS, ALL_BODY_PARTS, bodyPartLabel, classifyBone, buildBoneToGroup } from './skeletal/body-parts';
61
63
  export { loadGlbFromUrl, setGlbLoader } from './loader/shared/glb';
62
64
  export type { GlbCallback } from './loader/shared/glb';
63
- export { ENVIRONMENT_DEFAULT_LOD, ENVIRONMENT_PROXY_DEFAULTS, SplatRelight } from './relight/splat-relight';
65
+ export { ENVIRONMENT_DEFAULT_LOD, ENVIRONMENT_PROXY_DEFAULTS, SplatRelight, setPlayCanvasLightColor } from './relight/splat-relight';
64
66
  export type { RelightLightOptions, RelightPointLightOptions, RelightPreviewMode, RelightProxySettings, RelightProxySource, RelightTarget, RelightTargetOptions, RelightTargetParams, SplatRelightOptions, } from './relight/splat-relight';
65
67
  export type { EnvironmentRefreshMode } from './relight/relight-pass';
66
68
  export { alphaFromLogits, buildProxyMesh, buildVoxelGrid, defaultProxySettings, extractSurface } from './proxy/voxelizer';
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Internal math kernel for the skeletal core.
2
+ * The math kernel of the skeletal core: PlayCanvas's `Vec3` / `Quat` / `Mat4`.
3
3
  *
4
4
  * The rig, animation and skinning code is shared with the PlayCanvas build of
5
5
  * this engine and was written against that engine's `Vec3` / `Quat` / `Mat4`.
@@ -9,17 +9,31 @@
9
9
  *
10
10
  * Deliberately NOT `THREE.Vector3` and friends: the conventions differ in ways
11
11
  * that silently change results (`lerp(a, b, t)` vs `lerp(v, t)`, a two-argument
12
- * `cross`, a `Float32Array`-backed matrix), and a port that swapped them by
13
- * hand would be a port nobody could diff against the original.
12
+ * `cross`, a `Float32Array`-backed matrix, angles in degrees), and a port that
13
+ * swapped them by hand would be a port nobody could diff against the original.
14
14
  *
15
- * Nothing here is part of the public API. Values cross into three.js types at
16
- * the `Character` / `Armature` boundary.
15
+ * Exported because `Pose`, `Armature.getBoneWorldMatrix` and the rest of the
16
+ * rig hand these out, and game code ported from the PlayCanvas build calls
17
+ * PlayCanvas methods on them. Each class carries the whole of PlayCanvas
18
+ * 2.23's API for that class (`Vec4` arguments take any `{x, y, z, w}`), with
19
+ * its formulas, so such code can import them in place of `pc.Vec3` and
20
+ * friends. `Mat4.data` has the layout of `THREE.Matrix4.elements`:
21
+ * `new Matrix4().fromArray(m.data)` crosses over.
22
+ *
23
+ * @module
24
+ * @group Math
25
+ */
26
+ /**
27
+ * PlayCanvas's `Vec3`.
28
+ *
29
+ * @group Math
17
30
  */
18
31
  export declare class Vec3 {
19
32
  x: number;
20
33
  y: number;
21
34
  z: number;
22
- constructor(x?: number, y?: number, z?: number);
35
+ /** Three numbers, or one array-like of three. */
36
+ constructor(x?: number | ArrayLike<number>, y?: number, z?: number);
23
37
  set(x: number, y: number, z: number): this;
24
38
  copy(rhs: {
25
39
  x: number;
@@ -35,15 +49,66 @@ export declare class Vec3 {
35
49
  dot(rhs: Vec3): number;
36
50
  cross(lhs: Vec3, rhs: Vec3): this;
37
51
  length(): number;
38
- normalize(): this;
52
+ /** Normalize `src` (default: this) into this. A zero vector is left as it was. */
53
+ normalize(src?: Vec3): this;
39
54
  lerp(lhs: Vec3, rhs: Vec3, alpha: number): this;
55
+ addScalar(scalar: number): this;
56
+ /** `this += rhs * scalar`. */
57
+ addScaled(rhs: Vec3, scalar: number): this;
58
+ subScalar(scalar: number): this;
59
+ /** Component-wise. */
60
+ mul(rhs: Vec3): this;
61
+ /** Component-wise. */
62
+ mul2(lhs: Vec3, rhs: Vec3): this;
63
+ /** {@link mulScalar}. */
64
+ scale(scalar: number): this;
65
+ /** Component-wise. */
66
+ div(rhs: Vec3): this;
67
+ /** Component-wise. */
68
+ div2(lhs: Vec3, rhs: Vec3): this;
69
+ divScalar(scalar: number): this;
70
+ distance(rhs: Vec3): number;
71
+ distanceSq(rhs: Vec3): number;
72
+ lengthSq(): number;
73
+ equals(rhs: Vec3): boolean;
74
+ equalsApprox(rhs: Vec3, epsilon?: number): boolean;
75
+ floor(src?: Vec3): this;
76
+ ceil(src?: Vec3): this;
77
+ round(src?: Vec3): this;
78
+ /** Component-wise minimum with `rhs`. */
79
+ min(rhs: Vec3): this;
80
+ /** Component-wise maximum with `rhs`. */
81
+ max(rhs: Vec3): this;
82
+ /** Project this onto `rhs`. */
83
+ project(rhs: Vec3): this;
84
+ /** Read three numbers from `arr` at `offset`; missing ones keep their value. */
85
+ fromArray(arr: ArrayLike<number>, offset?: number): this;
86
+ toArray<T extends {
87
+ [i: number]: number;
88
+ } = number[]>(arr?: T, offset?: number): T;
89
+ toString(): string;
90
+ static readonly ZERO: Readonly<Vec3>;
91
+ static readonly HALF: Readonly<Vec3>;
92
+ static readonly ONE: Readonly<Vec3>;
93
+ static readonly UP: Readonly<Vec3>;
94
+ static readonly DOWN: Readonly<Vec3>;
95
+ static readonly RIGHT: Readonly<Vec3>;
96
+ static readonly LEFT: Readonly<Vec3>;
97
+ static readonly FORWARD: Readonly<Vec3>;
98
+ static readonly BACK: Readonly<Vec3>;
40
99
  }
100
+ /**
101
+ * PlayCanvas's `Quat`. Angles in and out are in degrees.
102
+ *
103
+ * @group Math
104
+ */
41
105
  export declare class Quat {
42
106
  x: number;
43
107
  y: number;
44
108
  z: number;
45
109
  w: number;
46
- constructor(x?: number, y?: number, z?: number, w?: number);
110
+ /** Four numbers, or one array-like of four. */
111
+ constructor(x?: number | ArrayLike<number>, y?: number, z?: number, w?: number);
47
112
  set(x: number, y: number, z: number, w: number): this;
48
113
  copy(rhs: {
49
114
  x: number;
@@ -52,11 +117,14 @@ export declare class Quat {
52
117
  w: number;
53
118
  }): this;
54
119
  clone(): Quat;
55
- conjugate(): this;
120
+ /** Conjugate `src` (default: this) into this. */
121
+ conjugate(src?: Quat): this;
56
122
  dot(other: Quat): number;
57
123
  length(): number;
58
- mulScalar(scalar: number): this;
59
- normalize(): this;
124
+ /** `this = src * scalar`, `src` defaulting to this. */
125
+ mulScalar(scalar: number, src?: Quat): this;
126
+ /** Normalize `src` (default: this) into this; a zero quaternion becomes the identity. */
127
+ normalize(src?: Quat): this;
60
128
  /** `this = lhs * rhs`. Safe when `this` aliases either operand. */
61
129
  mul2(lhs: Quat, rhs: Quat): this;
62
130
  mul(rhs: Quat): this;
@@ -69,8 +137,57 @@ export declare class Quat {
69
137
  }, res?: Vec3): Vec3;
70
138
  /** Rotation of the upper 3x3 of `m`, with any scale (and a mirror) divided out. */
71
139
  setFromMat4(m: Mat4): this;
140
+ lengthSq(): number;
141
+ /** The inverse of `src` (default: this), into this. */
142
+ invert(src?: Quat): this;
143
+ /** Normalized linear blend from `lhs` to `rhs`, taking the short way round. */
144
+ lerp(lhs: Quat, rhs: Quat, alpha: number): this;
145
+ equals(rhs: Quat): boolean;
146
+ equalsApprox(rhs: Quat, epsilon?: number): boolean;
147
+ /** A rotation of `angle` degrees about the unit vector `axis`. */
148
+ setFromAxisAngle(axis: {
149
+ x: number;
150
+ y: number;
151
+ z: number;
152
+ }, angle: number): this;
153
+ /**
154
+ * Write this rotation's axis into `axis` and return its angle in degrees.
155
+ * The axis is flipped to have no negative component where it can be, the
156
+ * angle with it.
157
+ */
158
+ getAxisAngle(axis: {
159
+ x: number;
160
+ y: number;
161
+ z: number;
162
+ }): number;
163
+ /** From Euler angles in degrees, applied X, then Y, then Z (as PlayCanvas). */
164
+ setFromEulerAngles(ex: number | Vec3, ey?: number, ez?: number): this;
165
+ /** This rotation as Euler angles in degrees (see {@link setFromEulerAngles}). */
166
+ getEulerAngles(eulers?: Vec3): Vec3;
167
+ /** The shortest rotation taking unit vector `from` to unit vector `to`. */
168
+ setFromDirections(from: Vec3, to: Vec3): this;
169
+ /** Read four numbers from `arr` at `offset`; missing ones keep their value. */
170
+ fromArray(arr: ArrayLike<number>, offset?: number): this;
171
+ toArray<T extends {
172
+ [i: number]: number;
173
+ } = number[]>(arr?: T, offset?: number): T;
174
+ toString(): string;
175
+ static readonly IDENTITY: Readonly<Quat>;
176
+ static readonly ZERO: Readonly<Quat>;
72
177
  }
73
- /** Column-major 4x4, `Float32Array`-backed. Same element layout as `THREE.Matrix4.elements`. */
178
+ type XYZW = {
179
+ x: number;
180
+ y: number;
181
+ z: number;
182
+ w: number;
183
+ };
184
+ /**
185
+ * PlayCanvas's `Mat4`: column-major 4x4, `Float32Array`-backed, the same
186
+ * element layout as `THREE.Matrix4.elements`. Angles in and out are in
187
+ * degrees.
188
+ *
189
+ * @group Math
190
+ */
74
191
  export declare class Mat4 {
75
192
  data: Float32Array;
76
193
  constructor();
@@ -83,7 +200,68 @@ export declare class Mat4 {
83
200
  /** `this = lhs * rhs`. Safe when `this` aliases either operand. */
84
201
  mul2(lhs: Mat4, rhs: Mat4): this;
85
202
  mul(rhs: Mat4): this;
86
- invert(): this;
203
+ /** The inverse of `src` (default: this), into this. A singular matrix gives the identity. */
204
+ invert(src?: Mat4): this;
87
205
  getTranslation(t?: Vec3): Vec3;
88
206
  getScale(scale?: Vec3): Vec3;
207
+ /** Copy 16 column-major numbers in; {@link setFromArray} under PlayCanvas's name. */
208
+ set(src: ArrayLike<number>): this;
209
+ add2(lhs: Mat4, rhs: Mat4): this;
210
+ add(rhs: Mat4): this;
211
+ equals(rhs: Mat4): boolean;
212
+ isIdentity(): boolean;
213
+ /** `this = lhs * rhs` for affine matrices (the bottom rows taken as 0 0 0 1). */
214
+ mulAffine2(lhs: Mat4, rhs: Mat4): this;
215
+ /** `vec` as a point (w = 1) through this matrix. */
216
+ transformPoint(vec: {
217
+ x: number;
218
+ y: number;
219
+ z: number;
220
+ }, res?: Vec3): Vec3;
221
+ /** `vec` as a direction (w = 0) through this matrix. */
222
+ transformVector(vec: {
223
+ x: number;
224
+ y: number;
225
+ z: number;
226
+ }, res?: Vec3): Vec3;
227
+ transformVec4<T extends XYZW = XYZW>(vec: XYZW, res?: T): T;
228
+ /** A transform at `position` whose -Z looks at `target`, with `up` as near up as it can be. */
229
+ setLookAt(position: Vec3, target: Vec3, up: Vec3): this;
230
+ setFrustum(left: number, right: number, bottom: number, top: number, znear: number, zfar: number): this;
231
+ /** `fov` in degrees: vertical, or horizontal when `fovIsHorizontal`. */
232
+ setPerspective(fov: number, aspect: number, znear: number, zfar: number, fovIsHorizontal?: boolean): this;
233
+ setOrtho(left: number, right: number, bottom: number, top: number, near: number, far: number): this;
234
+ /** A rotation of `angle` degrees about the unit vector `axis`. */
235
+ setFromAxisAngle(axis: {
236
+ x: number;
237
+ y: number;
238
+ z: number;
239
+ }, angle: number): this;
240
+ setTranslate(x: number, y: number, z: number): this;
241
+ setScale(x: number, y: number, z: number): this;
242
+ setViewport(x: number, y: number, width: number, height: number): this;
243
+ /** Reflection about the plane `normal · p = distance`. */
244
+ setReflection(normal: {
245
+ x: number;
246
+ y: number;
247
+ z: number;
248
+ }, distance: number): this;
249
+ /** The transpose of `src` (default: this), into this. */
250
+ transpose(src?: Mat4): this;
251
+ /** The X axis (first column). */
252
+ getX(x?: Vec3): Vec3;
253
+ /** The Y axis (second column). */
254
+ getY(y?: Vec3): Vec3;
255
+ /** The Z axis (third column). */
256
+ getZ(z?: Vec3): Vec3;
257
+ /** `-1` when the axes are mirrored, else `1`. */
258
+ get scaleSign(): number;
259
+ /** A rotation from Euler angles in degrees (see {@link Quat.setFromEulerAngles}). */
260
+ setFromEulerAngles(ex: number, ey: number, ez: number): this;
261
+ /** The rotation as Euler angles in degrees, with any scale divided out. */
262
+ getEulerAngles(eulers?: Vec3): Vec3;
263
+ toString(): string;
264
+ static readonly IDENTITY: Readonly<Mat4>;
265
+ static readonly ZERO: Readonly<Mat4>;
89
266
  }
267
+ export {};
@@ -95,6 +95,11 @@ export interface AmmoHinge extends AmmoConstraint {
95
95
  setLimit(low: number, high: number, softness?: number, bias?: number, relax?: number): void;
96
96
  }
97
97
  /** @internal */
98
+ export interface AmmoPoint2Point extends AmmoConstraint {
99
+ setPivotA(v: AmmoVec3): void;
100
+ setPivotB(v: AmmoVec3): void;
101
+ }
102
+ /** @internal */
98
103
  export interface AmmoGeneric6Dof extends AmmoConstraint {
99
104
  setLinearLowerLimit(v: AmmoVec3): void;
100
105
  setLinearUpperLimit(v: AmmoVec3): void;
@@ -191,6 +196,8 @@ export interface AmmoNS {
191
196
  btConeTwistConstraint: Ctor<AmmoConeTwist, [AmmoRigidBody, AmmoRigidBody, AmmoTransform, AmmoTransform]>;
192
197
  btHingeConstraint: Ctor<AmmoHinge, [AmmoRigidBody, AmmoRigidBody, AmmoVec3, AmmoVec3, AmmoVec3, AmmoVec3]>;
193
198
  btGeneric6DofConstraint: Ctor<AmmoGeneric6Dof, [AmmoRigidBody, AmmoRigidBody, AmmoTransform, AmmoTransform, boolean]>;
199
+ /** One body and its pivot (held where it is in the world), or two bodies and a pivot in each. */
200
+ btPoint2PointConstraint: Ctor<AmmoPoint2Point, [AmmoRigidBody, AmmoVec3]> & Ctor<AmmoPoint2Point, [AmmoRigidBody, AmmoRigidBody, AmmoVec3, AmmoVec3]>;
194
201
  ClosestRayResultCallback: Ctor<AmmoClosestRayCallback, [AmmoVec3, AmmoVec3]>;
195
202
  AllHitsRayResultCallback: Ctor<AmmoAllHitsRayCallback, [AmmoVec3, AmmoVec3]>;
196
203
  castObject<T>(obj: unknown, cls: Ctor<T, never[]>): T;
@@ -3,8 +3,8 @@ export type { RaycastOptions, RaycastResult } from './physics-world';
3
3
  export { RigidBody, BODYGROUP_NONE, BODYGROUP_DEFAULT, BODYGROUP_DYNAMIC, BODYGROUP_STATIC, BODYGROUP_KINEMATIC, BODYGROUP_ENGINE_1, BODYGROUP_TRIGGER, BODYGROUP_ENGINE_2, BODYGROUP_ENGINE_3, BODYGROUP_USER_1, BODYGROUP_USER_2, BODYGROUP_USER_3, BODYGROUP_USER_4, BODYGROUP_USER_5, BODYGROUP_USER_6, BODYGROUP_USER_7, BODYGROUP_USER_8, BODYMASK_NONE, BODYMASK_ALL, BODYMASK_STATIC, BODYMASK_NOT_STATIC, BODYMASK_NOT_STATIC_KINEMATIC, } from './rigid-body';
4
4
  export type { BodyPairEvent, CollisionShape, ContactPoint, ContactResult, RigidBodyEventMap, RigidBodyOptions, RigidBodyType, XYZ, XYZW, } from './rigid-body';
5
5
  export type { AmmoDynamicsWorld, AmmoRigidBody } from './ammo';
6
- export { createConeTwistJoint, createGeneric6DofJoint, createHingeJoint } from './joints';
7
- export type { ConeTwistJointOptions, Generic6DofJointOptions, HingeJointOptions, JointHandle } from './joints';
6
+ export { createConeTwistJoint, createGeneric6DofJoint, createHingeJoint, createPointToPointJoint } from './joints';
7
+ export type { ConeTwistJointOptions, Generic6DofJointOptions, HingeJointOptions, JointHandle, PointToPointJointHandle, PointToPointJointOptions, } from './joints';
8
8
  export { Ragdoll } from '../skeletal/ragdoll';
9
9
  export type { LimbDetachedInfo } from '../skeletal/ragdoll';
10
10
  export { DEFAULT_HUMANOID_RAGDOLL } from '../skeletal/ragdoll-config';
@@ -155,3 +155,52 @@ export declare function createGeneric6DofJoint(opts: Generic6DofJointOptions): J
155
155
  * @group Physics
156
156
  */
157
157
  export declare function createHingeJoint(opts: HingeJointOptions): JointHandle;
158
+ /**
159
+ * Options for {@link createPointToPointJoint}.
160
+ *
161
+ * @group Physics
162
+ */
163
+ export interface PointToPointJointOptions {
164
+ bodyA: RigidBody;
165
+ /** The pivot in `bodyA`'s local space. */
166
+ pivotInA: XYZ;
167
+ /** The body `bodyA` hangs from. Omit to hold `bodyA` to a point in the world. */
168
+ bodyB?: RigidBody | null;
169
+ /**
170
+ * The pivot in `bodyB`'s local space or, with no `bodyB`, the world point
171
+ * the pivot is held at. Default: wherever `pivotInA` is in the world now,
172
+ * so the joint starts at rest.
173
+ */
174
+ pivotInB?: XYZ;
175
+ /** See {@link Generic6DofJointOptions.breakImpulse}. */
176
+ breakImpulse?: number;
177
+ /** See {@link ConeTwistJointOptions.disableCollisionBetweenLinkedBodies}. */
178
+ disableCollisionBetweenLinkedBodies?: boolean;
179
+ }
180
+ /**
181
+ * A point-to-point joint. {@link setPivotB} moves the point it holds.
182
+ *
183
+ * @group Physics
184
+ */
185
+ export interface PointToPointJointHandle extends JointHandle {
186
+ /**
187
+ * Move the pivot on `bodyB`, or the world point the pivot is held at when
188
+ * the joint has no `bodyB` (dragging a body by a point, say). Wakes the
189
+ * bodies.
190
+ */
191
+ setPivotB(pivot: XYZ): void;
192
+ }
193
+ /**
194
+ * Create a point-to-point (ball-and-socket) constraint: a point on
195
+ * `bodyA` stays on a point of `bodyB`, or on a point in the world when
196
+ * there is no `bodyB`. Rotation is free. Chains, flails, a body pinned
197
+ * where a bolt hit it, or held by a point while dragged ({@link
198
+ * PointToPointJointHandle.setPivotB}).
199
+ *
200
+ * Bullet's `btPoint2PointConstraint`. Not in the PlayCanvas build, where
201
+ * games make it on Ammo themselves; made here, the joint is tied to its
202
+ * bodies like the others.
203
+ *
204
+ * @group Physics
205
+ */
206
+ export declare function createPointToPointJoint(opts: PointToPointJointOptions): PointToPointJointHandle;
@@ -38,7 +38,8 @@ export interface RaycastResult {
38
38
  /** Something tied to two bodies that must go before either does (a joint). @internal */
39
39
  export interface BodyAttachment {
40
40
  readonly bodyA: RigidBody;
41
- readonly bodyB: RigidBody;
41
+ /** `null` for a joint that holds `bodyA` to the world. */
42
+ readonly bodyB: RigidBody | null;
42
43
  remove(): void;
43
44
  /** One of the bodies is about to free its native object. */
44
45
  suspend(): void;
@@ -738,4 +738,23 @@ export declare function densestSplatOf(character: Pick<Character, 'splats'>): {
738
738
  splat: Splat;
739
739
  key: string;
740
740
  };
741
+ /**
742
+ * Give a three.js light the colour a PlayCanvas light with the same `color`
743
+ * and `intensity` delivers: `linear(colour) * intensity`, or
744
+ * `linear(colour * intensity)` below 1 (pow 2.2, as PlayCanvas linearizes),
745
+ * with `colour` gamma-space, as PlayCanvas's `light.color` is. Stored as three
746
+ * colour * intensity, so `light.intensity` still reads as what was asked for.
747
+ *
748
+ * For lights a game ported from the PlayCanvas build sets by hand, such as
749
+ * the ones it hands {@link SplatRelight.addLight}; {@link SplatRelight}
750
+ * applies it to its own. Call it again whenever the colour or intensity
751
+ * changes: writing `light.intensity` alone skips the curve below 1.
752
+ *
753
+ * @group Lighting
754
+ */
755
+ export declare function setPlayCanvasLightColor(light: Light, gamma: {
756
+ r: number;
757
+ g: number;
758
+ b: number;
759
+ }, intensity: number): void;
741
760
  export {};
@@ -83,6 +83,8 @@ export interface CreateSceneOptions {
83
83
  * GLB clips keep their root rotation, as in the PlayCanvas build 0.3.2.
84
84
  */
85
85
  legacyRootRotation?: boolean;
86
+ /** {@link Scene.updateOrder}. Default `'characters-first'`. */
87
+ updateOrder?: SceneUpdateOrder;
86
88
  /** Kept for PlayCanvas parity; three.js always has a depth buffer. */
87
89
  depth?: boolean;
88
90
  /** Kept for PlayCanvas parity; the skeleton library always loads. */
@@ -90,6 +92,13 @@ export interface CreateSceneOptions {
90
92
  }
91
93
  /** Events {@link Scene.on} accepts. */
92
94
  export type SceneEvent = 'update' | 'postUpdate' | 'preRender' | 'postRender';
95
+ /**
96
+ * When `'update'` listeners run relative to the characters; see
97
+ * {@link Scene.updateOrder}.
98
+ *
99
+ * @group Scene
100
+ */
101
+ export type SceneUpdateOrder = 'characters-first' | 'registration';
93
102
  type WebGPURendererFactory = (canvas: HTMLCanvasElement, opts: CreateSceneOptions) => Promise<unknown | null>;
94
103
  /**
95
104
  * Make `backend: 'webgpu'` available to {@link Scene.create}. Called by the
@@ -112,7 +121,9 @@ export declare function registerWebGPURendererFactory(factory: WebGPURendererFac
112
121
  * | `scene.app` | {@link renderer}, {@link threeScene} |
113
122
  * | `scene.cameraEntity` | {@link camera} |
114
123
  * | `scene.graphicsDevice.setResolution(w, h)` | {@link setResolution} |
115
- * | `scene.app.on('update', fn)` | {@link on}`('update', fn)` |
124
+ * | `scene.app.on('update', fn)` | {@link on}`('update', fn)` (see {@link updateOrder}) |
125
+ * | `scene.app.once('frameend', fn)` | {@link once}`('postRender', fn)` |
126
+ * | `scene.app.timeScale` / `maxDeltaTime` | {@link timeScale} / {@link maxDeltaTime} |
116
127
  * | `entity.addComponent('rigidbody' / 'collision', …)` | {@link physics}`.addBody(object, { shape, … })` |
117
128
  * | `entity.rigidbody` | {@link physics}`.getBody(object)` |
118
129
  * | `app.systems.rigidbody.raycastFirst / gravity / dynamicsWorld` | {@link physics}`.raycastFirst / gravity / dynamicsWorld` |
@@ -155,7 +166,36 @@ export declare class Scene extends SplatEngine {
155
166
  readonly transparent: boolean;
156
167
  /** Frames per second cap; `0` for none. Read every frame. */
157
168
  maxFps: number;
169
+ /**
170
+ * Speed of time for the loop {@link start} runs: each frame's step is
171
+ * multiplied by it before physics, the characters and every listener see
172
+ * it. `0` freezes the game while it keeps drawing; `0.5` is half speed.
173
+ * PlayCanvas's `app.timeScale`. Default `1`. A {@link tick} called by hand
174
+ * takes its `dt` as given.
175
+ */
176
+ timeScale: number;
177
+ /**
178
+ * Longest step, in seconds, the loop {@link start} runs takes in one frame,
179
+ * before {@link timeScale}, so a frame after a stall does not fling bodies.
180
+ * PlayCanvas's `app.maxDeltaTime`. Default `0.1`.
181
+ */
182
+ maxDeltaTime: number;
183
+ /**
184
+ * When `'update'` listeners run relative to the characters:
185
+ * - `'characters-first'` (the default): every character advances, then
186
+ * every listener runs. A listener reads this frame's poses.
187
+ * - `'registration'`: characters and listeners run in the order they were
188
+ * added, as in the PlayCanvas build, where each character is an
189
+ * `app.on('update')` handler of its own. A listener added before a
190
+ * character runs before it, so a pose it sets is used this frame.
191
+ *
192
+ * A character added back with `enableAutoUpdate` / `setActive(true)` moves
193
+ * to the end, as in the PlayCanvas build. Set at {@link Scene.create}.
194
+ */
195
+ readonly updateOrder: SceneUpdateOrder;
158
196
  private readonly _listeners;
197
+ /** Listener → the wrapper {@link once} registered for it, per event. */
198
+ private readonly _onceWrappers;
159
199
  private _running;
160
200
  private _suspended;
161
201
  private _lastTime;
@@ -190,14 +230,22 @@ export declare class Scene extends SplatEngine {
190
230
  private _fitToCanvas;
191
231
  private _applySize;
192
232
  /**
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.
233
+ * Run `fn` every frame. `'update'` runs after physics, and after or among
234
+ * the characters as {@link updateOrder} says; `'postUpdate'` after every
235
+ * `'update'` listener and character; `'preRender'` / `'postRender'` around
236
+ * the draw. `dt` is in seconds.
196
237
  * @returns A function that removes the listener.
197
238
  */
198
239
  on(event: SceneEvent, fn: (dt: number) => void): () => void;
199
- /** Remove a listener added with {@link on}. */
240
+ /**
241
+ * Run `fn` on the next frame only. {@link off} with the same `fn` cancels
242
+ * it, as for {@link on}.
243
+ * @returns A function that removes the listener.
244
+ */
245
+ once(event: SceneEvent, fn: (dt: number) => void): () => void;
246
+ /** Remove a listener added with {@link on} or {@link once}. */
200
247
  off(event: SceneEvent, fn: (dt: number) => void): void;
248
+ private _remove;
201
249
  /** Start the render loop. */
202
250
  start(): void;
203
251
  /** Stop the render loop. {@link start} resumes it. */
@@ -206,8 +254,10 @@ export declare class Scene extends SplatEngine {
206
254
  setSuspended(suspended: boolean): void;
207
255
  private _loop;
208
256
  /**
209
- * Advance and draw one frame by hand: physics, characters, the `'update'`
210
- * listeners, then the render. The loop {@link start} runs calls this.
257
+ * Advance and draw one frame by hand: physics, characters and the
258
+ * `'update'` listeners (in {@link updateOrder}), then the render. The loop
259
+ * {@link start} runs calls this with its step clamped to
260
+ * {@link maxDeltaTime} and scaled by {@link timeScale}.
211
261
  */
212
262
  tick(dt: number): void;
213
263
  /** Draw one frame with the current state, through the post-processing chain. */