@league-of-foundry-developers/foundry-vtt-types 9.280.1 → 12.331.2-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: Canvas.Point, B: Canvas.Point);
+
+    /**
+     * The origin point, `{x, y}`
+     */
+    A: Canvas.Point;
+
+    /**
+     * The destination point, `{x, y}`
+     */
+    B: Canvas.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: Canvas.PointArray, B: Canvas.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: Canvas.Point, point: Canvas.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: Canvas.Point, point: Canvas.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,249 @@
+import type { ConstructorOf, InexactPartial } from "../../../../../types/utils.d.mts";
+import type PointEffectSourceMixin from "../../../../client-esm/canvas/sources/point-effect-source.d.mts";
+
+declare global {
+  interface PointSourcePolygonConfig extends PointSourcePolygon._Config {
+    /** The type of polygon being computed */
+    type: PointSourcePolygon.PolygonType;
+  }
+
+  /**
+   * 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: Canvas.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: Canvas.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: Canvas.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: Canvas.Point, config: PointSourcePolygonConfig): void;
+
+    /**
+     * 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: Canvas.Point,
+      destination: Canvas.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 {
+    /** @internal */
+    type _Config = InexactPartial<{
+      /** 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
+       * @defaultValue `false`
+       */
+      useThreshold: boolean;
+
+      /**
+       * Include edges coming from darkness sources
+       * @defaultValue `false`
+       */
+      includeDarkness: boolean;
+
+      /** Priority when it comes to ignore edges from darkness sources */
+      priority: number;
+
+      /** Display debugging visualization and logging for the polygon */
+      debug: boolean;
+
+      /** The object (if any) that spawned this polygon. */
+      source: PointEffectSourceMixin.AnyMixed;
+
+      /** 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;
+    }>;
+
+    type PolygonType = "light" | "sight" | "sound" | "move" | "universal";
+
+    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,132 @@
+import type { InexactPartial } from "../../../../types/utils.d.mts";
+
+declare module "pixi.js" {
+  interface Circle {
+    /**
+     * Determine the center of the circle.
+     * Trivial, but used to match center method for other shapes.
+     */
+    get circle(): PIXI.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: Canvas.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: Canvas.Point, b: Canvas.Point): [Canvas.Point?, Canvas.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): Canvas.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: Canvas.Point, b: Canvas.Point, options?: Circle.PointsForArcOptions): Canvas.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): Canvas.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?: InexactPartial<{
+        /** 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?: PIXI.Circle.IntersectClipperOptions,
+    ): 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;
+    }
+
+    interface IntersectClipperOptions extends PIXI.Polygon.IntersectClipperOptions {
+          /** The number of points which defines the density of approximation */
+          density?: number | undefined;
+    }
+  }
+}

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

@@ -0,0 +1,43 @@
+export {};
+
+declare global {
+  namespace PIXI {
+    namespace Graphics {
+      type Path = [number[] | PIXI.IPointData[] | PIXI.Polygon] | Array<number | PIXI.IPointData>;
+    }
+  }
+}
+
+/**
+ * @remarks Internal helper to accommodate for the reuse of functions across the various Graphics classes
+ */
+interface GraphicsHelper {
+  /**
+   * Draws a path.
+   * @param path - The polygon or points.
+   * @returns This Graphics instance.
+   */
+  drawPath(...path: PIXI.Graphics.Path): this;
+
+  /**
+   * Draws a smoothed polygon.
+   * @param path - The polygon or points.
+   * @returns This Graphics instance.
+   */
+  drawSmoothedPolygon(...path: PIXI.Graphics.Path): this;
+
+  /**
+   * Draws a smoothed path.
+   * @param path - The polygon or points.
+   * @returns This Graphics instance.
+   */
+  drawSmoothedPath(...path: PIXI.Graphics.Path): this;
+}
+
+declare module "pixi.js" {
+  interface Graphics extends GraphicsHelper {}
+}
+
+declare module "@pixi/graphics-smooth" {
+  interface SmoothGraphics extends GraphicsHelper {}
+}

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

@@ -0,0 +1,5 @@
+import "./circle.d.mts";
+import "./graphics.d.mts";
+import "./observable-transform.d.mts";
+import "./polygon.d.mts";
+import "./rectangle.d.mts";

package/src/foundry/client/pixi/extensions/observable-transform.d.mts

@@ -0,0 +1,30 @@
+import type { AnyObject } from "../../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * 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."`
+   */
+  class ObservableTransform<Scope extends AnyObject, CB extends (this: Scope) => unknown> 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;
+  }
+}