@league-of-foundry-developers/foundry-vtt-types 9.238.1 → 9.242.0

package/src/foundry/foundry.js/pixi/polygons/pointSourcePolygon.d.ts

@@ -0,0 +1,98 @@
+interface PointSourcePolygonConfig {
+  /** The type of polygon being computed */
+  type?: foundry.CONST.WALL_RESTRICTION_TYPES;
+
+  /** The angle of emission, if limited */
+  angle?: number;
+
+  /** The desired density of padding rays, a number per PI */
+  density?: number;
+
+  /** A limited radius of the resulting polygon */
+  radius?: number;
+
+  /** The direction of facing, required if the angle is limited */
+  rotation?: number;
+
+  /** Display debugging visualization and logging for the polygon */
+  debug?: boolean;
+
+  /** Is this polygon constrained by any walls? */
+  walls?: boolean;
+
+  /** The object (if any) that spawned this polygon. */
+  source?: PointSource;
+}
+
+/**
+ * An extension of the default PIXI.Polygon which is used to represent the line of sight for a point source.
+ */
+declare abstract class PointSourcePolygon extends PIXI.Polygon {
+  /**
+   * The origin point of the source polygon.
+   */
+  origin: Point;
+
+  /**
+   * The configuration of this polygon.
+   * @defaultValue `{}`
+   */
+  config: PointSourcePolygonConfig;
+
+  /**
+   * A cached array of SightRay objects used to compute the polygon.
+   * @defaultValue `[]`
+   */
+  rays: SightRay[];
+
+  /**
+   * Compute the rectangular bounds for the Polygon.
+   * @param points - The initially provided array of coordinates
+   * @returns The computed Rectangular bounds
+   */
+  protected _getBounds(points: number[]): PIXI.Rectangle;
+
+  /**
+   * Benchmark the performance of polygon computation for this source
+   * @param iterations - The number of test iterations to perform
+   * @param args       - Arguments passed to the compute method
+   */
+  static benchmark(
+    iterations: number,
+    ...args: Parameters<typeof PointSourcePolygon['create']>
+  ): ReturnType<typeof foundry.utils.benchmark>;
+
+  /**
+   * Compute the polygon given a point origin and radius
+   * @param origin - The origin source point
+   * @param config - Configuration options which customize the polygon computation
+   * @returns The computed polygon instance
+   */
+  static create(
+    origin: Point,
+    config: Parameters<PointSourcePolygon['initialize']>[1]
+  ): ReturnType<PointSourcePolygon['compute']>;
+
+  /**
+   * Compute the polygon using the origin and configuration options.
+   * @returns The computed polygon
+   */
+  compute(): this;
+
+  /**
+   * Perform the implementation-specific computation
+   */
+  protected abstract _compute(): void;
+
+  /**
+   * Customize the provided configuration object for this polygon type.
+   * @param origin - The provided polygon origin
+   * @param config - The provided configuration object
+   */
+  initialize(origin: Point, config: PointSourcePolygonConfig): void;
+
+  /**
+   * Visualize the polygon, displaying its computed area, rays, and collision points
+   */
+  visualize(): void;
+}

package/src/foundry/foundry.js/pixi/polygons/pointSourcePolygons/clockwiseSweepPolygon.d.ts

@@ -0,0 +1,388 @@
+import type { ConfiguredObjectClassForName } from '../../../../../types/helperTypes.js';
+
+declare global {
+  type VertexMap = Map<number, PolygonVertex>;
+
+  type EdgeSet = Set<PolygonEdge>;
+
+  interface ClockwiseSweepPolygonConfig extends PointSourcePolygonConfig {
+    /** @defaultValue `canvas.dimensions.maxR` */
+    radius?: number;
+
+    /** @defaultValue `360` */
+    angle?: number;
+
+    /** @defaultValue `0` */
+    rotation?: number;
+
+    /**
+     * The desired density of padding rays, a number per PI
+     * @defaultValue `12`
+     */
+    density?: number;
+
+    /**
+     * The minimum angle of emission
+     * @defaultValue `config.hasLimitedAngle ? Math.normalizeRadians(Math.toRadians(config.rotation + 90 - (config.angle / 2))) : -Math.PI`
+     */
+    aMin?: number;
+
+    /**
+     * The maximum angle of emission
+     * @defaultValue `config.hasLimitedAngle ? config.aMin + Math.toRadians(config.angle) : Math.PI`
+     */
+    aMax?: number;
+
+    /**
+     * The minimum ray of emission
+     * @defaultValue `Ray.fromAngle(origin.x, origin.y, config.aMin, config.radius)`
+     */
+    rMin?: Ray;
+
+    /**
+     * The maximum ray of emission
+     * @defaultValue `config.hasLimitedAngle && Ray.fromAngle(origin.x, origin.y, config.aMax, config.radius)`
+     */
+    rMax?: Ray;
+
+    /**
+     * Does this polygon have a limited radius?
+     * @defaultValue `config.radius > 0`
+     */
+    hasLimitedRadius?: boolean;
+
+    /**
+     * Does this polygon have a limited angle?
+     * @defaultValue `config.angle !== 0`
+     */
+    hasLimitedAngle?: boolean;
+
+    /**
+     * The squared radius of the polygon, for faster computation later
+     * @defaultValue `Math.pow(config.radius, 2)`
+     */
+    radius2?: number;
+
+    /**
+     * A small epsilon used for avoiding floating point precision issues
+     * @defaultValue `0.5 / config.radius`
+     */
+    radiusE?: number;
+  }
+
+  /**
+   * A PointSourcePolygon implementation that uses CCW (counter-clockwise) geometry orientation.
+   * Sweep around the origin, accumulating collision points based on the set of active walls.
+   * This algorithm was created with valuable contributions from https://github.com/caewok
+   */
+  class ClockwiseSweepPolygon extends PointSourcePolygon {
+    /**
+     * The configuration of this polygon.
+     */
+    config:
+      | ClockwiseSweepPolygonConfig
+      | ClockwiseSweepPolygon.InitializedConfig
+      | ClockwiseSweepPolygon.LimitedAngleConfig;
+
+    /**
+     * A mapping of vertices which define potential collision points
+     */
+    vertices: VertexMap;
+
+    /**
+     * The set of edges which define potential boundaries of the polygon
+     */
+    edges: EdgeSet;
+
+    /**
+     * A collection of rays which are fired at vertices
+     */
+    rays: SightRay[];
+
+    static benchmark(
+      iterations: number,
+      ...args: Parameters<typeof ClockwiseSweepPolygon['create']>
+    ): ReturnType<typeof foundry.utils.benchmark>;
+
+    static create(
+      origin: Point,
+      config: Parameters<ClockwiseSweepPolygon['initialize']>[1]
+    ): ReturnType<ClockwiseSweepPolygon['compute']>;
+
+    /**
+     * @override
+     * @param origin - The provided polygon origin
+     * @param config - The provided configuration object
+     */
+    initialize(origin: Point, config: ClockwiseSweepPolygon.InitConfig): void;
+
+    /** @override */
+    protected _compute(): void;
+
+    /**
+     * Translate walls and other obstacles into edges which limit visibility
+     * @internal
+     */
+    protected _identifyEdges(): void;
+
+    /**
+     * Get the super-set of walls which could potentially apply to this polygon.
+     * @internal
+     */
+    protected _getWalls(): ConfiguredObjectClassForName<'Wall'>[];
+
+    /**
+     * Restrict the set of candidate edges to those which appear within the limited angle of emission.
+     * @internal
+     */
+    protected _restrictEdgesByAngle(): void;
+
+    /**
+     * Process the candidate edges to further constrain them using a circular radius of effect.
+     * @internal
+     */
+    protected _constrainEdgesByRadius(): void;
+
+    /**
+     * Consolidate all vertices from identified edges and register them as part of the vertex mapping.
+     * @internal
+     */
+    protected _identifyVertices(): void;
+
+    /**
+     * Add additional vertices for intersections between edges.
+     * @param wallEdgeMap - A mapping of wall IDs to PolygonEdge instances
+     * @internal
+     */
+    protected _identifyIntersections(wallEdgeMap: Map<string, PolygonEdge>): void;
+
+    /**
+     * Execute the sweep over wall vertices
+     * @internal
+     */
+    protected _executeSweep(): void;
+
+    /**
+     * Determine the initial set of active edges as those which intersect with the initial ray
+     * @returns A set of initially active edges
+     * @internal
+     */
+    protected _initializeActiveEdges(): EdgeSet;
+
+    /**
+     * Sort vertices clockwise from the initial ray (due west).
+     * @returns The array of sorted vertices
+     * @internal
+     */
+    protected _sortVertices(): PolygonVertex[];
+
+    /**
+     * Test whether a target vertex is behind some closer active edge
+     * @param ray         - The ray being evaluated
+     *                      (unused)
+     * @param vertex      - The target vertex
+     * @param activeEdges - The set of active edges
+     * @returns Is the target vertex behind some closer edge?
+     * @internal
+     */
+    protected _isVertexBehindActiveEdges(
+      ray: Ray,
+      vertex: PolygonVertex,
+      activeEdges: EdgeSet
+    ): { isBehind: boolean; wasLimited: boolean };
+
+    /**
+     * Determine the final result of a candidate ray.
+     * @param ray         - The candidate ray being tested
+     * @param vertex      - The target vertex
+     * @param result      - The result being prepared
+     * @param activeEdges - The set of active edges
+     * @internal
+     */
+    protected _determineRayResult(ray: Ray, vertex: PolygonVertex, result: CollisionResult, activeEdges: EdgeSet): void;
+
+    /**
+     * Jump to a new closest active edge.
+     * In this case, our target vertex will be the primary collision.
+     * We may have a secondary collision if other active edges exist or if the vertex is prior to the ray endpoint.
+     * @internal
+     *
+     * @param ray             - The ray being emitted
+     * @param result          - The pending collision result
+     * @param activeEdges     - The set of currently active edges
+     * @param isBinding       - Is the target vertex a binding collision point?
+     * @param secondaryBefore - Whether to add secondary collision points before ("unshift") or after ("push")
+     *                          (default: `true`)
+     */
+    protected _beginNewEdge(
+      ray: Ray,
+      result: CollisionResult,
+      activeEdges: EdgeSet,
+      isBinding: boolean,
+      secondaryBefore?: boolean
+    ): void;
+
+    /**
+     * If the target vertex is connected to a currently active edge, we are terminating that edge.
+     * We know the target vertex is not behind another edge, so the target is our initial collision.
+     * There may be a second collision afterwards if no connected walls continue clockwise.
+     * @internal
+     *
+     * @param ray         - The ray being emitted
+     * @param result      - The pending collision result
+     * @param activeEdges - The set of currently active edges
+     * @param isBinding   - Is the target vertex a binding collision point?
+     */
+    protected _completeCurrentEdge(ray: Ray, result: CollisionResult, activeEdges: EdgeSet, isBinding: boolean): void;
+
+    /**
+     * Augment a CollisionResult with an additional secondary collision.
+     * Require secondary collisions to be a greater distance than the target vertex.
+     * @param ray    - The ray being evaluated
+     * @param result - The collision result
+     * @param edges  - The subset of active edges which are candidates for collision
+     * @internal
+     */
+    protected _getSecondaryCollisions(ray: Ray, result: CollisionResult, edges: EdgeSet): PolygonVertex[];
+
+    /**
+     * Identify collision points for a required terminal ray.
+     * @internal
+     *
+     * @param ray         - The ray being emitted
+     * @param result      - The pending collision result
+     * @param activeEdges - The set of currently active edges
+     */
+    protected _findRequiredCollision(ray: Ray, result: CollisionResult, activeEdges: EdgeSet): void;
+
+    /**
+     * Identify the collision points between an emitted Ray and a set of active edges.
+     * @param ray             - The candidate ray to test
+     * @param activeEdges     - The set of active edges
+     * @returns A sorted array of collision points
+     * @internal
+     */
+    protected _getRayCollisions(
+      ray: Ray,
+      activeEdges: EdgeSet,
+      {
+        minimumDistance
+      }?: {
+        /**
+         * Require collisions to exceed some minimum distance
+         * @defaultValue `0`
+         */
+        minimumDistance?: number;
+      }
+    ): PolygonVertex[];
+
+    /**
+     * Update the set of active edges given the result of an emitted ray.
+     * @param result      - The collision result
+     * @param activeEdges - The set of currently active edges
+     * @internal
+     */
+    protected _updateActiveEdges(result: CollisionResult, activeEdges: EdgeSet): void;
+
+    /**
+     * Construct the polygon from ray collision points
+     * @internal
+     */
+    protected _constructPolygonPoints(): void;
+
+    /**
+     * Add additional points to limited-radius polygons to approximate the curvature of a circle
+     * @param r0 - The prior ray that collided with some vertex
+     * @param r1 - The next ray that collides with some vertex
+     * @internal
+     */
+    protected _getPaddingPoints(r0: Ray, r1: Ray): Point[];
+
+    /**
+     * Test whether a wall should be included in the computed polygon for a given origin and type
+     * @param wall   - The Wall being considered
+     * @param origin - The origin point for the ray or polygon
+     * @param type   - The type of perception or movement restriction being imposed
+     * @returns Should the wall be included?
+     *
+     */
+    static testWallInclusion(
+      wall: ConfiguredObjectClassForName<'Wall'>,
+      origin: Point,
+      type: foundry.CONST.WALL_RESTRICTION_TYPES
+    ): boolean;
+
+    /**
+     * Test whether a vertex lies between two boundary rays
+     * @param vertex - The target vertex
+     * @param rMin   - The counter-clockwise bounding ray
+     * @param rMax   - The clockwise bounding ray
+     * @param angle  - The angle being tested, in degrees
+     * @returns Is the vertex between the two rays?
+     */
+    static pointBetweenRays(vertex: PolygonVertex, rMin: Ray, rMax: Ray, angle: number): boolean;
+
+    /** @override */
+    visualize(): void;
+
+    /**
+     * Check whether a given ray intersects with walls.
+     * @param ray     - The Ray being tested
+     * @param options - Options which customize how collision is tested
+     * @returns Whether any collision occurred if mode is "any"
+     *          An array of collisions, if mode is "all"
+     *          The closest collision, if mode is "closest"
+     */
+    static getRayCollisions<Mode extends 'any' | 'closest' | 'all'>(
+      ray: Ray,
+      options?: {
+        /**
+         * Which collision type to check, a value in CONST.WALL_RESTRICTION_TYPES
+         * @defaultValue `"move"`
+         */
+        type?: foundry.CONST.WALL_RESTRICTION_TYPES;
+
+        /**
+         * Which type of collisions are returned: any, closest, all
+         * @defaultValue `"all"`
+         */
+        mode?: Mode;
+
+        /**
+         * Visualize some debugging data to help understand the collision test
+         * @defaultValue `false`
+         */
+        debug?: boolean;
+      }
+    ): Mode extends 'any' ? boolean : Mode extends 'closest' ? PolygonVertex : PolygonVertex[];
+
+    /**
+     * Visualize the polygon, displaying its computed area, rays, and collision points
+     * @internal
+     */
+    protected static _visualizeCollision(ray: Ray, edges: EdgeSet, collisions: PolygonVertex[]): void;
+  }
+
+  namespace ClockwiseSweepPolygon {
+    type InitConfig = Partial<Pick<ClockwiseSweepPolygonConfig, 'radius' | 'angle' | 'rotation' | 'density'>>;
+
+    interface InitializedConfig extends ClockwiseSweepPolygonConfig {
+      hasLimitedRadius: boolean;
+      radius: number;
+      radius2: number;
+      radiusE: number;
+      aMin: number;
+      aMax: number;
+      angle: number;
+      rotation: number;
+      hasLimitedAngle: boolean;
+      density: number;
+      rMin: Ray;
+    }
+
+    interface LimitedAngleConfig extends InitializedConfig {
+      hasLimitedAngle: true;
+      rMax: Ray;
+    }
+  }
+}

package/src/foundry/foundry.js/pixi/polygons/pointSourcePolygons/index.d.ts

@@ -0,0 +1 @@
+import './clockwiseSweepPolygon';

package/src/foundry/foundry.js/pixi/shaders/abstractBaseShader.d.ts

@@ -2,6 +2,9 @@
  * This class defines an interface which all shaders utilize
  */
 declare abstract class AbstractBaseShader extends PIXI.Shader {
+  /** The current uniforms of the Shader */
+  uniforms: AbstractBaseShader.Uniforms;
+
   constructor(program: PIXI.Program, uniforms: AbstractBaseShader.Uniforms);
 
   /**
@@ -10,12 +13,16 @@ declare abstract class AbstractBaseShader extends PIXI.Shader {
   protected _defaults: AbstractBaseShader.Uniforms;
 
   /**
-   * The default vertex shader used by all instances of AbstractBaseShader
+   * The raw vertex shader used by this class.
+   * A subclass of AbstractBaseShader must implement the fragmentShader static field.
+   * @defaultValue `""`
+   *
+   * @remarks This is abstract, subclasses must implement it.
    */
   static vertexShader: string;
 
   /**
-   * The fragment shader which renders this source.
+   * The raw fragment shader used by this class.
    * A subclass of AbstractBaseShader must implement the fragmentShader static field.
    * @defaultValue `""`
    *
@@ -39,42 +46,9 @@ declare abstract class AbstractBaseShader extends PIXI.Shader {
 
   /**
    * Reset the shader uniforms back to their provided default values
+   * @internal
    */
   protected reset(): void;
-
-  /**
-   * A Vec3 pseudo-random generator, based on uv position
-   */
-  static PRNG3D: string;
-
-  /**
-   * A conventional pseudo-random number generator with the "golden" numbers, based on uv position
-   */
-  static PRNG: string;
-
-  /**
-   * A conventional noise generator
-   */
-  static NOISE: string;
-
-  /**
-   * Fractional Brownian Motion for a given number of octaves
-   * @param octaves - (default: `4`)
-   * @param amp     - (default: `1.0`)
-   */
-  static FBM(octaves?: number, amp?: number): string;
-
-  /**
-   * Fade easing to use with distance in interval [0,1]
-   * @param amp  - (default: `3`)
-   * @param coef - (default: `0.80`)
-   */
-  static FADE(amp?: number, coef?: number): string;
-
-  /**
-   * Convert a Hue-Saturation-Brightness color to RGB - useful to convert polar coordinates to RGB
-   */
-  static HSB2RGB: string;
 }
 
 declare namespace AbstractBaseShader {
@@ -91,5 +65,5 @@ declare namespace AbstractBaseShader {
     | { x: number; y: number; z: number; w: number }[]
     | PIXI.Texture;
 
-  type Uniforms = Partial<Record<string, AbstractBaseShader.UniformValue>>;
+  type Uniforms = Record<string, AbstractBaseShader.UniformValue>;
 }

package/src/foundry/foundry.js/pixi/shaders/abstractBaseShaders/adaptiveLightingShader.d.ts

@@ -0,0 +1,114 @@
+interface LightingTechnique {
+  /** The numeric identifier of the technique */
+  id: number;
+
+  /** The localization string that labels the technique */
+  label: string;
+
+  /** The shader fragment when the technique is used */
+  shader: string;
+}
+
+/**
+ * This class defines an interface which all adaptive lighting shaders extend.
+ */
+declare class AdaptiveLightingShader extends AbstractBaseShader {
+  /** @override */
+  static vertexShader: string;
+
+  /**
+   * Useful constant values computed at compile time
+   */
+  static CONSTANTS: string;
+
+  /**
+   * The coloration technique shader fragment
+   */
+  static get ADAPTIVE_COLORATION(): string;
+
+  /**
+   * Fade easing to use with distance in interval [0,1]
+   * @param amp  - (default: `3`)
+   * @param coef - (default: `0.80`)
+   */
+  static FADE(amp?: number, coef?: number): string;
+
+  /**
+   * Fractional Brownian Motion for a given number of octaves
+   * @param octaves - (default: `4`)
+   * @param amp     - (default: `1.0`)
+   */
+  static FBM(octaves?: number, amp?: number): string;
+
+  /**
+   * A conventional pseudo-random number generator with the "golden" numbers, based on uv position
+   */
+  static PRNG: string;
+
+  /**
+   * A Vec3 pseudo-random generator, based on uv position
+   */
+  static PRNG3D: string;
+
+  /**
+   * A conventional noise generator
+   */
+  static NOISE: string;
+
+  /**
+   * Convert a Hue-Saturation-Brightness color to RGB - useful to convert polar coordinates to RGB
+   */
+  static HSB2RGB: string;
+
+  /**
+   * Fast approximate perceived brightness computation
+   * Using Digital ITU BT.709 : Exact luminance factors
+   */
+  static PERCEIVED_BRIGHTNESS: string;
+
+  /**
+   * Switch between an inner and outer color, by comparing distance from center to ratio
+   * Apply a strong gradient between the two areas if gradual uniform is set to true
+   */
+  static SWITCH_COLOR: string;
+
+  /**
+   * Transition between bright and dim colors, if requested
+   */
+  static TRANSITION: string;
+
+  /**
+   * Constrain light to LOS
+   */
+  static CONSTRAIN_TO_LOS: string;
+
+  /**
+   * Incorporate falloff if a gradual uniform is requested
+   */
+  static FALLOFF: string;
+
+  /**
+   * Compute distance from the light center
+   */
+  static DISTANCE: string;
+
+  /**
+   * A mapping of available coloration techniques
+   */
+  static COLORATION_TECHNIQUES: AdaptiveLightingShader.ColorationTechniques;
+}
+
+declare namespace AdaptiveLightingShader {
+  interface ColorationTechniques extends Record<string, LightingTechnique> {
+    LEGACY: LightingTechnique;
+    LUMINANCE: LightingTechnique;
+    INTERNAL_HALO: LightingTechnique;
+    EXTERNAL_HALO: LightingTechnique;
+    COLOR_BURN: LightingTechnique;
+    INTERNAL_BURN: LightingTechnique;
+    EXTERNAL_BURN: LightingTechnique;
+    LOW_ABSORPTION: LightingTechnique;
+    HIGH_ABSORPTION: LightingTechnique;
+    INVERT_ABSORPTION: LightingTechnique;
+  }
+}