@codexo/exojs 0.7.11 → 0.7.12

package/dist/esm/rendering/shader/Shader.js

@@ -1,5 +1,15 @@
+/**
+ * Backend-agnostic shader program descriptor.
+ *
+ * Holds raw GLSL source strings and, after {@link connect} is called, a live
+ * {@link ShaderProgram} with populated {@link attributes} and {@link uniforms} maps.
+ * Call {@link bind} before draw calls and {@link sync} after updating uniform values.
+ * Both maps are cleared on {@link disconnect} and {@link destroy}.
+ */
 class Shader {
+    /** Vertex attribute metadata populated by the backend after {@link connect}. */
     attributes = new Map();
+    /** Uniform metadata populated by the backend after {@link connect}. */
     uniforms = new Map();
     _vertexSource;
     _fragmentSource;
@@ -14,6 +24,10 @@ class Shader {
     get fragmentSource() {
         return this._fragmentSource;
     }
+    /**
+     * Attach a backend GPU program, compile/link it, and populate the attribute and uniform maps.
+     * Must be called before {@link bind}, {@link sync}, or accessing {@link attributes}/{@link uniforms}.
+     */
     connect(program) {
         this._program = program;
         program.initialize(this);
@@ -33,10 +47,18 @@ class Shader {
         this._program?.unbind(this);
         return this;
     }
+    /**
+     * Upload all dirty {@link ShaderUniform} values to the GPU.
+     * Call once per draw call after modifying uniform data.
+     */
     sync() {
         this._program?.sync(this);
         return this;
     }
+    /**
+     * Retrieve a named vertex attribute from the map populated by the backend.
+     * @throws Error if no attribute with `name` exists.
+     */
     getAttribute(name) {
         const attribute = this.attributes.get(name);
         if (!attribute) {
@@ -44,6 +66,10 @@ class Shader {
         }
         return attribute;
     }
+    /**
+     * Retrieve a named uniform from the map populated by the backend.
+     * @throws Error if no uniform with `name` exists.
+     */
     getUniform(name) {
         const uniform = this.uniforms.get(name);
         if (!uniform) {

package/dist/esm/rendering/shader/Shader.js.map

@@ -1 +1 @@
-{"version":3,"file":"Shader.js","sources":["../../../../../src/rendering/shader/Shader.ts"],"sourcesContent":[null],"names":[],"mappings":"MAWa,MAAM,CAAA;AAEC,IAAA,UAAU,GAAiC,IAAI,GAAG,EAA2B;AAC7E,IAAA,QAAQ,GAA+B,IAAI,GAAG,EAAyB;AAEtE,IAAA,aAAa;AACb,IAAA,eAAe;IACxB,QAAQ,GAAyB,IAAI;IAE7C,WAAA,CAAmB,YAAoB,EAAE,cAAsB,EAAA;AAC3D,QAAA,IAAI,CAAC,aAAa,GAAG,YAAY;AACjC,QAAA,IAAI,CAAC,eAAe,GAAG,cAAc;IACzC;AAEA,IAAA,IAAW,YAAY,GAAA;QACnB,OAAO,IAAI,CAAC,aAAa;IAC7B;AAEA,IAAA,IAAW,cAAc,GAAA;QACrB,OAAO,IAAI,CAAC,eAAe;IAC/B;AAEO,IAAA,OAAO,CAAC,OAAsB,EAAA;AACjC,QAAA,IAAI,CAAC,QAAQ,GAAG,OAAO;AACvB,QAAA,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;AAExB,QAAA,OAAO,IAAI;IACf;IAEO,UAAU,GAAA;AACb,QAAA,IAAI,CAAC,QAAQ,GAAG,IAAI;AACpB,QAAA,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE;AACvB,QAAA,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE;AAErB,QAAA,OAAO,IAAI;IACf;IAEO,IAAI,GAAA;AACP,QAAA,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC;AAEzB,QAAA,OAAO,IAAI;IACf;IAEO,MAAM,GAAA;AACT,QAAA,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC;AAE3B,QAAA,OAAO,IAAI;IACf;IAEO,IAAI,GAAA;AACP,QAAA,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC;AAEzB,QAAA,OAAO,IAAI;IACf;AAEO,IAAA,YAAY,CAAC,IAAY,EAAA;QAC5B,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC;QAE3C,IAAI,CAAC,SAAS,EAAE;AACZ,YAAA,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,CAAA,mBAAA,CAAqB,CAAC;QAC5D;AAEA,QAAA,OAAO,SAAS;IACpB;AAEO,IAAA,UAAU,CAAC,IAAY,EAAA;QAC1B,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;QAEvC,IAAI,CAAC,OAAO,EAAE;AACV,YAAA,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,CAAA,mBAAA,CAAqB,CAAC;QAC1D;AAEA,QAAA,OAAO,OAAO;IAClB;IAEO,OAAO,GAAA;AACV,QAAA,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC;AAC5B,QAAA,IAAI,CAAC,QAAQ,GAAG,IAAI;AACpB,QAAA,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE;AACvB,QAAA,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE;IACzB;AACH;;;;"}
+{"version":3,"file":"Shader.js","sources":["../../../../../src/rendering/shader/Shader.ts"],"sourcesContent":[null],"names":[],"mappings":"AAqBA;;;;;;;AAOG;MACU,MAAM,CAAA;;AAGC,IAAA,UAAU,GAAiC,IAAI,GAAG,EAA2B;;AAE7E,IAAA,QAAQ,GAA+B,IAAI,GAAG,EAAyB;AAEtE,IAAA,aAAa;AACb,IAAA,eAAe;IACxB,QAAQ,GAAyB,IAAI;IAE7C,WAAA,CAAmB,YAAoB,EAAE,cAAsB,EAAA;AAC3D,QAAA,IAAI,CAAC,aAAa,GAAG,YAAY;AACjC,QAAA,IAAI,CAAC,eAAe,GAAG,cAAc;IACzC;AAEA,IAAA,IAAW,YAAY,GAAA;QACnB,OAAO,IAAI,CAAC,aAAa;IAC7B;AAEA,IAAA,IAAW,cAAc,GAAA;QACrB,OAAO,IAAI,CAAC,eAAe;IAC/B;AAEA;;;AAGG;AACI,IAAA,OAAO,CAAC,OAAsB,EAAA;AACjC,QAAA,IAAI,CAAC,QAAQ,GAAG,OAAO;AACvB,QAAA,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;AAExB,QAAA,OAAO,IAAI;IACf;IAEO,UAAU,GAAA;AACb,QAAA,IAAI,CAAC,QAAQ,GAAG,IAAI;AACpB,QAAA,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE;AACvB,QAAA,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE;AAErB,QAAA,OAAO,IAAI;IACf;IAEO,IAAI,GAAA;AACP,QAAA,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC;AAEzB,QAAA,OAAO,IAAI;IACf;IAEO,MAAM,GAAA;AACT,QAAA,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC;AAE3B,QAAA,OAAO,IAAI;IACf;AAEA;;;AAGG;IACI,IAAI,GAAA;AACP,QAAA,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC;AAEzB,QAAA,OAAO,IAAI;IACf;AAEA;;;AAGG;AACI,IAAA,YAAY,CAAC,IAAY,EAAA;QAC5B,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC;QAE3C,IAAI,CAAC,SAAS,EAAE;AACZ,YAAA,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,CAAA,mBAAA,CAAqB,CAAC;QAC5D;AAEA,QAAA,OAAO,SAAS;IACpB;AAEA;;;AAGG;AACI,IAAA,UAAU,CAAC,IAAY,EAAA;QAC1B,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;QAEvC,IAAI,CAAC,OAAO,EAAE;AACV,YAAA,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,CAAA,mBAAA,CAAqB,CAAC;QAC1D;AAEA,QAAA,OAAO,OAAO;IAClB;IAEO,OAAO,GAAA;AACV,QAAA,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC;AAC5B,QAAA,IAAI,CAAC,QAAQ,GAAG,IAAI;AACpB,QAAA,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE;AACvB,QAAA,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE;IACzB;AACH;;;;"}

package/dist/esm/rendering/shader/ShaderAttribute.d.ts

@@ -1,8 +1,21 @@
+/**
+ * Metadata for a single vertex attribute declared in a GLSL vertex shader.
+ *
+ * Populated by the backend during {@link Shader.connect} using the values
+ * returned by `gl.getActiveAttrib`. The `size` field is derived from `type`
+ * via the backend's primitive-byte-size mapping and is used to stride vertex
+ * buffer layouts.
+ */
 export declare class ShaderAttribute {
+    /** Zero-based index of this attribute within the shader program. */
     readonly index: number;
+    /** GLSL attribute name as declared in the vertex shader source. */
     readonly name: string;
+    /** WebGL2 GLenum type token (e.g. `gl.FLOAT_VEC2`). */
     readonly type: number;
+    /** Byte size of one element of this attribute's type. */
     readonly size: number;
+    /** WebGL attribute location assigned by the driver. `-1` until the backend sets it. */
     location: number;
     constructor(index: number, name: string, type: number);
     destroy(): void;

package/dist/esm/rendering/shader/ShaderAttribute.js

@@ -1,10 +1,23 @@
 import { webGl2PrimitiveByteSizeMapping } from '../webgl2/WebGl2ShaderMappings.js';
 
+/**
+ * Metadata for a single vertex attribute declared in a GLSL vertex shader.
+ *
+ * Populated by the backend during {@link Shader.connect} using the values
+ * returned by `gl.getActiveAttrib`. The `size` field is derived from `type`
+ * via the backend's primitive-byte-size mapping and is used to stride vertex
+ * buffer layouts.
+ */
 class ShaderAttribute {
+    /** Zero-based index of this attribute within the shader program. */
     index;
+    /** GLSL attribute name as declared in the vertex shader source. */
     name;
+    /** WebGL2 GLenum type token (e.g. `gl.FLOAT_VEC2`). */
     type;
+    /** Byte size of one element of this attribute's type. */
     size;
+    /** WebGL attribute location assigned by the driver. `-1` until the backend sets it. */
     location = -1;
     constructor(index, name, type) {
         this.index = index;

package/dist/esm/rendering/shader/ShaderAttribute.js.map

@@ -1 +1 @@
-{"version":3,"file":"ShaderAttribute.js","sources":["../../../../../src/rendering/shader/ShaderAttribute.ts"],"sourcesContent":[null],"names":[],"mappings":";;MAEa,eAAe,CAAA;AAER,IAAA,KAAK;AACL,IAAA,IAAI;AACJ,IAAA,IAAI;AACJ,IAAA,IAAI;IACb,QAAQ,GAAG,EAAE;AAEpB,IAAA,WAAA,CAAmB,KAAa,EAAE,IAAY,EAAE,IAAY,EAAA;AACxD,QAAA,IAAI,CAAC,KAAK,GAAG,KAAK;AAClB,QAAA,IAAI,CAAC,IAAI,GAAG,IAAI;AAChB,QAAA,IAAI,CAAC,IAAI,GAAG,IAAI;AAChB,QAAA,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC,IAAI,CAAC;IACpD;IAEO,OAAO,GAAA;;IAEd;AACH;;;;"}
+{"version":3,"file":"ShaderAttribute.js","sources":["../../../../../src/rendering/shader/ShaderAttribute.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEA;;;;;;;AAOG;MACU,eAAe,CAAA;;AAGR,IAAA,KAAK;;AAEL,IAAA,IAAI;;AAEJ,IAAA,IAAI;;AAEJ,IAAA,IAAI;;IAEb,QAAQ,GAAG,EAAE;AAEpB,IAAA,WAAA,CAAmB,KAAa,EAAE,IAAY,EAAE,IAAY,EAAA;AACxD,QAAA,IAAI,CAAC,KAAK,GAAG,KAAK;AAClB,QAAA,IAAI,CAAC,IAAI,GAAG,IAAI;AAChB,QAAA,IAAI,CAAC,IAAI,GAAG,IAAI;AAChB,QAAA,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC,IAAI,CAAC;IACpD;IAEO,OAAO,GAAA;;IAEd;AACH;;;;"}

package/dist/esm/rendering/shader/ShaderUniform.d.ts

@@ -1,16 +1,43 @@
 import type { TypedArray } from '@/core/types';
+/**
+ * Metadata and current value for a single GLSL uniform variable.
+ *
+ * Populated by the backend during {@link Shader.connect}. The `dirty` flag is
+ * set to `true` on construction and on every {@link setValue} call; the backend
+ * clears it via {@link markClean} after uploading the value to the GPU.
+ * Array-type uniform names have their index suffix stripped (e.g. `uColors[0]`
+ * becomes `uColors`).
+ */
 export declare class ShaderUniform {
+    /** Zero-based index of this uniform within the shader program. */
     readonly index: number;
+    /** WebGL2 GLenum type token (e.g. `gl.FLOAT_MAT4`). */
     readonly type: number;
+    /** Number of elements for array uniforms; `1` for scalar uniforms. */
     readonly size: number;
+    /** GLSL uniform name with array suffixes stripped. */
     readonly name: string;
     private readonly _value;
     private _dirty;
     constructor(index: number, type: number, size: number, name: string, data: TypedArray);
+    /**
+     * The leaf segment of a dot-separated uniform name.
+     * For top-level uniforms this equals `name`; for struct members (e.g. `uLight.color`)
+     * it returns only the field name (`color`).
+     */
     get propName(): string;
     get value(): TypedArray;
+    /** Whether the value has changed since the last {@link markClean} call. */
     get dirty(): boolean;
+    /**
+     * Copy `value` into the internal typed-array buffer and mark the uniform dirty.
+     * The backend will upload the new value to the GPU on the next {@link Shader.sync} call.
+     */
     setValue(value: TypedArray): this;
+    /**
+     * Clear the dirty flag after the backend has successfully uploaded the uniform value.
+     * @internal
+     */
     markClean(): void;
     destroy(): void;
 }

package/dist/esm/rendering/shader/ShaderUniform.js

@@ -1,7 +1,20 @@
+/**
+ * Metadata and current value for a single GLSL uniform variable.
+ *
+ * Populated by the backend during {@link Shader.connect}. The `dirty` flag is
+ * set to `true` on construction and on every {@link setValue} call; the backend
+ * clears it via {@link markClean} after uploading the value to the GPU.
+ * Array-type uniform names have their index suffix stripped (e.g. `uColors[0]`
+ * becomes `uColors`).
+ */
 class ShaderUniform {
+    /** Zero-based index of this uniform within the shader program. */
     index;
+    /** WebGL2 GLenum type token (e.g. `gl.FLOAT_MAT4`). */
     type;
+    /** Number of elements for array uniforms; `1` for scalar uniforms. */
     size;
+    /** GLSL uniform name with array suffixes stripped. */
     name;
     _value;
     _dirty = true;
@@ -12,20 +25,34 @@ class ShaderUniform {
         this.size = size;
         this._value = data;
     }
+    /**
+     * The leaf segment of a dot-separated uniform name.
+     * For top-level uniforms this equals `name`; for struct members (e.g. `uLight.color`)
+     * it returns only the field name (`color`).
+     */
     get propName() {
-        return this.name.substr(this.name.lastIndexOf('.') + 1);
+        return this.name.substring(this.name.lastIndexOf('.') + 1);
     }
     get value() {
         return this._value;
     }
+    /** Whether the value has changed since the last {@link markClean} call. */
     get dirty() {
         return this._dirty;
     }
+    /**
+     * Copy `value` into the internal typed-array buffer and mark the uniform dirty.
+     * The backend will upload the new value to the GPU on the next {@link Shader.sync} call.
+     */
     setValue(value) {
         this._value.set(value);
         this._dirty = true;
         return this;
     }
+    /**
+     * Clear the dirty flag after the backend has successfully uploaded the uniform value.
+     * @internal
+     */
     markClean() {
         this._dirty = false;
     }

package/dist/esm/rendering/shader/ShaderUniform.js.map

@@ -1 +1 @@
-{"version":3,"file":"ShaderUniform.js","sources":["../../../../../src/rendering/shader/ShaderUniform.ts"],"sourcesContent":[null],"names":[],"mappings":"MAEa,aAAa,CAAA;AAEN,IAAA,KAAK;AACL,IAAA,IAAI;AACJ,IAAA,IAAI;AACJ,IAAA,IAAI;AAEH,IAAA,MAAM;IACf,MAAM,GAAG,IAAI;IAErB,WAAA,CAAmB,KAAa,EAAE,IAAY,EAAE,IAAY,EAAE,IAAY,EAAE,IAAgB,EAAA;QACxF,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;AACtC,QAAA,IAAI,CAAC,KAAK,GAAG,KAAK;AAClB,QAAA,IAAI,CAAC,IAAI,GAAG,IAAI;AAChB,QAAA,IAAI,CAAC,IAAI,GAAG,IAAI;AAChB,QAAA,IAAI,CAAC,MAAM,GAAG,IAAI;IACtB;AAEA,IAAA,IAAW,QAAQ,GAAA;AACf,QAAA,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3D;AAEA,IAAA,IAAW,KAAK,GAAA;QACZ,OAAO,IAAI,CAAC,MAAM;IACtB;AAEA,IAAA,IAAW,KAAK,GAAA;QACZ,OAAO,IAAI,CAAC,MAAM;IACtB;AAEO,IAAA,QAAQ,CAAC,KAAiB,EAAA;AAC7B,QAAA,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC;AACtB,QAAA,IAAI,CAAC,MAAM,GAAG,IAAI;AAElB,QAAA,OAAO,IAAI;IACf;IAEO,SAAS,GAAA;AACZ,QAAA,IAAI,CAAC,MAAM,GAAG,KAAK;IACvB;IAEO,OAAO,GAAA;;IAEd;AACH;;;;"}
+{"version":3,"file":"ShaderUniform.js","sources":["../../../../../src/rendering/shader/ShaderUniform.ts"],"sourcesContent":[null],"names":[],"mappings":"AAEA;;;;;;;;AAQG;MACU,aAAa,CAAA;;AAGN,IAAA,KAAK;;AAEL,IAAA,IAAI;;AAEJ,IAAA,IAAI;;AAEJ,IAAA,IAAI;AAEH,IAAA,MAAM;IACf,MAAM,GAAG,IAAI;IAErB,WAAA,CAAmB,KAAa,EAAE,IAAY,EAAE,IAAY,EAAE,IAAY,EAAE,IAAgB,EAAA;QACxF,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;AACtC,QAAA,IAAI,CAAC,KAAK,GAAG,KAAK;AAClB,QAAA,IAAI,CAAC,IAAI,GAAG,IAAI;AAChB,QAAA,IAAI,CAAC,IAAI,GAAG,IAAI;AAChB,QAAA,IAAI,CAAC,MAAM,GAAG,IAAI;IACtB;AAEA;;;;AAIG;AACH,IAAA,IAAW,QAAQ,GAAA;AACf,QAAA,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9D;AAEA,IAAA,IAAW,KAAK,GAAA;QACZ,OAAO,IAAI,CAAC,MAAM;IACtB;;AAGA,IAAA,IAAW,KAAK,GAAA;QACZ,OAAO,IAAI,CAAC,MAAM;IACtB;AAEA;;;AAGG;AACI,IAAA,QAAQ,CAAC,KAAiB,EAAA;AAC7B,QAAA,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC;AACtB,QAAA,IAAI,CAAC,MAAM,GAAG,IAAI;AAElB,QAAA,OAAO,IAAI;IACf;AAEA;;;AAGG;IACI,SAAS,GAAA;AACZ,QAAA,IAAI,CAAC,MAAM,GAAG,KAAK;IACvB;IAEO,OAAO,GAAA;;IAEd;AACH;;;;"}

package/dist/esm/rendering/sprite/AnimatedSprite.d.ts

@@ -5,15 +5,30 @@ import { Sprite } from './Sprite';
 import type { Spritesheet } from './Spritesheet';
 import type { Texture } from '@/rendering/texture/Texture';
 import type { RenderTexture } from '@/rendering/texture/RenderTexture';
+/** Definition for a single animation clip registered on an {@link AnimatedSprite}. */
 export interface AnimatedSpriteClipDefinition {
     readonly frames: ReadonlyArray<Rectangle>;
     readonly fps?: number;
     readonly loop?: boolean;
 }
+/** Per-call options passed to {@link AnimatedSprite.play}. */
 export interface AnimatedSpritePlayOptions {
     loop?: boolean;
     restart?: boolean;
 }
+/**
+ * A {@link Sprite} that advances through a sequence of texture-frame
+ * {@link Rectangle}s over time to produce frame-based animation.
+ *
+ * Multiple named clips can be registered via {@link defineClip} or the
+ * constructor. Call {@link play} to start a clip; call {@link update} each
+ * frame with the elapsed delta (seconds or a `Time` object) to advance
+ * playback. The `onFrame` signal fires on every frame advance and
+ * `onComplete` fires when a non-looping clip reaches its last frame.
+ *
+ * Use {@link AnimatedSprite.fromSpritesheet} to create an instance directly
+ * from a {@link Spritesheet}'s named animations.
+ */
 export declare class AnimatedSprite extends Sprite {
     private readonly _clips;
     private _currentClipName;
@@ -27,17 +42,40 @@ export declare class AnimatedSprite extends Sprite {
     get currentClip(): string | null;
     get currentFrame(): number;
     get playing(): boolean;
+    /**
+     * Whether the current clip loops. Returns the per-call loop override if set,
+     * otherwise the clip's own `loop` flag.
+     */
     get loop(): boolean;
     set loop(loop: boolean);
+    /** Replace all registered clips with the provided map. Clears any previously registered clips first. */
     setClips(clips: Readonly<Record<string, AnimatedSpriteClipDefinition>>): this;
+    /** Register a named clip. Frame rectangles are cloned so the caller may mutate the originals. */
     defineClip(name: string, clip: AnimatedSpriteClipDefinition): this;
+    /** Remove a registered clip by name. Stops playback first if the clip is currently active. */
     removeClip(name: string): this;
+    /**
+     * Start playing the named clip. By default restarts from frame 0; pass
+     * `{ restart: false }` to resume from the current frame if the same clip
+     * is already active. Optionally overrides the clip's loop setting.
+     */
     play(name: string, options?: AnimatedSpritePlayOptions): this;
+    /** Stop playback and rewind the active clip to frame 0. */
     stop(): this;
     pause(): this;
     resume(): this;
+    /**
+     * Advance playback by `delta` milliseconds (or a `Time` object). Call once
+     * per frame from the game loop. Dispatches `onFrame` for each frame
+     * boundary crossed and `onComplete` when a non-looping clip ends.
+     */
     update(delta: Time | number): this;
     destroy(): void;
+    /**
+     * Construct an {@link AnimatedSprite} from the named animations defined on
+     * a {@link Spritesheet}. Each animation becomes a looping clip whose frames
+     * are the spritesheet frame rectangles in declaration order.
+     */
     static fromSpritesheet(spritesheet: Spritesheet): AnimatedSprite;
     private _applyFrame;
 }

package/dist/esm/rendering/sprite/AnimatedSprite.js

@@ -2,6 +2,19 @@ import { Signal } from '../../core/Signal.js';
 import { Sprite } from './Sprite.js';
 
 const defaultClipFps = 12;
+/**
+ * A {@link Sprite} that advances through a sequence of texture-frame
+ * {@link Rectangle}s over time to produce frame-based animation.
+ *
+ * Multiple named clips can be registered via {@link defineClip} or the
+ * constructor. Call {@link play} to start a clip; call {@link update} each
+ * frame with the elapsed delta (seconds or a `Time` object) to advance
+ * playback. The `onFrame` signal fires on every frame advance and
+ * `onComplete` fires when a non-looping clip reaches its last frame.
+ *
+ * Use {@link AnimatedSprite.fromSpritesheet} to create an instance directly
+ * from a {@link Spritesheet}'s named animations.
+ */
 class AnimatedSprite extends Sprite {
     _clips = new Map();
     _currentClipName = null;
@@ -26,6 +39,10 @@ class AnimatedSprite extends Sprite {
     get playing() {
         return this._playing;
     }
+    /**
+     * Whether the current clip loops. Returns the per-call loop override if set,
+     * otherwise the clip's own `loop` flag.
+     */
     get loop() {
         if (this._loopOverride !== null) {
             return this._loopOverride;
@@ -38,6 +55,7 @@ class AnimatedSprite extends Sprite {
     set loop(loop) {
         this._loopOverride = loop;
     }
+    /** Replace all registered clips with the provided map. Clears any previously registered clips first. */
     setClips(clips) {
         this._clips.clear();
         for (const [name, clip] of Object.entries(clips)) {
@@ -45,6 +63,7 @@ class AnimatedSprite extends Sprite {
         }
         return this;
     }
+    /** Register a named clip. Frame rectangles are cloned so the caller may mutate the originals. */
     defineClip(name, clip) {
         if (name.trim().length === 0) {
             throw new Error('AnimatedSprite clip names must be non-empty strings.');
@@ -63,6 +82,7 @@ class AnimatedSprite extends Sprite {
         });
         return this;
     }
+    /** Remove a registered clip by name. Stops playback first if the clip is currently active. */
     removeClip(name) {
         if (this._currentClipName === name) {
             this.stop();
@@ -70,6 +90,11 @@ class AnimatedSprite extends Sprite {
         this._clips.delete(name);
         return this;
     }
+    /**
+     * Start playing the named clip. By default restarts from frame 0; pass
+     * `{ restart: false }` to resume from the current frame if the same clip
+     * is already active. Optionally overrides the clip's loop setting.
+     */
     play(name, options = {}) {
         const clip = this._clips.get(name);
         if (!clip) {
@@ -88,6 +113,7 @@ class AnimatedSprite extends Sprite {
         this._playing = true;
         return this;
     }
+    /** Stop playback and rewind the active clip to frame 0. */
     stop() {
         this._playing = false;
         this._elapsedFrameTimeMs = 0;
@@ -112,6 +138,11 @@ class AnimatedSprite extends Sprite {
         }
         return this;
     }
+    /**
+     * Advance playback by `delta` milliseconds (or a `Time` object). Call once
+     * per frame from the game loop. Dispatches `onFrame` for each frame
+     * boundary crossed and `onComplete` when a non-looping clip ends.
+     */
     update(delta) {
         if (!this._playing || this._currentClipName === null) {
             return this;
@@ -158,6 +189,11 @@ class AnimatedSprite extends Sprite {
         }
         this._clips.clear();
     }
+    /**
+     * Construct an {@link AnimatedSprite} from the named animations defined on
+     * a {@link Spritesheet}. Each animation becomes a looping clip whose frames
+     * are the spritesheet frame rectangles in declaration order.
+     */
     static fromSpritesheet(spritesheet) {
         const clips = {};
         for (const [clipName, frameNames] of spritesheet.animations) {

package/dist/esm/rendering/sprite/AnimatedSprite.js.map

@@ -1 +1 @@
-{"version":3,"file":"AnimatedSprite.js","sources":["../../../../../src/rendering/sprite/AnimatedSprite.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}
+{"version":3,"file":"AnimatedSprite.js","sources":["../../../../../src/rendering/sprite/AnimatedSprite.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/rendering/sprite/Sprite.d.ts

@@ -4,6 +4,11 @@ import { Vector } from '@/math/Vector';
 import { Interval } from '@/math/Interval';
 import type { Texture } from '@/rendering/texture/Texture';
 import type { RenderTexture } from '@/rendering/texture/RenderTexture';
+/**
+ * Internal dirty-flag bitmask used by {@link Sprite} to lazily recompute
+ * derived data (vertices, normals, texture coordinates, bounding boxes).
+ * @internal
+ */
 export declare enum SpriteFlags {
     None = 0,
     Translation = 1,
@@ -18,6 +23,21 @@ export declare enum SpriteFlags {
     Vertices = 1024,
     Normals = 2048
 }
+/**
+ * The primary 2D drawable for textured quads and the foundation of the
+ * rendering hierarchy.
+ *
+ * A Sprite wraps a {@link Texture} (or {@link RenderTexture}) and exposes
+ * full transform control (position, rotation, scale, origin) inherited from
+ * {@link Drawable}. The rendered quad is derived from `textureFrame`, which
+ * defaults to the full texture dimensions but can be narrowed to a sub-region
+ * (e.g. a frame from a {@link Spritesheet}).
+ *
+ * Vertex and normal data are computed lazily and cached until the transform
+ * or frame changes, making repeated read access free after the first evaluation.
+ * Collision helpers — `contains`, `getNormals`, `project` — are overridden to
+ * operate on the exact rotated quad rather than the AABB.
+ */
 export declare class Sprite extends Drawable {
     private _texture;
     private _textureFrame;
@@ -33,16 +53,52 @@ export declare class Sprite extends Drawable {
     set width(value: number);
     get height(): number;
     set height(value: number);
+    /**
+     * World-space corner positions of the sprite quad, computed lazily from the
+     * current transform and texture frame. Layout: [x0,y0, x1,y1, x2,y2, x3,y3]
+     * (TL, TR, BR, BL). Cached until the transform is invalidated.
+     */
     get vertices(): Float32Array;
+    /**
+     * Packed UV coordinates for the four quad corners, encoded as two
+     * 16-bit fixed-point values per element (low 16 bits = U, high 16 bits = V,
+     * each in the range 0–65535). Accounts for `Texture.flipY`. Throws if no
+     * texture is assigned.
+     */
     get texCoords(): Uint32Array;
+    /** Assign a new texture, refreshing the texture frame to the full texture dimensions. */
     setTexture(texture: Texture | RenderTexture | null): this;
+    /** Signal the GPU backend that the underlying texture source has changed and reset the frame to full dimensions. */
     updateTexture(): this;
+    /**
+     * Set a sub-region of the texture to render.
+     * When `resetSize` is `true` (default) the sprite's logical size snaps to
+     * the new frame dimensions; pass `false` to keep the current pixel size
+     * (useful for animation playback where the frame changes but the display
+     * size should stay constant).
+     */
     setTextureFrame(frame: Rectangle, resetSize?: boolean): this;
+    /** Reset the texture frame to the full dimensions of the current texture. Throws if no texture is set. */
     resetTextureFrame(): this;
+    /**
+     * Return the four outward-facing edge normals of the rotated quad, lazily
+     * computed from `vertices`. Used by the SAT collision system.
+     */
     getNormals(): Array<Vector>;
+    /**
+     * Project all four quad vertices onto `axis` and return the resulting
+     * scalar interval. Used by the SAT collision system.
+     */
     project(axis: Vector, result?: Interval): Interval;
+    /**
+     * Return `true` if the world-space point (`x`, `y`) lies inside the quad.
+     * Uses a fast AABB check when the rotation is a multiple of 90°, and the
+     * exact dot-product test for arbitrary angles.
+     */
     contains(x: number, y: number): boolean;
+    /** @internal */
     _invalidateSubtreeTransform(): void;
+    /** @internal */
     _invalidateBoundsCascade(): void;
     destroy(): void;
 }

package/dist/esm/rendering/sprite/Sprite.js

@@ -4,6 +4,11 @@ import { Vector } from '../../math/Vector.js';
 import { Interval } from '../../math/Interval.js';
 import { RenderNode } from '../RenderNode.js';
 
+/**
+ * Internal dirty-flag bitmask used by {@link Sprite} to lazily recompute
+ * derived data (vertices, normals, texture coordinates, bounding boxes).
+ * @internal
+ */
 var SpriteFlags;
 (function (SpriteFlags) {
     SpriteFlags[SpriteFlags["None"] = 0] = "None";
@@ -19,6 +24,21 @@ var SpriteFlags;
     SpriteFlags[SpriteFlags["Vertices"] = 1024] = "Vertices";
     SpriteFlags[SpriteFlags["Normals"] = 2048] = "Normals";
 })(SpriteFlags || (SpriteFlags = {}));
+/**
+ * The primary 2D drawable for textured quads and the foundation of the
+ * rendering hierarchy.
+ *
+ * A Sprite wraps a {@link Texture} (or {@link RenderTexture}) and exposes
+ * full transform control (position, rotation, scale, origin) inherited from
+ * {@link Drawable}. The rendered quad is derived from `textureFrame`, which
+ * defaults to the full texture dimensions but can be narrowed to a sub-region
+ * (e.g. a frame from a {@link Spritesheet}).
+ *
+ * Vertex and normal data are computed lazily and cached until the transform
+ * or frame changes, making repeated read access free after the first evaluation.
+ * Collision helpers — `contains`, `getNormals`, `project` — are overridden to
+ * operate on the exact rotated quad rather than the AABB.
+ */
 class Sprite extends Drawable {
     _texture = null;
     _textureFrame = new Rectangle();
@@ -59,6 +79,11 @@ class Sprite extends Drawable {
     set height(value) {
         this.scale.y = (value / this._textureFrame.height);
     }
+    /**
+     * World-space corner positions of the sprite quad, computed lazily from the
+     * current transform and texture frame. Layout: [x0,y0, x1,y1, x2,y2, x3,y3]
+     * (TL, TR, BR, BL). Cached until the transform is invalidated.
+     */
     get vertices() {
         if (this.flags.has(SpriteFlags.Vertices)) {
             const { left, top, right, bottom } = this.getLocalBounds();
@@ -75,6 +100,12 @@ class Sprite extends Drawable {
         }
         return this._vertices;
     }
+    /**
+     * Packed UV coordinates for the four quad corners, encoded as two
+     * 16-bit fixed-point values per element (low 16 bits = U, high 16 bits = V,
+     * each in the range 0–65535). Accounts for `Texture.flipY`. Throws if no
+     * texture is assigned.
+     */
     get texCoords() {
         if (this._texture === null) {
             throw new Error('texCoords can only be calculated when the sprite has a texture');
@@ -101,6 +132,7 @@ class Sprite extends Drawable {
         }
         return this._texCoords;
     }
+    /** Assign a new texture, refreshing the texture frame to the full texture dimensions. */
     setTexture(texture) {
         if (this._texture !== texture) {
             this._texture = texture;
@@ -109,6 +141,7 @@ class Sprite extends Drawable {
         }
         return this;
     }
+    /** Signal the GPU backend that the underlying texture source has changed and reset the frame to full dimensions. */
     updateTexture() {
         if (this._texture) {
             this._texture.updateSource();
@@ -117,6 +150,13 @@ class Sprite extends Drawable {
         }
         return this;
     }
+    /**
+     * Set a sub-region of the texture to render.
+     * When `resetSize` is `true` (default) the sprite's logical size snaps to
+     * the new frame dimensions; pass `false` to keep the current pixel size
+     * (useful for animation playback where the frame changes but the display
+     * size should stay constant).
+     */
     setTextureFrame(frame, resetSize = true) {
         const width = this.width;
         const height = this.height;
@@ -135,12 +175,17 @@ class Sprite extends Drawable {
         this.invalidateCache();
         return this;
     }
+    /** Reset the texture frame to the full dimensions of the current texture. Throws if no texture is set. */
     resetTextureFrame() {
         if (!this._texture) {
             throw new Error('Cannot reset texture frame when no texture was set');
         }
         return this.setTextureFrame(Rectangle.temp.set(0, 0, this._texture.width, this._texture.height));
     }
+    /**
+     * Return the four outward-facing edge normals of the rotated quad, lazily
+     * computed from `vertices`. Used by the SAT collision system.
+     */
     getNormals() {
         if (this.flags.has(SpriteFlags.Normals)) {
             const [x1, y1, x2, y2, x3, y3, x4, y4] = this.vertices;
@@ -152,6 +197,10 @@ class Sprite extends Drawable {
         }
         return this._normals;
     }
+    /**
+     * Project all four quad vertices onto `axis` and return the resulting
+     * scalar interval. Used by the SAT collision system.
+     */
     project(axis, result = new Interval()) {
         const [x1, y1, x2, y2, x3, y3, x4, y4] = this.vertices;
         const proj1 = axis.dot(x1, y1);
@@ -160,6 +209,11 @@ class Sprite extends Drawable {
         const proj4 = axis.dot(x4, y4);
         return result.set(Math.min(proj1, proj2, proj3, proj4), Math.max(proj1, proj2, proj3, proj4));
     }
+    /**
+     * Return `true` if the world-space point (`x`, `y`) lies inside the quad.
+     * Uses a fast AABB check when the rotation is a multiple of 90°, and the
+     * exact dot-product test for arbitrary angles.
+     */
     contains(x, y) {
         if ((this.rotation % 90 === 0)) {
             return this.getBounds().contains(x, y);
@@ -168,10 +222,12 @@ class Sprite extends Drawable {
         return (dotA > 0) && (dotA <= lenA)
             && (dotB > 0) && (dotB <= lenB);
     }
+    /** @internal */
     _invalidateSubtreeTransform() {
         super._invalidateSubtreeTransform();
         this.flags.push(SpriteFlags.Vertices | SpriteFlags.Normals);
     }
+    /** @internal */
     _invalidateBoundsCascade() {
         super._invalidateBoundsCascade();
         this.flags.push(SpriteFlags.Vertices | SpriteFlags.Normals);