@viggle/splat-engine-three 0.1.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (112) hide show
  1. package/CHANGELOG.md +58 -0
  2. package/README.md +158 -20
  3. package/dist/chunks/chunk-2GKWT24B.js +23182 -0
  4. package/dist/chunks/chunk-2GKWT24B.js.map +7 -0
  5. package/dist/index.js +235 -3
  6. package/dist/types/anim/animation-conversion.d.ts +2 -2
  7. package/dist/types/anim/keyframe-splines.d.ts +17 -41
  8. package/dist/types/animation.d.ts +84 -28
  9. package/dist/types/armature.d.ts +280 -2
  10. package/dist/types/character.d.ts +120 -2
  11. package/dist/types/effects/index.d.ts +12 -0
  12. package/dist/types/effects/outlines/outline-effect.d.ts +98 -0
  13. package/dist/types/effects/outlines/outline-shaders.d.ts +14 -0
  14. package/dist/types/effects/pixelart/pixelart-effect.d.ts +152 -0
  15. package/dist/types/effects/pixelart/pixelart-shaders.d.ts +31 -0
  16. package/dist/types/effects/postfx/base-capturing-pass.d.ts +109 -0
  17. package/dist/types/effects/postfx/camera-frame.d.ts +103 -0
  18. package/dist/types/effects/postfx/frame-renderer.d.ts +32 -0
  19. package/dist/types/effects/postfx/frame-shaders.d.ts +19 -0
  20. package/dist/types/effects/postfx/mask.d.ts +44 -0
  21. package/dist/types/effects/postfx/postfx.d.ts +144 -0
  22. package/dist/types/effects/postfx/program.d.ts +74 -0
  23. package/dist/types/effects/postfx/uniforms.d.ts +24 -0
  24. package/dist/types/effects/postfx/webgl-program.d.ts +6 -0
  25. package/dist/types/effects/postfx/webgpu-program.d.ts +3 -0
  26. package/dist/types/effects/vfx/data-types.d.ts +100 -0
  27. package/dist/types/effects/vfx/index.d.ts +37 -0
  28. package/dist/types/effects/vfx/json-vfx-prefab.d.ts +94 -0
  29. package/dist/types/effects/vfx/layer-renderer.d.ts +118 -0
  30. package/dist/types/effects/vfx/layers/mesh.d.ts +124 -0
  31. package/dist/types/effects/vfx/layers/particle.d.ts +90 -0
  32. package/dist/types/effects/vfx/layers/shader.d.ts +130 -0
  33. package/dist/types/effects/vfx/layers/shared.d.ts +40 -0
  34. package/dist/types/effects/vfx/layers/sprite.d.ts +45 -0
  35. package/dist/types/effects/vfx/pool.d.ts +51 -0
  36. package/dist/types/effects/vfx/prefab.d.ts +48 -0
  37. package/dist/types/effects/vfx/prewarm.d.ts +17 -0
  38. package/dist/types/effects/vfx/stage.d.ts +115 -0
  39. package/dist/types/effects/vfx/webgpu-register.d.ts +2 -0
  40. package/dist/types/effects/webgpu-register.d.ts +2 -0
  41. package/dist/types/engine.d.ts +18 -0
  42. package/dist/types/environment.d.ts +96 -8
  43. package/dist/types/index.d.ts +35 -6
  44. package/dist/types/loader/animation/animation-glb.d.ts +4 -4
  45. package/dist/types/loader/character/load.d.ts +6 -1
  46. package/dist/types/loader/environment/lod-bundle.d.ts +123 -0
  47. package/dist/types/loader/environment/spz-decode.d.ts +88 -0
  48. package/dist/types/loader/environment/spz.d.ts +28 -0
  49. package/dist/types/loader/shared/asset-fetch.d.ts +11 -0
  50. package/dist/types/loader/shared/asset-loader.d.ts +86 -0
  51. package/dist/types/loader/shared/bin-cache.d.ts +41 -14
  52. package/dist/types/loader/shared/decode-worker.d.ts +27 -0
  53. package/dist/types/loader/shared/glb.d.ts +30 -0
  54. package/dist/types/loader/shared/inflate.d.ts +9 -0
  55. package/dist/types/loader/shared/pack-splats-task.d.ts +17 -0
  56. package/dist/types/loader/shared/sog-decode.d.ts +81 -0
  57. package/dist/types/loader/shared/sog.d.ts +17 -0
  58. package/dist/types/math.d.ts +198 -13
  59. package/dist/types/physics/ammo.d.ts +217 -0
  60. package/dist/types/physics/index.d.ts +11 -0
  61. package/dist/types/physics/joints.d.ts +206 -0
  62. package/dist/types/physics/physics-world.d.ts +194 -0
  63. package/dist/types/physics/rigid-body.d.ts +361 -0
  64. package/dist/types/presets/camera/camera-preset.d.ts +43 -0
  65. package/dist/types/presets/camera/third-person-camera.d.ts +63 -0
  66. package/dist/types/presets/character/body-shape.d.ts +109 -0
  67. package/dist/types/presets/character/character-reveal.d.ts +90 -0
  68. package/dist/types/presets/character/socket-loadout.d.ts +61 -0
  69. package/dist/types/presets/index.d.ts +13 -0
  70. package/dist/types/presets/vfx/mesh-flash.d.ts +51 -0
  71. package/dist/types/presets/visual/bone-overlay.d.ts +57 -0
  72. package/dist/types/proxy/environment-input.d.ts +30 -0
  73. package/dist/types/proxy/environment-source.d.ts +39 -0
  74. package/dist/types/proxy/proxy-debug.d.ts +106 -0
  75. package/dist/types/proxy/splat-source.d.ts +42 -0
  76. package/dist/types/proxy/voxelizer.d.ts +383 -0
  77. package/dist/types/relight/backend.d.ts +101 -0
  78. package/dist/types/relight/index.d.ts +6 -0
  79. package/dist/types/relight/relight-pass.d.ts +367 -0
  80. package/dist/types/relight/relight-placeholder.d.ts +2 -0
  81. package/dist/types/relight/relight-shaders.d.ts +4 -0
  82. package/dist/types/relight/shadow-bias.d.ts +26 -0
  83. package/dist/types/relight/splat-relight.d.ts +760 -0
  84. package/dist/types/relight/webgl-backend.d.ts +3 -0
  85. package/dist/types/relight/webgpu/backend.d.ts +3 -0
  86. package/dist/types/relight/webgpu-register.d.ts +2 -0
  87. package/dist/types/scene.d.ts +291 -0
  88. package/dist/types/skeletal/animation-player.d.ts +31 -3
  89. package/dist/types/skeletal/body-parts.d.ts +55 -0
  90. package/dist/types/skeletal/ragdoll-config.d.ts +115 -0
  91. package/dist/types/skeletal/ragdoll.d.ts +283 -0
  92. package/dist/types/skeletal/skeleton.d.ts +9 -2
  93. package/dist/types/splat/backend.d.ts +2 -0
  94. package/dist/types/splat/color-modifier.d.ts +78 -0
  95. package/dist/types/splat/cut-groups.d.ts +27 -0
  96. package/dist/types/splat/relight-binding.d.ts +39 -0
  97. package/dist/types/splat/reveal-bake.d.ts +43 -0
  98. package/dist/types/splat/reveal-look.d.ts +64 -0
  99. package/dist/types/splat/splat-mesh.d.ts +1 -0
  100. package/dist/types/splat/splat.d.ts +154 -0
  101. package/dist/types/splat/webgl/shaders.d.ts +5 -1
  102. package/dist/types/splat/webgl/splat-mesh.d.ts +4 -0
  103. package/dist/types/splat/webgpu/radix-sort.d.ts +3 -0
  104. package/dist/types/splat/webgpu/splat-mesh.d.ts +23 -0
  105. package/dist/types/three/splat-character.d.ts +28 -0
  106. package/dist/types/three/spz-loader.d.ts +35 -0
  107. package/dist/types/types.d.ts +6 -0
  108. package/dist/webgpu.js +1137 -154
  109. package/dist/webgpu.js.map +4 -4
  110. package/package.json +6 -2
  111. package/dist/chunks/chunk-WN5WBKM4.js +0 -8606
  112. package/dist/chunks/chunk-WN5WBKM4.js.map +0 -7
@@ -0,0 +1,217 @@
1
+ /** @internal */
2
+ export interface AmmoVec3 {
3
+ x(): number;
4
+ y(): number;
5
+ z(): number;
6
+ setValue(x: number, y: number, z: number): void;
7
+ op_mul(s: number): AmmoVec3;
8
+ }
9
+ /** @internal */
10
+ export interface AmmoQuat {
11
+ x(): number;
12
+ y(): number;
13
+ z(): number;
14
+ w(): number;
15
+ setValue(x: number, y: number, z: number, w: number): void;
16
+ }
17
+ /** @internal */
18
+ export interface AmmoTransform {
19
+ setIdentity(): void;
20
+ setOrigin(v: AmmoVec3): void;
21
+ setRotation(q: AmmoQuat): void;
22
+ getOrigin(): AmmoVec3;
23
+ getRotation(): AmmoQuat;
24
+ }
25
+ /** @internal */
26
+ export interface AmmoMotionState {
27
+ getWorldTransform(out: AmmoTransform): void;
28
+ setWorldTransform(t: AmmoTransform): void;
29
+ }
30
+ /** @internal */
31
+ export interface AmmoShape {
32
+ calculateLocalInertia(mass: number, out: AmmoVec3): void;
33
+ setMargin(m: number): void;
34
+ }
35
+ /** @internal */
36
+ export interface AmmoConvexHull extends AmmoShape {
37
+ addPoint(p: AmmoVec3, recalcAabb?: boolean): void;
38
+ recalcLocalAabb(): void;
39
+ }
40
+ /** @internal */
41
+ export interface AmmoTriangleMesh {
42
+ addTriangle(a: AmmoVec3, b: AmmoVec3, c: AmmoVec3, removeDuplicateVertices?: boolean): void;
43
+ }
44
+ /** A `btRigidBody`. Games reach it through {@link RigidBody.ammoBody} for CCD and raw constraints. @group Physics */
45
+ export interface AmmoRigidBody {
46
+ setUserIndex(i: number): void;
47
+ getUserIndex(): number;
48
+ setFriction(v: number): void;
49
+ setRollingFriction(v: number): void;
50
+ setRestitution(v: number): void;
51
+ setDamping(linear: number, angular: number): void;
52
+ setLinearFactor(v: AmmoVec3): void;
53
+ setAngularFactor(v: AmmoVec3): void;
54
+ setGravity(v: AmmoVec3): void;
55
+ getFlags?(): number;
56
+ setFlags?(f: number): void;
57
+ setLinearVelocity(v: AmmoVec3): void;
58
+ getLinearVelocity(): AmmoVec3;
59
+ setAngularVelocity(v: AmmoVec3): void;
60
+ getAngularVelocity(): AmmoVec3;
61
+ getCollisionShape(): AmmoShape;
62
+ setMassProps(mass: number, inertia: AmmoVec3): void;
63
+ updateInertiaTensor(): void;
64
+ isActive(): boolean;
65
+ activate(force?: boolean): void;
66
+ setWorldTransform(t: AmmoTransform): void;
67
+ getWorldTransform(): AmmoTransform;
68
+ getMotionState(): AmmoMotionState | null;
69
+ getCollisionFlags(): number;
70
+ setCollisionFlags(f: number): void;
71
+ setActivationState(s: number): void;
72
+ forceActivationState(s: number): void;
73
+ applyForce(force: AmmoVec3, relPos: AmmoVec3): void;
74
+ applyImpulse(impulse: AmmoVec3, relPos: AmmoVec3): void;
75
+ applyTorque(torque: AmmoVec3): void;
76
+ applyTorqueImpulse(torque: AmmoVec3): void;
77
+ setCcdMotionThreshold(v: number): void;
78
+ setCcdSweptSphereRadius(v: number): void;
79
+ /** Sets the world transform and restarts interpolation from it. */
80
+ setCenterOfMassTransform(t: AmmoTransform): void;
81
+ }
82
+ /** @internal */
83
+ export interface AmmoConstraint {
84
+ setBreakingImpulseThreshold(v: number): void;
85
+ /** Absent from the games' Ammo build; see `Joint.isBroken`. */
86
+ getAppliedImpulse?(): number;
87
+ }
88
+ /** @internal */
89
+ export interface AmmoConeTwist extends AmmoConstraint {
90
+ /** Swing about local Y, swing about local Z, twist about local X. Radians. */
91
+ setLimit(swingY: number, swingZ: number, twist: number): void;
92
+ }
93
+ /** @internal */
94
+ export interface AmmoHinge extends AmmoConstraint {
95
+ setLimit(low: number, high: number, softness?: number, bias?: number, relax?: number): void;
96
+ }
97
+ /** @internal */
98
+ export interface AmmoPoint2Point extends AmmoConstraint {
99
+ setPivotA(v: AmmoVec3): void;
100
+ setPivotB(v: AmmoVec3): void;
101
+ }
102
+ /** @internal */
103
+ export interface AmmoGeneric6Dof extends AmmoConstraint {
104
+ setLinearLowerLimit(v: AmmoVec3): void;
105
+ setLinearUpperLimit(v: AmmoVec3): void;
106
+ setAngularLowerLimit(v: AmmoVec3): void;
107
+ setAngularUpperLimit(v: AmmoVec3): void;
108
+ }
109
+ /** @internal */
110
+ export interface AmmoManifoldPoint {
111
+ get_m_localPointA(): AmmoVec3;
112
+ get_m_localPointB(): AmmoVec3;
113
+ getPositionWorldOnA(): AmmoVec3;
114
+ getPositionWorldOnB(): AmmoVec3;
115
+ get_m_normalWorldOnB(): AmmoVec3;
116
+ getAppliedImpulse(): number;
117
+ }
118
+ /** @internal */
119
+ export interface AmmoManifold {
120
+ getBody0(): unknown;
121
+ getBody1(): unknown;
122
+ getNumContacts(): number;
123
+ getContactPoint(i: number): AmmoManifoldPoint;
124
+ }
125
+ /** @internal */
126
+ export interface AmmoDispatcher {
127
+ getNumManifolds(): number;
128
+ getManifoldByIndexInternal(i: number): AmmoManifold;
129
+ }
130
+ /** @internal */
131
+ export interface AmmoRayCallback {
132
+ set_m_collisionFilterGroup(g: number): void;
133
+ set_m_collisionFilterMask(m: number): void;
134
+ set_m_flags?(f: number): void;
135
+ hasHit(): boolean;
136
+ }
137
+ /** @internal */
138
+ export interface AmmoClosestRayCallback extends AmmoRayCallback {
139
+ get_m_collisionObject(): unknown;
140
+ get_m_hitPointWorld(): AmmoVec3;
141
+ get_m_hitNormalWorld(): AmmoVec3;
142
+ get_m_closestHitFraction(): number;
143
+ }
144
+ /** @internal */
145
+ export interface AmmoArray<T> {
146
+ size(): number;
147
+ at(i: number): T;
148
+ }
149
+ /** @internal */
150
+ export interface AmmoAllHitsRayCallback extends AmmoRayCallback {
151
+ get_m_collisionObjects(): AmmoArray<unknown>;
152
+ get_m_hitPointWorld(): AmmoArray<AmmoVec3>;
153
+ get_m_hitNormalWorld(): AmmoArray<AmmoVec3>;
154
+ get_m_hitFractions(): AmmoArray<number>;
155
+ }
156
+ /** A `btDiscreteDynamicsWorld`, exposed as {@link PhysicsWorld.dynamicsWorld} for raw constraints. @group Physics */
157
+ export interface AmmoDynamicsWorld {
158
+ setGravity(v: AmmoVec3): void;
159
+ stepSimulation(dt: number, maxSubSteps: number, fixedTimeStep: number): number;
160
+ addRigidBody(body: AmmoRigidBody, group?: number, mask?: number): void;
161
+ removeRigidBody(body: AmmoRigidBody): void;
162
+ addConstraint(c: AmmoConstraint, disableCollisionBetweenLinkedBodies?: boolean): void;
163
+ removeConstraint(c: AmmoConstraint): void;
164
+ rayTest(from: AmmoVec3, to: AmmoVec3, cb: AmmoRayCallback): void;
165
+ setInternalTickCallback?(fnPtr: number): void;
166
+ updateSingleAabb?(body: AmmoRigidBody): void;
167
+ }
168
+ type Ctor<T, A extends unknown[] = []> = new (...args: A) => T;
169
+ /** @internal */
170
+ export interface AmmoNS {
171
+ btVector3: Ctor<AmmoVec3, [number?, number?, number?]>;
172
+ btQuaternion: Ctor<AmmoQuat, [number, number, number, number]>;
173
+ btTransform: Ctor<AmmoTransform>;
174
+ btDefaultMotionState: Ctor<AmmoMotionState, [AmmoTransform]>;
175
+ btRigidBodyConstructionInfo: Ctor<unknown, [number, AmmoMotionState, AmmoShape, AmmoVec3]>;
176
+ btRigidBody: Ctor<AmmoRigidBody, [unknown]>;
177
+ btDefaultCollisionConfiguration: Ctor<unknown>;
178
+ btCollisionDispatcher: Ctor<AmmoDispatcher, [unknown]>;
179
+ btDbvtBroadphase: Ctor<unknown>;
180
+ btSequentialImpulseConstraintSolver: Ctor<unknown>;
181
+ btDiscreteDynamicsWorld: Ctor<AmmoDynamicsWorld, [AmmoDispatcher, unknown, unknown, unknown]>;
182
+ btBoxShape: Ctor<AmmoShape, [AmmoVec3]>;
183
+ btSphereShape: Ctor<AmmoShape, [number]>;
184
+ btCapsuleShape: Ctor<AmmoShape, [number, number]>;
185
+ btCapsuleShapeX: Ctor<AmmoShape, [number, number]>;
186
+ btCapsuleShapeZ: Ctor<AmmoShape, [number, number]>;
187
+ btCylinderShape: Ctor<AmmoShape, [AmmoVec3]>;
188
+ btCylinderShapeX: Ctor<AmmoShape, [AmmoVec3]>;
189
+ btCylinderShapeZ: Ctor<AmmoShape, [AmmoVec3]>;
190
+ btConeShape: Ctor<AmmoShape, [number, number]>;
191
+ btConeShapeX: Ctor<AmmoShape, [number, number]>;
192
+ btConeShapeZ: Ctor<AmmoShape, [number, number]>;
193
+ btConvexHullShape: Ctor<AmmoConvexHull>;
194
+ btTriangleMesh: Ctor<AmmoTriangleMesh>;
195
+ btBvhTriangleMeshShape: Ctor<AmmoShape, [AmmoTriangleMesh, boolean]>;
196
+ btConeTwistConstraint: Ctor<AmmoConeTwist, [AmmoRigidBody, AmmoRigidBody, AmmoTransform, AmmoTransform]>;
197
+ btHingeConstraint: Ctor<AmmoHinge, [AmmoRigidBody, AmmoRigidBody, AmmoVec3, AmmoVec3, AmmoVec3, AmmoVec3]>;
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]>;
201
+ ClosestRayResultCallback: Ctor<AmmoClosestRayCallback, [AmmoVec3, AmmoVec3]>;
202
+ AllHitsRayResultCallback: Ctor<AmmoAllHitsRayCallback, [AmmoVec3, AmmoVec3]>;
203
+ castObject<T>(obj: unknown, cls: Ctor<T, never[]>): T;
204
+ getPointer(obj: unknown): number;
205
+ addFunction?(fn: (...args: number[]) => void, signature: string): number;
206
+ destroy(obj: unknown): void;
207
+ }
208
+ /** `globalThis.Ammo`, or a clear error when physics was never set up. @internal */
209
+ export declare function ammo(): AmmoNS;
210
+ /** @internal */ export declare const CF_KINEMATIC_OBJECT = 2;
211
+ /** @internal */ export declare const CF_NO_CONTACT_RESPONSE = 4;
212
+ /** @internal */ export declare const ACTIVE_TAG = 1;
213
+ /** @internal */ export declare const DISABLE_DEACTIVATION = 4;
214
+ /** @internal */ export declare const DISABLE_SIMULATION = 5;
215
+ /** `btRigidBody` flag that stops the world's gravity overwriting a per-body gravity. @internal */
216
+ export declare const BT_DISABLE_WORLD_GRAVITY = 1;
217
+ export {};
@@ -0,0 +1,11 @@
1
+ export { PhysicsWorld } from './physics-world';
2
+ export type { RaycastOptions, RaycastResult } from './physics-world';
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
+ export type { BodyPairEvent, CollisionShape, ContactPoint, ContactResult, RigidBodyEventMap, RigidBodyOptions, RigidBodyType, XYZ, XYZW, } from './rigid-body';
5
+ export type { AmmoDynamicsWorld, AmmoRigidBody } from './ammo';
6
+ export { createConeTwistJoint, createGeneric6DofJoint, createHingeJoint, createPointToPointJoint } from './joints';
7
+ export type { ConeTwistJointOptions, Generic6DofJointOptions, HingeJointOptions, JointHandle, PointToPointJointHandle, PointToPointJointOptions, } from './joints';
8
+ export { Ragdoll } from '../skeletal/ragdoll';
9
+ export type { LimbDetachedInfo } from '../skeletal/ragdoll';
10
+ export { DEFAULT_HUMANOID_RAGDOLL } from '../skeletal/ragdoll-config';
11
+ export type { RagdollBoneDesc, RagdollConfig, RagdollJointDesc } from '../skeletal/ragdoll-config';
@@ -0,0 +1,206 @@
1
+ /**
2
+ * Thin wrapper around the Ammo constraint API that {@link PhysicsWorld}
3
+ * doesn't wrap itself. Construct via the helpers below; each returns a
4
+ * {@link JointHandle} whose `remove()` detaches the constraint from the
5
+ * dynamics world and frees the native object.
6
+ *
7
+ * Why this exists: ragdolls, hinged doors, swinging ropes and chains of
8
+ * bodies all need raw Bullet constraints. Joints made here are tied to their
9
+ * bodies: {@link PhysicsWorld.removeBody} removes them first, and a body that
10
+ * rebuilds its native object (a `type` change) has them re-made against the
11
+ * new one, so Bullet never steps a constraint on a freed body.
12
+ *
13
+ * Ported from the PlayCanvas build, where the bodies are entities with a
14
+ * `rigidbody` component. Here they are {@link RigidBody}s, and the options
15
+ * drop `app` (the world is the bodies').
16
+ *
17
+ * @module
18
+ * @group Physics
19
+ */
20
+ import type { RigidBody, XYZ, XYZW } from './rigid-body';
21
+ /**
22
+ * Reference to a live joint. `remove()` detaches the constraint and frees
23
+ * the underlying Ammo object. Idempotent.
24
+ *
25
+ * @group Physics
26
+ */
27
+ export interface JointHandle {
28
+ /** Detach from the dynamics world and free the underlying Ammo
29
+ * object. Idempotent. */
30
+ remove(): void;
31
+ /** True if the constraint has been broken by Bullet's solver (its
32
+ * applied impulse exceeded the configured `breakImpulse`). Always
33
+ * `true` after `remove()`. */
34
+ isBroken(): boolean;
35
+ }
36
+ /**
37
+ * Options for {@link createConeTwistJoint}.
38
+ *
39
+ * @group Physics
40
+ */
41
+ export interface ConeTwistJointOptions {
42
+ bodyA: RigidBody;
43
+ bodyB: RigidBody;
44
+ /** Joint anchor in `bodyA`'s local space. */
45
+ frameInA: {
46
+ position: XYZ;
47
+ rotation: XYZW;
48
+ };
49
+ /** Joint anchor in `bodyB`'s local space. */
50
+ frameInB: {
51
+ position: XYZ;
52
+ rotation: XYZW;
53
+ };
54
+ /** Cone half-angle about the joint's local Y axis (radians). Default π/4. */
55
+ swingY?: number;
56
+ /** Cone half-angle about the joint's local Z axis (radians). Default π/4. */
57
+ swingZ?: number;
58
+ /** Twist half-angle about the joint's local X axis (radians). Default π/6. */
59
+ twist?: number;
60
+ /**
61
+ * When true, the two bodies stop colliding with each other - required
62
+ * for limb pairs whose colliders overlap at the joint. Default `true`.
63
+ */
64
+ disableCollisionBetweenLinkedBodies?: boolean;
65
+ }
66
+ /**
67
+ * Create a cone-twist constraint between two bodies. Models ball-and-
68
+ * socket joints (shoulder, hip, neck) - bodyB can swing within an
69
+ * elliptical cone of bodyA and twist around the cone's axis.
70
+ *
71
+ * @group Physics
72
+ */
73
+ export declare function createConeTwistJoint(opts: ConeTwistJointOptions): JointHandle;
74
+ /**
75
+ * Options for {@link createHingeJoint}.
76
+ *
77
+ * @group Physics
78
+ */
79
+ export interface HingeJointOptions {
80
+ bodyA: RigidBody;
81
+ bodyB: RigidBody;
82
+ /** Hinge pivot in `bodyA`'s local space. */
83
+ pivotInA: XYZ;
84
+ /** Hinge pivot in `bodyB`'s local space. */
85
+ pivotInB: XYZ;
86
+ /** Hinge axis in `bodyA`'s local space. Need not be unit-length. */
87
+ axisInA: XYZ;
88
+ /** Hinge axis in `bodyB`'s local space. */
89
+ axisInB: XYZ;
90
+ /** Lower hinge angle (radians). Default −π (no lower stop). */
91
+ lowLimit?: number;
92
+ /** Upper hinge angle (radians). Default π (no upper stop). */
93
+ highLimit?: number;
94
+ /** See {@link ConeTwistJointOptions.disableCollisionBetweenLinkedBodies}. */
95
+ disableCollisionBetweenLinkedBodies?: boolean;
96
+ }
97
+ /**
98
+ * Options for {@link createGeneric6DofJoint}.
99
+ *
100
+ * @group Physics
101
+ */
102
+ export interface Generic6DofJointOptions {
103
+ bodyA: RigidBody;
104
+ bodyB: RigidBody;
105
+ /** Joint frame in `bodyA`'s local space. */
106
+ frameInA: {
107
+ position: XYZ;
108
+ rotation: XYZW;
109
+ };
110
+ /** Joint frame in `bodyB`'s local space. */
111
+ frameInB: {
112
+ position: XYZ;
113
+ rotation: XYZW;
114
+ };
115
+ /** Translation limits per axis (in the joint frame). Default `(0,0,0)` /
116
+ * `(0,0,0)` - fully locked, the typical ball-and-socket case. */
117
+ linearLowerLimit?: XYZ;
118
+ linearUpperLimit?: XYZ;
119
+ /** Rotation limits per axis (radians). Conventions in `btGeneric6DofConstraint`:
120
+ * - `lower < upper`: axis is limited to that range
121
+ * - `lower == upper`: axis is fully locked
122
+ * - `lower > upper`: axis is free (no limit)
123
+ *
124
+ * For a cone-twist-style joint where frame X is the twist/cone axis:
125
+ * `lower = (-twist, -swingY, -swingZ)`, `upper = (twist, swingY, swingZ)`. */
126
+ angularLowerLimit: XYZ;
127
+ angularUpperLimit: XYZ;
128
+ /**
129
+ * Breaking impulse threshold (N·s). When the constraint's applied
130
+ * impulse exceeds this value in a single physics step, Bullet
131
+ * auto-disables the constraint and the two bodies become free of each
132
+ * other. Poll {@link JointHandle.isBroken} each frame to react. Omit for
133
+ * an unbreakable joint.
134
+ */
135
+ breakImpulse?: number;
136
+ /** See {@link ConeTwistJointOptions.disableCollisionBetweenLinkedBodies}. */
137
+ disableCollisionBetweenLinkedBodies?: boolean;
138
+ }
139
+ /**
140
+ * Create a generic 6-DOF constraint between two bodies. The workhorse
141
+ * for ragdoll joints - independently constrain translation and rotation
142
+ * on each axis of a joint frame. More numerically robust than
143
+ * {@link createConeTwistJoint} for the asymmetric body orientations
144
+ * typical of ragdoll shoulders / hips.
145
+ *
146
+ * @group Physics
147
+ */
148
+ export declare function createGeneric6DofJoint(opts: Generic6DofJointOptions): JointHandle;
149
+ /**
150
+ * Create a hinge constraint between two bodies. Models single-axis joints
151
+ * like elbows, knees, and doors. Set `lowLimit`/`highLimit` to author
152
+ * realistic limb ranges (e.g. an elbow swings 0 → +2.4 rad, not the full
153
+ * ±π default).
154
+ *
155
+ * @group Physics
156
+ */
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;
@@ -0,0 +1,194 @@
1
+ import { Object3D, Vector3 } from 'three';
2
+ import type { AmmoDynamicsWorld } from './ammo';
3
+ import { RigidBody } from './rigid-body';
4
+ import type { RigidBodyOptions, XYZ } from './rigid-body';
5
+ /**
6
+ * Options for {@link PhysicsWorld.raycastFirst} / {@link PhysicsWorld.raycastAll}.
7
+ * PlayCanvas's raycast options, with `filterTags` dropped (three.js objects
8
+ * have no tags; use `filterCallback`).
9
+ *
10
+ * @group Physics
11
+ */
12
+ export interface RaycastOptions {
13
+ /** The ray's own collision group. Bodies whose mask excludes it are not hit. */
14
+ filterCollisionGroup?: number;
15
+ /** Groups the ray can hit. */
16
+ filterCollisionMask?: number;
17
+ /** Return `false` to skip a body. */
18
+ filterCallback?: (body: RigidBody) => boolean;
19
+ /** `raycastAll` only: sort hits nearest first. Default `false`. */
20
+ sort?: boolean;
21
+ }
22
+ /**
23
+ * One ray hit. PlayCanvas's `RaycastResult`, with `entity` → `object`.
24
+ *
25
+ * @group Physics
26
+ */
27
+ export interface RaycastResult {
28
+ /** The hit body's object. */
29
+ object: Object3D;
30
+ body: RigidBody;
31
+ /** World-space hit point. */
32
+ point: Vector3;
33
+ /** World-space surface normal at the hit. */
34
+ normal: Vector3;
35
+ /** Where along the ray the hit is, 0 at `start` to 1 at `end`. */
36
+ hitFraction: number;
37
+ }
38
+ /** Something tied to two bodies that must go before either does (a joint). @internal */
39
+ export interface BodyAttachment {
40
+ readonly bodyA: RigidBody;
41
+ /** `null` for a joint that holds `bodyA` to the world. */
42
+ readonly bodyB: RigidBody | null;
43
+ remove(): void;
44
+ /** One of the bodies is about to free its native object. */
45
+ suspend(): void;
46
+ /** That body has its new native object. */
47
+ resume(): void;
48
+ }
49
+ /**
50
+ * Ammo (Bullet) rigid-body physics for a {@link Scene}, which steps it every
51
+ * frame before characters update. Create the scene with
52
+ * `Scene.create(canvas, { physics: { loadAmmo } })` and use `scene.physics`.
53
+ * The engine does not ship Ammo: the game loads it, and this class reads
54
+ * `globalThis.Ammo`.
55
+ *
56
+ * Bodies attach to `THREE.Object3D`s ({@link addBody}); a dynamic body moves
57
+ * its object, a kinematic one follows it. Stepping, interpolation, collision
58
+ * groups, events and raycasts behave as PlayCanvas's `rigidbody` system, so
59
+ * game code maps across almost name for name:
60
+ *
61
+ * | PlayCanvas | here |
62
+ * |---------------------------------------------------------|---------------------------------------------------|
63
+ * | `e.addComponent('collision', shape)` + `e.addComponent('rigidbody', opts)` | `physics.addBody(object, { shape, ...opts })` |
64
+ * | `e.addComponent('collision', shape)` alone (a trigger) | `physics.addBody(object, { shape, trigger: true })` |
65
+ * | `collision.linearOffset` / `angularOffset` | `linearOffset` / `angularOffset` options |
66
+ * | `{ type: 'mesh', model }` | `{ type: 'mesh', geometry: object3DOrGeometry }` |
67
+ * | `e.rigidbody` | `physics.getBody(object)` |
68
+ * | `e.rigidbody.body` (btRigidBody) | `body.ammoBody` |
69
+ * | `e.removeComponent('rigidbody')` / `e.destroy()` | `physics.removeBody(body)` |
70
+ * | `rb.applyForce(x, y, z)` / `applyImpulse(v, p)` | `body.applyForce(vec)` / `applyImpulse(vec, p)` - vectors only |
71
+ * | `rb.applyTorque` / `applyTorqueImpulse` | same |
72
+ * | `rb.linearVelocity` / `angularVelocity` (get / set) | same, `THREE.Vector3` |
73
+ * | `rb.teleport(pos, rot)` | `body.teleport(pos, quatOrEuler)` - Euler in radians |
74
+ * | `rb.type` / `mass` / `friction` / `restitution` / `linearDamping` / `angularDamping` / `linearFactor` / `angularFactor` / `gravityScale` / `group` / `mask` / `enabled` | same |
75
+ * | `rb.activate()` / `isActive()` | same |
76
+ * | `rb.on('collisionstart', (r: ContactResult) => …)` | `body.addEventListener('collisionstart', (r) => …)`; `r.other` is the Object3D |
77
+ * | `collisionend` / `contact` / `triggerenter` / `triggerleave` | same names |
78
+ * | `app.systems.rigidbody.raycastFirst(a, b, opts)` | `physics.raycastFirst(a, b, opts)`; `hit.entity` → `hit.object` |
79
+ * | `app.systems.rigidbody.raycastAll(a, b, opts)` | `physics.raycastAll(a, b, opts)` |
80
+ * | `app.systems.rigidbody.gravity` | `physics.gravity` (mutable `THREE.Vector3`) |
81
+ * | `app.systems.rigidbody.fixedTimeStep` / `maxSubSteps` | same |
82
+ * | `app.systems.rigidbody.dynamicsWorld` | `physics.dynamicsWorld` |
83
+ * | `BODYTYPE_STATIC` / `DYNAMIC` / `KINEMATIC` | `'static'` / `'dynamic'` / `'kinematic'` |
84
+ * | `BODYGROUP_*` / `BODYMASK_*` | same names and values, exported from this package |
85
+ *
86
+ * @group Physics
87
+ */
88
+ export declare class PhysicsWorld {
89
+ /** World gravity, m/s². Mutate it freely; it is applied at the next step. */
90
+ readonly gravity: Vector3;
91
+ /** Simulation step, seconds. Frames are cut into steps of this size. Default `1/60`. */
92
+ fixedTimeStep: number;
93
+ /** Most fixed steps one frame may take before time is dropped. Default `10`. */
94
+ maxSubSteps: number;
95
+ /** Multiplier on frame time; `0` pauses the simulation. Default `1`. */
96
+ timeScale: number;
97
+ /** The Bullet `btDiscreteDynamicsWorld`, for raw constraints. */
98
+ readonly dynamicsWorld: AmmoDynamicsWorld;
99
+ private readonly _A;
100
+ private readonly _collisionConfiguration;
101
+ private readonly _dispatcher;
102
+ private readonly _broadphase;
103
+ private readonly _solver;
104
+ private readonly _host;
105
+ private readonly _appliedGravity;
106
+ private readonly _btVec1;
107
+ private readonly _btVec2;
108
+ private readonly _btQuat;
109
+ private readonly _btTransform;
110
+ private _nextId;
111
+ private readonly _bodies;
112
+ private readonly _byObject;
113
+ private readonly _dynamic;
114
+ private readonly _kinematic;
115
+ private readonly _triggers;
116
+ private readonly _attachments;
117
+ /** body → the bodies it is touching (or overlapping, for a trigger) as of the last sub-step. */
118
+ private readonly _collisions;
119
+ private readonly _frameCollisions;
120
+ private readonly _queue;
121
+ private readonly _worldPointer;
122
+ private readonly _tickDispatcher;
123
+ private _destroyed;
124
+ /**
125
+ * Await the game's Ammo loader (when given) and build a world. Throws when
126
+ * `globalThis.Ammo` is still not set.
127
+ */
128
+ static create(opts: true | {
129
+ loadAmmo: () => Promise<void>;
130
+ }): Promise<PhysicsWorld>;
131
+ /** Build a world on the already-loaded `globalThis.Ammo`. {@link Scene.create} does this for you. */
132
+ constructor();
133
+ /**
134
+ * Give `object` a rigid body, placed at the object's current world pose.
135
+ * One body per object; throws if it already has one. Put the object in the
136
+ * scene graph first if it has a parent, so its world pose is known.
137
+ */
138
+ addBody(object: Object3D, opts: RigidBodyOptions): RigidBody;
139
+ /** The body {@link addBody} gave `object`, or `null`. */
140
+ getBody(object: Object3D): RigidBody | null;
141
+ /** Every live body, in creation order. */
142
+ get bodies(): IterableIterator<RigidBody>;
143
+ /**
144
+ * Take a body (or the body on an object) out of the world and free it.
145
+ * Joints made with this module's joint helpers that use it go first. The
146
+ * object itself is left where it is. Idempotent.
147
+ */
148
+ removeBody(target: RigidBody | Object3D): void;
149
+ /** @internal Joints register so they are removed before the bodies they hold. */
150
+ _attach(a: BodyAttachment): void;
151
+ /** @internal */
152
+ _detach(a: BodyAttachment): void;
153
+ /** The nearest body the segment `start` → `end` hits, or `null`. */
154
+ raycastFirst(start: XYZ, end: XYZ, options?: RaycastOptions): RaycastResult | null;
155
+ /** Every body the segment `start` → `end` hits. Unordered unless `options.sort`. */
156
+ raycastAll(start: XYZ, end: XYZ, options?: RaycastOptions): RaycastResult[];
157
+ /**
158
+ * Advance the simulation by `dt` seconds, in {@link fixedTimeStep} steps,
159
+ * then move dynamic objects to their (interpolated) bodies and dispatch
160
+ * collision events. {@link Scene} calls this every frame before characters
161
+ * update; call it yourself only on a world you drive by hand.
162
+ */
163
+ step(dt: number): void;
164
+ /** Free every body, joint and the world. {@link Scene.destroy} calls it. */
165
+ destroy(): void;
166
+ private _assertAlive;
167
+ private _simulationChanged;
168
+ /**
169
+ * `body` frees and re-creates its btRigidBody inside `replace`: the joints
170
+ * that hold it let go first and are re-made against the new one after.
171
+ */
172
+ private _nativeReplacing;
173
+ private _bodyFromNative;
174
+ /**
175
+ * Drop a body's own contact bookkeeping. Bodies it was touching keep it in
176
+ * theirs, so the next sub-step ends those collisions and they get their
177
+ * `collisionend` / `triggerleave`, as in PlayCanvas.
178
+ */
179
+ private _forgetCollisions;
180
+ /**
181
+ * Read this sub-step's contact manifolds into events. PlayCanvas's
182
+ * `onContactPair` logic: contact points are gathered only for bodies with
183
+ * listeners, a pair is new if it was not touching last sub-step, and a pair
184
+ * that stopped touching ends. Events are queued, not fired, because this
185
+ * may run inside Bullet's step, where a listener removing a body would
186
+ * free memory the solver is still using.
187
+ * @internal
188
+ */
189
+ _walkContacts(): void;
190
+ /** Record `body` touching `other` this sub-step; true if it was not touching last time. */
191
+ private _store;
192
+ private _enqueue;
193
+ private _flushEvents;
194
+ }