@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,193 @@
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
+ readonly bodyB: RigidBody;
42
+ remove(): void;
43
+ /** One of the bodies is about to free its native object. */
44
+ suspend(): void;
45
+ /** That body has its new native object. */
46
+ resume(): void;
47
+ }
48
+ /**
49
+ * Ammo (Bullet) rigid-body physics for a {@link Scene}, which steps it every
50
+ * frame before characters update. Create the scene with
51
+ * `Scene.create(canvas, { physics: { loadAmmo } })` and use `scene.physics`.
52
+ * The engine does not ship Ammo: the game loads it, and this class reads
53
+ * `globalThis.Ammo`.
54
+ *
55
+ * Bodies attach to `THREE.Object3D`s ({@link addBody}); a dynamic body moves
56
+ * its object, a kinematic one follows it. Stepping, interpolation, collision
57
+ * groups, events and raycasts behave as PlayCanvas's `rigidbody` system, so
58
+ * game code maps across almost name for name:
59
+ *
60
+ * | PlayCanvas | here |
61
+ * |---------------------------------------------------------|---------------------------------------------------|
62
+ * | `e.addComponent('collision', shape)` + `e.addComponent('rigidbody', opts)` | `physics.addBody(object, { shape, ...opts })` |
63
+ * | `e.addComponent('collision', shape)` alone (a trigger) | `physics.addBody(object, { shape, trigger: true })` |
64
+ * | `collision.linearOffset` / `angularOffset` | `linearOffset` / `angularOffset` options |
65
+ * | `{ type: 'mesh', model }` | `{ type: 'mesh', geometry: object3DOrGeometry }` |
66
+ * | `e.rigidbody` | `physics.getBody(object)` |
67
+ * | `e.rigidbody.body` (btRigidBody) | `body.ammoBody` |
68
+ * | `e.removeComponent('rigidbody')` / `e.destroy()` | `physics.removeBody(body)` |
69
+ * | `rb.applyForce(x, y, z)` / `applyImpulse(v, p)` | `body.applyForce(vec)` / `applyImpulse(vec, p)` - vectors only |
70
+ * | `rb.applyTorque` / `applyTorqueImpulse` | same |
71
+ * | `rb.linearVelocity` / `angularVelocity` (get / set) | same, `THREE.Vector3` |
72
+ * | `rb.teleport(pos, rot)` | `body.teleport(pos, quatOrEuler)` - Euler in radians |
73
+ * | `rb.type` / `mass` / `friction` / `restitution` / `linearDamping` / `angularDamping` / `linearFactor` / `angularFactor` / `gravityScale` / `group` / `mask` / `enabled` | same |
74
+ * | `rb.activate()` / `isActive()` | same |
75
+ * | `rb.on('collisionstart', (r: ContactResult) => …)` | `body.addEventListener('collisionstart', (r) => …)`; `r.other` is the Object3D |
76
+ * | `collisionend` / `contact` / `triggerenter` / `triggerleave` | same names |
77
+ * | `app.systems.rigidbody.raycastFirst(a, b, opts)` | `physics.raycastFirst(a, b, opts)`; `hit.entity` → `hit.object` |
78
+ * | `app.systems.rigidbody.raycastAll(a, b, opts)` | `physics.raycastAll(a, b, opts)` |
79
+ * | `app.systems.rigidbody.gravity` | `physics.gravity` (mutable `THREE.Vector3`) |
80
+ * | `app.systems.rigidbody.fixedTimeStep` / `maxSubSteps` | same |
81
+ * | `app.systems.rigidbody.dynamicsWorld` | `physics.dynamicsWorld` |
82
+ * | `BODYTYPE_STATIC` / `DYNAMIC` / `KINEMATIC` | `'static'` / `'dynamic'` / `'kinematic'` |
83
+ * | `BODYGROUP_*` / `BODYMASK_*` | same names and values, exported from this package |
84
+ *
85
+ * @group Physics
86
+ */
87
+ export declare class PhysicsWorld {
88
+ /** World gravity, m/s². Mutate it freely; it is applied at the next step. */
89
+ readonly gravity: Vector3;
90
+ /** Simulation step, seconds. Frames are cut into steps of this size. Default `1/60`. */
91
+ fixedTimeStep: number;
92
+ /** Most fixed steps one frame may take before time is dropped. Default `10`. */
93
+ maxSubSteps: number;
94
+ /** Multiplier on frame time; `0` pauses the simulation. Default `1`. */
95
+ timeScale: number;
96
+ /** The Bullet `btDiscreteDynamicsWorld`, for raw constraints. */
97
+ readonly dynamicsWorld: AmmoDynamicsWorld;
98
+ private readonly _A;
99
+ private readonly _collisionConfiguration;
100
+ private readonly _dispatcher;
101
+ private readonly _broadphase;
102
+ private readonly _solver;
103
+ private readonly _host;
104
+ private readonly _appliedGravity;
105
+ private readonly _btVec1;
106
+ private readonly _btVec2;
107
+ private readonly _btQuat;
108
+ private readonly _btTransform;
109
+ private _nextId;
110
+ private readonly _bodies;
111
+ private readonly _byObject;
112
+ private readonly _dynamic;
113
+ private readonly _kinematic;
114
+ private readonly _triggers;
115
+ private readonly _attachments;
116
+ /** body → the bodies it is touching (or overlapping, for a trigger) as of the last sub-step. */
117
+ private readonly _collisions;
118
+ private readonly _frameCollisions;
119
+ private readonly _queue;
120
+ private readonly _worldPointer;
121
+ private readonly _tickDispatcher;
122
+ private _destroyed;
123
+ /**
124
+ * Await the game's Ammo loader (when given) and build a world. Throws when
125
+ * `globalThis.Ammo` is still not set.
126
+ */
127
+ static create(opts: true | {
128
+ loadAmmo: () => Promise<void>;
129
+ }): Promise<PhysicsWorld>;
130
+ /** Build a world on the already-loaded `globalThis.Ammo`. {@link Scene.create} does this for you. */
131
+ constructor();
132
+ /**
133
+ * Give `object` a rigid body, placed at the object's current world pose.
134
+ * One body per object; throws if it already has one. Put the object in the
135
+ * scene graph first if it has a parent, so its world pose is known.
136
+ */
137
+ addBody(object: Object3D, opts: RigidBodyOptions): RigidBody;
138
+ /** The body {@link addBody} gave `object`, or `null`. */
139
+ getBody(object: Object3D): RigidBody | null;
140
+ /** Every live body, in creation order. */
141
+ get bodies(): IterableIterator<RigidBody>;
142
+ /**
143
+ * Take a body (or the body on an object) out of the world and free it.
144
+ * Joints made with this module's joint helpers that use it go first. The
145
+ * object itself is left where it is. Idempotent.
146
+ */
147
+ removeBody(target: RigidBody | Object3D): void;
148
+ /** @internal Joints register so they are removed before the bodies they hold. */
149
+ _attach(a: BodyAttachment): void;
150
+ /** @internal */
151
+ _detach(a: BodyAttachment): void;
152
+ /** The nearest body the segment `start` → `end` hits, or `null`. */
153
+ raycastFirst(start: XYZ, end: XYZ, options?: RaycastOptions): RaycastResult | null;
154
+ /** Every body the segment `start` → `end` hits. Unordered unless `options.sort`. */
155
+ raycastAll(start: XYZ, end: XYZ, options?: RaycastOptions): RaycastResult[];
156
+ /**
157
+ * Advance the simulation by `dt` seconds, in {@link fixedTimeStep} steps,
158
+ * then move dynamic objects to their (interpolated) bodies and dispatch
159
+ * collision events. {@link Scene} calls this every frame before characters
160
+ * update; call it yourself only on a world you drive by hand.
161
+ */
162
+ step(dt: number): void;
163
+ /** Free every body, joint and the world. {@link Scene.destroy} calls it. */
164
+ destroy(): void;
165
+ private _assertAlive;
166
+ private _simulationChanged;
167
+ /**
168
+ * `body` frees and re-creates its btRigidBody inside `replace`: the joints
169
+ * that hold it let go first and are re-made against the new one after.
170
+ */
171
+ private _nativeReplacing;
172
+ private _bodyFromNative;
173
+ /**
174
+ * Drop a body's own contact bookkeeping. Bodies it was touching keep it in
175
+ * theirs, so the next sub-step ends those collisions and they get their
176
+ * `collisionend` / `triggerleave`, as in PlayCanvas.
177
+ */
178
+ private _forgetCollisions;
179
+ /**
180
+ * Read this sub-step's contact manifolds into events. PlayCanvas's
181
+ * `onContactPair` logic: contact points are gathered only for bodies with
182
+ * listeners, a pair is new if it was not touching last sub-step, and a pair
183
+ * that stopped touching ends. Events are queued, not fired, because this
184
+ * may run inside Bullet's step, where a listener removing a body would
185
+ * free memory the solver is still using.
186
+ * @internal
187
+ */
188
+ _walkContacts(): void;
189
+ /** Record `body` touching `other` this sub-step; true if it was not touching last time. */
190
+ private _store;
191
+ private _enqueue;
192
+ private _flushEvents;
193
+ }
@@ -0,0 +1,361 @@
1
+ import { BufferGeometry, EventDispatcher, Euler, Object3D, Quaternion, Vector3 } from 'three';
2
+ import type { AmmoDynamicsWorld, AmmoQuat, AmmoRigidBody, AmmoTransform, AmmoVec3 } from './ammo';
3
+ import type { PhysicsWorld } from './physics-world';
4
+ /** Anything with `x`, `y`, `z`: a `THREE.Vector3`, or a plain object. @group Physics */
5
+ export interface XYZ {
6
+ x: number;
7
+ y: number;
8
+ z: number;
9
+ }
10
+ /** Anything with `x`, `y`, `z`, `w`: a `THREE.Quaternion`, or a plain object. @group Physics */
11
+ export interface XYZW {
12
+ x: number;
13
+ y: number;
14
+ z: number;
15
+ w: number;
16
+ }
17
+ /**
18
+ * How a body moves. As in PlayCanvas: `'static'` never moves, `'dynamic'` is
19
+ * simulated and writes its pose to the object, `'kinematic'` follows the
20
+ * object and pushes dynamic bodies out of the way.
21
+ *
22
+ * @group Physics
23
+ */
24
+ export type RigidBodyType = 'static' | 'dynamic' | 'kinematic';
25
+ /**
26
+ * Collision shape, in the same terms as PlayCanvas's `collision` component.
27
+ * `axis` is 0 = X, 1 = Y (default), 2 = Z. A capsule's `height` includes its
28
+ * two caps. Primitive shapes ignore the object's scale, as in PlayCanvas.
29
+ *
30
+ * `'mesh'` builds a static triangle mesh from every `Mesh` under `geometry`
31
+ * (or from the geometry itself), in the body object's frame with its world
32
+ * scale baked in. Bullet cannot simulate a triangle mesh as a dynamic body:
33
+ * pass `convexHull: true` for a moving one.
34
+ *
35
+ * @group Physics
36
+ */
37
+ export type CollisionShape = {
38
+ type: 'box';
39
+ halfExtents: XYZ;
40
+ } | {
41
+ type: 'sphere';
42
+ radius: number;
43
+ } | {
44
+ type: 'capsule';
45
+ radius: number;
46
+ height: number;
47
+ axis?: 0 | 1 | 2;
48
+ } | {
49
+ type: 'cylinder';
50
+ radius: number;
51
+ height: number;
52
+ axis?: 0 | 1 | 2;
53
+ } | {
54
+ type: 'cone';
55
+ radius: number;
56
+ height: number;
57
+ axis?: 0 | 1 | 2;
58
+ } | {
59
+ type: 'mesh';
60
+ geometry: BufferGeometry | Object3D;
61
+ convexHull?: boolean;
62
+ };
63
+ /**
64
+ * Options for {@link PhysicsWorld.addBody}. Every default matches
65
+ * PlayCanvas's `rigidbody` component.
66
+ *
67
+ * @group Physics
68
+ */
69
+ export interface RigidBodyOptions {
70
+ shape: CollisionShape;
71
+ /** Default `'static'`. */
72
+ type?: RigidBodyType;
73
+ /** Kilograms; only dynamic bodies have mass. Default `1`. */
74
+ mass?: number;
75
+ /** Default `0.5`. */
76
+ friction?: number;
77
+ /** Default `0`. */
78
+ rollingFriction?: number;
79
+ /** Default `0`. */
80
+ restitution?: number;
81
+ /** Default `0`. */
82
+ linearDamping?: number;
83
+ /** Default `0`. */
84
+ angularDamping?: number;
85
+ /** Per-axis multiplier on linear motion; `(1, 1, 0)` keeps a body in the XY plane. Default `(1, 1, 1)`. */
86
+ linearFactor?: XYZ;
87
+ /** Per-axis multiplier on rotation. Default `(1, 1, 1)`. */
88
+ angularFactor?: XYZ;
89
+ /** Multiplier on the world's gravity. Default `1`. */
90
+ gravityScale?: number;
91
+ /** Collision group bits. Default from {@link type}: dynamic 1, static 2, kinematic 4. */
92
+ group?: number;
93
+ /** Groups this body collides with. Default: static `BODYMASK_NOT_STATIC`, others `BODYMASK_ALL`. */
94
+ mask?: number;
95
+ /** Shape position in the object's frame (PlayCanvas `collision.linearOffset`). */
96
+ linearOffset?: XYZ;
97
+ /** Shape rotation in the object's frame (PlayCanvas `collision.angularOffset`). */
98
+ angularOffset?: XYZW;
99
+ /**
100
+ * A sensor: no collision response, follows the object every step and fires
101
+ * `triggerenter` / `triggerleave`. PlayCanvas's `collision` component
102
+ * without a `rigidbody`. `type`, `mass` and the material options are
103
+ * ignored. Default `false`.
104
+ */
105
+ trigger?: boolean;
106
+ /** Whether the body starts in the simulation. Default `true`. */
107
+ enabled?: boolean;
108
+ }
109
+ /**
110
+ * One point of contact between two bodies, seen from the body the event is
111
+ * dispatched on. PlayCanvas's `ContactPoint`.
112
+ *
113
+ * @group Physics
114
+ */
115
+ export interface ContactPoint {
116
+ /** On this body, in its local frame. */
117
+ localPoint: Vector3;
118
+ /** On the other body, in its local frame. */
119
+ localPointOther: Vector3;
120
+ /** On this body, world space. */
121
+ point: Vector3;
122
+ /** On the other body, world space. */
123
+ pointOther: Vector3;
124
+ /** World-space contact normal, pointing from the other body toward this one. */
125
+ normal: Vector3;
126
+ /** Impulse the solver applied at this point, N·s. */
127
+ impulse: number;
128
+ }
129
+ /**
130
+ * Payload of `contact` and `collisionstart`. PlayCanvas's `ContactResult`,
131
+ * with `other` the other body's object.
132
+ *
133
+ * @group Physics
134
+ */
135
+ export interface ContactResult {
136
+ other: Object3D;
137
+ otherBody: RigidBody;
138
+ contacts: ContactPoint[];
139
+ }
140
+ /** Payload of `collisionend`, `triggerenter` and `triggerleave`. @group Physics */
141
+ export interface BodyPairEvent {
142
+ other: Object3D;
143
+ otherBody: RigidBody;
144
+ }
145
+ /**
146
+ * Events a {@link RigidBody} dispatches, with PlayCanvas's names. They fire
147
+ * after the step that produced them, once every dynamic object is in place.
148
+ *
149
+ * - `contact`: every physics sub-step the bodies touch.
150
+ * - `collisionstart` / `collisionend`: the first and the first-not-touching sub-step.
151
+ * - `triggerenter` / `triggerleave`: on both a trigger and the body entering it.
152
+ *
153
+ * @group Physics
154
+ */
155
+ export interface RigidBodyEventMap {
156
+ contact: ContactResult;
157
+ collisionstart: ContactResult;
158
+ collisionend: BodyPairEvent;
159
+ triggerenter: BodyPairEvent;
160
+ triggerleave: BodyPairEvent;
161
+ }
162
+ /** @group Physics */ export declare const BODYGROUP_NONE = 0;
163
+ /** @group Physics */ export declare const BODYGROUP_DEFAULT = 1;
164
+ /** @group Physics */ export declare const BODYGROUP_DYNAMIC = 1;
165
+ /** @group Physics */ export declare const BODYGROUP_STATIC = 2;
166
+ /** @group Physics */ export declare const BODYGROUP_KINEMATIC = 4;
167
+ /** @group Physics */ export declare const BODYGROUP_ENGINE_1 = 8;
168
+ /** @group Physics */ export declare const BODYGROUP_TRIGGER = 16;
169
+ /** @group Physics */ export declare const BODYGROUP_ENGINE_2 = 32;
170
+ /** @group Physics */ export declare const BODYGROUP_ENGINE_3 = 64;
171
+ /** @group Physics */ export declare const BODYGROUP_USER_1 = 128;
172
+ /** @group Physics */ export declare const BODYGROUP_USER_2 = 256;
173
+ /** @group Physics */ export declare const BODYGROUP_USER_3 = 512;
174
+ /** @group Physics */ export declare const BODYGROUP_USER_4 = 1024;
175
+ /** @group Physics */ export declare const BODYGROUP_USER_5 = 2048;
176
+ /** @group Physics */ export declare const BODYGROUP_USER_6 = 4096;
177
+ /** @group Physics */ export declare const BODYGROUP_USER_7 = 8192;
178
+ /** @group Physics */ export declare const BODYGROUP_USER_8 = 16384;
179
+ /** @group Physics */ export declare const BODYMASK_NONE = 0;
180
+ /** @group Physics */ export declare const BODYMASK_ALL = 65535;
181
+ /** @group Physics */ export declare const BODYMASK_STATIC = 2;
182
+ /** @group Physics */ export declare const BODYMASK_NOT_STATIC: number;
183
+ /** @group Physics */ export declare const BODYMASK_NOT_STATIC_KINEMATIC: number;
184
+ /**
185
+ * The parts of {@link PhysicsWorld} a body calls into. Kept narrow so the two
186
+ * classes don't reach into each other's state.
187
+ * @internal
188
+ */
189
+ export interface BodyHost {
190
+ readonly world: PhysicsWorld;
191
+ readonly gravity: Vector3;
192
+ readonly native: AmmoDynamicsWorld;
193
+ readonly btVec1: AmmoVec3;
194
+ readonly btVec2: AmmoVec3;
195
+ readonly btTransform: AmmoTransform;
196
+ readonly btQuat: AmmoQuat;
197
+ simulationChanged(body: RigidBody, inWorld: boolean): void;
198
+ /** Run `replace`, which frees and re-creates `body`'s btRigidBody, with its joints let go meanwhile. */
199
+ nativeReplacing(body: RigidBody, replace: () => void): void;
200
+ }
201
+ /**
202
+ * A rigid body attached to a `THREE.Object3D`: PlayCanvas's `rigidbody` and
203
+ * `collision` components in one object. Create one with
204
+ * {@link PhysicsWorld.addBody}; {@link PhysicsWorld.getBody} finds it again
205
+ * from the object.
206
+ *
207
+ * A dynamic body writes its pose into the object's `position` and
208
+ * `quaternion` after each step (converted into the parent's frame, so the
209
+ * object may sit anywhere in the graph; its own scale is left alone). A
210
+ * kinematic body or a trigger reads the object's world pose before each step.
211
+ * A static body reads it when created, enabled or {@link teleport}ed.
212
+ *
213
+ * Events use three.js's `addEventListener`; see {@link RigidBodyEventMap}.
214
+ *
215
+ * @group Physics
216
+ */
217
+ export declare class RigidBody extends EventDispatcher<RigidBodyEventMap> {
218
+ /** The object this body moves (dynamic) or follows (kinematic, trigger). */
219
+ readonly object: Object3D;
220
+ /** The shape description the body was built from. */
221
+ readonly shape: CollisionShape;
222
+ /** True for a sensor body; see {@link RigidBodyOptions.trigger}. */
223
+ readonly isTrigger: boolean;
224
+ /** @internal Key for looking the body up from a Bullet pointer (`btRigidBody` user index). */
225
+ readonly _id: number;
226
+ private readonly _host;
227
+ private _ammoShape;
228
+ /** Native objects the shape keeps alive (triangle meshes), freed with it. */
229
+ private readonly _shapeParts;
230
+ private _body;
231
+ private _type;
232
+ private _mass;
233
+ private _friction;
234
+ private _rollingFriction;
235
+ private _restitution;
236
+ private _linearDamping;
237
+ private _angularDamping;
238
+ private readonly _linearFactor;
239
+ private readonly _angularFactor;
240
+ private _gravityScale;
241
+ private _group;
242
+ private _mask;
243
+ private _enabled;
244
+ private _inWorld;
245
+ private readonly _linearOffset;
246
+ private readonly _angularOffset;
247
+ private readonly _linearVelocity;
248
+ private readonly _angularVelocity;
249
+ /** @internal Use {@link PhysicsWorld.addBody}. */
250
+ constructor(host: BodyHost, id: number, object: Object3D, opts: RigidBodyOptions);
251
+ /**
252
+ * The Bullet `btRigidBody`, for what this wrapper does not cover: CCD
253
+ * (`setCcdMotionThreshold`), raw constraints on
254
+ * {@link PhysicsWorld.dynamicsWorld}. PlayCanvas's `rigidbody.body`.
255
+ * `null` once the body is removed.
256
+ */
257
+ get ammoBody(): AmmoRigidBody | null;
258
+ /** The world this body belongs to. */
259
+ get world(): PhysicsWorld;
260
+ /** Whether the body is in the simulation. Disabling takes it out without destroying it. */
261
+ get enabled(): boolean;
262
+ set enabled(v: boolean);
263
+ /**
264
+ * Body type. Changing it rebuilds the body and resets {@link group} and
265
+ * {@link mask} to the new type's defaults, as in PlayCanvas.
266
+ */
267
+ get type(): RigidBodyType;
268
+ set type(t: RigidBodyType);
269
+ /** Collision group bits. Setting it re-adds the body to the world. */
270
+ get group(): number;
271
+ set group(g: number);
272
+ /** Groups this body collides with. Setting it re-adds the body to the world. */
273
+ get mask(): number;
274
+ set mask(m: number);
275
+ /** Kilograms. Only dynamic bodies use it. */
276
+ get mass(): number;
277
+ set mass(m: number);
278
+ get friction(): number;
279
+ set friction(v: number);
280
+ get rollingFriction(): number;
281
+ set rollingFriction(v: number);
282
+ get restitution(): number;
283
+ set restitution(v: number);
284
+ get linearDamping(): number;
285
+ set linearDamping(v: number);
286
+ get angularDamping(): number;
287
+ set angularDamping(v: number);
288
+ /** Per-axis multiplier on linear motion. Assign a vector; mutating the returned one does nothing. */
289
+ get linearFactor(): Vector3;
290
+ set linearFactor(f: XYZ);
291
+ /** Per-axis multiplier on rotation. Assign a vector; mutating the returned one does nothing. */
292
+ get angularFactor(): Vector3;
293
+ set angularFactor(f: XYZ);
294
+ /** Multiplier on the world's gravity for this body. */
295
+ get gravityScale(): number;
296
+ set gravityScale(s: number);
297
+ /**
298
+ * World-space linear velocity, m/s. Dynamic bodies only. The getter returns
299
+ * one reused vector; clone it to keep it. Setting it wakes the body.
300
+ */
301
+ get linearVelocity(): Vector3;
302
+ set linearVelocity(v: XYZ);
303
+ /** World-space angular velocity, rad/s. Same rules as {@link linearVelocity}. */
304
+ get angularVelocity(): Vector3;
305
+ set angularVelocity(v: XYZ);
306
+ /**
307
+ * Apply a world-space force (N) for the next step, at `relativePoint`
308
+ * (world-space offset from the centre of mass; default the centre).
309
+ */
310
+ applyForce(force: XYZ, relativePoint?: XYZ): void;
311
+ /** Apply a world-space impulse (N·s) at `relativePoint` (as {@link applyForce}). */
312
+ applyImpulse(impulse: XYZ, relativePoint?: XYZ): void;
313
+ /** Apply a world-space torque (N·m) for the next step. */
314
+ applyTorque(torque: XYZ): void;
315
+ /** Apply a world-space angular impulse (N·m·s). */
316
+ applyTorqueImpulse(torque: XYZ): void;
317
+ /** Whether Bullet is simulating the body this step (it sleeps once it comes to rest). */
318
+ isActive(): boolean;
319
+ /** Wake the body. */
320
+ activate(): void;
321
+ /**
322
+ * Move the object and the body to a world-space position, and optionally a
323
+ * world-space rotation (a quaternion, or an Euler in radians). Velocities
324
+ * are kept. PlayCanvas's `rigidbody.teleport`.
325
+ */
326
+ teleport(position: XYZ, rotation?: XYZW | Euler): void;
327
+ /** @internal Kinematic bodies: the object's pose becomes the motion-state target. */
328
+ _updateKinematic(): void;
329
+ /** @internal Triggers follow the object as if teleported every step. */
330
+ _updateTrigger(): void;
331
+ /**
332
+ * @internal Dynamic bodies: write the motion state's pose, which Bullet
333
+ * interpolates between fixed steps, into the object. Sleeping bodies are
334
+ * skipped, so an object moved by hand stays put until the body wakes.
335
+ */
336
+ _updateDynamic(): void;
337
+ /** @internal Re-apply gravity to a body with its own gravity scale after the world gravity changed. */
338
+ _onGravityChanged(): void;
339
+ /** @internal Whether contacts must be gathered for this body's listeners. */
340
+ _wantsContacts(): boolean;
341
+ /** @internal Free every native object. Called by {@link PhysicsWorld.removeBody}. */
342
+ _destroy(): void;
343
+ /** The object's world pose, moved to where the shape sits (collision offsets). */
344
+ private _readObjectPose;
345
+ /** Place the body where the object is: PlayCanvas's `syncEntityToBody`. */
346
+ private _syncObjectToBody;
347
+ private _createBody;
348
+ private _destroyBody;
349
+ private _enableSimulation;
350
+ private _disableSimulation;
351
+ private _readd;
352
+ private _applyGravityScale;
353
+ private _bt;
354
+ private _bt2;
355
+ private _btXform;
356
+ }
357
+ /**
358
+ * Give `object` this world-space position and rotation by solving for its
359
+ * local transform under its parent. The object's own scale is kept.
360
+ */
361
+ export declare function setObjectWorldPose(object: Object3D, pos: Vector3, quat: Quaternion): void;
@@ -0,0 +1,43 @@
1
+ import type { Object3D } from 'three';
2
+ /**
3
+ * Host context every camera preset attaches to: the canvas it takes input
4
+ * from and the camera it moves. `Scene` supplies both as `scene.canvas` and
5
+ * `scene.camera`.
6
+ *
7
+ * @group Presets
8
+ */
9
+ export interface CameraHost {
10
+ canvas: HTMLCanvasElement;
11
+ /** The camera (or any object) the preset positions and orients. */
12
+ camera: Object3D;
13
+ }
14
+ /**
15
+ * The shape every built-in camera conforms to: construct with config,
16
+ * `attach` to the host, `update` each frame, `detach` on teardown.
17
+ *
18
+ * @group Presets
19
+ */
20
+ export interface CameraPreset {
21
+ attach(host: CameraHost): void;
22
+ update(dt: number): void;
23
+ detach(): void;
24
+ /** Exposed so controllers can use camera yaw to interpret movement input. */
25
+ readonly yaw: number;
26
+ }
27
+ /**
28
+ * A position as a plain `{ x, y, z }`, so a `THREE.Vector3` and an ad-hoc
29
+ * literal both satisfy it.
30
+ *
31
+ * @group Presets
32
+ */
33
+ export type Vec3Like = {
34
+ x: number;
35
+ y: number;
36
+ z: number;
37
+ };
38
+ /**
39
+ * Position supplier - what a camera follows, read every frame.
40
+ *
41
+ * @group Presets
42
+ */
43
+ export type TargetSupplier = () => Vec3Like;
@@ -0,0 +1,63 @@
1
+ import type { CameraHost, CameraPreset, TargetSupplier } from './camera-preset';
2
+ /**
3
+ * Options for {@link ThirdPersonCamera}.
4
+ *
5
+ * @group Presets
6
+ */
7
+ export interface ThirdPersonCameraOptions {
8
+ /** Position the camera orbits around, read each frame. */
9
+ target: TargetSupplier;
10
+ /** Default 4. */
11
+ distance?: number;
12
+ /** LookAt vertical offset above target. Default 1.2. */
13
+ height?: number;
14
+ /** Initial pitch (degrees, downward positive). Default 15. */
15
+ pitch?: number;
16
+ /** Mouse-look sensitivity in degrees per pixel. Default 0.2. */
17
+ mouseSensitivity?: number;
18
+ }
19
+ /**
20
+ * Third-person follow camera.
21
+ *
22
+ * Orbits behind a target position at `distance` with adjustable `yaw`/`pitch`
23
+ * (degrees), looking at `target + (0, height, 0)`. Yaw 0 puts the camera on
24
+ * the target's +Z side. Mouse handling via pointer lock (click the canvas to
25
+ * capture, Escape to release). No smoothing.
26
+ *
27
+ * @example
28
+ * ```ts
29
+ * const cam = new ThirdPersonCamera({ target: () => hero.getPosition(), distance: 5, pitch: 25 });
30
+ * cam.attach({ canvas: scene.canvas, camera: scene.camera });
31
+ * scene.on('update', (dt) => cam.update(dt));
32
+ * ```
33
+ *
34
+ * @group Presets
35
+ */
36
+ export declare class ThirdPersonCamera implements CameraPreset {
37
+ yaw: number;
38
+ pitch: number;
39
+ distance: number;
40
+ height: number;
41
+ mouseSensitivity: number;
42
+ /** When false, mouse-look stops mutating yaw/pitch and the canvas no
43
+ * longer grabs pointer lock. The follow `update()` still runs, so a
44
+ * scripted camera move (e.g. a death cutscene) can drive yaw/pitch/
45
+ * distance/height itself without the player fighting it. Setting this
46
+ * false also releases an active pointer lock. */
47
+ get inputEnabled(): boolean;
48
+ set inputEnabled(v: boolean);
49
+ private _target;
50
+ private _host;
51
+ private _pointerLocked;
52
+ private _inputEnabled;
53
+ private _scratchPos;
54
+ private _scratchLook;
55
+ constructor(config: ThirdPersonCameraOptions);
56
+ attach(host: CameraHost): void;
57
+ detach(): void;
58
+ /** Place the camera for this frame. Call after the target has moved. */
59
+ update(_dt: number): void;
60
+ private _onClickToLock;
61
+ private _onLockChange;
62
+ private _onMouseMove;
63
+ }