@woosh/meep-engine 2.131.17 → 2.131.20

package/README.md

@@ -1,126 +1,110 @@
 # Meep Engine
+**The unopinionated, high-performance ECS engine for code-first developers.**
 
-## Getting Started
+Meep is a battle-tested JavaScript game engine designed for scale. Built over 10+ years and used in commercial Steam releases, it strips away the bloat of traditional engines to offer a molecular, zero-allocation architecture.
 
-We offer a [minimal project](http://gitlab.company-named.com/travnik/dream-engine-template) with no bells or whistles, just enough to run the engine and get you starter. If you're starting from scratch this is likely the best option.
+It is designed for engineers who want full control, offering performance that rivals native code on the web.
 
-## Documentation
+[🚀 Quick Start Template](http://gitlab.company-named.com/travnik/dream-engine-template) | [📚 Documentation](http://meep-engine.company-named.com:8080/docs/getting_started/Installation)
 
-[Engine Documentation](http://meep-engine.company-named.com:8080/docs/getting_started/Installation)
+---
+
+## Why Meep?
+Most web engines are heavy, opinionated, and struggle with garbage collection. Meep is different.
+
+* **Pure ECS Architecture:** A true data-oriented foundation that supports complex hierarchies and millions of entities. Unlike hybrid engines, our component queries are instantaneous.
+* **Molecular Modularity:** Distributed as ~3,000 fine-grained modules. Need a lerp function? Import it for a 4-line footprint. You never pay for code you don't use.
+* **Zero-Garbage Architecture:** Custom memory management ensures stable frame rates. Meep handles millions of objects on low-spec mobile hardware without GC spikes.
+* **Code-First:** No GUI. No black boxes. Meep is a programmatic tool designed for software engineers who value architecture and long-term integration.
+* **Battle-Hardened:** Covered by 3,000+ unit tests and extensive assertions. This is not a prototype; it is industrial-grade software.
+
+---
+
+## 💎 Architecture: Pure ECS
+Meep is not yet another Object-Oriented engine with an ECS tacked on; it is a **Pure Entity Component System** engine.
+
+While other engines (like Unity) struggle with slow query times and documentation that advises you to use component lookups "sparingly" — Meep thrives on them.
+
+* **Strict Data-Oriented Design:** One component instance per type per entity. This guarantees memory layout optimization and cache locality.
+* **The Hierarchy Problem: Solved.**  Pure ECS architectures historically struggle with scene graphs and parent-child transforms. Meep solves this natively. You get the composability of a scene graph with the raw speed of a flat array. (Similar to the Rust-based Bevy engine).
+* **Tiered API Access:**
+  * **High-Level:** Use convenient abstraction layers for gameplay logic.
+  * **Low-Level:** Drop down to raw typed arrays for performance-critical paths.
+* **Uncompromised Speed:** Because the architecture is solid, you can query, filter, and iterate over millions of entities without performance cliffs.
+
+---
+
+## ⚡ High-Performance Rendering
+Meep implements a Clustered Forward+ rendering pipeline, allowing for scenes that traditional web engines choke on.
+
+* **Unlimited Lighting:** Render thousands of point lights (muzzle flashes, explosions, torches) with clustered lighting.
+
+* **GPU-Driven Decals:** Handle 1,000,000+ decals for persistent battle damage and environmental details.
+
+* **Massive Terrain:** Chunk-based, auto-culled terrain system supporting up to 256 layers (vs Unity's 4).
 
-## Samples
-To help get you started, various samples are provided under `/samples` folder. Feel free to use them as a point of reference.
+* **"Particular" Particle Engine:** A zero-allocation particle system with full lighting, soft particles, and automatic atlassing. Compiled into just 4 shaders to eliminate state-switching overhead.
 
-## Quality
+* **Path Tracing:** Includes a pure JS path tracer utilizing the engine's internal BVH.
 
-### Testing
-Meep is covered by 2,944 handwritten unit tests, reaching 90%+ coverage in `core` and 40%+ coverage total.
+## 🧠 AI & Simulation Tools
+Meep provides a suite of tools rarely found in JS engines, optimized for complex decision making.
 
-The aim is to [ensure quality](https://about.codecov.io/blog/the-case-against-100-code-coverage/). As a result, the tests are written to cover complex code first and to exhaustively validate critical algorithms.
-Most of the test code is significantly larger than the code that is being tested.
+* **Behavior Trees & Blackboards:** Industry-standard tools for state management.
 
-### Assertions
-Meep is covered by 3,968 asserts. [Assertions](https://en.wikipedia.org/wiki/Assertion_(software_development)) provide very extensive pre- and post-condition checks throughout the engine.
-Asserts are intended primarily for development builds.
-To remove asserts in Vite builds, you can use `@rollup/plugin-strip` package like so:
+* **Monte-Carlo Tree Search:** The same algorithm used in AlphaGo, available for your decision logic.
+
+* **Resource Allocation Solver:** Plan optimal actions based on limited resources (ammo, health, currency).
+
+* **Spatial Query System:** Highly optimized BVH for Ray, Box, Frustum, and Point queries.
+
+* **Inverse Kinematics:** Includes FABRIK solvers and specialized bip/quadruped solvers for uneven terrain adaptation.
+
+## 🛠️ Developer Experience
+
+### Installation & Stripping
+
+Meep is designed to be invisible in production.
+```shell
+npm install @woosh/meep-engine
+```
+
+**Development Mode:** The engine includes ~4,000 assertions to help you catch errors instantly.
+
+**Production Mode:** Using @rollup/plugin-strip, Meep compiles to tiny size and runs at the speed of light.
 
 ```js
+// vite.config.js
 import strip from '@rollup/plugin-strip';
-import { defineConfig } from 'vite';
-
 export default defineConfig({
-    plugins: [{
-        // this will remove all assert statements from the production build
-        ...strip(),
-        apply: 'build'
-    }],
-    // ... the rest of the config ...
+    plugins: [{ ...strip(), apply: 'build' }]
 });
 ```
 
-Assertion package can be found under `/src/core/assert.js`.
-
-## Package Size
+### Reliability
+* **Tests:** 2,944 handwritten tests covering critical algorithms and complex edge cases.
 
-Meep is infinitely tree-shakable, you only package what you use.
+* **Coverage:** 90%+ core coverage.
 
-Meep is distributed as a fine-grained set of ~3,000 modules, with an average module being ~70 lines of code. 
-If you use meep in your project, you add as much or as little to your overall bundle size as you want.
+* **Stability:** Exhaustively tested corner cases over a decade of development.
 
-For example, if you include `core/math/lerp` function, you only add 4 lines of code to your project.
-
-## Performance
+---
 
-Some say that JavaScript is not a viable choice when performance is a factor. I disagree. Meep aims to strike a balance between performance and comfort. 
-That said, meep is performance-first engine. Various API wrappers are offered for convenience, but you're always welcome to drop down to low-level API. 
-Meep is written to generate close to 0 garbage and where that would be otherwise impossible - Meep implements custom memory management to make it possible.
-The engine is built to handle millions of objects at the same time on even low-spec mobile hardware. 
+## Additional Features
 
-## Features
+| Category         | Features                                                                                                              |
+|------------------|-----------------------------------------------------------------------------------------------------------------------|
+| Audio            | Custom culling and attenuation; supports 1,000s of positional sources with zero overhead                              |
+| Input            | Unified abstraction for Touch, Mouse, and Keyboard. Event-driven and Query-based APIs                                 |
+| Assets           | Web-first asset streaming. The engine runs before assets even load                                                    |
+| Serialization    | Binary serialization system with version upgrading                                                                    |
+| UI               | High-speed, zero-garbage UI system. Optional—can be replaced with React/Vue if desired                                |
+| Color Management | Scientific-grade color management toolkit, including spectral-integration tools and modern color spaces such as OKLab |
+| NodeGraph        | A building block for node-graph systems, such as shader editors and workflow engines                                  | 
+| Achievements     | State-of-the-art achievement system, using expressions and blackboards                                                |
+| Inverse Kinematics (IK) | Highly optimized FABRIK inverse kinematics solver even the most complex IK use cases                                  |
 
 ---
-## Input
-* Touch / Mouse / Keyboard device support
-* Unified abstraction of input, offering both query and event-driven APIs
-* Input binding implementation via `InputController` component
-
-## Rendering & Lighting
-### Automatic instancing
-This will minimize the number of draw calls and improve performance.
-### Clustered lighting, aka Forward+
-Meep implements clustered lighting technique which allows you to have a pretty much an unlimited number of point lights in your scene. All the other light types are supported as well, but only point lights are clustered for now. Point lights are useful for various effects, like muzzle flashes, grenade explosions, torches, etc.
-### Terrain
-The terrain engine is chunk-based, which means that terrain is split into rectangular pieces internally, and they are built on-the-fly inside a web-worker based on camera position. Terrain is automatically culled based on camera position, so you're only drawing the chunks that are in view. Terrain supports layers just like Unity, but unlike Unity - Meep supports up to 256 layers of terrain instead of 4.
-### Path tracer
-Pure JS implementation of a path tracer, using engine's BVH (See Physics section)  
-
-## Visual Effects
-### Decals
-Decals in meep are done on the GPU, and as a result you can have a lot of them in your scene. The most I tested in a single scene is 1,000,000 which works quite well. Decals are useful for bullet holes, blood splatter and various scene decorations such as signs and scuff marks.
-### Particles
-Meep's particle engine ("Particular") is optimized for game development needs, this means supporting complex effects and being able to spawn/destroy many particle systems every frame. There are a lot of particle engines out there, but they tend to have costly spawning routines, take up a lot of draw calls and not manage memory well, which leads to pretty poor performance in games. My particle engine supports full particle lighting as well, and soft particles. On top of that - all particles are automatically atlassed in the background and are compiled with just 4 shaders. This means that no matter how many particle effects you have - there will be no shader switching and no texture switching, and there will be no delays associated with shader compilation. Particles are culled, so particle systems that are off-screen are not rendered and simulation for them can be paused to save CPU resources (this is automatic behavior)
-### Trails
-Meep implements a fairly complex trail system, where a trail can be attached to an entity, and it will create a trail behind.
-
-## Audio
-### Sound engine
-Meep has a custom sound engine which is culled and has custom attenuation, this allows scenes to have 1000s of positional audio sources without any extra cost in terms of performance
-
-## Physics
-### High performance spatial index
-Meep features a BVH (bounding volume hierarchy) implementation optimized for speed and memory usage that provides a wide variety of spatial queries, such as:
-* Ray
-* Box
-* Sphere
-* Planar
-* Frustum
-* Point intersection
-* Point distance 
-### Inverse kinematics
-* Meep has 2 very useful IK solvers to fix foot position for characters on uneven terrain or stairs, aligning both the position and orientation of character feet. This works for hands as well if you want and is not limited to bipeds, the system works just as well for, say, spiders.
-* Highly optimized FABRIK inverse kinematics solver for more complex IK use cases
-
-## Other
-### Asset streaming
-Meep in general is a web-first engine, all assets are streamed, meaning that the engine is up and running even before any models/texture are loaded, and you're free to decide when to let the player see your level, wait until everything is loaded or drop them in as soon as you can. There is a pre-loader module in case you want to load some assets in bulk before starting the game.
-### AI tools
-including, but not limited to:
-  * full-fledged Behavior trees
-  * Blackboard (took for recording information useful for AI to read/write relevant world state, very commonly used with Behavior Trees)
-  * monte-carlo tree search (same as Google's AlphaGo, useful for decision-making)
-  * state optimization (useful for decision-making)
-  * grid-based path finding (optimized for 10,000s of queries per second)
-  * resource allocation solver (useful for planning, given certain resources such as bullets/grenades/money/health - plan what actions to take to optimize your chances of winning)
-  * and a number of other useful tools to complement development of game AI and other intelligent behavior use cases.
-### High-performance serialization
-Extremely compact binary serialization system. You can save/load your scenes from files. This serialization system supports format changes, so as you develop your game - old saves will be supported and the system will automatically upgrade them to the most recent version, so the player doesn't have to lose any data.
-### Achievements
-Achievements work with Blackboard components and are very easy to define. There is an abstraction system that helps connect your achievements to various platforms such as Steam or XBox (you'd have to implement that binding yourself though), by default it comes with a browser backend, storing data in IndexedDB. I also have bindings for Steam and NewGrounds that I can share.
-### UI system
-You're free to use it or not, the engine works just fine without it. The system is written for speed, and it offers a few commonly used tools, such as popup windows, notifications and pages. The UI system is optimized for speed, so it generates no garbage, but again - if you want to use, say React - you can ignore this system or integrate it with the system.
-
-
-For more information, please refer to the documentation
 
----
-Copyright © 2025 Company Named Limited, All Rights Reserved
+## License & Copyright
+Copyright © 2025 Company Named Limited, All Rights Reserved.

package/editor/ecs/component/editors/geom/QuaternionEditor.js

@@ -1,8 +1,8 @@
-import { TypeEditor } from "../../TypeEditor.js";
 import Vector3 from "../../../../../src/core/geom/Vector3.js";
-import { makeV3_editor } from "../common/makeV3_editor.js";
 import { DEG_TO_RAD } from "../../../../../src/core/math/DEG_TO_RAD.js";
 import { RAD_TO_DEG } from "../../../../../src/core/math/RAD_TO_DEG.js";
+import { TypeEditor } from "../../TypeEditor.js";
+import { makeV3_editor } from "../common/makeV3_editor.js";
 
 export class QuaternionEditor extends TypeEditor {
     build(parent, field, registry) {
@@ -22,7 +22,7 @@ export class QuaternionEditor extends TypeEditor {
 
             lock = true;
 
-            q.__setFromEuler(
+            q.fromEulerAnglesXYZ(
                 euler.x * DEG_TO_RAD,
                 euler.y * DEG_TO_RAD,
                 euler.z * DEG_TO_RAD

package/editor/tools/TransformTool.js

@@ -103,7 +103,7 @@ class TransformContainer {
             allowWriteToSurrogate = false;
 
             try {
-                transform.rotation.__setFromEuler(surrogate.rotation.x, surrogate.rotation.y, surrogate.rotation.z, 'XYZ');
+                transform.rotation.fromEulerAnglesXYZ(surrogate.rotation.x, surrogate.rotation.y, surrogate.rotation.z);
             } catch (e) {
                 console.error(e);
             }
@@ -131,7 +131,13 @@ class TransformContainer {
 
         //set surrogate transform to match component
         surrogate.position.copy(transform.position);
-        transform.rotation.__setFromEuler(surrogate.rotation.x, surrogate.rotation.y, surrogate.rotation.z, surrogate.rotation.order);
+
+        if (surrogate.rotation.order === "XYZ") {
+            transform.rotation.fromEulerAnglesXYZ(surrogate.rotation.x, surrogate.rotation.y, surrogate.rotation.z);
+        } else {
+            throw new Error("Unsupported rotation order");
+        }
+
         surrogate.quaternion.copy(transform.rotation);
         surrogate.scale.copy(transform.scale);
 
@@ -160,7 +166,12 @@ class TransformContainer {
                 if (allowWriteToSurrogate) {
                     const rotation = transform.rotation;
 
-                    rotation.__setFromEuler(surrogate.rotation.x, surrogate.rotation.y, surrogate.rotation.z, surrogate.rotation.order);
+                    if (surrogate.rotation.order === "XYZ") {
+                        rotation.fromEulerAnglesXYZ(surrogate.rotation.x, surrogate.rotation.y, surrogate.rotation.z);
+                    } else {
+                        throw new Error("Unsupported rotation order");
+                    }
+
 
                     surrogate.quaternion.set(rotation.x, rotation.y, rotation.z, rotation.w);
                 }

package/package.json

@@ -5,7 +5,7 @@
   "description": "Pure JavaScript game engine. Fully featured and production ready.",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "2.131.17",
+  "version": "2.131.20",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/src/core/geom/Quaternion.d.ts

@@ -71,7 +71,7 @@ export class Quaternion implements Iterable<number> {
      */
     w: number;
     /**
-     * Fired when value of the quaternion changes
+     * Fires when the value of the quaternion changes
      * Signature of the signal data is as follows:
      *      (new_x, new_y, new_z, new_w, old_x, old_y, old_z, old_w)
      * @readonly
@@ -122,6 +122,9 @@ export class Quaternion implements Iterable<number> {
      * Orient quaternion on a `forward` vector, with the spin matching `up` vector
      * Useful for `lookAt` operations, such as for camera or inverse kinematics.
      * Normalizes input, meaning input does not have to be normalized.
+     *
+     * NOTE: `forward` and `up` vectors being the same is allowed, but you will likely get unexpected rotation along the look axis, so prefer not to do it.
+     *
      * @param {number} fx forward vector
      * @param {number} fy forward vector
      * @param {number} fz forward vector
@@ -151,10 +154,20 @@ export class Quaternion implements Iterable<number> {
      */
     copyInverse(other: Quaternion): this;
     /**
-     * Calculates the inverse
+     * Calculates the inverse.
+     * Correctly handles unnormalized quaternions.
+     *
+     * If your quaternion is normalized, you can use {@link conjugate} instead for speed.
      * @returns {this}
+     * @see conjugate
      */
     invert(): this;
+    /**
+     * NOTE: this is the same as {@link invert} if the quaternion is normalized.
+     * @returns {this}
+     * @see invert
+     */
+    conjugate(): this;
     /**
      * Returns angle between this orientation and another
      * @param {Quaternion} other
@@ -256,17 +269,14 @@ export class Quaternion implements Iterable<number> {
      */
     lookAt(source: Vector3, target: Vector3, up?: Vector3): void;
     /**
-     * @deprecated use {@link random} instead
-     * @param {function():number} random
-     */
-    setRandom(random: () => number): void;
-    /**
+     * @deprecated use {@link fromEulerAnglesXYZ} or others specifically.
      *
      * @param {number} x
      * @param {number} y
      * @param {number} z
      * @param {String} [order='XYZ'] a combination of capital letters X,Y,Z. Examples: XYZ, YXZ
      * @returns {this}
+     *
      * @see fromEulerAnglesXYZ
      * @see fromEulerAnglesYXZ
      * @see fromEulerAnglesZXY
@@ -291,6 +301,21 @@ export class Quaternion implements Iterable<number> {
      * @param {Vector3} result
      */
     toEulerAnglesZYX(result: Vector3): void;
+    /**
+     * Set rotation from Euler angles in degrees.
+     *
+     * Order is explicitly XYZ.
+     *
+     * Utility shortcut, same as `fromEulerAnglesXYZ(x * π / 180, y * π / 180, z * π / 180)`
+     *
+     * @param {number} [x] angle in degrees
+     * @param {number} [y] angle in degrees
+     * @param {number} [z] angle in degrees
+     * @returns {this}
+     *
+     * @see fromEulerAnglesXYZ
+     */
+    fromDegrees(x?: number, y?: number, z?: number): this;
     /**
      * XYZ order
      * @source: https://stackoverflow.com/questions/12088610/conversion-between-euler-quaternion-like-in-unity3d-engine
@@ -445,11 +470,6 @@ export class Quaternion implements Iterable<number> {
      * @returns {this}
      */
     set(x: number, y: number, z: number, w: number): this;
-    /**
-     *
-     * @returns {this}
-     */
-    conjugate(): this;
     toJSON(): {
         x: number;
         y: number;
@@ -488,14 +508,14 @@ export class Quaternion implements Iterable<number> {
      * @param {number} [offset]
      * @returns {this}
      */
-    readFromArray(array: number[], offset?: number): this;
+    fromArray(array: number[], offset?: number): this;
     /**
      *
      * @param {number[]} [array]
      * @param {number} [offset]
      * @returns {number[]}
      */
-    writeToArray(array?: number[], offset?: number): number[];
+    toArray(array?: number[], offset?: number): number[];
     /**
      * Strict equality check
      * @param {Quaternion} other
@@ -525,15 +545,28 @@ export class Quaternion implements Iterable<number> {
      * @return {boolean}
      */
     _roughlyEquals(x: number, y: number, z: number, w: number, tolerance?: number): boolean;
+    /**
+     * @deprecated use {@link random} instead
+     * @param {function():number} random
+     */
+    setRandom(random: () => number): void;
     /**
      * Randomly orient current quaternion
-     * @param {function():number} [random] Defaults to {@link Math.random}
-     * @return {Quaternion}
+     * @param {function():number} [random=Math.random] Random number generator function.
      */
-    random(random?: () => number): Quaternion;
+    random(random?: () => number): this;
     toString(): string;
-    fromArray: (array: number[], offset?: number) => this;
-    toArray: (array?: number[], offset?: number) => number[];
+    /**
+     * @deprecated use `fromArray`
+     */
+    readFromArray: (array: number[], offset?: number) => this;
+    /**
+     * @deprecated use `toArray`
+     */
+    writeToArray: (array?: number[], offset?: number) => number[];
+    /**
+     * @deprecated use `toArray`
+     */
     asArray: (array?: number[], offset?: number) => number[];
     fromEulerAngles: (x: number, y: number, z: number) => this;
     /**

package/src/core/geom/Quaternion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Quaternion.d.ts","sourceRoot":"","sources":["../../../../src/core/geom/Quaternion.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;GAWG;AACH,4CALwB,MAAM;IA+R1B;;;;;OAKG;IACH,2BAJW,OAAO,SACP,MAAM,GACJ,UAAU,CAQtB;IAiqCD;;;;OAIG;IACH,kCAFa,UAAU,CAQtB;IAED;;;;;;;OAOG;IACH,0BALW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,UAAU,CAQtB;IAED;;;;;;OAMG;IACH,6BALW,UAAU,QACV,UAAU,MACV,UAAU,aACV,MAAM,QA0BhB;IAlgDD;;;;;;;OAOG;IACH,gBANW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,EAsChB;IA7BG;;;OAGG;IACH,GAFU,MAAM,CAEN;IACV;;;OAGG;IACH,GAFU,MAAM,CAEN;IACV;;;OAGG;IACH,GAFU,MAAM,CAEN;IACV;;;OAGG;IACH,GAFU,MAAM,CAEN;IAEV;;;;;;OAMG;IACH,oBAFU,OAAO,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEnD;IAqCjC;;;OAGG;IACH,mBAEC;IAtCD;;;OAGG;IACH,gBAEC;IAkCD;;;OAGG;IACH,mBAEC;IAtCD;;;OAGG;IACH,gBAEC;IAkCD;;;OAGG;IACH,mBAEC;IAtCD;;;OAGG;IACH,gBAEC;IAkCD;;;OAGG;IACH,mBAEC;IAtCD;;;OAGG;IACH,gBAEC;IAgDD;;;;;;;;;;;OAWG;IACH,kBARW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,IAAI,CAqDhB;IAED;;;;;OAKG;IACH,sBAJW,OAAO,OACP,OAAO,GACL,IAAI,CAShB;IAED;;;;OAIG;IACH,WAHW,UAAU,GACT,MAAM,CAQjB;IAED;;;;OAIG;IACH,mBAHW,UAAU,GACR,IAAI,CAKhB;IAED;;;OAGG;IACH,UAFa,IAAI,CAuBhB;IAED;;;;OAIG;IACH,eAHW,UAAU,GACT,MAAM,CAoBjB;IAiBD;;;;;OAKG;IACH,oBAJW,OAAO,SACP,MAAM,GACJ,IAAI,CAQhB;IAED;;;;;;;OAOG;IACH,uBANW,MAAM,UACN,MAAM,UACN,MAAM,SACN,MAAM,GACJ,IAAI,CAkChB;IAED;;;;;;;;OAQG;IACH,2BANW,OAAO,SACP,UAAU,SACV,UAAU,GACR,IAAI,CAyChB;IAED;;;;OAIG;IACH,wBAHW,OAAO,GACL,MAAM,CAYlB;IAED;;;;OAIG;IACH,sBAHW,OAAO,GACL,MAAM,CAmBlB;IAED;;;OAGG;IACH,aAFa,IAAI,CAehB;IAED;;;;OAIG;IACH,oBAHW,MAAM,GACL,IAAI,CASf;IAED;;;OAGG;IACH,gBAHW,UAAU,GACR,IAAI,CAIhB;IAED;;;;;OAKG;IACH,2BAJW,UAAU,UACV,UAAU,GACR,IAAI,CAchB;IAED;;;;;;;;;;;OAWG;IACH,yBAVW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,IAAI,CAehB;IAED;;;OAGG;IACH,UAFY,MAAM,CASjB;IAED;;;;;OAKG;IACH,qBAJW,UAAU,aACV,MAAM,GACJ,IAAI,CAMhB;IAED;;;;;;OAMG;IACH,eALW,OAAO,UACP,OAAO,OACP,OAAO,QAWjB;IAED;;;OAGG;IACH,wBAFsB,MAAM,QAI3B;IAED;;;;;;;;;;;;;OAaG;IACH,kBAZW,MAAM,KACN,MAAM,KACN,MAAM,mBAEJ,IAAI,CA8ChB;IAED;;;;OAIG;IACH,yBAFW,OAAO,QA4BjB;IAED;;;OAGG;IACH,yBAFW,OAAO,QA2BjB;IAED;;;OAGG;IACH,yBAFW,OAAO,QA0BjB;IAGD;;;;;;;;;OASG;IACH,sBALW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,IAAI,CAqBhB;IAED;;;;;;;;;OASG;IACH,sBALW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,IAAI,CAqBhB;IAED;;;;;;;;;OASG;IACH,sBALW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,IAAI,CAqBhB;IAED;;;;;;;;;OASG;IACH,sBALW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,IAAI,CAqBhB;IAED;;;;;;;;;OASG;IACH,sBALW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,IAAI,CAqBhB;IAED;;;;;;;;;OASG;IACH,sBALW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,IAAI,CAqBhB;IAED;;;;;;OAMG;IACH,sBAJW,OAAO,MACP,OAAO,GACL,IAAI,CAkEhB;IAED;;;OAGG;IACH,4BAHW,MAAM,EAAE,GAAC,YAAY,GACnB,IAAI,CAYhB;IAED;;;;;;;;;;;;;;OAcG;IACH,6BAXW,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,GACJ,IAAI,CA4EhB;IAED;;;;;OAKG;IACH,YAJW,UAAU,KACV,MAAM,GACJ,IAAI,CAMhB;IAED;;;;;;;OAOG;IACH,uBALW,UAAU,UACV,UAAU,KACV,MAAM,GACJ,IAAI,CAgBhB;IAED;;;;;;OAMG;IACH,uBALW,UAAU,MACV,UAAU,KACV,MAAM,GACJ,IAAI,CA4DhB;IAGD;;;;;OAKG;IACH,aAJW,UAAU,KACV,MAAM,GACJ,IAAI,CAIhB;IAED;;;;;OAKG;IACH,sCAFa,IAAI,CAUhB;IAED;;;;OAIG;IACH,YAHW,UAAU,GACR,IAAI,CAIhB;IAED;;;OAGG;IACH,SAFa,UAAU,CAQtB;IAED;;;;;;;;OAQG;IACH,OANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,IAAI,CA+BhB;IAED;;;OAGG;IACH,aAFa,IAAI,CAIhB;IAED;;;;;MAOC;IAED;;;;OAIG;IACH,oBAFY,IAAI,CAIf;IAED;;;OAGG;IACH,2CAKC;IAED;;;OAGG;IACH,6CAOC;IAED;;;OAGG;IACH,kDAKC;IAED;;;OAGG;IACH,oDAOC;IAED;;;;;OAKG;IACH,qBAJW,MAAM,EAAE,WACR,MAAM,GACJ,IAAI,CAShB;IAED;;;;;OAKG;IACH,qBAJW,MAAM,EAAE,WACR,MAAM,GACJ,MAAM,EAAE,CASpB;IAED;;;;;OAKG;IACH,cAJW,UAAU,GACR,OAAO,CASnB;IAED;;;OAGG;IACH,QAFa,MAAM,CAQlB;IAED;;;;;OAKG;IACH,qBAJW,UAAU,cACV,MAAM,GACL,OAAO,CAOlB;IAED;;;;;;;;OAQG;IACH,kBAPW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,cACN,MAAM,GACL,OAAO,CASlB;IAED;;;;OAIG;IACH,sBAHsB,MAAM,GAChB,UAAU,CAuBrB;IAED,mBAEC;IAiEL,mBApLe,MAAM,EAAE,WACR,MAAM,KACJ,IAAI,CAkLS;IAC9B,kBAtKe,MAAM,EAAE,WACR,MAAM,KACJ,MAAM,EAAE,CAoKG;IAC5B,kBAvKe,MAAM,EAAE,WACR,MAAM,KACJ,MAAM,EAAE,CAqKG;IAC5B,qBA3yBe,MAAM,KACN,MAAM,KACN,MAAM,KACJ,IAAI,CAwyBe;IAQpC;;;;OAIG;IACH,uBAFU,OAAO,CAEgB;IAt6C7B;;;OAGG;IACH,qBAFa,UAAU,MAAM,CAAC,CAS7B;CAy4CJ;;kBASS,UAAU;kBAaV,MAAM;;;mBAzjDG,4BAA4B;oBAU3B,cAAc"}
+{"version":3,"file":"Quaternion.d.ts","sourceRoot":"","sources":["../../../../src/core/geom/Quaternion.js"],"names":[],"mappings":"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"}

package/src/core/geom/Quaternion.js

@@ -2,6 +2,7 @@ import { assert } from "../assert.js";
 import Signal from "../events/signal/Signal.js";
 import { clamp } from "../math/clamp.js";
 import { clamp01 } from "../math/clamp01.js";
+import { DEG_TO_RAD } from "../math/DEG_TO_RAD.js";
 import { EPSILON } from "../math/EPSILON.js";
 import { epsilonEquals } from "../math/epsilonEquals.js";
 import { lerp } from "../math/lerp.js";
@@ -67,7 +68,7 @@ export class Quaternion {
         this.w = w;
 
         /**
-         * Fired when value of the quaternion changes
+         * Fires when the value of the quaternion changes
          * Signature of the signal data is as follows:
          *      (new_x, new_y, new_z, new_w, old_x, old_y, old_z, old_w)
          * @readonly
@@ -160,6 +161,9 @@ export class Quaternion {
      * Orient quaternion on a `forward` vector, with the spin matching `up` vector
      * Useful for `lookAt` operations, such as for camera or inverse kinematics.
      * Normalizes input, meaning input does not have to be normalized.
+     *
+     * NOTE: `forward` and `up` vectors being the same is allowed, but you will likely get unexpected rotation along the look axis, so prefer not to do it.
+     *
      * @param {number} fx forward vector
      * @param {number} fy forward vector
      * @param {number} fz forward vector
@@ -260,8 +264,12 @@ export class Quaternion {
     }
 
     /**
-     * Calculates the inverse
+     * Calculates the inverse.
+     * Correctly handles unnormalized quaternions.
+     *
+     * If your quaternion is normalized, you can use {@link conjugate} instead for speed.
      * @returns {this}
+     * @see conjugate
      */
     invert() {
         const x = this.x;
@@ -269,14 +277,14 @@ export class Quaternion {
         const z = this.z;
         const w = this.w;
 
-        const length_sqr = x * x + y * y + z * z + w * w;
+        const dot_product = x * x + y * y + z * z + w * w;
 
-        if (length_sqr === 0) {
+        if (dot_product === 0) {
             // 0 magnitude, avoid division by 0 and set identity (arbitrage)
             return this.set(0, 0, 0, 1);
         }
 
-        const invDot = 1.0 / length_sqr;
+        const invDot = 1.0 / dot_product;
 
         const _x = -x * invDot;
         const _y = -y * invDot;
@@ -286,6 +294,15 @@ export class Quaternion {
         return this.set(_x, _y, _z, _w);
     }
 
+    /**
+     * NOTE: this is the same as {@link invert} if the quaternion is normalized.
+     * @returns {this}
+     * @see invert
+     */
+    conjugate() {
+        return this.set(-this.x, -this.y, -this.z, this.w);
+    }
+
     /**
      * Returns angle between this orientation and another
      * @param {Quaternion} other
@@ -602,21 +619,16 @@ export class Quaternion {
         this.lookRotation(forward, up);
     }
 
-    /**
-     * @deprecated use {@link random} instead
-     * @param {function():number} random
-     */
-    setRandom(random) {
-        throw new Error("use .random() instead");
-    }
 
     /**
+     * @deprecated use {@link fromEulerAnglesXYZ} or others specifically.
      *
      * @param {number} x
      * @param {number} y
      * @param {number} z
      * @param {String} [order='XYZ'] a combination of capital letters X,Y,Z. Examples: XYZ, YXZ
      * @returns {this}
+     *
      * @see fromEulerAnglesXYZ
      * @see fromEulerAnglesYXZ
      * @see fromEulerAnglesZXY
@@ -758,6 +770,28 @@ export class Quaternion {
         result.set(psi, theta, phi);
     }
 
+    /**
+     * Set rotation from Euler angles in degrees.
+     *
+     * Order is explicitly XYZ.
+     *
+     * Utility shortcut, same as `fromEulerAnglesXYZ(x * π / 180, y * π / 180, z * π / 180)`
+     *
+     * @param {number} [x] angle in degrees
+     * @param {number} [y] angle in degrees
+     * @param {number} [z] angle in degrees
+     * @returns {this}
+     *
+     * @see fromEulerAnglesXYZ
+     */
+    fromDegrees(x = 0, y = 0, z = 0) {
+        return this.fromEulerAnglesXYZ(
+            x * DEG_TO_RAD,
+            y * DEG_TO_RAD,
+            z * DEG_TO_RAD
+        );
+    }
+
 
     /**
      * XYZ order
@@ -1316,14 +1350,6 @@ export class Quaternion {
         return this;
     }
 
-    /**
-     *
-     * @returns {this}
-     */
-    conjugate() {
-        return this.set(-this.x, -this.y, -this.z, this.w);
-    }
-
     toJSON() {
         return {
             x: this.x,
@@ -1396,7 +1422,10 @@ export class Quaternion {
      * @param {number} [offset]
      * @returns {this}
      */
-    readFromArray(array, offset = 0) {
+    fromArray(array, offset = 0) {
+        assert.defined(array, "array");
+        assert.isNonNegativeInteger(offset, "offset");
+
         return this.set(
             array[offset],
             array[offset + 1],
@@ -1411,7 +1440,10 @@ export class Quaternion {
      * @param {number} [offset]
      * @returns {number[]}
      */
-    writeToArray(array = [], offset = 0) {
+    toArray(array = [], offset = 0) {
+        assert.defined(array, 'array');
+        assert.isNonNegativeInteger(offset, "offset");
+
         array[offset] = this.x;
         array[offset + 1] = this.y;
         array[offset + 2] = this.z;
@@ -1477,10 +1509,17 @@ export class Quaternion {
             && epsilonEquals(this.w, w, tolerance);
     }
 
+    /**
+     * @deprecated use {@link random} instead
+     * @param {function():number} random
+     */
+    setRandom(random) {
+        throw new Error("use .random() instead");
+    }
+
     /**
      * Randomly orient current quaternion
-     * @param {function():number} [random] Defaults to {@link Math.random}
-     * @return {Quaternion}
+     * @param {function():number} [random=Math.random] Random number generator function.
      */
     random(random = Math.random) {
         assert.isFunction(random, 'random');
@@ -1572,9 +1611,20 @@ export class Quaternion {
     }
 }
 
-Quaternion.prototype.fromArray = Quaternion.prototype.readFromArray;
-Quaternion.prototype.toArray = Quaternion.prototype.writeToArray;
-Quaternion.prototype.asArray = Quaternion.prototype.writeToArray;
+/**
+ * @deprecated use `fromArray`
+ */
+Quaternion.prototype.readFromArray = Quaternion.prototype.fromArray;
+
+/**
+ * @deprecated use `toArray`
+ */
+Quaternion.prototype.writeToArray = Quaternion.prototype.toArray;
+
+/**
+ * @deprecated use `toArray`
+ */
+Quaternion.prototype.asArray = Quaternion.prototype.toArray;
 Quaternion.prototype.fromEulerAngles = Quaternion.prototype.fromEulerAnglesXYZ;
 
 /**