@league-of-foundry-developers/foundry-vtt-types 9.280.1 → 12.331.1-beta

package/src/foundry/client/pixi/core/shapes/ray.d.mts

@@ -0,0 +1,165 @@
+import type { LineIntersection } from "../../../../common/utils/geometry.d.mts";
+
+declare global {
+  interface RayIntersection {
+    /** The x-coordinate of intersection */
+    x: number;
+
+    /** The y-coordinate of intersection */
+    y: number;
+
+    /** The proximity to the Ray origin, as a ratio of distance */
+    t0: number;
+
+    /** The proximity to the Ray destination, as a ratio of distance */
+    t1: number;
+  }
+
+  /**
+   * A ray for the purposes of computing sight and collision
+   * Given points A[x,y] and B[x,y]
+   *
+   * Slope-Intercept form:
+   * y = a + bx
+   * y = A.y + ((B.y - A.Y) / (B.x - A.x))x
+   *
+   * Parametric form:
+   * R(t) = (1-t)A + tB
+   */
+  class Ray {
+    /**
+     * @param A - The origin of the Ray
+     * @param B - The destination of the Ray
+     */
+    constructor(A: Point, B: Point);
+
+    /**
+     * The origin point, `{x, y}`
+     */
+    A: Point;
+
+    /**
+     * The destination point, `{x, y}`
+     */
+    B: Point;
+
+    /**
+     * The origin y-coordinate
+     */
+    y0: number;
+
+    /**
+     * The origin x-coordinate
+     */
+    x0: number;
+
+    /**
+     * The horizontal distance of the ray, x1 - x0
+     */
+    dx: number;
+
+    /**
+     * The vertical distance of the ray, y1 - y0
+     */
+    dy: number;
+
+    /**
+     * The slope of the ray, dy over dx
+     */
+    slope: number;
+
+    /**
+     * The cached angle, computed lazily in Ray#angle
+     * @defaultValue `undefined`
+     * @internal
+     */
+    protected _angle: number | undefined;
+
+    /**
+     * The cached distance, computed lazily in Ray#distance
+     * @defaultValue `undefined`
+     * @internal
+     */
+    protected _distance: number | undefined;
+
+    /**
+     * The normalized angle of the ray in radians on the range (-PI, PI).
+     * The angle is computed lazily (only if required) and cached.
+     */
+    get angle(): number;
+    set angle(value: number);
+
+    /**
+     * A bounding rectangle that encompasses the Ray
+     */
+    get bounds(): PIXI.Rectangle;
+
+    /**
+     * The distance (length) of the Ray in pixels.
+     * The distance is computed lazily (only if required) and cached.
+     */
+    get distance(): number;
+    set distance(value: number);
+
+    /**
+     * A factory method to construct a Ray from an origin point, an angle, and a distance
+     * @param x        - The origin x-coordinate
+     * @param y        - The origin y-coordinate
+     * @param radians  - The ray angle in radians
+     * @param distance - The distance of the ray in pixels
+     * @returns The constructed Ray instance
+     */
+    static fromAngle(x: number, y: number, radians: number, distance: number): Ray;
+
+    /**
+     * A factory method to construct a Ray from points in array format.
+     * @param A - The origin point [x,y]
+     * @param B - The destination point [x,y]
+     * @returns The constructed Ray instance
+     */
+    static fromArrays(A: PointArray, B: PointArray): Ray;
+
+    /**
+     * Project the Array by some proportion of it's initial distance.
+     * Return the coordinates of that point along the path.
+     * @param t - The distance along the Ray
+     * @returns The coordinates of the projected point
+     */
+    project(t: number): { x: number; y: number };
+
+    /**
+     * Create a Ray by projecting a certain distance towards a known point.
+     * @param origin   - The origin of the Ray
+     * @param point    - The point towards which to project
+     * @param distance - The distance of projection
+     */
+    static towardsPoint(origin: Point, point: Point, distance: number): Ray;
+
+    /**
+     * Create a Ray by projecting a certain squared-distance towards a known point.
+     * @param origin    - The origin of the Ray
+     * @param point     - The point towards which to project
+     * @param distance2 - The squared distance of projection
+     */
+    static towardsPointSquared(origin: Point, point: Point, distance2: number): Ray;
+
+    /**
+     * Reverse the direction of the Ray, returning a second Ray
+     */
+    reverse(): Ray;
+
+    /**
+     * Create a new ray which uses the same origin point, but a slightly offset angle and distance
+     * @param offset   - An offset in radians which modifies the angle of the original Ray
+     * @param distance - A distance the new ray should project, otherwise uses the same distance.
+     * @returns A new Ray with an offset angle
+     */
+    shiftAngle(angleOffset: number, distance?: number): Ray;
+
+    /**
+     * Find the point I[x,y] and distance t* on ray R(t) which intersects another ray
+     * @see foundry.utils.lineLineIntersection
+     */
+    intersectSegment(coords: [x0: number, y0: number, x1: number, y1: number]): LineIntersection | null;
+  }
+}

package/src/foundry/client/pixi/core/shapes/source-polygon.d.mts

@@ -0,0 +1,251 @@
+import type { ConstructorOf } from "../../../../../types/utils.d.mts";
+
+declare global {
+  interface PointSourcePolygonConfig {
+    /** The type of polygon being computed */
+    type?: foundry.CONST.WALL_RESTRICTION_TYPES;
+
+    /** The angle of emission, if limited */
+    angle?: number;
+
+    /** The desired density of padding rays, a number per PI */
+    density?: number;
+
+    /** A limited radius of the resulting polygon */
+    radius?: number;
+
+    /** The direction of facing, required if the angle is limited */
+    rotation?: number;
+
+    /** Customize how wall direction of one-way walls is applied */
+    wallDirectionMode?: number;
+
+    /** Compute the polygon with threshold wall constraints applied */
+    useThreshold?: boolean;
+
+    /** Display debugging visualization and logging for the polygon */
+    debug?: boolean;
+
+    /** The object (if any) that spawned this polygon. */
+    source?: PointSource;
+
+    /** Limiting polygon boundary shapes */
+    boundaryShapes?: Array<PIXI.Rectangle | PIXI.Circle | PIXI.Polygon>;
+
+    /** Does this polygon use the Scene inner or outer bounding rectangle */
+    readonly useInnerBounds?: boolean;
+
+    /** Does this polygon have a limited radius? */
+    readonly hasLimitedRadius?: boolean;
+
+    /** Does this polygon have a limited angle? */
+    readonly hasLimitedAngle?: boolean;
+
+    /** The computed bounding box for the polygon */
+    readonly boundingBox?: PIXI.Rectangle;
+  }
+
+  /**
+   * An extension of the default PIXI.Polygon which is used to represent the line of sight for a point source.
+   */
+  abstract class PointSourcePolygon extends PIXI.Polygon {
+    /**
+     * Customize how wall direction of one-way walls is applied
+     */
+    static readonly WALL_DIRECTION_MODES: Readonly<{
+      NORMAL: 0;
+      REVERSED: 1;
+      BOTH: 2;
+    }>;
+
+    /**
+     * The rectangular bounds of this polygon
+     * @defaultValue `new PIXI.Rectangle(0, 0, 0, 0)`
+     */
+    bounds: PIXI.Rectangle;
+
+    /**
+     * The origin point of the source polygon.
+     */
+    origin: Point;
+
+    /**
+     * The configuration of this polygon.
+     * @defaultValue `{}`
+     */
+    config: PointSourcePolygonConfig;
+
+    /**
+     * An indicator for whether this polygon is constrained by some boundary shape?
+     */
+    get isConstrained(): boolean;
+
+    /**
+     * Benchmark the performance of polygon computation for this source
+     * @param iterations - The number of test iterations to perform
+     * @param origin     - The origin point to benchmark
+     * @param config     - The polygon configuration to benchmark
+     */
+    static benchmark(iterations: number, origin: Point, config: PointSourcePolygonConfig): Promise<void>;
+
+    /**
+     * Compute the polygon given a point origin and radius
+     * @param origin - The origin source point
+     * @param config - Configuration options which customize the polygon computation
+     *                 (default: `{}`)
+     * @returns The computed polygon instance
+     */
+    static create<T extends ConstructorOf<PointSourcePolygon>>(
+      this: T,
+      origin: Point,
+      config?: Parameters<InstanceType<T>["initialize"]>[1],
+    ): InstanceType<T>;
+
+    /**
+     * Create a clone of this polygon.
+     * This overrides the default PIXI.Polygon#clone behavior.
+     * @returns A cloned instance
+     */
+    override clone(): this;
+
+    /**
+     * Compute the polygon using the origin and configuration options.
+     * @returns The computed polygon
+     */
+    compute(): this;
+
+    /**
+     * Perform the implementation-specific computation
+     */
+    protected abstract _compute(): void;
+
+    /**
+     * Customize the provided configuration object for this polygon type.
+     * @param origin - The provided polygon origin
+     * @param config - The provided configuration object
+     */
+    initialize(origin: Point, config: PointSourcePolygonConfig): void;
+
+    /**
+     * Get the super-set of walls which could potentially apply to this polygon.
+     * Define a custom collision test used by the Quadtree to obtain candidate Walls.
+     */
+    protected _getWalls(): Set<Wall>;
+
+    /**
+     * Test whether a wall should be included in the computed polygon for a given origin and type
+     * @param wall    - The Wall being considered
+     * @param bounds  - The overall bounding box
+     * @returns Should the wall be included?
+     */
+    protected _testWallInclusion(wall: Wall, bounds: PIXI.Rectangle): 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;
+
+    /**
+     * Apply a constraining boundary shape to an existing PointSourcePolygon.
+     * Return a new instance of the polygon with the constraint applied.
+     * The new instance is only a "shallow clone", as it shares references to component properties with the original.
+     * @param constraint          - The constraining boundary shape
+     * @param intersectionOptions - Options passed to the shape intersection method
+     * @returns A new constrained polygon
+     */
+    applyConstraint(
+      constraint: PIXI.Circle | PIXI.Rectangle | PIXI.Polygon,
+      intersectionOptions?: Record<string, unknown>,
+    ): PointSourcePolygon;
+
+    contains(x: number, y: number): boolean;
+
+    /**
+     * Constrain polygon points by applying boundary shapes.
+     */
+    protected _constrainBoundaryShapes(): void;
+
+    /**
+     * Test whether a Ray between the origin and destination points would collide with a boundary of this Polygon.
+     * A valid wall restriction type is compulsory and must be passed into the config options.
+     * @param origin      - An origin point
+     * @param destination - A destination point
+     * @param config      - The configuration that defines a certain Polygon type
+     * @param mode        - The collision mode to test: "any", "all", or "closest"
+     *                      (default: "all")
+     * @returns The collision result depends on the mode of the test:
+     *          * any: returns a boolean for whether any collision occurred
+     *          * all: returns a sorted array of PolygonVertex instances
+     *          * closest: returns a PolygonVertex instance or null
+     */
+    static testCollision<Mode extends PointSourcePolygon.CollisionModes>(
+      origin: Point,
+      destination: Point,
+      {
+        mode,
+        ...config
+      }: {
+        /**
+         * The collision mode to test: "any", "all", or "closest"
+         * (default: "all")
+         */
+        mode?: Mode;
+
+        /** The configuration that defines a certain Polygon type */
+        config?: PointSourcePolygonConfig;
+      },
+    ): PointSourcePolygon.TestCollision<Mode>;
+
+    /**
+     * Determine the set of collisions which occurs for a Ray.
+     * @param ray  - The Ray to test
+     * @param mode - The collision mode being tested
+     * @returns The collision test result
+     */
+    protected abstract _testCollision<Mode extends PointSourcePolygon.CollisionModes>(
+      ray: Ray,
+      mode: Mode,
+    ): PointSourcePolygon.TestCollision<Mode>;
+
+    /**
+     * Visualize the polygon, displaying its computed area, rays, and collision points
+     * @returns The rendered debugging shape
+     */
+    visualize(): PIXI.Graphics | undefined;
+
+    /**
+     * Determine if the shape is a complete circle.
+     * The config object must have an angle and a radius properties.
+     */
+    isCompleteCircle(): boolean;
+
+    /**
+     * Augment a PointSourcePolygon by adding additional coverage for shapes permitted by threshold walls.
+     * @param polygon - The computed polygon
+     * @returns The augmented polygon
+     */
+    static applyThresholdAttenuation(polygon: PointSourcePolygon): PointSourcePolygon;
+
+    /**
+     * @deprecated since v11, will be removed in v13
+     * @remarks You are referencing PointSourcePolygon#rays which is no longer a required property of that interface.
+     *          If your subclass uses the rays property it should be explicitly defined by the subclass which requires it.
+     */
+    get rays(): Ray[];
+
+    set rays(rays);
+  }
+
+  namespace PointSourcePolygon {
+    type CollisionModes = "any" | "all" | "closest";
+
+    interface CollisionTypes {
+      any: boolean;
+      closest: foundry.canvas.edges.PolygonVertex;
+      all: foundry.canvas.edges.PolygonVertex[] | null;
+    }
+
+    type TestCollision<Mode extends CollisionModes> = CollisionTypes[Mode];
+  }
+}

package/src/foundry/client/pixi/extensions/circle.d.mts

@@ -0,0 +1,130 @@
+export {};
+
+declare module "pixi.js" {
+  interface Circle {
+    /**
+     * Determine the center of the circle.
+     * Trivial, but used to match center method for other shapes.
+     */
+    get circle(): Point;
+
+    /**
+     * Determine if a point is on or nearly on this circle.
+     * @param point   - Point to test
+     * @param epsilon - Tolerated margin of error
+     *                  (default: `1e-08`)
+     * @returns Is the point on the circle within the allowed tolerance?
+     */
+    pointIsOn(point: Point, epsilon: number): boolean;
+
+    /**
+     * Get all intersection points on this circle for a segment A|B
+     * Intersections are sorted from A to B.
+     * @param a - The first endpoint on segment A|B
+     * @param b - The second endpoint on segment A|B
+     * @returns Points where the segment A|B intersects the circle
+     */
+    segmentIntersections(a: Point, b: Point): [Point?, Point?];
+
+    /**
+     * Calculate an x,y point on this circle's circumference given an angle
+     * 0: due east
+     * π / 2: due south
+     * π or -π: due west
+     * -π/2: due north
+     * @param angle - Angle of the point, in radians
+     * @returns The point on the circle at the given angle
+     */
+    pointAtAngle(angle: number): Point;
+
+    /**
+     * Get all the points for a polygon approximation of this circle between two points.
+     * The two points can be anywhere in 2d space. The intersection of this circle with the line from this circle center
+     * to the point will be used as the start or end point, respectively.
+     * This is used to draw the portion of the circle (the arc) between two intersection points on this circle.
+     * @param a       - Point in 2d space representing the start point
+     * @param b       - Point in 2d space representing the end point
+     * @param options - Options passed on to the pointsForArc method
+     * @returns An array of points arranged clockwise from start to end
+     */
+    pointsBetween(a: Point, b: Point, options?: Circle.PointsForArcOptions): Point[];
+
+    /**
+     * Get the points that would approximate a circular arc along this circle, given a starting and ending angle.
+     * Points returned are clockwise. If from and to are the same, a full circle will be returned.
+     * @param fromAngle - Starting angle, in radians. π is due north, π/2 is due east
+     * @param toAngle   - Ending angle, in radians
+     * @param options   - Options which affect how the circle is converted
+     * @returns An array of points along the requested arc
+     */
+    pointsForArc(fromAngle: number, toAngle: number, options?: Circle.PointsForArcOptions): Point[];
+
+    /**
+     * Approximate this PIXI.Circle as a PIXI.Polygon
+     * @param options - Options forwarded on to the pointsForArc method
+     * @returns The Circle expressed as a PIXI.Polygon
+     */
+    toPolygon(options?: Circle.PointsForArcOptions): PIXI.Polygon;
+
+    /**
+     * The recommended vertex density for the regular polygon approximation of a circle of a given radius.
+     * Small radius circles have fewer vertices. The returned value will be rounded up to the nearest integer.
+     * See the formula described at:
+     * https://math.stackexchange.com/questions/4132060/compute-number-of-regular-polgy-sides-to-approximate-circle-to-defined-precision
+     * @param radius  - Circle radius
+     * @param epsilon - The maximum tolerable distance between an approximated line segment and the true radius.
+     *                            A larger epsilon results in fewer points for a given radius.
+     * @returns The number of points for the approximated polygon
+     */
+    approximateVertexDensity(radius: number, epsilon?: number): number;
+
+    /**
+     * Intersect this PIXI.Circle with a PIXI.Polygon.
+     * @param polygon - A PIXI.Polygon
+     * @param options - Options which configure how the intersection is computed
+     * @returns The intersected polygon
+     */
+    intersectPolygon(
+      polygon: PIXI.Polygon,
+      options?: {
+        /** The number of points which defines the density of approximation */
+        density: number;
+
+        /** The clipper clip type */
+        clipType: number;
+
+        /**
+         * Use the Weiler-Atherton algorithm. Otherwise, use Clipper.
+         * (default: `true`)
+         * */
+        weilerAtherton: boolean;
+      },
+    ): PIXI.Polygon;
+
+    /**
+     * Intersect this PIXI.Circle with an array of ClipperPoints.
+     * Convert the circle to a Polygon approximation and use intersectPolygon.
+     * In the future we may replace this with more specialized logic which uses the line-circle intersection formula.
+     * @param clipperPoints - Array of ClipperPoints generated by PIXI.Polygon.toClipperPoints()
+     * @param options       - Options which configure how the intersection is computed
+     * @returns The intersected polygon
+     */
+    intersectClipper(
+      clipperPoints: PIXI.Polygon.ClipperPoint[],
+      options?: {
+        /** The number of points which defines the density of approximation */
+        density: number;
+      },
+    ): PIXI.Polygon;
+  }
+
+  namespace Circle {
+    interface PointsForArcOptions {
+      /** The number of points which defines the density of approximation */
+      density: number;
+
+      /** Whether to include points at the circle where the arc starts and ends */
+      includeEndpoints: boolean;
+    }
+  }
+}

package/src/foundry/client/pixi/extensions/index.d.mts

@@ -0,0 +1,3 @@
+import "./circle.d.mts";
+import "./polygon.d.mts";
+import "./rectangle.d.mts";

package/src/foundry/client/pixi/extensions/polygon.d.mts

@@ -0,0 +1,152 @@
+export {};
+
+declare module "pixi.js" {
+  namespace Polygon {
+    interface ClipperPoint {
+      X: number;
+      Y: number;
+    }
+  }
+
+  interface Polygon {
+    /**
+     * Test whether the polygon is has a positive signed area.
+     * Using a y-down axis orientation, this means that the polygon is "clockwise".
+     */
+    get isPositive(): boolean;
+
+    /**
+     * @remarks Non enumerable
+     */
+    _isPositive?: boolean;
+
+    /**
+     * Clear the cached signed orientation.
+     */
+    clearCache(): void;
+
+    /**
+     * Compute the signed area of polygon using an approach similar to ClipperLib.Clipper.Area.
+     * The math behind this is based on the Shoelace formula. https://en.wikipedia.org/wiki/Shoelace_formula.
+     * The area is positive if the orientation of the polygon is positive.
+     * @returns The signed area of the polygon
+     */
+    signedArea(): number;
+
+    /**
+     * Reverse the order of the polygon points in-place, replacing the points array into the polygon.
+     * Note: references to the old points array will not be affected.
+     * @returns This polygon with its orientation reversed
+     */
+    reverseOrientation(): PIXI.Polygon;
+
+    /**
+     * Add a de-duplicated point to the Polygon.
+     * @param point - The point to add to the Polygon
+     * @returns A reference to the polygon for method chaining
+     */
+    addPoint(point: Point): this;
+
+    /**
+     * Return the bounding box for a PIXI.Polygon.
+     * The bounding rectangle is normalized such that the width and height are non-negative.
+     * @returns The bounding PIXI.Rectangle
+     */
+    getBounds(): PIXI.Rectangle;
+
+    /**
+     * Construct a PIXI.Polygon instance from an array of clipper points [\{X,Y\}, ...].
+     * @param points  - An array of points returned by clipper
+     * @param options - Options which affect how canvas points are generated
+     * @param scalingFactor -
+     * @returns The resulting PIXI.Polygon
+     */
+    fromClipperPoints(
+      points: PIXI.Polygon.ClipperPoint[],
+      options?: {
+        /**
+         * A scaling factor used to preserve floating point precision
+         * (default: `1`)
+         */
+        scalingFactor: number;
+      },
+    ): PIXI.Polygon;
+
+    /**
+     * Convert a PIXI.Polygon into an array of clipper points [\{X,Y\}, ...].
+     * Note that clipper points must be rounded to integers.
+     * In order to preserve some amount of floating point precision, an optional scaling factor may be provided.
+     * @param options - Options which affect how clipper points are generated
+     * @returns An array of points to be used by clipper
+     */
+    toClipperPoints(options?: {
+      /** A scaling factor used to preserve floating point precision
+       *  (default: `1`) */
+      scalingFactor: number;
+    }): PIXI.Polygon.ClipperPoint[];
+
+    /**
+     * Determine whether the PIXI.Polygon is closed, defined by having the same starting and ending point.
+     */
+    get isClosed(): boolean;
+
+    /**
+     * Intersect this PIXI.Polygon with another PIXI.Polygon using the clipper library.
+     * @param other   - Another PIXI.Polygon
+     * @param options - Options which configure how the intersection is computed
+     * @returns The intersected polygon or null if no solution was present
+     */
+    intersectPolygon(
+      other: PIXI.Polygon,
+      options: {
+        /** The clipper clip type */
+        clipType?: number;
+
+        /** A scaling factor passed to Polygon#toClipperPoints to preserve precision */
+        scalingFactor?: number;
+      },
+    ): PIXI.Polygon | null;
+
+    /**
+     * Intersect this PIXI.Polygon with an array of ClipperPoints.
+     * @param clipperPoints - Array of clipper points generated by PIXI.Polygon.toClipperPoints()
+     * @param options       - Options which configure how the intersection is computed
+     */
+    intersectClipper(
+      clipperPoints: PIXI.Polygon.ClipperPoint[],
+      options?: {
+        /** The clipper clip type */
+        clipType?: number;
+
+        /** A scaling factor passed to Polygon#toClipperPoints to preserve precision */
+        scalingFactor?: number;
+      },
+    ): PIXI.Polygon.ClipperPoint[];
+
+    /**
+     * Intersect this PIXI.Polygon with a PIXI.Circle.
+     * For now, convert the circle to a Polygon approximation and use intersectPolygon.
+     * In the future we may replace this with more specialized logic which uses the line-circle intersection formula.
+     * @param circle  - A PIXI.Circle
+     * @param options - Options which configure how the intersection is computed
+     * @returns The intersected polygon
+     */
+    intersectCircle(
+      circle: PIXI.Circle,
+      options?: {
+        /** The number of points which defines the density of approximation */
+        density: number;
+      },
+    ): PIXI.Polygon;
+
+    /**
+     * Intersect this PIXI.Polygon with a PIXI.Rectangle.
+     * For now, convert the rectangle to a Polygon and use intersectPolygon.
+     * In the future we may replace this with more specialized logic which uses the line-line intersection formula.
+     * @param rect    - A PIXI.Rectangle
+     * @param options - Options which configure how the intersection is computed
+     * @returns The intersected polygon
+     */
+    intersectRectangle(rect: PIXI.Rectangle, options?: Record<string, unknown>): PIXI.Polygon;
+  }
+}