@league-of-foundry-developers/foundry-vtt-types 13.340.1 → 13.345.1

package/src/foundry/client/canvas/geometry/edges/edges.d.mts

@@ -0,0 +1,70 @@
+import type { Identity, InexactPartial } from "#utils";
+import type Edge from "./edge.d.mts";
+import type { Quadtree } from "../_module.d.mts";
+
+/**
+ * A specialized Map class that manages all edges used to restrict perception in a Scene.
+ * Integrates with a Quadtree for efficient spatial queries.
+ */
+declare class CanvasEdges extends Map<string, Edge> {
+  /**
+   * Clear content and initializes the quadtree.
+   * @remarks Calls `"initializeEdges"` hook via `callAll`
+   */
+  initialize(): void;
+
+  override set(key: string, value: Edge): this;
+
+  override delete(key: string): boolean;
+
+  override clear(): void;
+
+  /**
+   * Incrementally refreshes edges by computing intersections between all registered edges.
+   * Utilizes the Quadtree to optimize the intersection detection process.
+   */
+  refresh(): void;
+
+  /**
+   * Retrieves edges that intersect with a given rectangle.
+   * Utilizes the Quadtree for efficient spatial querying.
+   * @param rect - The rectangle to query against.
+   * @returns A set of {@linkcode Edge} instances that intersect with the provided rectangle.
+   */
+  getEdges(rect: PIXI.Rectangle, options?: CanvasEdges.GetEdgesOptions): Set<Edge>;
+
+  #CanvasEdges: true;
+}
+
+declare namespace CanvasEdges {
+  interface Any extends AnyCanvasEdges {}
+  interface AnyConstructor extends Identity<typeof AnyCanvasEdges> {}
+
+  /** @internal */
+  type _GetEdgesOptions = InexactPartial<{
+    /**
+     * Should inner bounds be added?
+     * @defaultValue `false`
+     */
+    includeInnerBounds: boolean;
+
+    /**
+     * Should outer bounds be added?
+     * @defaultValue `true`
+     */
+    includeOuterBounds: boolean;
+
+    /**
+     * Collision function to test edge inclusion.
+     */
+    collisionTest: Quadtree.CollisionTestFunction<Edge>;
+  }>;
+
+  interface GetEdgesOptions extends _GetEdgesOptions {}
+}
+
+export default CanvasEdges;
+
+declare abstract class AnyCanvasEdges extends CanvasEdges {
+  constructor(...args: never);
+}

package/src/foundry/client/canvas/geometry/edges/vertex.d.mts

@@ -0,0 +1,198 @@
+import type { Identity, InexactPartial } from "#utils";
+import type Edge from "./edge.d.mts";
+import type { Canvas } from "#client/canvas/_module.d.mts";
+import type { LineIntersection } from "#common/utils/geometry.mjs";
+
+/**
+ * A specialized point data structure used to represent vertices in the context of the ClockwiseSweepPolygon.
+ * This class is not designed or intended for use outside of that context.
+ */
+declare class PolygonVertex {
+  constructor(x: number, y: number, options?: PolygonVertex.ConstructorOptions);
+
+  x: number;
+
+  y: number;
+
+  /** @defaultValue `PolygonVertex.getKey(this.x, this.y)` */
+  key: number;
+
+  /**
+   * Determine the sort key to use for this vertex, arranging points from north-west to south-east.
+   * @param x - The x-coordinate
+   * @param y - The y-coordinate
+   * @returns The key used to identify the vertex
+   */
+  static getKey(x: number, y: number): number;
+
+  /**
+   * The set of edges which connect to this vertex.
+   * This set is initially empty and populated later after vertices are de-duplicated.
+   * @defaultValue `new Set()`
+   */
+  edges: Set<Edge>;
+
+  /**
+   * The subset of edges which continue clockwise from this vertex.
+   * @defaultValue `new Set()`
+   */
+  cwEdges: Set<Edge>;
+
+  /**
+   * The subset of edges which continue counter-clockwise from this vertex.
+   * @defaultValue `new Set()`
+   */
+  ccwEdges: Set<Edge>;
+
+  /**
+   * The set of vertices collinear to this vertex
+   * @defaultValue `new Set()`
+   */
+  collinearVertices: Set<PolygonVertex>;
+
+  /**
+   * Is this vertex an endpoint of one or more edges?
+   */
+  isEndpoint: boolean | undefined;
+
+  /**
+   * Does this vertex have a single counterclockwise limiting edge?
+   */
+  isLimitingCCW: boolean | undefined;
+
+  /**
+   * Does this vertex have a single clockwise limiting edge?
+   */
+  isLimitingCW: boolean | undefined;
+
+  /**
+   * Does this vertex have non-limited edges or 2+ limited edges counterclockwise?
+   */
+  isBlockingCCW: boolean | undefined;
+
+  /**
+   * Does this vertex have non-limited edges or 2+ limited edges clockwise?
+   */
+  isBlockingCW: boolean | undefined;
+
+  /**
+   * Does this vertex result from an internal collision?
+   * @defaultValue `false`
+   */
+  isInternal: boolean;
+
+  /**
+   * The maximum restriction imposed by this vertex.
+   * @defaultValue {@linkcode CONST.WALL_SENSE_TYPES.NONE}
+   * @remarks Actually initialized to `0` literal, but is meant as a `WALL_SENSE_TYPES`
+   */
+  restriction: CONST.WALL_SENSE_TYPES;
+
+  /**
+   * Record whether this PolygonVertex has been visited in the sweep
+   * @defaultValue `false`
+   * @remarks Set externally during {@linkcode ClockwiseSweepPolygon} initialization
+   * @internal
+   */
+  protected _visited: boolean;
+
+  /**
+   * The distance from a polygon origin to this vertex.
+   * @defaultValue `undefined`
+   * @remarks Set to the value passed in construction options. Accessed externally in {@linkcode ClockwiseSweepPolygon._testCollision | ClockwiseSweepPolygon#_testCollision}
+   * @internal
+   */
+  protected _distance: number | undefined;
+
+  /**
+   * The squared distance from a polygon origin to this vertex.
+   * @defaultValue `undefined`
+   * @remarks Only set *or* read externally in {@linkcode ClockwiseSweepPolygon} methods
+   * @internal
+   */
+  protected _d2: number | undefined;
+
+  /**
+   * The integer index of this vertex in an ordered sweep.
+   * @remarks Set to the value passed in construction options. Accessed externally in {@linkcode ClockwiseSweepPolygon} methods
+   * @internal
+   */
+  protected _index: number | undefined;
+
+  /**
+   * The angle of the ray from the origin to this vertex.
+   * @remarks Only set *or* read externally in {@linkcode ClockwiseSweepPolygon._sortVertices | ClockwiseSweepPolygon#_sortVertices}
+   * @internal
+   */
+  protected _angle: number | undefined;
+
+  /**
+   * The line intersection coordinates of the two edges that create this vertex.
+   * @remarks Only set *or* read externally in {@linkcode ClockwiseSweepPolygon} methods
+   * @internal
+   */
+  protected _intersectionCoordinates: LineIntersection | undefined;
+
+  /**
+   * Is this vertex limited in type?
+   */
+  get isLimited(): boolean;
+
+  /**
+   * Associate an edge with this vertex.
+   * @param edge        - The edge being attached
+   * @param orientation - The orientation of the edge with respect to the origin
+   * @param type        - The restriction type of the polygon being created
+   */
+  attachEdge(edge: Edge, orientation: number, type: CONST.WALL_RESTRICTION_TYPES): void;
+
+  /**
+   * Is this vertex terminal (at the maximum radius)
+   */
+  get isTerminal(): boolean;
+
+  /**
+   * Is this vertex the same point as some other vertex?
+   * @param other - Some other vertex
+   * @returns Are they the same point?
+   */
+  equals(other: PolygonVertex): boolean;
+
+  /**
+   * Construct a PolygonVertex instance from some other Point structure.
+   * @param point   - The point
+   * @param options - Additional options that apply to this vertex
+   * @returns The constructed vertex
+   */
+  static fromPoint(point: Canvas.Point, options?: PolygonVertex.ConstructorOptions): PolygonVertex;
+
+  #PolygonVertex: true;
+}
+
+declare namespace PolygonVertex {
+  interface Any extends AnyPolygonVertex {}
+  interface AnyConstructor extends Identity<typeof AnyPolygonVertex> {}
+
+  /** @internal */
+  type _ConstructorOptions = InexactPartial<{
+    /** A known distance from a polygon origin to this vertex. */
+    distance: number;
+
+    /** An integer index of this vertex in an ordered sweep. */
+    index: number;
+
+    /**
+     * Whether to round the input `{x,y}` coordinates provided.
+     * @defaultValue `false`
+     */
+    round: boolean;
+  }>;
+
+  interface ConstructorOptions extends _ConstructorOptions {}
+}
+
+export default PolygonVertex;
+
+declare abstract class AnyPolygonVertex extends PolygonVertex {
+  constructor(...args: never);
+}

package/src/foundry/client/canvas/geometry/observable-transform.d.mts

@@ -0,0 +1,39 @@
+import type { Identity } from "#utils";
+
+/**
+ * A custom Transform class allowing to observe changes with a callback.
+ * @privateRemarks Scope extends object is intentional; `"The scope bound to an ObservableTransform class must be a valid object/class."`
+ */
+declare class ObservableTransform<CB extends (this: Scope) => unknown, Scope extends object> extends PIXI.Transform {
+  /**
+   *
+   * @param callback - The callback called to observe changes.
+   * @param scope    - The scope of the callback.
+   */
+  constructor(callback: CB, scope: Scope);
+
+  /**
+   * The callback which is observing the changes.
+   */
+  cb: CB;
+
+  /**
+   * The scope of the callback.
+   */
+  scope: Scope;
+
+  protected override onChange(): void;
+
+  protected override updateSkew(): void;
+}
+
+declare namespace ObservableTransform {
+  interface Any extends AnyObservableTransform {}
+  interface AnyConstructor extends Identity<typeof AnyObservableTransform> {}
+}
+
+export default ObservableTransform;
+
+declare abstract class AnyObservableTransform extends ObservableTransform<any, any> {
+  constructor(...args: never);
+}

package/src/foundry/client/canvas/geometry/quad-tree.d.mts

@@ -0,0 +1,324 @@
+import type { Brand, Identity, InexactPartial, ToMethod } from "#utils";
+import type { Canvas } from "#client/canvas/_module.d.mts";
+import type { PrimaryCanvasObjectMixin } from "#client/canvas/primary/_module.d.mts";
+import type { PlaceableObject } from "#client/canvas/placeables/_module.d.mts";
+import type Edge from "./edges/edge.d.mts";
+
+/**
+ * A Quadtree implementation that supports collision detection for rectangles.
+ */
+declare class Quadtree<out T> {
+  /**
+   * @param bounds  - The outer bounds of the region
+   * @param options - Additional options which configure the Quadtree
+   */
+  constructor(bounds: Canvas.Rectangle, options?: Quadtree.Options<T>);
+
+  /**
+   * Bounding rectangle of the quadtree.
+   */
+  protected _bounds: PIXI.Rectangle;
+
+  /**
+   * The maximum number of objects allowed within this node before it must split
+   * @defaultValue `20`
+   */
+  maxObjects: number;
+
+  /**
+   * The maximum number of levels that the base quadtree is allowed
+   * @defaultValue `4`
+   */
+  maxDepth: number;
+
+  /**
+   * The depth of this node within the root Quadtree
+   * @defaultValue `0`
+   */
+  depth: number;
+
+  /**
+   * The objects contained at this level of the tree
+   * @defaultValue `[]`
+   */
+  objects: Quadtree.Object<T>[];
+
+  /**
+   * Children of this node
+   * @defaultValue `[]`
+   */
+  nodes: Quadtree<T>[];
+
+  /**
+   * The root Quadtree
+   */
+  root: Quadtree<T>;
+
+  /**
+   * A constant that enumerates the index order of the quadtree nodes from top-left to bottom-right.
+   */
+  static INDICES: Quadtree.Indices;
+
+  /**
+   * The bounding rectangle of the region
+   */
+  get bounds(): PIXI.Rectangle;
+
+  set bounds(newBounds);
+
+  /**
+   * The width of the bounding rectangle
+   */
+  get width(): number;
+
+  set width(w);
+
+  /**
+   * The height of the bounding rectangle
+   */
+  get height(): number;
+
+  set height(h);
+
+  /**
+   * The x-coordinate of the bounding rectangle
+   */
+  get x(): number;
+
+  set x(x);
+
+  /**
+   * The y-coordinate of the bounding rectangle
+   */
+  get y(): number;
+
+  set y(y);
+
+  /**
+   * Return an array of all the objects in the Quadtree (recursive)
+   */
+  get all(): Quadtree.Object<T>[];
+
+  /**
+   * Re-position the bounding rectangle of this Quadtree, clear existing data, and re-insert all objects.
+   * Useful if the Quadtree needs to move.
+   * @param x - The new x-coordinate of the bounding rectangle
+   * @param y - The new y-coordinate of the bounding rectangle
+   * @returns This Quadtree for method chaining
+   */
+  setPosition(x: number, y: number): this;
+
+  /**
+   * Re-dimension the bounding rectangle of this Quadtree, clear existing data, and re-insert all objects.
+   * Useful if the underlying canvas or region is resized.
+   * @param width  - The new width of the bounding rectangle
+   * @param height - The new height of the bounding rectangle
+   * @returns This Quadtree for method chaining
+   */
+  setDimensions(width: number, height: number): this;
+
+  /**
+   * Split this node into 4 sub-nodes.
+   * @returns The split Quadtree
+   */
+  split(): this;
+
+  /**
+   * Clear the quadtree of all existing contents
+   * @returns The cleared Quadtree
+   */
+  clear(): this;
+
+  /**
+   * Add a rectangle object to the tree
+   * @param obj - The object being inserted
+   * @returns The Quadtree nodes the object was added to.
+   */
+  insert(obj: Quadtree.Object<T>): Quadtree<T>[];
+
+  /**
+   * Remove an object from the quadtree
+   * @param target - The quadtree target being removed
+   * @returns The Quadtree for method chaining
+   */
+  remove(target: T): this;
+
+  /**
+   * Remove an existing object from the quadtree and re-insert it with a new position
+   * @param obj - The object being inserted
+   * @returns The Quadtree nodes the object was added to
+   */
+  update(obj: Quadtree.Object<T>): Quadtree<T>[];
+
+  /**
+   * Get all the objects which could collide with the provided rectangle
+   * @param rect - The normalized target rectangle
+   * @param options - Options affecting the collision test.
+   * @returns The objects in the Quadtree which represent potential collisions
+   */
+  getObjects(rect: Canvas.Rectangle, options?: Quadtree.GetObjectsOptions<T>): Set<T>;
+
+  /**
+   * Obtain the leaf nodes to which a target rectangle belongs.
+   * This traverses the quadtree recursively obtaining the final nodes which have no children.
+   * @param rect - The target rectangle.x
+   * @returns The Quadtree nodes to which the target rectangle belongs
+   */
+  getLeafNodes(rect: Canvas.Rectangle): Quadtree<T>[];
+
+  /**
+   * Obtain the child nodes within the current node which a rectangle belongs to.
+   * Note that this function is not recursive, it only returns nodes at the current or child level.
+   * @param rect - The target rectangle.
+   * @returns The Quadtree nodes to which the target rectangle belongs
+   */
+  getChildNodes(rect: Canvas.Rectangle): Quadtree<T>[];
+
+  /**
+   * Identify all nodes which are adjacent to this one within the parent Quadtree.
+   */
+  getAdjacentNodes(): Quadtree<T>[];
+
+  /**
+   * Visualize the nodes and objects in the quadtree
+   */
+  visualize(options?: Quadtree.VisualizeOptions): void;
+}
+
+declare namespace Quadtree {
+  interface Any extends AnyQuadtree {}
+  interface AnyConstructor extends Identity<typeof AnyQuadtree> {}
+
+  /** @internal */
+  type _OptionalSet<T> = InexactPartial<{
+    /** @remarks Foundry never passes an object including `n`, which is handled by `obj.n = obj.n || new Set()` in `#insert()` */
+    n?: Set<Quadtree<T>>;
+  }>;
+
+  /** @internal */
+  interface _ObjectBase<T> {
+    r: Canvas.Rectangle;
+    t: 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`
+     */
+    maxObjects: number;
+
+    /**
+     * The maximum number of levels within the root Quadtree
+     * @defaultValue `4`
+     */
+    maxDepth: number;
+
+    /**
+     * The depth level of the sub-tree. For internal use
+     * @defaultValue `0`
+     * @remarks Can't be `null` because of an `=== 0` check in `#visualize()`, and it only has a parameter default
+     * @internal
+     */
+    _depth: number;
+
+    /**
+     * The root of the quadtree. For internal use
+     * @internal
+     */
+    _root: Quadtree<T> | null;
+  }>;
+
+  /**
+   * Additional options which configure the Quadtree
+   */
+  interface Options<T> extends _Options<T> {}
+
+  type CollisionTestFunction<T> = ToMethod<(o: Quadtree.Object<T>, rect: PIXI.Rectangle) => boolean>;
+
+  /** @internal */
+  type _GetObjectsOptions<T> = InexactPartial<{
+    /**
+     * 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.
+     */
+    // Note(LukeAbby): Made a method to preserve covariance.
+    collisionTest: CollisionTestFunction<T>;
+
+    /**
+     * The existing result set, for internal use.
+     * @defaultValue `new Set<T>()`
+     * @internal
+     */
+    _s: Set<T>;
+  }>;
+
+  interface GetObjectsOptions<T> extends _GetObjectsOptions<T> {}
+
+  /** @internal */
+  type _VisualizeOptions = InexactPartial<{
+    /**
+     * 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:
+ * - {@linkcode foundry.canvas.groups.PrimaryCanvasGroup.quadtree | canvas.primary.quadtree}: {@linkcode foundry.canvas.primary.PrimaryCanvasObjectMixin.AnyMixed | PrimaryCanvasObject}s (generally if not always {@linkcode foundry.canvas.primary.PrimarySpriteMesh | PrimarySpriteMesh}es)
+ * - Various {@linkcode foundry.canvas.layers.PlaceablesLayer.quadtree | PlaceablesLayer} subclasses: Their associated {@linkcode foundry.canvas.placeables.PlaceableObject.Any | PlaceableObject}s
+ * - {@linkcode foundry.canvas.geometry.edges.CanvasEdges | canvas.edges}: {@linkcode foundry.canvas.geometry.edges.Edge | Edge}s (this quadtree is true private on `CanvasEdges` so can't be linked to)
+ */
+declare class CanvasQuadtree<out T extends CanvasQuadtree.CanvasQuadtreeObject> extends Quadtree<T> {
+  /**
+   * Create a CanvasQuadtree which references `canvas.dimensions.rect`.
+   * We pass an empty object to the parent, then override `_bounds`.
+   * @param options - Additional options passed to the parent Quadtree.
+   */
+  constructor(options?: Quadtree.Options<T>);
+
+  /**
+   * @remarks This is `defineProperty`'d as an accessor in construction, explicitly `configurable: true, enumerable: true`.
+   *
+   * The getter returns {@linkcode Canvas.Dimensions.rect | canvas.dimensions.rect} if it exists or a new, all-zeroes, PIXI.Rectangle otherwise
+   *
+   * The setter is a no-op that drops a console warning: "`CanvasQuadtree` ignores direct assignment to `_bounds`; it always uses `canvas.dimensions.rect`."
+   */
+  protected _bounds: PIXI.Rectangle;
+}
+
+declare namespace CanvasQuadtree {
+  interface Any extends AnyCanvasQuadtree {}
+  interface AnyConstructor extends Identity<typeof AnyCanvasQuadtree> {}
+
+  /** @remarks See {@linkcode CanvasQuadtree} class description */
+  type CanvasQuadtreeObject = PrimaryCanvasObjectMixin.AnyMixed | PlaceableObject.Any | Edge;
+}
+
+export { Quadtree as default, CanvasQuadtree };
+
+declare abstract class AnyQuadtree extends Quadtree<unknown> {
+  constructor(...args: never);
+}
+
+declare abstract class AnyCanvasQuadtree extends CanvasQuadtree<CanvasQuadtree.CanvasQuadtreeObject> {
+  constructor(...args: never);
+}