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

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

@@ -0,0 +1,226 @@
+export {};
+
+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(): 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: 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: 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: Point, b: Point): 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.
+     */
+    segmentIntersections(a: Point, b: Point): 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: Point;
+      B: Point;
+    };
+
+    /**
+     * Get the right edge of this rectangle.
+     * The returned edge endpoints are oriented clockwise around the rectangle.
+     */
+    get rightEdge(): {
+      A: Point;
+      B: Point;
+    };
+
+    /**
+     * Get the top edge of this rectangle.
+     * The returned edge endpoints are oriented clockwise around the rectangle.
+     */
+    get topEdge(): {
+      A: Point;
+      B: Point;
+    };
+
+    /**
+     * Get the bottom edge of this rectangle.
+     * The returned edge endpoints are oriented clockwise around the rectangle.
+     */
+    get bottomEdge(): {
+      A: Point;
+      B: 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: 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: Point,
+      b: 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?: {
+        /** 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 | null;
+
+    /**
+     * 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?: {
+        /** 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;
+
+    /**
+     * Generate a new rectangle by rotating this one clockwise about its center by a certain number of radians
+     * @param radians - The angle of rotation
+     * @returns A new rotated rectangle
+     */
+    rotate(radians: number): 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
+     * @returns The constructed rotated rectangle bounds
+     */
+    fromRotation(x: number, y: number, width: number, height: number, radians: number): PIXI.Rectangle;
+  }
+}
+
+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,189 @@
+export {};
+
+// TODO: Remove after layer is defined by #2841
+type CanvasDarknessEffects = CanvasLayer;
+
+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: 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: 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: 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: VisualEffectsMaskingFilter.FilterMode,
+      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: ColorSource;
+
+      /** The brightest ambient color */
+      brightestColor: ColorSource;
+
+      /** The color of darkness */
+      darknessColor: ColorSource;
+
+      /** The ambient daylight color */
+      daylightColor: ColorSource;
+
+      /** The color applied to explored areas */
+      fogExploredColor: ColorSource;
+
+      /** The color applied to unexplored areas */
+      fogUnexploredColor: ColorSource;
+
+      /** 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>;
+  }
+}

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

@@ -0,0 +1,7 @@
+import "./effects.d.mts";
+import "./environment.d.mts";
+import "./hidden.d.mts";
+import "./interface.d.mts";
+import "./overlay.d.mts";
+import "./primary.d.mts";
+import "./rendered.d.mts";

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

@@ -0,0 +1,74 @@
+import type { InexactPartial } from "../../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * A container group which displays interface elements rendered above other canvas groups.
+   */
+  class InterfaceCanvasGroup extends CanvasGroupMixin(PIXI.Container) {
+    /**
+     * @defaultValue `"interface"`
+     */
+    static override groupName: string;
+
+    /**
+     * Add a PrimaryGraphics to the group.
+     * @param drawing - The Drawing being added
+     * @returns The created Graphics instance
+     */
+    addDrawing(drawing: Drawing): PIXI.Graphics;
+
+    /**
+     * Remove a PrimaryGraphics from the group.
+     * @param drawing - The Drawing being removed
+     */
+    removeDrawing(drawing: Drawing): void;
+
+    protected override _draw(options: CanvasGroupMixin.DrawOptions): Promise<void>;
+
+    /**
+     * Display scrolling status text originating from this ObjectHUD container.
+     * @param origin  - An origin point where the text should first emerge
+     * @param content - The text content to display
+     * @param options - Options which customize the text animation
+     * @returns - The created PreciseText object which is scrolling
+     */
+    createScrollingText(
+      origin: Point,
+      content: string,
+      options?: {
+        /**
+         * The duration of the scrolling effect in milliseconds
+         * @defaultValue `2000`
+         */
+        duration?: number;
+
+        /**
+         * The distance in pixels that the scrolling text should travel
+         * @defaultValue (2 * text.width)
+         */
+        distance?: number;
+
+        /**
+         * The original anchor point where the text appears
+         */
+        anchor: foundry.CONST.TEXT_ANCHOR_POINTS;
+
+        /**
+         * The direction in which the text scrolls
+         */
+        direction: foundry.CONST.TEXT_ANCHOR_POINTS;
+
+        /**
+         * An amount of randomization between [0, 1] applied to the initial position
+         * @defaultValue `0`
+         */
+        jitter: number;
+
+        /**
+         * Additional parameters of PIXI.TextStyle which are applied to the text
+         */
+        textStyle: InexactPartial<PIXI.ITextStyle>;
+      },
+    ): Promise<PreciseText | null>;
+  }
+}

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

@@ -0,0 +1,18 @@
+export {};
+
+declare global {
+  /**
+   * A container group which is not bound to the stage world transform.
+   */
+  class OverlayCanvasGroup extends CanvasGroupMixin(UnboundContainer) {
+    /**
+     * @defaultValue `"overlay"`
+     */
+    static override groupName: string;
+
+    /**
+     * @defaultValue `false`
+     */
+    static override tearDownChildren: boolean;
+  }
+}