@league-of-foundry-developers/foundry-vtt-types 13.340.0 → 13.345.1-beta.20250704.94554

package/src/foundry/client/canvas/geometry/clockwise-sweep.d.mts

@@ -0,0 +1,281 @@
+import type { Identity, InexactPartial } from "#utils";
+import type { Canvas } from "#client/canvas/_module.d.mts";
+import type { Edge, PolygonVertex, CollisionResult } from "#client/canvas/geometry/edges/_module.d.mts";
+import type { PointSourcePolygon, Ray } from "#client/canvas/geometry/_module.d.mts";
+
+/**
+ * A PointSourcePolygon implementation that uses CCW (counter-clockwise) geometry orientation.
+ * Sweep around the origin, accumulating collision points based on the set of active walls.
+ * This algorithm was created with valuable contributions from https://github.com/caewok
+ */
+declare class ClockwiseSweepPolygon extends PointSourcePolygon {
+  /** @privateRemarks Necessary type override */
+  static override benchmark(
+    iterations: number,
+    origin: Canvas.PossiblyElevatedPoint,
+    config: ClockwiseSweepPolygon.Config,
+  ): Promise<void>;
+
+  /** @privateRemarks Necessary type override */
+  static override create(origin: Canvas.Point, config: ClockwiseSweepPolygon.Config): ClockwiseSweepPolygon;
+
+  /** @privateRemarks Necessary type override */
+  static override testCollision<Mode extends PointSourcePolygon.CollisionModes | undefined = undefined>(
+    origin: Canvas.PossiblyElevatedPoint,
+    destination: Canvas.PossiblyElevatedPoint,
+    { mode, ...config }: ClockwiseSweepPolygon.TestCollisionOptions<Mode>,
+  ): PointSourcePolygon.TestCollision<Mode>;
+
+  /** @privateRemarks Necessary type override */
+  override config: ClockwiseSweepPolygon.StoredConfig;
+
+  /**
+   * A mapping of vertices which define potential collision points
+   */
+  vertices: Map<number, PolygonVertex>;
+
+  /**
+   * The set of edges which define potential boundaries of the polygon
+   */
+  edges: Set<Edge>;
+
+  /**
+   * A collection of rays which are fired at vertices
+   */
+  rays: ClockwiseSweepPolygon.Ray[];
+
+  /**
+   * Is this polygon using inner bounds?
+   */
+  get useInnerBounds(): boolean;
+
+  override initialize(origin: Canvas.PossiblyElevatedPoint, config: ClockwiseSweepPolygon.Config): void;
+
+  /**
+   * Determine the edge types and their manner of inclusion for this polygon instance.
+   * @param config - Optional polygon config which may include deprecated properties
+   * @remarks The deprecated properties referred to are {@linkcode ClockwiseSweepPolygon.Config.useInnerBounds | useInnerBounds}
+   * and {@linkcode ClockwiseSweepPolygon.Config.includeDarkness | includeDarkness}
+   */
+  protected _determineEdgeTypes(
+    type: Edge.EdgeTypes,
+    priority: number,
+    config?: ClockwiseSweepPolygon.Config,
+  ): ClockwiseSweepPolygon.EdgeTypesConfiguration;
+
+  clone(): this;
+
+  protected override _compute(): void;
+
+  /**
+   * Retrieves the super-set of walls that could potentially apply to this polygon.
+   * Utilizes a custom collision test and the Quadtree to obtain candidate edges efficiently.
+   */
+  protected _identifyEdges(): void;
+
+  /**
+   * Test whether a wall should be included in the computed polygon for a given origin and type
+   * @param edge      - The Edge being considered
+   * @param edgeTypes - Which types of edges are being used? 0=no, 1=maybe, 2=always
+   * @returns Should the edge be included?
+   * @remarks See {@linkcode ClockwiseSweepPolygon.Config.edgeTypes}
+   */
+  protected _testEdgeInclusion(edge: Edge, edgeTypes: ClockwiseSweepPolygon.EdgeTypesConfiguration): boolean;
+
+  /**
+   * Compute the aggregate bounding box which is the intersection of all boundary shapes.
+   * Round and pad the resulting rectangle by 1 pixel to ensure it always contains the origin.
+   */
+  protected _defineBoundingBox(): PIXI.Rectangle;
+
+  /**
+   * Consolidate all vertices from identified edges and register them as part of the vertex mapping.
+   */
+  protected _identifyVertices(): void;
+
+  /**
+   * Add additional vertices for intersections between edges.
+   */
+  protected _identifyIntersections(edgeMap: Map<string, Edge>): void;
+
+  /**
+   * Execute the sweep over wall vertices
+   */
+  protected _executeSweep(): void;
+
+  /**
+   * Determine the initial set of active edges as those which intersect with the initial ray
+   * @returns A set of initially active edges
+   */
+  protected _initializeActiveEdges(): Set<Edge>;
+
+  /**
+   * Sort vertices clockwise from the initial ray (due west).
+   * @returns The array of sorted vertices
+   */
+  protected _sortVertices(): PolygonVertex[];
+
+  /**
+   * Test whether a target vertex is behind some closer active edge.
+   * If the vertex is to the left of the edge, is must be behind the edge relative to origin.
+   * If the vertex is collinear with the edge, it should be considered "behind" and ignored.
+   * We know edge.VertexA is ccw to edge.VertexB because of the logic in _identifyVertices.
+   * @param vertex      - The target vertex
+   * @param activeEdges - The set of active edges
+   * @returns Is the target vertex behind some closer edge?
+   */
+  protected _isVertexBehindActiveEdges(
+    vertex: PolygonVertex,
+    activeEdges: Set<Edge>,
+  ): ClockwiseSweepPolygon.IsVertexBehindActiveEdges;
+
+  /**
+   * Determine the result for the sweep at a given vertex
+   * @param vertex        - The target vertex
+   * @param activeEdges   - The set of active edges
+   * @param hasCollinear  - Are there collinear vertices behind the target vertex? (default: `false`)
+   */
+  protected _determineSweepResult(vertex: PolygonVertex, activeEdges: Set<Edge>, hasCollinear?: boolean): void;
+
+  /**
+   * Switch to a new active edge.
+   * Moving from the origin, a collision that first blocks a side must be stored as a polygon point.
+   * Subsequent collisions blocking that side are ignored. Once both sides are blocked, we are done.
+   *
+   * Collisions that limit a side will block if that side was previously limited.
+   *
+   * If neither side is blocked and the ray internally collides with a non-limited edge, n skip without adding polygon
+   * endpoints. Sight is unaffected before this edge, and the internal collision can be ignored.
+   *
+   * @param result      - The pending collision result
+   * @param activeEdges - The set of currently active edges
+   */
+  protected _switchEdge(result: CollisionResult, activeEdges: Set<Edge>): void;
+
+  /** @remarks Does not take the new-as-of-v13 `destination` param from {@linkcode PointSourcePolygon._testCollision | super} (yet?) */
+  protected override _testCollision<Mode extends PointSourcePolygon.CollisionModes>(
+    ray: Ray,
+    mode: Mode,
+  ): PointSourcePolygon.TestCollision<Mode>;
+
+  override visualize(): PIXI.Graphics;
+
+  /**
+   * Visualize the polygon, displaying its computed area, rays, and collision points
+   */
+  protected _visualizeCollision(ray: Ray, collisions: PolygonVertex[]): void;
+
+  /**
+   * This function has been adapted from {@linkcode ClipperLib.Clipper.CleanPolygon | Clipper's CleanPolygon function}.
+   * When adding a new point to the polygon, check for collinearity with prior points to cull unnecessary points.
+   * This also removes spikes where we traverse points (a, b, a).
+   * We also enforce a minimum distance between two points, or a minimum perpendicular distance between three almost
+   * collinear points.
+   */
+  override addPoint(point: PIXI.IPointData): this;
+
+  #ClockwiseSweepPolygon: true;
+}
+
+declare namespace ClockwiseSweepPolygon {
+  interface Any extends AnyClockwiseSweepPolygon {}
+  interface AnyConstructor extends Identity<typeof AnyClockwiseSweepPolygon> {}
+
+  /**
+   * CSP-added properties of the config that have defaults applied in {@linkcode ClockwiseSweepPolygon.initialize | ClockwiseSweepPolygon#initialize}
+   * @internal
+   */
+  interface _Config {
+    /**
+     * Optional priority when it comes to ignore edges from darkness and light sources
+     * @defaultValue `0`
+     */
+    priority: number;
+
+    /**
+     * Edge types configuration object. This is not required by most polygons and will be inferred based on the polygon type and priority.
+     *
+     * How modes are working:
+     * - `0` (no):     The edges of this type are rejected and not processed (equivalent of not having an edgeType.)
+     * - `1` (maybe):  The edges are processed and tested for inclusion.
+     * - `2` (always): The edges are automatically included.
+     * @defaultValue {@linkcode ClockwiseSweepPolygon._determineEdgeTypes | this._determineEdgeTypes(config.type, config.priority, config)}
+     */
+    edgeTypes: EdgeTypesConfiguration;
+
+    /**
+     * The computed bounding box for the polygon
+     * @defaultValue {@linkcode ClockwiseSweepPolygon._defineBoundingBox | this._defineBoundingBox()}
+     * @privateRemarks Foundry includes this in the `PointSourcePolygonConfig` typedef, but it is only used in `ClockwiseSweepPolygon`
+     */
+    boundingBox: PIXI.Rectangle;
+  }
+
+  /**
+   * CSP-added properties of the config that are not guaranteed to exist by {@linkcode ClockwiseSweepPolygon.initialize | ClockwiseSweepPolygon#initialize}
+   * @internal
+   */
+  type _InexactConfig = InexactPartial<{
+    /**
+     * Deactivate/Activate specific edge types behaviors.
+     */
+    edgeOptions: EdgeOptions;
+
+    /**
+     * @deprecated "`config.useInnerBounds` is now deprecated, replaced by {@linkcode ClockwiseSweepPolygon.Config.edgeTypes | edgeTypes}
+     * polygon configuration behaviors." (since v13, until v15)
+     */
+    useInnerBounds: boolean;
+
+    /**
+     * @deprecated "`config.includeDarkness` is now deprecated, replaced by {@linkcode ClockwiseSweepPolygon.Config.edgeTypes | edgeTypes}
+     * polygon configuration behaviors." (since v13, until v15)
+     */
+    includeDarkness: boolean;
+  }>;
+
+  interface Config extends PointSourcePolygon.Config, InexactPartial<_Config>, _InexactConfig {}
+
+  interface StoredConfig extends PointSourcePolygon.StoredConfig, _Config, _InexactConfig {}
+
+  interface TestCollisionConfig extends PointSourcePolygon._TestCollisionConfig, Omit<Config, "type"> {}
+
+  interface TestCollisionOptions<Mode extends PointSourcePolygon.CollisionModes | undefined = undefined>
+    extends PointSourcePolygon._TestCollisionOptions<Mode>,
+      TestCollisionConfig {}
+
+  /**
+   * @remarks See {@linkcode Config.edgeTypes}
+   *
+   * @privateRemarks Foundry never sets any keys to `0`, they're simply omitted, then tested for truthiness in
+   * {@linkcode ClockwiseSweepPolygon._testEdgeInclusion | #_testEdgeInclusion}.
+   */
+  interface EdgeTypesConfiguration extends InexactPartial<Record<Edge.EdgeTypes, 0 | 1 | 2>> {}
+
+  /**
+   * @privateRemarks Entries are only checked for `===` or `!== false` in {@linkcode ClockwiseSweepPolygon._determineEdgeTypes | ClockwiseSweepPolygon#_determineEdgeTypes},
+   * so `undefined` is fine
+   */
+  interface EdgeOptions extends InexactPartial<Record<Edge.EdgeTypes, boolean>> {}
+
+  interface IsVertexBehindActiveEdges {
+    isBehind: boolean;
+    wasLimited: boolean;
+  }
+
+  interface Ray extends foundry.canvas.geometry.Ray {
+    /**
+     * @remarks Only set in {@linkcode ClockwiseSweepPolygon._switchEdge | ClockwiseSweepPolygon#_switchEdge} and only consumed in
+     * {@linkcode ClockwiseSweepPolygon.visualize | #visualize}, despite unrelated method(s) having parameters claiming to want a `PolygonRay`
+     *
+     * Tested for truthiness in `#visualize` before use, so a nullish value is fine but never attains in core
+     */
+    result?: CollisionResult | undefined;
+  }
+}
+
+export default ClockwiseSweepPolygon;
+
+declare abstract class AnyClockwiseSweepPolygon extends ClockwiseSweepPolygon {
+  constructor(...args: never);
+}

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

@@ -0,0 +1,131 @@
+import type { Identity, InexactPartial } from "#utils";
+import type Edge from "./edge.d.mts";
+import type PolygonVertex from "./vertex.d.mts";
+
+/**
+ * A specialized object that contains the result of a collision in the context of the ClockwiseSweepPolygon.
+ * This class is not designed or intended for use outside of that context.
+ */
+declare class CollisionResult {
+  constructor(values?: CollisionResult.ConstructorValues);
+
+  /**
+   * The vertex that was the target of this result
+   */
+  target: PolygonVertex;
+
+  /**
+   * The array of collision points which apply to this result
+   * @defaultValue `[]`
+   */
+  collisions: PolygonVertex[];
+
+  /**
+   * The set of edges connected to the target vertex that continue clockwise
+   */
+  cwEdges: Set<Edge> | undefined;
+
+  /**
+   * The set of edges connected to the target vertex that continue counter-clockwise
+   */
+  ccwEdges: Set<Edge> | undefined;
+
+  /**
+   * Is the target vertex for this result behind some closer active edge?
+   * @remarks Set directly from the constructor, so possibly was passed nullish
+   */
+  isBehind: boolean | undefined;
+
+  /**
+   * Does the target vertex for this result impose a limited collision?
+   * @remarks Set directly from the constructor, so possibly was passed nullish
+   */
+  isLimited: boolean | undefined;
+
+  /**
+   * Has the set of collisions for this result encountered a limited edge?
+   * @remarks Set directly from the constructor, so possibly was passed nullish
+   */
+  wasLimited: boolean | undefined;
+
+  /**
+   * Is this result limited in the clockwise direction?
+   * @defaultValue `false`
+   */
+  limitedCW: boolean;
+
+  /**
+   * Is this result limited in the counter-clockwise direction?
+   * @defaultValue `false`
+   */
+  limitedCCW: boolean;
+
+  /**
+   * Is this result blocking in the clockwise direction?
+   * @defaultValue `false`
+   */
+  blockedCW: boolean;
+
+  /**
+   * Is this result blocking in the counter-clockwise direction?
+   * @defaultValue `false`
+   */
+  blockedCCW: boolean;
+
+  /**
+   * Previously blocking in the clockwise direction?
+   * @defaultValue `false`
+   */
+  blockedCWPrev: boolean;
+
+  /**
+   * Previously blocking in the counter-clockwise direction?
+   * @defaultValue `false`
+   */
+  blockedCCWPrev: boolean;
+}
+
+declare namespace CollisionResult {
+  interface Any extends AnyCollisionResult {}
+  interface AnyConstructor extends Identity<typeof AnyCollisionResult> {}
+
+  type _ConstructorValues = InexactPartial<{
+    /**
+     * The set of edges connected to the target vertex that continue clockwise
+     */
+    cwEdges: Set<Edge>;
+
+    /**
+     * The set of edges connected to the target vertex that continue counter-clockwise
+     */
+    ccwEdges: Set<Edge>;
+
+    /** Is the target vertex for this result behind some closer active edge? */
+    isBehind: boolean;
+
+    /** Does the target vertex for this result impose a limited collision? */
+    isLimited: boolean;
+
+    /** Has the set of collisions for this result encountered a limited edge? */
+    wasLimited: boolean;
+
+    /**
+     * The array of collision points which apply to this result
+     * @defaultValue `[]`
+     */
+    collisions: PolygonVertex[];
+  }>;
+
+  interface ConstructorValues extends _ConstructorValues {
+    /**
+     * The vertex that was the target of this result
+     */
+    target: PolygonVertex;
+  }
+}
+
+export default CollisionResult;
+
+declare abstract class AnyCollisionResult extends CollisionResult {
+  constructor(...args: never);
+}

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

@@ -0,0 +1,258 @@
+import type PolygonVertex from "./vertex.d.mts";
+import type { LineIntersection } from "#common/utils/geometry.d.mts";
+import type { Identity, InexactPartial } from "#utils";
+import type { Canvas } from "#client/canvas/_module.d.mts";
+import type { PlaceableObject } from "#client/canvas/placeables/_module.d.mts";
+
+/**
+ * A data structure used to represent potential edges used by the ClockwiseSweepPolygon.
+ * Edges are not polygon-specific, meaning they can be reused across many polygon instances.
+ */
+declare class Edge {
+  /**
+   * Construct an Edge by providing the following information.
+   * @param a - The first endpoint of the edge
+   * @param b - The second endpoint of the edge
+   * @param options - Additional options which describe the edge
+   */
+  constructor(a: Canvas.Point, b: Canvas.Point, options?: Edge.ConstructorOptions);
+
+  /**
+   * The first endpoint of the edge.
+   */
+  a: PIXI.Point;
+
+  /**
+   * The second endpoint of the edge.
+   */
+  b: PIXI.Point;
+
+  /**
+   * A string used to uniquely identify this edge.
+   * @defaultValue `object?.id ?? undefined`
+   */
+  id: string | undefined;
+
+  /**
+   * A PlaceableObject that is responsible for this edge, if any
+   * @remarks This property is never read by Foundry, so it being nullish won't break anything as of 12.331
+   */
+  object: PlaceableObject.Any | undefined;
+
+  /**
+   * The type of edge
+   * @defaultValue `"wall"`
+   */
+  type: Edge.EdgeTypes;
+
+  /**
+   * The direction of effect for the edge.
+   * @defaultValue {@linkcode CONST.WALL_DIRECTIONS.BOTH}
+   */
+  direction: CONST.WALL_DIRECTIONS;
+
+  /**
+   * How this edge restricts light.
+   * @defaultValue {@linkcode CONST.WALL_SENSE_TYPES.NONE}
+   */
+  light: CONST.WALL_SENSE_TYPES;
+
+  /**
+   * How this edge restricts movement.
+   * @defaultValue {@linkcode CONST.WALL_SENSE_TYPES.NONE}
+   */
+  move: CONST.WALL_SENSE_TYPES;
+
+  /**
+   * How this edge restricts sight.
+   * @defaultValue {@linkcode CONST.WALL_SENSE_TYPES.NONE}
+   */
+  sight: CONST.WALL_SENSE_TYPES;
+
+  /**
+   * How this edge restricts sound.
+   * @defaultValue {@linkcode CONST.WALL_SENSE_TYPES.NONE}
+   */
+  sound: CONST.WALL_SENSE_TYPES;
+
+  /**
+   * Specialized threshold data for this edge.
+   */
+  threshold: WallDocument.ThresholdData | undefined;
+
+  /**
+   * A source priority for this edge. Typically zero unless this edge was contributed by a high-priority source.
+   * @defaultValue `0`
+   */
+  priority: number;
+
+  /**
+   * The endpoint of the edge which is oriented towards the top-left.
+   */
+  nw: Canvas.Point;
+
+  /**
+   * The endpoint of the edge which is oriented towards the bottom-right.
+   */
+  se: Canvas.Point;
+
+  /**
+   * The rectangular bounds of the edge. Used by the quadtree.
+   */
+  bounds: PIXI.Rectangle;
+
+  /**
+   * Record other edges which this one intersects with.
+   */
+  intersections: Edge.IntersectionEntry[];
+
+  /**
+   * A PolygonVertex instance.
+   * Used as part of {@linkcode ClockwiseSweepPolygon} computation.
+   * @remarks Only set in {@link ClockwiseSweepPolygon._identifyVertices | `ClockwiseSweepPolygon#_identifyVertices`} (part of CSP initialization)
+   */
+  vertexA: PolygonVertex | undefined;
+
+  /**
+   * A PolygonVertex instance.
+   * Used as part of {@linkcode ClockwiseSweepPolygon} computation.
+   * @remarks Only set in {@link ClockwiseSweepPolygon._identifyVertices | `ClockwiseSweepPolygon#_identifyVertices`} (part of CSP initialization)
+   */
+  vertexB: PolygonVertex | undefined;
+
+  /**
+   * Is this edge limited for a particular type?
+   */
+  isLimited(type: CONST.WALL_RESTRICTION_TYPES): boolean;
+
+  /**
+   * Create a copy of the Edge which can be safely mutated.
+   */
+  clone(): this;
+
+  /**
+   * Get an intersection point between this Edge and another.
+   */
+  getIntersection(other: Edge): LineIntersection | void;
+
+  /**
+   * Test whether to apply a proximity threshold to this edge.
+   * If the proximity threshold is met, this edge excluded from perception calculations.
+   * @param sourceType     - Sense type for the source
+   * @param sourceOrigin   - The origin or position of the source on the canvas
+   * @param externalRadius - The external radius of the source (default: `0`)
+   * @returns True if the edge has a threshold greater than `0` for the source type,
+   * and the source type is within that distance.
+   */
+  applyThreshold(sourceType: Edge.AttenuationTypes, sourceOrigin: Canvas.Point, externalRadius?: number): boolean;
+
+  /**
+   * Determine the orientation of this Edge with respect to a reference point.
+   * @param point - Some reference point, relative to which orientation is determined
+   * @returns An orientation in {@linkcode CONST.WALL_DIRECTIONS} which indicates whether the Point is left,
+   * right, or collinear (both) with the Edge
+   */
+  orientPoint(point: Canvas.Point): CONST.WALL_DIRECTIONS;
+
+  /**
+   * Identify intersections between a provided iterable of edges.
+   * @param edges - An iterable of edges
+   */
+  static identifyEdgeIntersections(edges: Iterable<Edge>): void;
+
+  /**
+   * Record the intersections between two edges.
+   * @param other - Another edge to test and record
+   */
+  recordIntersections(other: Edge): void;
+
+  /**
+   * Remove intersections of this edge with all other edges.
+   */
+  removeIntersections(): void;
+}
+
+declare namespace Edge {
+  interface Any extends AnyEdge {}
+  interface AnyConstructor extends Identity<typeof AnyEdge> {}
+
+  /** @internal */
+  type _ConstructorOptions = InexactPartial<{
+    /**
+     * A string used to uniquely identify this edge
+     *
+     */
+    id: string | null;
+
+    /**
+     * A PlaceableObject that is responsible for this edge, if any
+     * @remarks `Edge#object` is never read by Foundry, so this being nullish won't break anything as of 12.331
+     */
+    object: PlaceableObject.Any;
+
+    /**
+     * The type of edge
+     * @defaultValue `"wall"`
+     */
+    type: Edge.EdgeTypes;
+
+    /**
+     * How this edge restricts light
+     * @defaultValue {@linkcode CONST.WALL_SENSE_TYPES.NONE}
+     */
+    light: CONST.WALL_SENSE_TYPES;
+
+    /**
+     * How this edge restricts movement
+     * @defaultValue {@linkcode CONST.WALL_SENSE_TYPES.NONE}
+     */
+    move: CONST.WALL_SENSE_TYPES;
+
+    /**
+     * How this edge restricts sight
+     * @defaultValue {@linkcode CONST.WALL_SENSE_TYPES.NONE}
+     */
+    sight: CONST.WALL_SENSE_TYPES;
+
+    /**
+     * How this edge restricts sound
+     * @defaultValue {@linkcode CONST.WALL_SENSE_TYPES.NONE}
+     */
+    sound: CONST.WALL_SENSE_TYPES;
+
+    /**
+     * A direction of effect for the edge
+     * @defaultValue {@linkcode CONST.WALL_DIRECTIONS.BOTH}
+     */
+    direction: CONST.WALL_DIRECTIONS;
+
+    /**
+     * Configuration of threshold data for this edge
+     * @remarks Foundry only accesses this in nullish-safe ways as of 12.331
+     */
+    threshold: WallDocument.ThresholdData;
+
+    /**
+     * A source priority for this edge. Typically zero unless this edge was contributed by a high-priority source.
+     * @defaultValue `0`
+     */
+    priority: number;
+  }>;
+
+  interface ConstructorOptions extends _ConstructorOptions {}
+
+  type EdgeTypes = "wall" | "darkness" | "light" | "innerBounds" | "outerBounds";
+
+  type AttenuationTypes = Exclude<foundry.CONST.WALL_RESTRICTION_TYPES, "move">;
+
+  interface IntersectionEntry {
+    edge: Edge;
+    intersection: LineIntersection;
+  }
+}
+
+declare abstract class AnyEdge extends Edge {
+  constructor(...args: never);
+}
+
+export default Edge;