@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
@@ -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>;
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Internal math kernel for the skeletal core.
2
+ * The math kernel of the skeletal core: PlayCanvas's `Vec3` / `Quat` / `Mat4`.
3
3
  *
4
4
  * The rig, animation and skinning code is shared with the PlayCanvas build of
5
5
  * this engine and was written against that engine's `Vec3` / `Quat` / `Mat4`.
@@ -9,17 +9,31 @@
9
9
  *
10
10
  * Deliberately NOT `THREE.Vector3` and friends: the conventions differ in ways
11
11
  * that silently change results (`lerp(a, b, t)` vs `lerp(v, t)`, a two-argument
12
- * `cross`, a `Float32Array`-backed matrix), and a port that swapped them by
13
- * hand would be a port nobody could diff against the original.
12
+ * `cross`, a `Float32Array`-backed matrix, angles in degrees), and a port that
13
+ * swapped them by hand would be a port nobody could diff against the original.
14
14
  *
15
- * Nothing here is part of the public API. Values cross into three.js types at
16
- * the `Character` / `Armature` boundary.
15
+ * Exported because `Pose`, `Armature.getBoneWorldMatrix` and the rest of the
16
+ * rig hand these out, and game code ported from the PlayCanvas build calls
17
+ * PlayCanvas methods on them. Each class carries the whole of PlayCanvas
18
+ * 2.23's API for that class (`Vec4` arguments take any `{x, y, z, w}`), with
19
+ * its formulas, so such code can import them in place of `pc.Vec3` and
20
+ * friends. `Mat4.data` has the layout of `THREE.Matrix4.elements`:
21
+ * `new Matrix4().fromArray(m.data)` crosses over.
22
+ *
23
+ * @module
24
+ * @group Math
25
+ */
26
+ /**
27
+ * PlayCanvas's `Vec3`.
28
+ *
29
+ * @group Math
17
30
  */
18
31
  export declare class Vec3 {
19
32
  x: number;
20
33
  y: number;
21
34
  z: number;
22
- constructor(x?: number, y?: number, z?: number);
35
+ /** Three numbers, or one array-like of three. */
36
+ constructor(x?: number | ArrayLike<number>, y?: number, z?: number);
23
37
  set(x: number, y: number, z: number): this;
24
38
  copy(rhs: {
25
39
  x: number;
@@ -29,20 +43,72 @@ export declare class Vec3 {
29
43
  clone(): Vec3;
30
44
  add(rhs: Vec3): this;
31
45
  add2(lhs: Vec3, rhs: Vec3): this;
46
+ sub(rhs: Vec3): this;
32
47
  sub2(lhs: Vec3, rhs: Vec3): this;
33
48
  mulScalar(scalar: number): this;
34
49
  dot(rhs: Vec3): number;
35
50
  cross(lhs: Vec3, rhs: Vec3): this;
36
51
  length(): number;
37
- normalize(): this;
52
+ /** Normalize `src` (default: this) into this. A zero vector is left as it was. */
53
+ normalize(src?: Vec3): this;
38
54
  lerp(lhs: Vec3, rhs: Vec3, alpha: number): this;
55
+ addScalar(scalar: number): this;
56
+ /** `this += rhs * scalar`. */
57
+ addScaled(rhs: Vec3, scalar: number): this;
58
+ subScalar(scalar: number): this;
59
+ /** Component-wise. */
60
+ mul(rhs: Vec3): this;
61
+ /** Component-wise. */
62
+ mul2(lhs: Vec3, rhs: Vec3): this;
63
+ /** {@link mulScalar}. */
64
+ scale(scalar: number): this;
65
+ /** Component-wise. */
66
+ div(rhs: Vec3): this;
67
+ /** Component-wise. */
68
+ div2(lhs: Vec3, rhs: Vec3): this;
69
+ divScalar(scalar: number): this;
70
+ distance(rhs: Vec3): number;
71
+ distanceSq(rhs: Vec3): number;
72
+ lengthSq(): number;
73
+ equals(rhs: Vec3): boolean;
74
+ equalsApprox(rhs: Vec3, epsilon?: number): boolean;
75
+ floor(src?: Vec3): this;
76
+ ceil(src?: Vec3): this;
77
+ round(src?: Vec3): this;
78
+ /** Component-wise minimum with `rhs`. */
79
+ min(rhs: Vec3): this;
80
+ /** Component-wise maximum with `rhs`. */
81
+ max(rhs: Vec3): this;
82
+ /** Project this onto `rhs`. */
83
+ project(rhs: Vec3): this;
84
+ /** Read three numbers from `arr` at `offset`; missing ones keep their value. */
85
+ fromArray(arr: ArrayLike<number>, offset?: number): this;
86
+ toArray<T extends {
87
+ [i: number]: number;
88
+ } = number[]>(arr?: T, offset?: number): T;
89
+ toString(): string;
90
+ static readonly ZERO: Readonly<Vec3>;
91
+ static readonly HALF: Readonly<Vec3>;
92
+ static readonly ONE: Readonly<Vec3>;
93
+ static readonly UP: Readonly<Vec3>;
94
+ static readonly DOWN: Readonly<Vec3>;
95
+ static readonly RIGHT: Readonly<Vec3>;
96
+ static readonly LEFT: Readonly<Vec3>;
97
+ static readonly FORWARD: Readonly<Vec3>;
98
+ static readonly BACK: Readonly<Vec3>;
39
99
  }
100
+ /**
101
+ * PlayCanvas's `Quat`. Angles in and out are in degrees.
102
+ *
103
+ * @group Math
104
+ */
40
105
  export declare class Quat {
41
106
  x: number;
42
107
  y: number;
43
108
  z: number;
44
109
  w: number;
45
- constructor(x?: number, y?: number, z?: number, w?: number);
110
+ /** Four numbers, or one array-like of four. */
111
+ constructor(x?: number | ArrayLike<number>, y?: number, z?: number, w?: number);
46
112
  set(x: number, y: number, z: number, w: number): this;
47
113
  copy(rhs: {
48
114
  x: number;
@@ -51,19 +117,77 @@ export declare class Quat {
51
117
  w: number;
52
118
  }): this;
53
119
  clone(): Quat;
54
- conjugate(): this;
120
+ /** Conjugate `src` (default: this) into this. */
121
+ conjugate(src?: Quat): this;
55
122
  dot(other: Quat): number;
56
123
  length(): number;
57
- mulScalar(scalar: number): this;
58
- normalize(): this;
124
+ /** `this = src * scalar`, `src` defaulting to this. */
125
+ mulScalar(scalar: number, src?: Quat): this;
126
+ /** Normalize `src` (default: this) into this; a zero quaternion becomes the identity. */
127
+ normalize(src?: Quat): this;
59
128
  /** `this = lhs * rhs`. Safe when `this` aliases either operand. */
60
129
  mul2(lhs: Quat, rhs: Quat): this;
61
130
  mul(rhs: Quat): this;
62
131
  slerp(lhs: Quat, rhs: Quat, alpha: number): this;
132
+ /** Rotate `vec` by this quaternion. */
133
+ transformVector(vec: {
134
+ x: number;
135
+ y: number;
136
+ z: number;
137
+ }, res?: Vec3): Vec3;
63
138
  /** Rotation of the upper 3x3 of `m`, with any scale (and a mirror) divided out. */
64
139
  setFromMat4(m: Mat4): this;
140
+ lengthSq(): number;
141
+ /** The inverse of `src` (default: this), into this. */
142
+ invert(src?: Quat): this;
143
+ /** Normalized linear blend from `lhs` to `rhs`, taking the short way round. */
144
+ lerp(lhs: Quat, rhs: Quat, alpha: number): this;
145
+ equals(rhs: Quat): boolean;
146
+ equalsApprox(rhs: Quat, epsilon?: number): boolean;
147
+ /** A rotation of `angle` degrees about the unit vector `axis`. */
148
+ setFromAxisAngle(axis: {
149
+ x: number;
150
+ y: number;
151
+ z: number;
152
+ }, angle: number): this;
153
+ /**
154
+ * Write this rotation's axis into `axis` and return its angle in degrees.
155
+ * The axis is flipped to have no negative component where it can be, the
156
+ * angle with it.
157
+ */
158
+ getAxisAngle(axis: {
159
+ x: number;
160
+ y: number;
161
+ z: number;
162
+ }): number;
163
+ /** From Euler angles in degrees, applied X, then Y, then Z (as PlayCanvas). */
164
+ setFromEulerAngles(ex: number | Vec3, ey?: number, ez?: number): this;
165
+ /** This rotation as Euler angles in degrees (see {@link setFromEulerAngles}). */
166
+ getEulerAngles(eulers?: Vec3): Vec3;
167
+ /** The shortest rotation taking unit vector `from` to unit vector `to`. */
168
+ setFromDirections(from: Vec3, to: Vec3): this;
169
+ /** Read four numbers from `arr` at `offset`; missing ones keep their value. */
170
+ fromArray(arr: ArrayLike<number>, offset?: number): this;
171
+ toArray<T extends {
172
+ [i: number]: number;
173
+ } = number[]>(arr?: T, offset?: number): T;
174
+ toString(): string;
175
+ static readonly IDENTITY: Readonly<Quat>;
176
+ static readonly ZERO: Readonly<Quat>;
65
177
  }
66
- /** Column-major 4x4, `Float32Array`-backed. Same element layout as `THREE.Matrix4.elements`. */
178
+ type XYZW = {
179
+ x: number;
180
+ y: number;
181
+ z: number;
182
+ w: number;
183
+ };
184
+ /**
185
+ * PlayCanvas's `Mat4`: column-major 4x4, `Float32Array`-backed, the same
186
+ * element layout as `THREE.Matrix4.elements`. Angles in and out are in
187
+ * degrees.
188
+ *
189
+ * @group Math
190
+ */
67
191
  export declare class Mat4 {
68
192
  data: Float32Array;
69
193
  constructor();
@@ -76,7 +200,68 @@ export declare class Mat4 {
76
200
  /** `this = lhs * rhs`. Safe when `this` aliases either operand. */
77
201
  mul2(lhs: Mat4, rhs: Mat4): this;
78
202
  mul(rhs: Mat4): this;
79
- invert(): this;
203
+ /** The inverse of `src` (default: this), into this. A singular matrix gives the identity. */
204
+ invert(src?: Mat4): this;
80
205
  getTranslation(t?: Vec3): Vec3;
81
206
  getScale(scale?: Vec3): Vec3;
207
+ /** Copy 16 column-major numbers in; {@link setFromArray} under PlayCanvas's name. */
208
+ set(src: ArrayLike<number>): this;
209
+ add2(lhs: Mat4, rhs: Mat4): this;
210
+ add(rhs: Mat4): this;
211
+ equals(rhs: Mat4): boolean;
212
+ isIdentity(): boolean;
213
+ /** `this = lhs * rhs` for affine matrices (the bottom rows taken as 0 0 0 1). */
214
+ mulAffine2(lhs: Mat4, rhs: Mat4): this;
215
+ /** `vec` as a point (w = 1) through this matrix. */
216
+ transformPoint(vec: {
217
+ x: number;
218
+ y: number;
219
+ z: number;
220
+ }, res?: Vec3): Vec3;
221
+ /** `vec` as a direction (w = 0) through this matrix. */
222
+ transformVector(vec: {
223
+ x: number;
224
+ y: number;
225
+ z: number;
226
+ }, res?: Vec3): Vec3;
227
+ transformVec4<T extends XYZW = XYZW>(vec: XYZW, res?: T): T;
228
+ /** A transform at `position` whose -Z looks at `target`, with `up` as near up as it can be. */
229
+ setLookAt(position: Vec3, target: Vec3, up: Vec3): this;
230
+ setFrustum(left: number, right: number, bottom: number, top: number, znear: number, zfar: number): this;
231
+ /** `fov` in degrees: vertical, or horizontal when `fovIsHorizontal`. */
232
+ setPerspective(fov: number, aspect: number, znear: number, zfar: number, fovIsHorizontal?: boolean): this;
233
+ setOrtho(left: number, right: number, bottom: number, top: number, near: number, far: number): this;
234
+ /** A rotation of `angle` degrees about the unit vector `axis`. */
235
+ setFromAxisAngle(axis: {
236
+ x: number;
237
+ y: number;
238
+ z: number;
239
+ }, angle: number): this;
240
+ setTranslate(x: number, y: number, z: number): this;
241
+ setScale(x: number, y: number, z: number): this;
242
+ setViewport(x: number, y: number, width: number, height: number): this;
243
+ /** Reflection about the plane `normal · p = distance`. */
244
+ setReflection(normal: {
245
+ x: number;
246
+ y: number;
247
+ z: number;
248
+ }, distance: number): this;
249
+ /** The transpose of `src` (default: this), into this. */
250
+ transpose(src?: Mat4): this;
251
+ /** The X axis (first column). */
252
+ getX(x?: Vec3): Vec3;
253
+ /** The Y axis (second column). */
254
+ getY(y?: Vec3): Vec3;
255
+ /** The Z axis (third column). */
256
+ getZ(z?: Vec3): Vec3;
257
+ /** `-1` when the axes are mirrored, else `1`. */
258
+ get scaleSign(): number;
259
+ /** A rotation from Euler angles in degrees (see {@link Quat.setFromEulerAngles}). */
260
+ setFromEulerAngles(ex: number, ey: number, ez: number): this;
261
+ /** The rotation as Euler angles in degrees, with any scale divided out. */
262
+ getEulerAngles(eulers?: Vec3): Vec3;
263
+ toString(): string;
264
+ static readonly IDENTITY: Readonly<Mat4>;
265
+ static readonly ZERO: Readonly<Mat4>;
82
266
  }
267
+ export {};