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

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

@@ -0,0 +1,142 @@
+import type { InexactPartial } from "../../../../types/utils.d.mts";
+
+declare module "pixi.js" {
+  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: Canvas.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?: InexactPartial<{
+        /**
+         * A scaling factor used to preserve floating point precision
+         * @defaultValue `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
+     */
+    intersectPolygon(other: PIXI.Polygon, options: PIXI.Polygon.IntersectClipperOptions): PIXI.Polygon;
+
+    /**
+     * 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?: PIXI.Polygon.IntersectClipperOptions,
+    ): 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?: PIXI.Circle.IntersectClipperOptions): 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?: PIXI.Rectangle.IntersectPolygonOptions): PIXI.Polygon;
+  }
+
+  namespace Polygon {
+    interface ClipperPoint {
+      X: number;
+      Y: number;
+    }
+
+    /** @internal Helper type for interface to simplify InexactPartial usage */
+    type _IntersectClipperOptions = InexactPartial<{
+      /** The clipper clip type */
+      clipType: number;
+
+      /** A scaling factor passed to Polygon#toClipperPoints to preserve precision */
+      scalingFactor: number;
+    }>;
+
+    interface IntersectClipperOptions extends _IntersectClipperOptions {}
+  }
+}

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

@@ -0,0 +1,248 @@
+import type { InexactPartial } from "../../../../types/utils.d.mts";
+
+declare module "pixi.js" {
+  interface Rectangle {
+    /**
+     * Bit code labels splitting a rectangle into zones, based on the Cohen-Sutherland algorithm.
+     * See https://en.wikipedia.org/wiki/Cohen%E2%80%93Sutherland_algorithm
+     *          left    central   right
+     * top      1001    1000      1010
+     * central  0001    0000      0010
+     * bottom   0101    0100      0110
+     */
+    CS_ZONES: {
+      INSIDE: 0x0000;
+      LEFT: 0x0001;
+      RIGHT: 0x0010;
+      TOP: 0x1000;
+      BOTTOM: 0x0100;
+      TOPLEFT: 0x1001;
+      TOPRIGHT: 0x1010;
+      BOTTOMRIGHT: 0x0110;
+      BOTTOMLEFT: 0x0101;
+    };
+
+    /**
+     * Calculate center of this rectangle.
+     */
+    get center(): Canvas.Point;
+
+    /**
+     * Return the bounding box for a PIXI.Rectangle.
+     * The bounding rectangle is normalized such that the width and height are non-negative.
+     */
+    getBounds(): PIXI.Rectangle;
+
+    /**
+     * Determine if a point is on or nearly on this rectangle.
+     * @param p - Point to test
+     * @returns Is the point on the rectangle boundary?
+     */
+    pointIsOn(p: Canvas.Point): boolean;
+
+    /**
+     * Calculate the rectangle Zone for a given point located around, on, or in the rectangle.
+     * See https://en.wikipedia.org/wiki/Cohen%E2%80%93Sutherland_algorithm
+     * This differs from _getZone in how points on the edge are treated: they are not considered inside.
+     * @param point - A point to test for location relative to the rectangle
+     * @returns Which edge zone does the point belong to?
+     */
+    _getEdgeZone(point: Canvas.Point): PIXI.Rectangle["CS_ZONES"];
+
+    /**
+     * Get all the points (corners) for a polygon approximation of a rectangle between two points on the rectangle.
+     * The two points can be anywhere in 2d space on or outside the rectangle.
+     * The starting and ending side are based on the zone of the corresponding a and b points.
+     * (See PIXI.Rectangle.CS_ZONES.)
+     * This is the rectangular version of PIXI.Circle.prototype.pointsBetween, and is similarly used
+     * to draw the portion of the shape between two intersection points on that shape.
+     * @param a - A point on or outside the rectangle, representing the starting position.
+     * @param b - A point on or outside the rectangle, representing the starting position.
+     * @returns Points returned are clockwise from start to end.
+     */
+    pointsBetween(a: Canvas.Point, b: Canvas.Point): Canvas.Point[];
+
+    /**
+     * Get all intersection points for a segment A|B
+     * Intersections are sorted from A to B.
+     * @param a - Endpoint A of the segment
+     * @param b - Endpoint B of the segment
+     * @returns Array of intersections or empty if no intersection.
+     *  If A|B is parallel to an edge of this rectangle, returns the two furthest points on
+     *  the segment A|B that are on the edge.
+     *  The return object's t0 property signifies the location of the intersection on segment A|B.
+     *  This will be NaN if the segment is a point.
+     *  The return object's t1 property signifies the location of the intersection on the rectangle edge.
+     *  The t1 value is measured relative to the intersecting edge of the rectangle.
+     */
+    segmentIntersections(a: Canvas.Point, b: Canvas.Point): Canvas.Point[];
+
+    /**
+     * Compute the intersection of this Rectangle with some other Rectangle.
+     * @param other - Some other rectangle which intersects this one
+     * @returns The intersected rectangle
+     */
+    intersection(other: PIXI.Rectangle): PIXI.Rectangle;
+
+    /**
+     * Convert this PIXI.Rectangle into a PIXI.Polygon
+     * @returns The Rectangle expressed as a PIXI.Polygon
+     */
+    toPolygon(): PIXI.Rectangle;
+
+    /**
+     * Get the left edge of this rectangle.
+     * The returned edge endpoints are oriented clockwise around the rectangle.
+     */
+    get leftEdge(): {
+      A: Canvas.Point;
+      B: Canvas.Point;
+    };
+
+    /**
+     * Get the right edge of this rectangle.
+     * The returned edge endpoints are oriented clockwise around the rectangle.
+     */
+    get rightEdge(): {
+      A: Canvas.Point;
+      B: Canvas.Point;
+    };
+
+    /**
+     * Get the top edge of this rectangle.
+     * The returned edge endpoints are oriented clockwise around the rectangle.
+     */
+    get topEdge(): {
+      A: Canvas.Point;
+      B: Canvas.Point;
+    };
+
+    /**
+     * Get the bottom edge of this rectangle.
+     * The returned edge endpoints are oriented clockwise around the rectangle.
+     */
+    get bottomEdge(): {
+      A: Canvas.Point;
+      B: Canvas.Point;
+    };
+
+    /**
+     * Calculate the rectangle Zone for a given point located around or in the rectangle.
+     * https://en.wikipedia.org/wiki/Cohen%E2%80%93Sutherland_algorithm
+     *
+     * @param p - Point to test for location relative to the rectangle
+     */
+    _getZone(p: Canvas.Point): PIXI.Rectangle["CS_ZONES"];
+
+    /**
+     * Test whether a line segment AB intersects this rectangle.
+     * @param a       - The first endpoint of segment AB
+     * @param b       - The second endpoint of segment AB
+     * @param options - Options affecting the intersect test.
+     * @returns True if intersects.
+     */
+    lineSegmentIntersects(
+      a: Canvas.Point,
+      b: Canvas.Point,
+      options?: {
+        /** If true, a line contained within the rectangle will return true */
+        inside?: boolean;
+      },
+    ): boolean;
+
+    /**
+     * Intersect this PIXI.Rectangle 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?: PIXI.Rectangle.IntersectPolygonOptions): PIXI.Polygon;
+
+    /**
+     * Intersect this PIXI.Rectangle with an array of ClipperPoints. Currently, uses the clipper library.
+     * In the future we may replace this with more specialized logic which uses the line-line 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?: InexactPartial<{
+        /** The number of points which defines the density of approximation */
+        density: number;
+      }>,
+    ): PIXI.Polygon | null;
+
+    /**
+     * Determine whether some other Rectangle overlaps with this one.
+     * This check differs from the parent class Rectangle#intersects test because it is true for adjacency (zero area).
+     * @param other - Some other rectangle against which to compare
+     * @returns Do the rectangles overlap?
+     */
+    overlaps(other: PIXI.Rectangle): boolean;
+
+    /**
+     * Normalize the width and height of the rectangle in-place, enforcing that those dimensions be positive.
+     */
+    normalize(): PIXI.Rectangle;
+
+    /**
+     * Fits this rectangle around this rectangle rotated around the given pivot counterclockwise by the given angle in radians.
+     * @param radians - The angle of rotation.
+     * @param pivot   - An optional pivot point (normalized).
+     * @returns A new rotated rectangle
+     */
+    rotate(radians: number, pivot?: PIXI.Point): PIXI.Rectangle;
+
+    /**
+     * Create normalized rectangular bounds given a rectangle shape and an angle of central rotation.
+     * @param x       - The top-left x-coordinate of the un-rotated rectangle
+     * @param y       - The top-left y-coordinate of the un-rotated rectangle
+     * @param width   - The width of the un-rotated rectangle
+     * @param height  - The height of the un-rotated rectangle
+     * @param radians - The angle of rotation about the center
+     * @param pivot   - An optional pivot point (if not provided, the pivot is the centroid)
+     * @param _outRect - (Internal)
+     * @returns The constructed rotated rectangle bounds
+     */
+    fromRotation(
+      x: number,
+      y: number,
+      width: number,
+      height: number,
+      radians: number,
+      pivot?: PIXI.Point,
+      _outRect?: PIXI.Rectangle,
+    ): PIXI.Rectangle;
+  }
+
+  namespace Rectangle {
+    /** @internal Helper type for interface to simplify InexactPartial usage */
+    type _IntersectPolygonOptions = 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.
+       * @defaultValue `true`
+       * */
+      weilerAtherton: boolean;
+
+      /** If the WeilerAtherton constructor could mutate or not */
+      canMutate: boolean;
+    }>;
+
+    interface IntersectPolygonOptions extends _IntersectPolygonOptions {}
+  }
+}
+
+declare global {
+  /**
+   * A PIXI.Rectangle where the width and height are always positive and the x and y are always the top-left
+   * @deprecated You are using the NormalizedRectangle class which has been deprecated in favor of PIXI.Rectangle.prototype.normalize
+   */
+  class NormalizedRectangle extends PIXI.Rectangle {}
+}

package/src/foundry/client/pixi/groups/effects.d.mts

@@ -0,0 +1,186 @@
+import type { ValueOf } from "../../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * A container group which contains visual effects rendered above the primary group.
+   */
+  class EffectsCanvasGroup extends CanvasGroupMixin(PIXI.Container) {
+    constructor();
+
+    /**
+     * Whether to currently animate light sources.
+     */
+    animateLightSources: boolean;
+
+    /**
+     * Whether to currently animate vision sources.
+     */
+    animateVisionSources: boolean;
+
+    /**
+     * A mapping of light sources which are active within the rendered Scene.
+     */
+    lightSources: Collection<foundry.canvas.sources.PointLightSource>;
+
+    /**
+     * A mapping of darkness sources which are active within the rendered Scene.
+     */
+    darknessSources: Collection<foundry.canvas.sources.PointDarknessSource>;
+
+    /**
+     * A Collection of vision sources which are currently active within the rendered Scene.
+     */
+    visionSources: Collection<foundry.canvas.sources.PointVisionSource.Any>;
+
+    /**
+     * A set of vision mask filters used in visual effects group
+     */
+    visualEffectsMaskingFilters: Set<VisualEffectsMaskingFilter>;
+
+    /**
+     * Iterator for all light and darkness sources.
+     */
+    allSources(): Generator<
+      foundry.canvas.sources.PointDarknessSource | foundry.canvas.sources.PointLightSource,
+      void,
+      void
+    >;
+
+    override _createLayers(): Record<string, CanvasLayer>;
+
+    /**
+     * A layer of background alteration effects which change the appearance of the primary group render texture.
+     */
+    background: CanvasBackgroundAlterationEffects;
+
+    /**
+     * A layer which adds illumination-based effects to the scene.
+     */
+    illumination: CanvasIlluminationEffects;
+
+    /**
+     * A layer which adds color-based effects to the scene.
+     */
+    coloration: CanvasColorationEffects;
+
+    /**
+     * A layer which adds darkness effects to the scene.
+     */
+    darkness: CanvasDarknessEffects;
+
+    /**
+     * Clear all effects containers and animated sources.
+     */
+    clearEffects(): void;
+
+    protected override _draw(options: CanvasGroupMixin.DrawOptions): Promise<void>;
+
+    /**
+     * Initialize positive light sources which exist within the active Scene.
+     * Packages can use the "initializeLightSources" hook to programmatically add light sources.
+     */
+    initializeLightSources(): void;
+
+    /**
+     * Re-initialize the shapes of all darkness sources in the Scene.
+     * This happens before initialization of light sources because darkness sources contribute additional edges which
+     * limit perception.
+     * Packages can use the "initializeDarknessSources" hook to programmatically add darkness sources.
+     */
+    initializeDarknessSources(): void;
+
+    /**
+     * Refresh the state and uniforms of all light sources and darkness sources objects.
+     */
+    refreshLightSources(): boolean;
+
+    /**
+     * Refresh the state and uniforms of all VisionSource objects.
+     */
+    refreshVisionSources(): boolean;
+
+    /**
+     * Refresh the active display of lighting.
+     */
+    refreshLighting(): boolean;
+
+    /**
+     * Test whether the point is inside light.
+     * @param point     - The point.
+     * @param elevation - The elevation of the point.
+     * @returns Is inside light?
+     */
+    testInsideLight(point: Canvas.Point, elevation: number): boolean;
+
+    /**
+     * Test whether the point is inside darkness.
+     * @param point     - The point.
+     * @param elevation - The elevation of the point.
+     * @returns Is inside darkness?
+     */
+    testInsideDarkness(point: Canvas.Point, elevation: number): boolean;
+
+    /**
+     * Get the darkness level at the given point.
+     * @param point     - The point.
+     * @param elevation - The elevation of the point.
+     * @returns The darkness level.
+     */
+    getDarknessLevel(point: Canvas.Point, elevation: number): number;
+
+    override _tearDown(options: CanvasGroupMixin.TearDownOptions): Promise<void>;
+
+    /**
+     * Activate vision masking for visual effects
+     * @param enabled - Whether to enable or disable vision masking
+     *                  (default: `true`)
+     */
+    toggleMaskingFilters(enabled: boolean): void;
+
+    /**
+     * Activate post-processing effects for a certain effects channel.
+     * @param filterMode          - The filter mode to target.
+     * @param postProcessingModes - The post-processing modes to apply to this filter.
+     * @param uniforms            - The uniforms to update.
+     */
+    activatePostProcessingFilters(
+      filterMode: ValueOf<VisualEffectsMaskingFilter.FILTER_MODES>,
+      postProcessingModes: VisualEffectsMaskingFilter.PostProcessModes,
+      uniforms: AbstractBaseShader.Uniforms,
+    ): void;
+
+    /**
+     * Reset post-processing modes on all Visual Effects masking filters.
+     */
+    resetPostProcessingFilters(): void;
+
+    /**
+     * Activate light source animation for AmbientLight objects within this layer
+     */
+    activateAnimation(): void;
+
+    /**
+     * Deactivate light source animation for AmbientLight objects within this layer
+     */
+    deactivateAnimation(): void;
+
+    /**
+     * Animate a smooth transition of the darkness overlay to a target value.
+     * Only begin animating if another animation is not already in progress.
+     * @param target - The target darkness level between 0 and 1
+     * @returns A Promise which resolves once the animation is complete
+     */
+    animateDarkness(
+      target?: number,
+      {
+        duration,
+      }?: {
+        /**
+         * The desired animation time in milliseconds. Default is 10 seconds
+         * @defaultValue 10000
+         */
+        duration?: number;
+      },
+    ): ReturnType<(typeof CanvasAnimation)["animate"]>;
+  }
+}

package/src/foundry/client/pixi/groups/environment.d.mts

@@ -0,0 +1,80 @@
+import type { InexactPartial } from "../../../../types/utils.d.mts";
+
+// TODO: Remove when this is typed as part of #2674
+type SceneEnvironmentData = unknown;
+
+declare global {
+  /**
+   * A container group which contains the primary canvas group and the effects canvas group.
+   */
+  class EnvironmentCanvasGroup extends CanvasGroupMixin(PIXI.Container) {
+    /**
+     * The global light source attached to the environment
+     */
+    globalLightSource(): foundry.canvas.sources.GlobalLightSource;
+
+    /**
+     * @defaultValue `"environment"`
+     */
+    static override groupName: string;
+
+    /**
+     * @defaultValue `false`
+     */
+    static override tearDownChildren: boolean;
+
+    /**
+     * Colors exposed by the manager.
+     */
+    colors: Record<string, Color | undefined>;
+
+    /**
+     * Weights used by the manager to compute colors.
+     */
+    weights: Record<string, number | undefined>;
+
+    /**
+     * Get the darkness level of this scene.
+     */
+    get darknessLevel(): number;
+
+    protected override _draw(options: CanvasGroupMixin.DrawOptions): Promise<void>;
+
+    /**
+     * Initialize the scene environment options.
+     * @remarks `@fires PIXI.FederatedEvent type: "darknessChange" - event: {environmentData: {darknessLevel, priorDarknessLevel}}`
+     */
+    initialize(config: InexactPartial<EnvironmentCanvasGroup.InitializeConfig>): void;
+
+    /**
+     * @deprecated since v12, will be removed in v14
+     * @remarks `"EnvironmentCanvasGroup#darknessPenalty is deprecated without replacement. The darkness penalty is no longer applied on light and vision sources."`
+     */
+    get darknessPenalty(): 0;
+  }
+
+  namespace EnvironmentCanvasGroup {
+    interface InitializeConfig {
+      /** The background canvas color */
+      backgroundColor: Color.Source;
+
+      /** The brightest ambient color */
+      brightestColor: Color.Source;
+
+      /** The color of darkness */
+      darknessColor: Color.Source;
+
+      /** The ambient daylight color */
+      daylightColor: Color.Source;
+
+      /** The color applied to explored areas */
+      fogExploredColor: Color.Source;
+
+      /** The color applied to unexplored areas */
+      fogUnexploredColor: Color.Source;
+
+      /** The scene environment data */
+      environment: SceneEnvironmentData;
+    }
+  }
+}

package/src/foundry/client/pixi/groups/hidden.d.mts

@@ -0,0 +1,40 @@
+import type { EventMode } from "pixi.js";
+
+declare global {
+  /**
+   * A specialized canvas group for rendering hidden containers before all others (like masks).
+   */
+  class HiddenCanvasGroup extends CanvasGroupMixin(PIXI.Container) {
+    /**
+     * @defaultValue `"none"`
+     */
+    override eventMode: EventMode;
+
+    /**
+     * The container which hold masks.
+     */
+    masks: PIXI.Container;
+
+    /**
+     * @defaultValue `"hidden"`
+     */
+    static override groupName: string;
+
+    /**
+     * Add a mask to this group.
+     * @param name          - Name of the mask.
+     * @param displayObject - Display object to add.
+     * @param position      - Position of the mask.
+     */
+    addMask(name: string, displayObject: PIXI.DisplayObject, position?: number): void;
+
+    /**
+     * Invalidate the masks: flag them for rerendering.
+     */
+    invalidateMasks(): void;
+
+    protected override _draw(options: CanvasGroupMixin.DrawOptions): Promise<void>;
+
+    protected override _tearDown(options: CanvasGroupMixin.TearDownOptions): Promise<void>;
+  }
+}