@league-of-foundry-developers/foundry-vtt-types 12.331.3-beta → 12.331.5

package/src/foundry/client/pixi/core/containers/point-source-mesh.d.mts

@@ -1,26 +1,27 @@
-export {};
+import type { Identity } from "#utils";
 
 declare global {
   /**
    * Extension of a PIXI.Mesh, with the capabilities to provide a snapshot of the framebuffer.
+   * @remarks Foundry only uses this with `AdaptiveLightingShader` subclasses, thus the type param default
    */
-  class PointSourceMesh extends PIXI.Mesh {
+  class PointSourceMesh<Shader extends PIXI.Shader = AdaptiveLightingShader> extends PIXI.Mesh<Shader> {
     /**
-     * @remarks This override is not in the actual Foundry code, this is reflecting actual usage.
-     * PIXI.Mesh asks for a PIXI.MeshMaterial for its second argument, a subclass of PIXI.Shader.
-     * But foundry doesn't use those additional properties, so in actual practice it just needs PIXI.Shader.
+     * @remarks This override is not in the actual Foundry code, it's just to sync up the Shader type param with super
      */
-    constructor(geometry: PIXI.Geometry, shader: PIXI.Shader, state?: PIXI.State, drawMode?: PIXI.DRAW_MODES);
+    constructor(geometry: PIXI.Geometry, shader: Shader, state?: PIXI.State, drawMode?: PIXI.DRAW_MODES);
 
     /**
      * To store the previous blend mode of the last renderer PointSourceMesh.
+     * @privateRemarks Despite being `protected`, this is accessed externally in `CanvasIlluminationEffects#render`
      */
-    protected static _priorBlendMode: PIXI.BLEND_MODES;
+    protected static _priorBlendMode: PIXI.BLEND_MODES | undefined;
 
     /**
      * The current texture used by the mesh.
+     * @privateRemarks Despite being `protected`, this is accessed externally in `CanvasIlluminationEffects#render`
      */
-    protected static _currentTexture: PIXI.Texture;
+    protected static _currentTexture: PIXI.Texture | undefined;
 
     /**
      * The transform world ID of the bounds.
@@ -44,12 +45,6 @@ declare global {
     /** @throws You can't add children to a PointSourceMesh. */
     override addChildAt(): never;
 
-    /**
-     * @throws You can't add children to a PointSourceMesh.
-     * @privateRemarks This method is meant to be an override, but the PIXI.Mesh class does not have an addChildren() method
-     */
-    addChildren(): never;
-
     protected override _render(renderer: PIXI.Renderer): void;
 
     override calculateBounds(): void;
@@ -57,6 +52,21 @@ declare global {
     protected override _calculateBounds(): void;
 
     /** The local bounds need to be drawn from the underlying geometry. */
-    override getLocalBounds(rect?: PIXI.Rectangle): PIXI.Rectangle;
+    override getLocalBounds(
+      /**
+       * @defaultValue `new PIXI.Rectangle()`
+       * @remarks Default provided by `??=` in function body. `null` would be allowable here but breaks inheritance
+       */
+      rect?: PIXI.Rectangle,
+    ): PIXI.Rectangle;
   }
+
+  namespace PointSourceMesh {
+    interface Any extends AnyPointSourceMesh {}
+    interface AnyConstructor extends Identity<typeof AnyPointSourceMesh> {}
+  }
+}
+
+declare abstract class AnyPointSourceMesh extends PointSourceMesh<PIXI.Shader.Any> {
+  constructor(...args: never);
 }

package/src/foundry/client/pixi/core/containers/quad-mesh.d.mts

@@ -1,15 +1,16 @@
-export {};
+import type { Identity } from "#utils";
 
 declare global {
   /**
    * A basic rectangular mesh with a shader only. Does not natively handle textures (but a bound shader can).
    * Bounds calculations are simplified and the geometry does not need to handle texture coords.
+   * @privateRemarks Ideally the `shaderClass` passed to the constructor and `get shader()` could be synced up, but `setShaderClass` removes that option
    */
   class QuadMesh extends PIXI.Container {
     /**
      * @param shaderClass - The shader class to use.
      */
-    constructor(shaderClass: typeof AbstractBaseShader);
+    constructor(shaderClass: AbstractBaseShader.AnyConstructor);
 
     /**
      * The shader bound to this mesh.
@@ -21,15 +22,15 @@ declare global {
      */
     get blendMode(): PIXI.BLEND_MODES;
 
-    set blendMode(value: PIXI.BLEND_MODES);
+    set blendMode(value);
 
     /**
      * Initialize shader based on the shader class type.
      * @param shaderClass - Shader class used. Must inherit from AbstractBaseShader.
      */
-    setShaderClass(shaderClass: typeof AbstractBaseShader): void;
+    setShaderClass(shaderClass: AbstractBaseShader.AnyConstructor): void;
 
-    protected override _render(_renderer: PIXI.Renderer): void;
+    protected override _render(renderer: PIXI.Renderer): void;
 
     protected override _calculateBounds(): void;
 
@@ -38,6 +39,15 @@ declare global {
      */
     containsPoint(point: PIXI.IPointData): boolean;
 
-    override destroy(options?: boolean | PIXI.IDestroyOptions): void;
+    override destroy(options?: PIXI.IDestroyOptions | boolean): void;
   }
+
+  namespace QuadMesh {
+    interface Any extends AnyQuadMesh {}
+    interface AnyConstructor extends Identity<typeof AnyQuadMesh> {}
+  }
+}
+
+declare abstract class AnyQuadMesh extends QuadMesh {
+  constructor(...args: never);
 }

package/src/foundry/client/pixi/core/containers/quadtree.d.mts

@@ -1,11 +1,8 @@
-export {};
+import type { Brand, Identity, InexactPartial, NullishProps } from "#utils";
 
 declare global {
-  interface QuadtreeObject<T> {
-    r: Canvas.Rectangle;
-    t: T;
-    n: Set<Quadtree<T>>;
-  }
+  /** @deprecated {@link Quadtree.Object | `Quadtree.Object`} */
+  type QuadtreeObject<T> = Quadtree.Object<T>;
 
   /**
    * A Quadtree implementation that supports collision detection for rectangles.
@@ -14,8 +11,10 @@ declare global {
     /**
      * @param bounds  - The outer bounds of the region
      * @param options - Additional options which configure the Quadtree
+     * @remarks `bounds` is NullishProps because `PIXI.Rectangle`'s constructor casts `null`/`undefined` to `0`.
+     * A `width` or `height` of zero is likely undesirable, however.
      */
-    constructor(bounds: PIXI.Rectangle, options?: Quadtree.Options<T>);
+    constructor(bounds: NullishProps<Canvas.Rectangle>, options?: Quadtree.Options<T>);
 
     /**
      * The bounding rectangle of the region
@@ -44,7 +43,7 @@ declare global {
      * The objects contained at this level of the tree
      * @defaultValue `[]`
      */
-    objects: QuadtreeObject<T>[];
+    objects: Quadtree.Object<T>[];
 
     /**
      * Children of this node
@@ -60,17 +59,12 @@ declare global {
     /**
      * A constant that enumerates the index order of the quadtree nodes from top-left to bottom-right.
      */
-    static readonly INDICES: {
-      tl: 0;
-      tr: 1;
-      bl: 2;
-      br: 3;
-    };
+    static INDICES: Quadtree.Indices;
 
     /**
      * Return an array of all the objects in the Quadtree (recursive)
      */
-    get all(): QuadtreeObject<T>[];
+    get all(): Quadtree.Object<T>[];
 
     /**
      * Split this node into 4 sub-nodes.
@@ -89,7 +83,7 @@ declare global {
      * @param obj - The object being inserted
      * @returns The Quadtree nodes the object was added to.
      */
-    insert(obj: QuadtreeObject<T>): Quadtree<T>[];
+    insert(obj: Quadtree.Object<T>): Quadtree<T>[];
 
     /**
      * Remove an object from the quadtree
@@ -103,7 +97,7 @@ declare global {
      * @param obj - The object being inserted
      * @returns The Quadtree nodes the object was added to
      */
-    update(obj: QuadtreeObject<T>): Quadtree<T>[];
+    update(obj: Quadtree.Object<T>): Quadtree<T>[];
 
     /**
      * Get all the objects which could collide with the provided rectangle
@@ -111,21 +105,7 @@ declare global {
      * @param options - Options affecting the collision test.
      * @returns The objects in the Quadtree which represent potential collisions
      */
-    getObjects(
-      rect: Canvas.Rectangle,
-      options?: {
-        /* Function to further refine objects to return
-         * after a potential collision is found. Parameters are the object and rect, and the
-         * function should return true if the object should be added to the result set.
-         */
-        collisionTest: (o: QuadtreeObject<T>, rect: Canvas.Rectangle) => boolean;
-
-        /** The existing result set, for internal use.
-         *  (default: `new Set<T>()`)
-         */
-        _s?: Set<T>;
-      },
-    ): Set<T>;
+    getObjects(rect: Canvas.Rectangle, options?: Quadtree.GetObjectsOptions<T>): Set<T>;
 
     /**
      * Obtain the leaf nodes to which a target rectangle belongs.
@@ -150,50 +130,129 @@ declare global {
 
     /**
      * Visualize the nodes and objects in the quadtree
-     * @param objects - Visualize the rectangular bounds of objects in the Quadtree. Default is false.
-     *                  (default: `false`)
      */
-    visualize({ objects }?: { objects?: boolean }): void;
+    visualize({ objects }?: Quadtree.VisualizeOptions): void;
   }
 
-  /**
-   * A subclass of Quadtree specifically intended for classifying the location of objects on the game canvas.
-   */
-  class CanvasQuadtree extends Quadtree<object> {
-    constructor(options?: Quadtree.Options<object>);
+  namespace Quadtree {
+    interface Any extends AnyQuadtree {}
+    interface AnyConstructor extends Identity<typeof AnyQuadtree> {}
 
-    readonly bounds: PIXI.Rectangle;
-  }
+    /** @internal */
+    type _OptionalSet<T> = NullishProps<{
+      /** @remarks Foundry never passes an object including `n`, which is handled by `obj.n = obj.n || new Set()` in `#insert()` */
+      n?: Set<Quadtree<T>>;
+    }>;
 
-  namespace Quadtree {
-    /**
-     * Additional options which configure the Quadtree
-     */
-    interface Options<T> {
+    /** @internal */
+    interface _ObjectBase<T> {
+      r: Canvas.Rectangle;
+      t: T;
+    }
+
+    /** @deprecated {@link Quadtree.Object | `Quadtree.Object`} */
+    type QuadtreeObject<T> = Object<T>;
+
+    interface Object<T> extends _ObjectBase<T>, _OptionalSet<T> {}
+
+    type INDICES = Brand<number, "Quadtree.INDICES">;
+
+    interface Indices {
+      tl: 0 & Quadtree.INDICES;
+      tr: 1 & Quadtree.INDICES;
+      bl: 2 & Quadtree.INDICES;
+      br: 3 & Quadtree.INDICES;
+    }
+
+    /** @internal */
+    type _Options<T> = InexactPartial<{
       /**
        * The maximum number of objects per node
        * @defaultValue `20`
+       * @remarks Can't be `null` because it only has a parameter default.
        */
-      maxObjects?: number;
+      maxObjects: number;
 
       /**
        * The maximum number of levels within the root Quadtree
        * @defaultValue `4`
+       * @remarks Can't be `null` because it only has a parameter default.
        */
-      maxDepth?: number;
+      maxDepth: number;
 
       /**
        * The depth level of the sub-tree. For internal use
        * @defaultValue `0`
-       * @internal
+       * @remarks Can't be `null` because of an `=== 0` check in `#visualize()`, and it only has a parameter default
+       * Foundry marked `@internal`
        */
-      _depth?: number;
+      _depth: number;
 
       /**
        * The root of the quadtree. For internal use
-       * @internal
+       * Foundry marked `@internal`
        */
-      _root?: Quadtree<T>;
-    }
+      _root: Quadtree<T> | null;
+    }>;
+
+    /**
+     * Additional options which configure the Quadtree
+     */
+    interface Options<T> extends _Options<T> {}
+
+    /** @internal */
+    type _GetObjectsOptions<T> = NullishProps<{
+      /**
+       * Function to further refine objects to return
+       * after a potential collision is found. Parameters are the object and rect, and the
+       * function should return true if the object should be added to the result set.
+       */
+      collisionTest: (o: Quadtree.Object<T>, rect: Canvas.Rectangle) => boolean;
+
+      /**
+       * The existing result set, for internal use.
+       * @defaultValue `new Set<T>()`
+       * @remarks Foundry marked `@internal`
+       */
+      _s: Set<T>;
+    }>;
+
+    interface GetObjectsOptions<T> extends _GetObjectsOptions<T> {}
+
+    /** @internal */
+    type _VisualizeOptions = NullishProps<{
+      /**
+       * Visualize the rectangular bounds of objects in the Quadtree.
+       * @defaultValue `false`
+       */
+      objects: boolean;
+    }>;
+
+    interface VisualizeOptions extends _VisualizeOptions {}
+  }
+  /**
+   * A subclass of Quadtree specifically intended for classifying the location of objects on the game canvas.
+   * @remarks Foundry never uses `Quadtree` directly, only this class, and only ever fills it with `PrimaryCanvasObject`s or `PlaceableObject`s
+   */
+  class CanvasQuadtree<T extends CanvasQuadtree.CanvasQuadtreeObject> extends Quadtree<T> {
+    constructor(options?: Quadtree.Options<T>);
+
+    /** @remarks A getter for `canvas.dimensions.rect` */
+    readonly bounds: PIXI.Rectangle;
+  }
+
+  namespace CanvasQuadtree {
+    interface Any extends AnyCanvasQuadtree {}
+    interface AnyConstructor extends Identity<typeof AnyCanvasQuadtree> {}
+
+    type CanvasQuadtreeObject = PrimaryCanvasObjectMixin.AnyMixed | PlaceableObject.Any;
   }
 }
+
+declare abstract class AnyQuadtree extends Quadtree<unknown> {
+  constructor(...args: never);
+}
+
+declare abstract class AnyCanvasQuadtree extends CanvasQuadtree<CanvasQuadtree.CanvasQuadtreeObject> {
+  constructor(...args: never);
+}

package/src/foundry/client/pixi/core/containers/sprite-mesh.d.mts

@@ -1,4 +1,4 @@
-export {};
+import type { Identity } from "#utils";
 
 declare global {
   /**
@@ -11,22 +11,15 @@ declare global {
      * @param shaderCls - Shader class used by this sprite mesh.
      *                    (default: `BaseSamplerShader`)
      */
-    constructor(texture?: PIXI.Texture, shaderCls?: typeof BaseSamplerShader);
+    constructor(texture?: PIXI.Texture | null, shaderClass?: BaseSamplerShader.AnyConstructor);
 
+    /** @defaultValue `true` */
     override isSprite: boolean;
 
     /**
      * Snapshot of some parameters of this display object to render in batched mode.
      */
-    protected _batchData: {
-      _tintRGB: number;
-      _texture: PIXI.Texture;
-      indices: number[];
-      uvs: number[];
-      blendMode: PIXI.BLEND_MODES;
-      vertexData: number[];
-      worldAlpha: number;
-    };
+    protected _batchData: SpriteMesh.BatchData;
 
     /**
      * The indices of the geometry.
@@ -48,7 +41,7 @@ declare global {
     /**
      * The texture that the sprite is using.
      */
-    protected _texture: PIXI.Texture;
+    protected _texture: PIXI.Texture | null;
 
     /**
      * The texture ID
@@ -58,14 +51,15 @@ declare global {
 
     /**
      * Cached tint value so we can tell when the tint is changed.
+     * @defaultValue `[1, 1, 1, 1]`
      */
-    protected _cachedTint: [red: number, green: number, blue: number, alpha: number];
+    protected _cachedTint: Color.RGBAColorVector;
 
     /**
      * The texture trimmed ID.
      * @defaultValue `-1`
      */
-    _textureTrimmedID: number;
+    protected _textureTrimmedID: number;
 
     /**
      * This is used to store the uvs data of the sprite, assigned at the same time
@@ -102,6 +96,7 @@ declare global {
 
     /**
      * The transform ID.
+     * @defaultValue `-1`
      */
     private _transformID: number;
 
@@ -165,6 +160,7 @@ declare global {
      */
     get padding(): number;
 
+    /** @throws If `value < 0` */
     set padding(value);
 
     /**
@@ -208,6 +204,7 @@ declare global {
     /**
      * Returns the SpriteMesh associated batch plugin. By default the returned plugin is that of the associated shader.
      * If a plugin is forced, it will returns the forced plugin.
+     * @defaultValue `this._shader.pluginName`
      */
     get pluginName(): string;
 
@@ -220,12 +217,12 @@ declare global {
     /**
      * The texture that the sprite is using
      */
-    get texture(): PIXI.Texture;
+    get texture(): PIXI.Texture | null;
 
     set texture(texture);
 
     /**
-     * The anchor sets the origin point of the sprite. The default value is taken from the {@link PIXI.Texture|Texture}
+     * The anchor sets the origin point of the sprite. The default value is taken from the {@link PIXI.Texture | `PIXI.Texture`}
      * and passed to the constructor.
      *
      * The default is `(0,0)`, this means the sprite's origin is the top left.
@@ -235,8 +232,9 @@ declare global {
      * Setting the anchor to `(1,1)` would mean the sprite's origin point will be the bottom right corner.
      *
      * If you pass only single parameter, it will set both x and y to the same value as shown in the example below.
+     * @privateRemarks Technically should be `ObservablePoint<this>` but this breaks `PrimarySpriteMesh`
      */
-    get anchor(): PIXI.ObservablePoint;
+    get anchor(): PIXI.ObservablePoint<SpriteMesh.Any>;
 
     set anchor(anchor);
 
@@ -246,12 +244,13 @@ declare global {
      * A value of 0xFFFFFF will remove any tint effect.
      * @defaultValue `0xFFFFFF`
      */
-    get tint(): PIXI.ColorSource;
+    get tint(): number;
 
     set tint(tint);
 
     /**
      * The HTML source element for this SpriteMesh texture.
+     * @privateRemarks This could possibly be `PIXI.ImageSource | null`, but the below is Foundry's typing, which I think is accurate in practice
      */
     get sourceElement(): HTMLImageElement | HTMLVideoElement | null;
 
@@ -263,12 +262,12 @@ declare global {
     /**
      * When the texture is updated, this event will fire to update the scale and frame.
      */
-    _onTextureUpdate(): void;
+    protected _onTextureUpdate(): void;
 
     /**
      * Called when the anchor position updates.
      */
-    _onAnchorUpdate(): void;
+    protected _onAnchorUpdate(): void;
 
     /**
      * Update uvs and push vertices and uv buffers on GPU if necessary.
@@ -277,9 +276,9 @@ declare global {
 
     /**
      * Initialize shader based on the shader class type.
-     * @param shaderClass - Shader class used. Must inherit from AbstractBaseShader.
+     * @param shaderClass - The shader class
      */
-    setShaderClass(shaderClass: typeof AbstractBaseShader): void;
+    setShaderClass(shaderClass: BaseSamplerShader.AnyConstructor): void;
 
     override updateTransform(): void;
 
@@ -306,21 +305,65 @@ declare global {
 
     override getLocalBounds(rect: PIXI.Rectangle): PIXI.Rectangle;
 
+    /** @privateRemarks Foundry still marks this `@override` from when this class used to extend `PIXI.Mesh` */
     containsPoint(point: PIXI.IPointData): boolean;
 
-    override destroy(options: PIXI.IDestroyOptions | boolean): void;
+    override destroy(options?: PIXI.IDestroyOptions | boolean): void;
 
     /**
      * Create a SpriteMesh from another source.
      * You can specify texture options and a specific shader class derived from BaseSamplerShader.
      * @param source         - Source to create texture from.
-     * @param textureOptions - See {@link PIXI.BaseTexture}'s constructor for options.
+     * @param textureOptions - See {@link PIXI.BaseTexture | `PIXI.BaseTexture`}'s constructor for options.
      * @param shaderClass    - The shader class to use. BaseSamplerShader by default.
      */
     static from(
-      source: string | PIXI.Texture | HTMLCanvasElement | HTMLVideoElement,
+      source: PIXI.Texture | HTMLImageElement | HTMLVideoElement | string,
       textureOptions?: PIXI.IBaseTextureOptions,
-      shaderClass?: typeof AbstractBaseShader,
+      shaderClass?: BaseSamplerShader.AnyConstructor,
     ): SpriteMesh;
   }
+
+  namespace SpriteMesh {
+    interface Any extends AnySpriteMesh {}
+    interface AnyConstructor extends Identity<typeof AnySpriteMesh> {}
+
+    /** Snapshot of some parameters of this display object to render in batched mode. */
+    interface BatchData {
+      _tintRGB: number | undefined;
+      _texture: PIXI.Texture | undefined | null;
+
+      /**
+       * @defaultValue `this.#geometry.indexBuffer.data`
+       * @remarks Set during construction
+       */
+      indices: number[];
+
+      /**
+       * @defaultValue `this.#geometry.buffers[1].data`
+       * @remarks Set during construction
+       */
+      uvs: number[];
+
+      blendMode: PIXI.BLEND_MODES | undefined;
+
+      /**
+       * @defaultValue `this.#geometry.buffers[0].data`
+       * @remarks Set during construction
+       */
+      vertexData: number[];
+
+      worldAlpha: number | undefined;
+
+      /**
+       * @defaultValue `this`
+       * @remarks Set during construction
+       */
+      object: SpriteMesh;
+    }
+  }
+}
+
+declare abstract class AnySpriteMesh extends SpriteMesh {
+  constructor(...args: never);
 }

package/src/foundry/client/pixi/core/containers/unbound-container.d.mts

@@ -1,4 +1,4 @@
-import type { Transform } from "pixi.js";
+import type { Identity } from "#utils";
 
 declare global {
   /**
@@ -9,6 +9,11 @@ declare global {
     transform: UnboundTransform;
   }
 
+  namespace UnboundContainer {
+    interface Any extends AnyUnboundContainer {}
+    interface AnyConstructor extends Identity<typeof AnyUnboundContainer> {}
+  }
+
   /**
    * A custom Transform class which is not bound to the parent worldTransform.
    * localTransform are working as usual.
@@ -16,6 +21,19 @@ declare global {
   class UnboundTransform extends PIXI.Transform {
     static override IDENTITY: UnboundTransform;
 
-    override updateTransform(parentTransform: Transform): void;
+    override updateTransform(parentTransform: PIXI.Transform): void;
+  }
+
+  namespace UnboundTransform {
+    interface Any extends AnyUnboundTransform {}
+    interface AnyConstructor extends Identity<typeof AnyUnboundTransform> {}
   }
 }
+
+declare abstract class AnyUnboundContainer extends UnboundContainer {
+  constructor(...args: never);
+}
+
+declare abstract class AnyUnboundTransform extends UnboundTransform {
+  constructor(...args: never);
+}