@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
@@ -1,19 +1,46 @@
1
+ declare function cacheKeyFor(url: string): string;
1
2
  /**
2
- * Fetch through a persistent Cache API layer with a 1-hour TTL.
3
- * - Assets with cacheable extensions (.bin, .vsplat, .anim, .ply, …) →
4
- * cached in Cache API
5
- * - Signed URLs (with ?verify= or ?X-Amz-) → query stripped for cache key
6
- * - No-store assets → never persisted. `NO_STORE_EXTENSIONS` is empty
7
- * today, so nothing takes this branch; see its declaration.
8
- * Server `Cache-Control: max-age` and `Expires` headers are honored as a cap
9
- * when they provide a positive TTL.
10
- * On network error, a stale cached copy is returned in preference to throwing.
3
+ * Delete expired entries and index the rest, so {@link cachedFetch} can start
4
+ * an uncached download without waiting on a Cache API lookup. Call once when
5
+ * the page is idle, before the first load; later calls share the first run.
6
+ * Resolves to the number of entries removed.
7
+ */
8
+ declare function indexAssetCache(): Promise<number>;
9
+ /**
10
+ * The fetch the engine downloads asset bytes with (`.bin` / `.vsplat`
11
+ * bundles, `.spz` / `.ply` splats, VFX sprite sheets). By default it is the
12
+ * engine's persistent Cache API layer (`engineCachedFetch` above); a host that
13
+ * installs its own with {@link setBinFetch} gets that instead.
11
14
  */
12
15
  declare function cachedFetch(url: string, init?: RequestInit): Promise<Response>;
13
16
  /**
14
- * Sweep the persistent cache and delete every entry whose stamp is in the
15
- * past. Intended to run once per app boot, non-blocking, to keep the Cache
16
- * API store from accumulating dead entries across sessions.
17
+ * Install the fetch the engine uses for asset bytes, in place of its own
18
+ * Cache API layer: for a host with its own caching stack. Call once at boot, before any asset loads. Pass `null`
19
+ * to go back to the engine's own.
20
+ */
21
+ declare function setBinFetch(fetchImpl: ((url: string) => Promise<Response>) | null): void;
22
+ /**
23
+ * Route every cacheable asset request made with `fetch` or `XMLHttpRequest`,
24
+ * including PlayCanvas's own (LOD octree chunks, textures, GLBs), through the
25
+ * persistent Cache API layer. Opt-in and global: it replaces
26
+ * `globalThis.fetch` and patches `XMLHttpRequest`. Requests for other URLs
27
+ * pass through untouched. A routed request keeps its headers, credentials
28
+ * mode and abort signal. Call once at boot; safe to call again.
29
+ * {@link uninstallFetchInterceptor} puts both back.
30
+ */
31
+ declare function installFetchInterceptor(): void;
32
+ /** Undo {@link installFetchInterceptor}: restore `fetch` and `XMLHttpRequest`. No-op when not installed. */
33
+ declare function uninstallFetchInterceptor(): void;
34
+ /**
35
+ * Whether a URL is in the persistent cache (and not expired), without
36
+ * fetching it. False for URLs the cache never stores, or with no Cache API.
37
+ */
38
+ declare function isCached(url: string): Promise<boolean>;
39
+ /**
40
+ * Former name of {@link indexAssetCache}, kept for compatibility: it
41
+ * still deletes expired entries and resolves to how many it removed.
42
+ *
43
+ * @deprecated Use {@link indexAssetCache}.
17
44
  */
18
- declare function evictExpired(): Promise<number>;
19
- export { cachedFetch, evictExpired };
45
+ declare const evictExpired: typeof indexAssetCache;
46
+ export { cacheKeyFor, cachedFetch, evictExpired, indexAssetCache, installFetchInterceptor, isCached, setBinFetch, uninstallFetchInterceptor, };
@@ -0,0 +1,27 @@
1
+ /**
2
+ * One worker, shared by every load, for the CPU-heavy half of an `.spz` or
3
+ * SOG decode, packing included: a million-splat unpack, Morton order and pack
4
+ * is the better part of a second of main thread on a phone otherwise.
5
+ *
6
+ * The worker is built from a Blob of the decode functions' own source text, as
7
+ * `AsyncDepthSorter` builds its sorter, so there is no second file for an
8
+ * application's bundler to lose. Each function is emitted under the name it
9
+ * has in this bundle, which is the name its callers use too - so whatever a
10
+ * bundler or minifier renamed, the functions still find each other.
11
+ */
12
+ import type { PackedSplats } from '../../splat/packed-splats';
13
+ import { decodeSpzTask } from '../environment/spz-decode';
14
+ import { decodeSogTask } from './sog-decode';
15
+ /** The decode tasks, by name, and what each takes. */
16
+ interface TaskInputs {
17
+ spz: Parameters<typeof decodeSpzTask>[0];
18
+ sog: Parameters<typeof decodeSogTask>[0];
19
+ }
20
+ /**
21
+ * Decode and pack in the shared worker - or on this thread where there are
22
+ * no workers (a test runner, a server render, a page whose CSP blocks them).
23
+ * The buffers in `transfer` are moved, not copied: the caller must not read
24
+ * them afterwards.
25
+ */
26
+ export declare function runDecodeTask<K extends keyof TaskInputs>(task: K, input: TaskInputs[K], transfer: ArrayBuffer[]): Promise<PackedSplats>;
27
+ export {};
@@ -0,0 +1,30 @@
1
+ import type { GLTF, GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
2
+ /**
3
+ * Use `loader` for {@link loadGlbFromUrl} - one configured with a
4
+ * `DRACOLoader`, `KTX2Loader` or `MeshoptDecoder` for GLBs that need them.
5
+ *
6
+ * @group Loaders
7
+ */
8
+ export declare function setGlbLoader(loader: GLTFLoader): void;
9
+ /** Callback form of {@link loadGlbFromUrl}: `(error message, null)` or `(null, gltf)`. */
10
+ export type GlbCallback = (err: string | null, gltf: GLTF | null) => void;
11
+ /**
12
+ * Load a `.glb` through the engine's asset cache (so it is served from the
13
+ * persistent cache like characters and clips) and parse it with three.js's
14
+ * `GLTFLoader`. Add `gltf.scene` to your scene, or clone it per use.
15
+ *
16
+ * The PlayCanvas build's `loadGlbFromUrl(app, url, callback)` handed back a
17
+ * container asset; this resolves the parsed `GLTF`. That call shape still
18
+ * works - the leading argument is accepted and not needed - and so does the
19
+ * callback, alongside the returned promise.
20
+ *
21
+ * @example
22
+ * ```ts
23
+ * const gltf = await loadGlbFromUrl('/assets/sword.glb');
24
+ * character.object3D.add(gltf.scene);
25
+ * ```
26
+ *
27
+ * @group Loaders
28
+ */
29
+ export declare function loadGlbFromUrl(url: string, callback?: GlbCallback): Promise<GLTF>;
30
+ export declare function loadGlbFromUrl(host: unknown, url: string, callback?: GlbCallback): Promise<GLTF>;
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Inflate `data`, refusing to produce more than `maxBytes`. A size the file
3
+ * declares is only an upper bound a hostile one sets itself, so callers cap
4
+ * it by what a valid file could hold; `capFromHead`, when given, tightens the
5
+ * cap once the first `headBytes` of output are in - a format whose header
6
+ * says how long the rest is. Runs in the decode worker too (see
7
+ * `decode-worker.ts`), so it uses nothing from outside itself.
8
+ */
9
+ export declare function inflateCapped(data: Uint8Array, format: 'gzip' | 'deflate-raw', maxBytes: number, headBytes?: number, capFromHead?: ((head: Uint8Array) => number) | null): Promise<Uint8Array>;
@@ -0,0 +1,17 @@
1
+ /**
2
+ * `packSplats` for the decode worker.
3
+ *
4
+ * Packing a million splats is ~100 ms of main thread on a desktop (half-float
5
+ * conversions and an `exp` per scale axis), several times that on a phone, so
6
+ * the worker packs what it decodes. `packSplats` itself cannot go there - it
7
+ * converts through three's `DataUtils.toHalfFloat`, and the worker has no
8
+ * three - so this is that function again with three's conversion inlined.
9
+ *
10
+ * IT MUST STAY BIT-IDENTICAL TO `packSplats` (splat/packed-splats.ts): an
11
+ * `.spz` and the same scene as `.ply` have to upload the same texels. Change
12
+ * the two together. Like the other worker functions it reads nothing at
13
+ * module scope.
14
+ */
15
+ import type { PackedSplats } from '../../splat/packed-splats';
16
+ import type { SplatAttributes } from '../character/types';
17
+ export declare function packSplatsInWorker(numSplats: number, s: SplatAttributes): PackedSplats;
@@ -0,0 +1,81 @@
1
+ /**
2
+ * The CPU half of a SOG decode (PlayCanvas's "Spatially Ordered Gaussians":
3
+ * a `meta.json` and lossless WebP images, unbundled or zipped as `.sog`):
4
+ * image bytes to pixels to the 3DGS PLY conventions of {@link SplatAttributes}.
5
+ * The arithmetic is PlayCanvas's `GSplatSogData.decompress`, as the PlayCanvas
6
+ * build's `sog-decode.ts` reproduces it.
7
+ *
8
+ * Like `spz-decode.ts`, these functions are also the decode worker's source
9
+ * text (`decode-worker.ts`), so they read nothing at module scope.
10
+ */
11
+ import type { SplatAttributes } from '../character/types';
12
+ /** A SOG `meta.json`: version 2 (codebooks), or the version 1 layout PlayCanvas still reads. */
13
+ export interface SogMeta {
14
+ version?: number;
15
+ /** Version 2. Version 1 has `means.shape[0]` instead. */
16
+ count?: number;
17
+ means: {
18
+ mins: number[];
19
+ maxs: number[];
20
+ files: string[];
21
+ shape?: number[];
22
+ };
23
+ scales: {
24
+ codebook?: (number | null)[];
25
+ mins?: number[];
26
+ maxs?: number[];
27
+ files: string[];
28
+ };
29
+ quats: {
30
+ files: string[];
31
+ };
32
+ sh0: {
33
+ codebook?: (number | null)[];
34
+ mins?: number[];
35
+ maxs?: number[];
36
+ files: string[];
37
+ };
38
+ }
39
+ /** RGBA8 pixels of the five images a DC-only decode reads, in file order (row-major from the top). */
40
+ export interface SogPixels {
41
+ means_l: Uint8Array;
42
+ means_u: Uint8Array;
43
+ quats: Uint8Array;
44
+ scales: Uint8Array;
45
+ sh0: Uint8Array;
46
+ }
47
+ /** Splat count of a SOG, from either version of its meta. */
48
+ export declare function sogCount(meta: SogMeta): number;
49
+ /**
50
+ * Decode images to their exact RGBA8 bytes.
51
+ *
52
+ * Not through a 2D canvas: `getImageData` hands back pixels that went through
53
+ * premultiplied storage, and SOG keeps data in alpha (opacity in `sh0.a`, the
54
+ * rotation's mode byte in `quats.a`), so every pixel with alpha below 255
55
+ * would come back with its colour quantised against it. An unpremultiplied
56
+ * `ImageBitmap` uploaded to a WebGL2 texture and read back is exact - and is
57
+ * what PlayCanvas itself does with these images.
58
+ */
59
+ export declare function readImagePixels(files: Uint8Array[]): Promise<Uint8Array[]>;
60
+ /**
61
+ * SOG pixels to splat attributes, with PlayCanvas's arithmetic:
62
+ *
63
+ * - centre: 16 bits per axis over `means.mins..maxs`, stored log-encoded
64
+ * (`sign(t) * (exp|t| - 1)`);
65
+ * - rotation: three components over `±sqrt(1/2)` and a mode byte (252-255)
66
+ * naming which one was dropped. A mode outside that range keeps the
67
+ * previous splat's rotation, as PlayCanvas's iterator does;
68
+ * - scale and colour: a byte each per channel into a codebook (version 2) or
69
+ * onto `mins..maxs` (version 1), colour as the SH DC term;
70
+ * - opacity: `sh0.a` is the alpha (version 2) or a logit byte (version 1),
71
+ * returned as a logit clamped to ±40.
72
+ */
73
+ export declare function decodeSogPixels(meta: SogMeta, px: SogPixels): SplatAttributes;
74
+ /** The worker's whole SOG job: the five images' bytes, in {@link SogPixels} order, to splat attributes. */
75
+ export declare function decodeSogTask(input: {
76
+ meta: SogMeta;
77
+ images: Uint8Array[];
78
+ }): Promise<{
79
+ numSplats: number;
80
+ splats: SplatAttributes;
81
+ }>;
@@ -0,0 +1,17 @@
1
+ /**
2
+ * SOG scenes: a `meta.json` beside its WebP images (what a streaming LOD
3
+ * bundle is made of, one per chunk), or the same files zipped into one `.sog`.
4
+ * Fetching and unzipping happen here; decoding the images and the splats is
5
+ * the decode worker's (`sog-decode.ts`).
6
+ */
7
+ import type { PackedSplats } from '../../splat/packed-splats';
8
+ /** `url` resolved against `base`, itself resolved against the page. */
9
+ export declare function resolveUrl(url: string, base: string): string;
10
+ /**
11
+ * Fetch and decode an unbundled SOG from its `meta.json`; the images are
12
+ * fetched from beside it. Higher SH bands (`shN`) are not fetched: splats here
13
+ * are lit by their DC colour.
14
+ */
15
+ export declare function loadSogMeta(url: string): Promise<PackedSplats>;
16
+ /** Decode a bundled `.sog` (a zip of `meta.json` and its images) held in memory. */
17
+ export declare function decodeSogBundle(file: Uint8Array): Promise<PackedSplats>;
@@ -29,6 +29,7 @@ export declare class Vec3 {
29
29
  clone(): Vec3;
30
30
  add(rhs: Vec3): this;
31
31
  add2(lhs: Vec3, rhs: Vec3): this;
32
+ sub(rhs: Vec3): this;
32
33
  sub2(lhs: Vec3, rhs: Vec3): this;
33
34
  mulScalar(scalar: number): this;
34
35
  dot(rhs: Vec3): number;
@@ -60,6 +61,12 @@ export declare class Quat {
60
61
  mul2(lhs: Quat, rhs: Quat): this;
61
62
  mul(rhs: Quat): this;
62
63
  slerp(lhs: Quat, rhs: Quat, alpha: number): this;
64
+ /** Rotate `vec` by this quaternion. */
65
+ transformVector(vec: {
66
+ x: number;
67
+ y: number;
68
+ z: number;
69
+ }, res?: Vec3): Vec3;
63
70
  /** Rotation of the upper 3x3 of `m`, with any scale (and a mirror) divided out. */
64
71
  setFromMat4(m: Mat4): this;
65
72
  }
@@ -0,0 +1,210 @@
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 AmmoGeneric6Dof extends AmmoConstraint {
99
+ setLinearLowerLimit(v: AmmoVec3): void;
100
+ setLinearUpperLimit(v: AmmoVec3): void;
101
+ setAngularLowerLimit(v: AmmoVec3): void;
102
+ setAngularUpperLimit(v: AmmoVec3): void;
103
+ }
104
+ /** @internal */
105
+ export interface AmmoManifoldPoint {
106
+ get_m_localPointA(): AmmoVec3;
107
+ get_m_localPointB(): AmmoVec3;
108
+ getPositionWorldOnA(): AmmoVec3;
109
+ getPositionWorldOnB(): AmmoVec3;
110
+ get_m_normalWorldOnB(): AmmoVec3;
111
+ getAppliedImpulse(): number;
112
+ }
113
+ /** @internal */
114
+ export interface AmmoManifold {
115
+ getBody0(): unknown;
116
+ getBody1(): unknown;
117
+ getNumContacts(): number;
118
+ getContactPoint(i: number): AmmoManifoldPoint;
119
+ }
120
+ /** @internal */
121
+ export interface AmmoDispatcher {
122
+ getNumManifolds(): number;
123
+ getManifoldByIndexInternal(i: number): AmmoManifold;
124
+ }
125
+ /** @internal */
126
+ export interface AmmoRayCallback {
127
+ set_m_collisionFilterGroup(g: number): void;
128
+ set_m_collisionFilterMask(m: number): void;
129
+ set_m_flags?(f: number): void;
130
+ hasHit(): boolean;
131
+ }
132
+ /** @internal */
133
+ export interface AmmoClosestRayCallback extends AmmoRayCallback {
134
+ get_m_collisionObject(): unknown;
135
+ get_m_hitPointWorld(): AmmoVec3;
136
+ get_m_hitNormalWorld(): AmmoVec3;
137
+ get_m_closestHitFraction(): number;
138
+ }
139
+ /** @internal */
140
+ export interface AmmoArray<T> {
141
+ size(): number;
142
+ at(i: number): T;
143
+ }
144
+ /** @internal */
145
+ export interface AmmoAllHitsRayCallback extends AmmoRayCallback {
146
+ get_m_collisionObjects(): AmmoArray<unknown>;
147
+ get_m_hitPointWorld(): AmmoArray<AmmoVec3>;
148
+ get_m_hitNormalWorld(): AmmoArray<AmmoVec3>;
149
+ get_m_hitFractions(): AmmoArray<number>;
150
+ }
151
+ /** A `btDiscreteDynamicsWorld`, exposed as {@link PhysicsWorld.dynamicsWorld} for raw constraints. @group Physics */
152
+ export interface AmmoDynamicsWorld {
153
+ setGravity(v: AmmoVec3): void;
154
+ stepSimulation(dt: number, maxSubSteps: number, fixedTimeStep: number): number;
155
+ addRigidBody(body: AmmoRigidBody, group?: number, mask?: number): void;
156
+ removeRigidBody(body: AmmoRigidBody): void;
157
+ addConstraint(c: AmmoConstraint, disableCollisionBetweenLinkedBodies?: boolean): void;
158
+ removeConstraint(c: AmmoConstraint): void;
159
+ rayTest(from: AmmoVec3, to: AmmoVec3, cb: AmmoRayCallback): void;
160
+ setInternalTickCallback?(fnPtr: number): void;
161
+ updateSingleAabb?(body: AmmoRigidBody): void;
162
+ }
163
+ type Ctor<T, A extends unknown[] = []> = new (...args: A) => T;
164
+ /** @internal */
165
+ export interface AmmoNS {
166
+ btVector3: Ctor<AmmoVec3, [number?, number?, number?]>;
167
+ btQuaternion: Ctor<AmmoQuat, [number, number, number, number]>;
168
+ btTransform: Ctor<AmmoTransform>;
169
+ btDefaultMotionState: Ctor<AmmoMotionState, [AmmoTransform]>;
170
+ btRigidBodyConstructionInfo: Ctor<unknown, [number, AmmoMotionState, AmmoShape, AmmoVec3]>;
171
+ btRigidBody: Ctor<AmmoRigidBody, [unknown]>;
172
+ btDefaultCollisionConfiguration: Ctor<unknown>;
173
+ btCollisionDispatcher: Ctor<AmmoDispatcher, [unknown]>;
174
+ btDbvtBroadphase: Ctor<unknown>;
175
+ btSequentialImpulseConstraintSolver: Ctor<unknown>;
176
+ btDiscreteDynamicsWorld: Ctor<AmmoDynamicsWorld, [AmmoDispatcher, unknown, unknown, unknown]>;
177
+ btBoxShape: Ctor<AmmoShape, [AmmoVec3]>;
178
+ btSphereShape: Ctor<AmmoShape, [number]>;
179
+ btCapsuleShape: Ctor<AmmoShape, [number, number]>;
180
+ btCapsuleShapeX: Ctor<AmmoShape, [number, number]>;
181
+ btCapsuleShapeZ: Ctor<AmmoShape, [number, number]>;
182
+ btCylinderShape: Ctor<AmmoShape, [AmmoVec3]>;
183
+ btCylinderShapeX: Ctor<AmmoShape, [AmmoVec3]>;
184
+ btCylinderShapeZ: Ctor<AmmoShape, [AmmoVec3]>;
185
+ btConeShape: Ctor<AmmoShape, [number, number]>;
186
+ btConeShapeX: Ctor<AmmoShape, [number, number]>;
187
+ btConeShapeZ: Ctor<AmmoShape, [number, number]>;
188
+ btConvexHullShape: Ctor<AmmoConvexHull>;
189
+ btTriangleMesh: Ctor<AmmoTriangleMesh>;
190
+ btBvhTriangleMeshShape: Ctor<AmmoShape, [AmmoTriangleMesh, boolean]>;
191
+ btConeTwistConstraint: Ctor<AmmoConeTwist, [AmmoRigidBody, AmmoRigidBody, AmmoTransform, AmmoTransform]>;
192
+ btHingeConstraint: Ctor<AmmoHinge, [AmmoRigidBody, AmmoRigidBody, AmmoVec3, AmmoVec3, AmmoVec3, AmmoVec3]>;
193
+ btGeneric6DofConstraint: Ctor<AmmoGeneric6Dof, [AmmoRigidBody, AmmoRigidBody, AmmoTransform, AmmoTransform, boolean]>;
194
+ ClosestRayResultCallback: Ctor<AmmoClosestRayCallback, [AmmoVec3, AmmoVec3]>;
195
+ AllHitsRayResultCallback: Ctor<AmmoAllHitsRayCallback, [AmmoVec3, AmmoVec3]>;
196
+ castObject<T>(obj: unknown, cls: Ctor<T, never[]>): T;
197
+ getPointer(obj: unknown): number;
198
+ addFunction?(fn: (...args: number[]) => void, signature: string): number;
199
+ destroy(obj: unknown): void;
200
+ }
201
+ /** `globalThis.Ammo`, or a clear error when physics was never set up. @internal */
202
+ export declare function ammo(): AmmoNS;
203
+ /** @internal */ export declare const CF_KINEMATIC_OBJECT = 2;
204
+ /** @internal */ export declare const CF_NO_CONTACT_RESPONSE = 4;
205
+ /** @internal */ export declare const ACTIVE_TAG = 1;
206
+ /** @internal */ export declare const DISABLE_DEACTIVATION = 4;
207
+ /** @internal */ export declare const DISABLE_SIMULATION = 5;
208
+ /** `btRigidBody` flag that stops the world's gravity overwriting a per-body gravity. @internal */
209
+ export declare const BT_DISABLE_WORLD_GRAVITY = 1;
210
+ 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 } from './joints';
7
+ export type { ConeTwistJointOptions, Generic6DofJointOptions, HingeJointOptions, JointHandle } 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,157 @@
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;