@7h3laughingman/foundry-types 13.351.0

package/src/client/canvas/geometry/shapes/ray.d.mts

@@ -0,0 +1,126 @@
+import { Point } from "#common/_types.mjs";
+import { LineIntersection } from "#common/utils/_types.mjs";
+
+/**
+ * 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
+ */
+export default class 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;
+
+    /* -------------------------------------------- */
+    /*  Attributes                                  */
+    /* -------------------------------------------- */
+
+    /**
+     * 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 normalized 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);
+
+    /* -------------------------------------------- */
+    /*  Methods                                     */
+    /* -------------------------------------------- */
+
+    /**
+     * 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: [number, number], B: [number, number]): 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
+     * @return The coordinates of the projected point
+     */
+    project(t: number): Point;
+
+    /**
+     * 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.
+     * @return 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
+     * http://paulbourke.net/geometry/pointlineplane/
+     */
+    intersectSegment(coords: [number]): LineIntersection | null;
+}

package/src/client/canvas/geometry/shapes/source-polygon.d.mts

@@ -0,0 +1,161 @@
+import { PointSourcePolygonConfig } from "../_types.mjs";
+import PolygonVertex from "../edges/vertex.mjs";
+import { ElevatedPoint, Point } from "./../../../../common/_types.mjs";
+import Ray from "./ray.mjs";
+
+/**
+ * An extension of Polygon which is used to represent the line of sight for a point source.
+ */
+export default abstract class PointSourcePolygon<TConfig extends PointSourcePolygonConfig = PointSourcePolygonConfig> extends PIXI.Polygon {
+    /**
+     * Customize how wall direction of one-way walls is applied
+     */
+    static WALL_DIRECTION_MODES: Readonly<{
+        NORMAL: 0;
+        REVERSED: 1;
+        BOTH: 2;
+    }>;
+
+    /**
+     * The rectangular bounds of this polygon
+     */
+    bounds: PIXI.Rectangle;
+
+    /**
+     * The origin point of the source polygon.
+     */
+    origin: ElevatedPoint;
+
+    /**
+     * The configuration of this polygon.
+     */
+    config: TConfig;
+
+    /**
+     * 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): void;
+
+    /**
+     * Compute the polygon given a point origin and radius
+     * @param origin The origin source point. The elevation defaults to
+     *                                                the elevation of config.source if passed and otherwise 0.
+     * @param config Configuration options which customize the polygon computation
+     * @returns The computed polygon instance
+     */
+    static create<C extends PointSourcePolygonConfig, T extends PointSourcePolygon<C>>(this: ConstructorOf<T>, origin: Point, config?: C): T;
+
+    /**
+     * Create a clone of this polygon.
+     * This overrides the default PIXI.Polygon#clone behavior.
+     * @returns A cloned instance
+     */
+    override clone(): this;
+
+    /* -------------------------------------------- */
+    /*  Polygon Computation                         */
+    /* -------------------------------------------- */
+
+    /**
+     * 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: TConfig): 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?: object): this;
+
+    override contains(x: number, y: number): boolean;
+
+    /* -------------------------------------------- */
+    /*  Polygon Boundary Constraints                */
+    /* -------------------------------------------- */
+
+    /**
+     * Constrain polygon points by applying boundary shapes.
+     */
+    protected _constrainBoundaryShapes(): void;
+
+    /* -------------------------------------------- */
+    /*  Collision Testing                           */
+    /* -------------------------------------------- */
+
+    /**
+     * Test whether a Ray between the origin and destination points would collide with a boundary of this Polygon
+     * @param origin        An origin point
+     * @param destination   A destination point
+     * @param config        The configuration that defines a certain Polygon type
+     * @param [config.mode] The collision mode to test: "any", "all", or "closest"
+     * @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(origin: Point, destination: Point, config?: PointSourcePolygonConfig & { mode: "closest" }): PolygonVertex | null;
+    static testCollision(origin: Point, destination: Point, config?: PointSourcePolygonConfig & { mode: "any" }): boolean;
+    static testCollision(origin: Point, destination: Point, config?: PointSourcePolygonConfig & { mode: "all" }): PolygonVertex[];
+    static testCollision(
+        origin: Point,
+        destination: Point,
+        config?: PointSourcePolygonConfig & { mode?: "any" | "all" | "closest" },
+    ): boolean | PolygonVertex | PolygonVertex[] | null;
+
+    /**
+     * 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(ray: Ray, mode: string): boolean | PolygonVertex | PolygonVertex[] | null;
+
+    /* -------------------------------------------- */
+    /*  Visualization and Debugging                 */
+    /* -------------------------------------------- */
+
+    /** Visualize the polygon, displaying its computed area, rays, and collision points */
+    visualize(): void;
+
+    /* -------------------------------------------- */
+    /*  Threshold Polygons                          */
+    /* -------------------------------------------- */
+
+    /**
+     * Augment a PointSourcePolygon by adding additional coverage for shapes permitted by threshold walls.
+     * @param {PointSourcePolygon} polygon        The computed polygon
+     * @returns {PointSourcePolygon}              The augmented polygon
+     */
+    static applyThresholdAttenuation<TPolygon extends PointSourcePolygon>(polygon: TPolygon): TPolygon;
+
+    /**
+     * Determine if the shape is a complete circle.
+     * The config object must have an angle and a radius properties.
+     */
+    isCompleteCircle(): boolean;
+}

package/src/client/canvas/geometry/unbound-transform.d.mts

@@ -0,0 +1,9 @@
+/**
+ * A custom Transform class which is not bound to the parent worldTransform.
+ * localTransform are working as usual.
+ */
+export default class UnboundTransform extends PIXI.Transform {
+    static override IDENTITY: UnboundTransform;
+
+    override updateTransform(parentTransform: PIXI.Transform): void;
+}

package/src/client/canvas/geometry/weiler-atherton-clipping.d.mts

@@ -0,0 +1,120 @@
+/**
+ * An implementation of the Weiler Atherton algorithm for clipping polygons.
+ * This currently only handles combinations that will not result in any holes.
+ * Support may be added for holes in the future.
+ *
+ * This algorithm is faster than the Clipper library for this task because it relies on the unique properties of the
+ * circle, ellipse, or convex simple clip object.
+ * It is also more precise in that it uses the actual intersection points between the circle/ellipse and polygon,
+ * instead of relying on the polygon approximation of the circle/ellipse to find the intersection points.
+ *
+ * For more explanation of the underlying algorithm, see:
+ * https://en.wikipedia.org/wiki/Weiler%E2%80%93Atherton_clipping_algorithm
+ * https://www.geeksforgeeks.org/weiler-atherton-polygon-clipping-algorithm
+ * https://h-educate.in/weiler-atherton-polygon-clipping-algorithm/
+ */
+export default class WeilerAthertonClipper {
+    /**
+     * Construct a WeilerAthertonClipper instance used to perform the calculation.
+     * @param polygon    Polygon to clip
+     * @param clipObject Object used to clip the polygon
+     * @param clipType   Type of clip to use
+     * @param clipOpts   Object passed to the clippingObject methods toPolygon and pointsBetween
+     */
+    constructor(polygon: PIXI.Polygon, clipObject: PIXI.Rectangle | PIXI.Circle, clipType: number, clipOpts: object);
+
+    /**
+     * The supported clip types.
+     * Values are equivalent to those in ClipperLib.ClipType.
+     */
+    static CLIP_TYPES: Readonly<{ INTERSECT: 0; UNION: 1 }>;
+
+    /**
+     * The supported intersection types.
+     */
+    static INTERSECTION_TYPES: Readonly<{ OUT_IN: -1; IN_OUT: 1; TANGENT: 0 }>;
+
+    /**
+     * Test if one shape envelops the other. Assumes the shapes do not intersect.
+     *  1. Polygon is contained within the clip object. Union: clip object; Intersect: polygon
+     *  2. Clip object is contained with polygon. Union: polygon; Intersect: clip object
+     *  3. Polygon and clip object are outside one another. Union: both; Intersect: null
+     * @param polygon    Polygon to clip
+     * @param clipObject Object to clip against the polygon
+     * @param clipType   One of CLIP_TYPES
+     * @param clipOpts   Clip options which are forwarded to toPolygon methods
+     * @returns Returns the polygon, the clipObject.toPolygon(), both, or neither.
+     */
+    static testForEnvelopment(
+        polygon: PIXI.Polygon,
+        clipObject: PIXI.Rectangle | PIXI.Circle,
+        clipType: Readonly<{
+            INTERSECT: 0;
+            UNION: 1;
+        }>,
+        clipOpts: object,
+    ): PIXI.Polygon[];
+
+    polygon: PIXI.Polygon;
+
+    clipObject: PIXI.Rectangle | PIXI.Circle;
+
+    /**
+     * Configuration settings
+     */
+    config?: {
+        /** One of CLIP_TYPES */
+        clipType?: WAClipperType;
+        /** Object passed to the clippingObject methods toPolygon and pointsBetween */
+        clipOpts?: object;
+    };
+
+    /**
+     * Union a polygon and clipObject using the Weiler Atherton algorithm.
+     * @param polygon    Polygon to clip
+     * @param clipObject Object to clip against the polygon
+     * @param clipOpts   Options passed to the clipping object methods toPolygon and pointsBetween
+     */
+    static union(polygon: PIXI.Polygon, clipObject: PIXI.Rectangle | PIXI.Circle, clipOpts?: object): PIXI.Polygon[];
+
+    /**
+     * Intersect a polygon and clipObject using the Weiler Atherton algorithm.
+     * @param polygon    Polygon to clip
+     * @param clipObject Object to clip against the polygon
+     * @param clipOpts   Options passed to the clipping object methods toPolygon and pointsBetween
+     */
+    static intersect(polygon: PIXI.Polygon, clipObject: PIXI.Rectangle | PIXI.Circle, clipOpts?: object): PIXI.Polygon[];
+
+    /**
+     * Clip a given clipObject using the Weiler-Atherton algorithm.
+     *
+     * At the moment, this will return a single PIXI.Polygon in the array unless clipType is a union and the polygon
+     * and clipObject do not overlap, in which case the [polygon, clipObject.toPolygon()] array will be returned.
+     * If this algorithm is expanded in the future to handle holes, an array of polygons may be returned.
+     *
+     * @param polygon           Polygon to clip
+     * @param clipObject        Object to clip against the polygon
+     * @param options           Options which configure how the union or intersection is computed
+     * @param options.clipType  One of {@link foundry.canvas.geometry.WeilerAthertonClipper.CLIP_TYPES}
+     * @param options.canMutate If the WeilerAtherton constructor could mutate or not the subject polygon points
+     *
+     * - Any additional properties in `options` (besides clipType and canMutate)
+     *   are captured by the rest operator (`...clipOpts`) and passed to the WeilerAthertonClipper constructor.
+     *
+     * @returns Array of polygons and clipObjects
+     */
+    static combine(
+        polygon: PIXI.Polygon,
+        clipObject: PIXI.Rectangle | PIXI.Circle,
+        {
+            clipType,
+            canMutate,
+            ...clipOpts
+        }?: {
+            clipType: number;
+            canMutate?: boolean;
+        },
+    ): PIXI.Polygon[];
+}
+
+type WAClipperType = (typeof WeilerAthertonClipper)[keyof typeof WeilerAthertonClipper];

package/src/client/canvas/groups/_module.d.mts

@@ -0,0 +1,10 @@
+export { default as CanvasGroupMixin } from "./canvas-group-mixin.mjs";
+export { default as EffectsCanvasGroup } from "./effects.mjs";
+export * from "./environment.mjs";
+export { default as EnvironmentCanvasGroup } from "./environment.mjs";
+export { default as HiddenCanvasGroup } from "./hidden.mjs";
+export { default as InterfaceCanvasGroup } from "./interface.mjs";
+export { default as OverlayCanvasGroup } from "./overlay.mjs";
+export { default as PrimaryCanvasGroup } from "./primary.mjs";
+export { default as RenderedCanvasGroup } from "./rendered.mjs";
+export { default as CanvasVisibility } from "./visibility.mjs";

package/src/client/canvas/groups/canvas-group-mixin.mts

@@ -0,0 +1,95 @@
+/* eslint-disable @typescript-eslint/no-unused-expressions */
+import CanvasLayer from "../layers/base/canvas-layer.mjs";
+
+/**
+ * A mixin which decorates any container with base canvas common properties.
+ * @param {typeof PIXI.Container} ContainerClass  The parent Container class being mixed.
+ * @returns A ContainerClass subclass mixed with CanvasGroupMixin features.
+ */
+export default function CanvasGroupMixin<TBase extends ConstructorOf<PIXI.Container>>(ContainerClass: TBase) {
+    class CanvasGroup extends ContainerClass {
+        constructor(...args: any[]) {
+            super(...args);
+        }
+
+        /**
+         * The name of this canvas group.
+         */
+        static groupName: string | undefined;
+
+        /**
+         * If this canvas group should teardown non-layers children.
+         */
+        static tearDownChildren: boolean;
+
+        /**
+         * The canonical name of the canvas group is the name of the constructor that is the immediate child of the
+         * defined base class.
+         */
+        override get name(): string {
+            return "";
+        }
+
+        /**
+         * The name used by hooks to construct their hook string.
+         * Note: You should override this getter if hookName should not return the class constructor name.
+         */
+        get hookName(): string {
+            return "";
+        }
+
+        /**
+         * A mapping of CanvasLayer classes which belong to this group.
+         */
+        declare layers: Record<string, CanvasLayer>;
+
+        /* -------------------------------------------- */
+
+        /**
+         * Create CanvasLayer instances which belong to the canvas group.
+         */
+        protected _createLayers(): Record<string, CanvasLayer> {
+            return {};
+        }
+
+        /* -------------------------------------------- */
+        /*  Rendering                                   */
+        /* -------------------------------------------- */
+
+        /**
+         * Draw the canvas group and all its components.
+         * @returns A Promise which resolves once the group is fully drawn
+         */
+        async draw(options?: object): Promise<this> {
+            options;
+            return this;
+        }
+
+        /**
+         * Draw the canvas group and all its component layers.
+         */
+        protected async _draw(options?: object): Promise<void> {
+            options;
+        }
+
+        /* -------------------------------------------- */
+        /*  Tear-Down                                   */
+        /* -------------------------------------------- */
+
+        /**
+         * Remove and destroy all layers from the base canvas.
+         */
+        async tearDown(options?: object): Promise<this> {
+            options;
+            return this;
+        }
+
+        /**
+         * Remove and destroy all layers from the base canvas.
+         */
+        protected async _tearDown(options: object): Promise<void> {
+            options;
+        }
+    }
+    return CanvasGroup;
+}

package/src/client/canvas/groups/effects.d.mts

@@ -0,0 +1,118 @@
+import CanvasLayer from "../layers/base/canvas-layer.mjs";
+import { AmbientLight, Token } from "../placeables/_module.mjs";
+import type { GlobalLightSource, PointLightSource, PointVisionSource } from "../sources/_module.mjs";
+import { Point } from "./../../../common/_types.mjs";
+import Collection from "./../../../common/utils/collection.mjs";
+import CanvasGroupMixin from "./canvas-group-mixin.mjs";
+
+/**
+ * A container group which contains visual effects rendered above the primary group.
+ *
+ * ### Hook Events
+ * - {@link hookEvents.drawEffectsCanvasGroup}
+ * - {@link hookEvents.createEffectsCanvasGroup}
+ * - {@link hookEvents.lightingRefresh}
+ */
+export default class EffectsCanvasGroup extends CanvasGroupMixin(PIXI.Container) {
+    constructor();
+
+    /** The current global light source */
+    globalLightSource: GlobalLightSource;
+
+    /** 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<string, PointLightSource<AmbientLight | Token>>;
+
+    /** A Collection of vision sources which are currently active within the rendered Scene. */
+    visionSources: Collection<string, PointVisionSource<Token>>;
+
+    /** A set of vision mask filters used in visual effects group */
+    visualEffectsMaskingFilters: Set<PIXI.Filter>;
+
+    /** A layer of background alteration effects which change the appearance of the primary group render texture. */
+    background: CanvasLayer;
+
+    /** A layer which adds illumination-based effects to the scene. */
+    illumination: CanvasLayer;
+
+    /** A layer which adds color-based effects to the scene. */
+    coloration: CanvasLayer;
+
+    /** A layer which adds darkness effects to the scene */
+    darkness: CanvasLayer;
+
+    /** Clear all effects containers and animated sources. */
+    clearEffects(): void;
+
+    /** Initialize LightSource objects for all AmbientLightDocument instances that exist within the active Scene. */
+    initializeLightSources(): void;
+
+    /** Update the global light source which provide global illumination to the Scene. */
+    protected _updateGlobalLightSource(): GlobalLightSource;
+
+    /** Refresh the state and uniforms of all LightSource objects. */
+    refreshLightSources(): void;
+
+    /** Refresh the state and uniforms of all LightSource objects. */
+    refreshVisionSources(): void;
+
+    /** Refresh the active display of lighting. */
+    refreshLighting(): void;
+
+    /**
+     * Test whether the point is inside light.
+     * @param position      The point.
+     * @param elevation     The elevation of the point.
+     * @returns             Is inside light?
+     */
+    testInsideLight(position: Point, elevation: number): boolean;
+
+    /**
+     * Test whether the point is inside darkness.
+     * @param position      The point.
+     * @param elevation     The elevation of the point.
+     * @returns             Is inside a darkness?
+     */
+    testInsideDarkness(position: Point, elevation: number): boolean;
+
+    /**
+     * Activate vision masking for visual effects
+     * @param [enabled=true]    Whether to enable or disable vision masking
+     */
+    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: string, postProcessingModes?: string[], uniforms?: object): void;
+
+    /** Reset post-processing modes on all Visual Effects masking filters. */
+    resetPostProcessingFilters(): void;
+
+    /* -------------------------------------------- */
+    /*  Animation Management                        */
+    /* -------------------------------------------- */
+
+    /** 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
+     * @param duration The desired animation time in milliseconds. Default is 10 seconds
+     * @returns A Promise which resolves once the animation is complete
+     */
+    animateDarkness(target?: number, { duration }?: { duration?: number }): Promise<void>;
+}