@league-of-foundry-developers/foundry-vtt-types 9.255.1 → 9.268.0

package/src/foundry/foundry.js/pixi/containers/canvasLayers/sightLayer.d.ts

@@ -4,18 +4,17 @@
  * @see PointSource
  *
  * The container structure of this layer is as follows:
- * sight: SightLayer              The SightLayer itself
- *   msk: PIXI.Graphics           A masking rectangle that restricts exploration to the scene background
- *   unexplored: PIXI.Graphics    An unexplored background that spans the entire scene canvas
- *   explored: PIXI.Container     The exploration container
- *      revealed: PIXI.Container  The container of areas which have been previously revealed
- *        saved: PIXI.Sprite      The saved FOW exploration texture from the database
- *        pending: PIXI.Container A container of pending exploration polygons that have not yet been saved
- *        roofs: PIXI.Container   A container of occluded roof sprites which should not be marked as explored
- *      current: PIXI.Container   The current vision container
- *        los: PIXI.Graphics      The current line-of-sight polygon
- *        fov: PIXI.Graphics      The current filed-of-view polygon
- *      msk: PIXI.Graphics        The masking rectangle that limits exploration to the Scene background
+ *
+ * unexplored   The unexplored background which spans the entire canvas
+ * explored     The exploration container which tracks exploration progress
+ * revealed       A container of regions which have previously been revealed
+ * saved          The saved fog exploration texture
+ * pending        Pending exploration which has not yet been committed to the texture
+ * vision         The container of current vision exploration
+ * vision.base      Baseline provided vision
+ * vision.fov       Current light source field-of-view polygons
+ * vision.los       Current vision source line-of-sight polygons
+ * vision.roofs     Roof textures which should temporarily be revealed
  *
  * @example <caption>The sightRefresh hook</caption>
  * ```typescript
@@ -26,6 +25,21 @@ import { ConfiguredDocumentClass } from '../../../../../types/helperTypes';
 
 declare global {
   class SightLayer extends CanvasLayer<SightLayer.LayerOptions> {
+    /** The unexplored background which spans the entire canvas */
+    unexplored?: PIXI.Graphics;
+
+    /** The exploration container which tracks exploration progress */
+    explored?: PIXI.Container;
+
+    /** A container of regions which have previously been revealed */
+    revealed?: PIXI.Container;
+
+    /** The saved fog exploration texture */
+    saved?: PIXI.Sprite;
+
+    /** Pending exploration which has not yet been committed to the texture */
+    pending?: PIXI.Container;
+
     constructor();
 
     /**
@@ -39,46 +53,78 @@ declare global {
      */
     sources: foundry.utils.Collection<PointSource>;
 
-    /**
-     * The canonical line-of-sight polygon which defines current Token visibility.
-     */
-    los: PIXI.Graphics;
-
     /**
      * A status flag for whether the layer initialization workflow has succeeded
      * @defaultValue `false`
+     * @internal
      */
     protected _initialized: boolean;
 
     /**
-     * A pool of fog of war exploration containers that can be recycled
-     * @defaultValue `[]`
+     * A debounced function to save fog of war exploration once a stream of updates have stopped
      */
-    protected _visionPool: PIXI.Container[];
+    debounceSaveFog: (...args: Parameters<this['saveFog']>) => void;
 
     /**
-     * Track whether fog of war exploration has been updated and required saving
-     * @defaultValue `false`
+     * The current vision container which provides line-of-sight for vision sources and field-of-view of light sources.
+     * @defaultValue `undefined`
      */
-    protected _fogUpdated: boolean;
+    vision:
+      | (PIXI.Container & {
+          /** Baseline provided vision */
+          base: PIXI.Graphics;
+
+          /** Current light source field-of-view polygons */
+          fov: PIXI.Container;
+
+          /** Current vision source line-of-sight polygons */
+          los: PIXI.Graphics;
+
+          /** Roof textures which should temporarily be revealed */
+          roofs: PIXI.Container;
+        })
+      | undefined;
 
     /**
-     * Track the number of moves which have updated fog of war
-     * @defaultValue `0`
+     * The canonical line-of-sight polygon which defines current Token visibility.
+     * @defaultValue `undefined`
      */
-    protected _fogUpdates: number;
+    los: PIXI.Graphics | undefined;
 
     /**
-     * A debounced function to save fog of war exploration once a stream of updates have stopped
+     * A cached container which creates a render texture used for the LOS mask.
+     * @defaultValue `undefined`
      */
-    debounceSaveFog: (...args: Parameters<this['saveFog']>) => void;
+    losCache: CachedContainer | undefined;
+
+    /**
+     * Track whether we have pending fog updates which have not yet been saved to the database
+     * @defaultValue `false`
+     * @internal
+     */
+    protected _fogUpdated: boolean;
 
     /**
      * The configured resolution used for the saved fog-of-war texture
      * @defaultValue `undefined`
+     * @internal
      */
     protected _fogResolution: { resolution: number; width: number; height: number } | undefined;
 
+    /**
+     * A pool of RenderTexture objects which can be cycled through to save fog exploration progress.
+     * @defaultValue `[]`
+     * @internal
+     */
+    protected _fogTextures: PIXI.RenderTexture[];
+
+    /**
+     * Track whether there is a source of vision within the buffer region outside the primary scene canvas
+     * @defaultValue `false`
+     * @internal
+     */
+    protected _inBuffer: boolean;
+
     /**
      * Define the threshold value for the number of distinct Wall endpoints.
      * Below this threshold, exact vision computation is used by casting a Ray at every endpoint.
@@ -93,6 +139,12 @@ declare global {
      */
     static FOG_COMMIT_THRESHOLD: number;
 
+    /**
+     * The maximum allowable fog of war texture size.
+     * @defaultValue `4096`
+     */
+    static MAXIMUM_FOW_TEXTURE_SIZE: number;
+
     /**
      * @remarks This is not overridden in foundry but reflects the real behavior.
      */
@@ -123,18 +175,6 @@ declare global {
     /** @override */
     tearDown(): Promise<this>;
 
-    /**
-     * Initialize the Sight Layer. Initialization has the following hierarchical workflow:
-     *
-     * Initialize Layer (reset entire layer)
-     *  InitializeLights (used to reset all lights)
-     *    UpdateLight (update a single light)
-     *  InitializeTokens (reset all tokens)
-     *    UpdateToken (update a single token)
-     *  Initialize Fog (reset FOW state)
-     */
-    initialize(): Promise<void>;
-
     /**
      * Initialize fog of war - resetting it when switching scenes or re-drawing the canvas
      */
@@ -145,42 +185,45 @@ declare global {
      */
     initializeSources(): Promise<void>;
 
-    /** @override */
-    draw(): Promise<this>;
-
     /**
-     * Construct a vision container that is used to render a single view position.
-     * These containers are placed into the _visionPool and recycled as needed.
+     * Update FoW unexplored and explored colors
      */
-    protected _createVisionContainer(): PIXI.Container;
+    updateFogExplorationColors(): void;
+
+    /** @override */
+    draw(): Promise<this>;
 
     /**
-     * Obtain a vision container from the recycling pool, or create one if no container exists.
-     * Assign the container as the current fog exploration and the current LOS polygon.
+     * Create the cached container and sprite used to provide a LOS mask
+     * @internal
      */
-    protected _getVisionContainer(): PIXI.Container;
+    protected _createCachedMask(): void;
 
     /**
-     * Return a vision container back to the pool, recycling it for future use.
-     * @param c - The container to recycle
+     * Construct a vision container that is used to render a single view position.
+     * @internal
      */
-    protected _recycleVisionContainer(c: PIXI.Container): void;
+    protected _createVisionContainer(): PIXI.Container;
 
     /**
      * Update the display of the sight layer.
      * Organize sources into rendering queues and draw lighting containers for each source
-     *
-     * @param forceUpdateFog - Always update the Fog exploration progress for this update
-     *                         (default: `false`)
-     * @param noUpdateFog    - Never update the Fog exploration progress for this update
-     *                         (default: `false`)
      */
     refresh({
       forceUpdateFog,
-      noUpdateFog
+      skipUpdateFog
     }?: {
+      /**
+       * Always update the Fog exploration progress for this update
+       * (default: `false`)
+       */
       forceUpdateFog?: boolean;
-      noUpdateFog?: boolean;
+
+      /**
+       * Never update the Fog exploration progress for this update
+       * (default: `false`)
+       */
+      skipUpdateFog?: boolean;
     }): void | ReturnType<this['restrictVisibility']>;
 
     /**
@@ -192,21 +235,34 @@ declare global {
     /**
      * Test whether a point on the Canvas is visible based on the current vision and LOS polygons
      *
-     * @param point     - The point in space to test, an object with coordinates x and y.
-     * @param tolerance - A numeric radial offset which allows for a non-exact match. For example, if
-     *                    tolerance is 2 then the test will pass if the point is within 2px of a vision
-     *                    polygon.
-     *                    (defaultValue: `2`)
-     * @param object    - An optional reference to the object whose visibility is being tested
-     *                    (defaultValue: `null`)
-     *
+     * @param point - The point in space to test, an object with coordinates x and y.
      * @returns Whether the point is currently visible.
      */
     testVisibility(
       point: Point,
-      { tolerance, object }?: { tolerance?: number; object?: PIXI.DisplayObject | null }
+      {
+        tolerance,
+        object
+      }?: {
+        /**
+         * A numeric radial offset which allows for a non-exact match. For example, if
+         * tolerance is 2 then the test will pass if the point is within 2px of a vision
+         * polygon.
+         * (defaultValue: `2`)
+         */
+        tolerance?: number;
+
+        /**
+         * An optional reference to the object whose visibility is being tested
+         * (defaultValue: `null`)
+         */
+        object?: PIXI.DisplayObject | null;
+      }
     ): boolean;
 
+    /** @internal */
+    protected _getFogTexture(): PIXI.RenderTexture;
+
     /**
      * Once a new Fog of War location is explored, composite the explored container with the current staging sprite
      * Save that staging Sprite as the rendered fog exploration and swap it out for a fresh staging texture
@@ -242,6 +298,7 @@ declare global {
     /**
      * Choose an adaptive fog rendering resolution which downscales the saved fog textures for larger dimension Scenes.
      * It is important that the width and height of the fog texture is evenly divisible by the downscaling resolution.
+     * @internal
      */
     protected _configureFogResolution(): { resolution: number; width: number; height: number };
 
@@ -249,50 +306,11 @@ declare global {
      * If fog of war data is reset from the server, re-draw the canvas
      */
     protected _handleResetFog(): Promise<void>;
-
-    /**
-     * Visualize the sight layer to understand algorithm performance.
-     * @param bounds    - The initial rectangular bounds of the vision check
-     * @param endpoints - The wall endpoints being tested
-     * @param rays      - The array of cast vision Rays
-     * @param los       - The resulting line-of-sight polygon
-     * @param fov       - The resulting field-of-vision polygon
-     */
-    protected static _visualizeSight(
-      bounds: Rectangle,
-      endpoints: PointArray[],
-      rays: Ray[],
-      los: PIXI.Polygon,
-      fov: PIXI.Polygon
-    ): void;
-
-    /**
-     * @deprecated since 0.8.2
-     * @see WallsLayer#computePolygon
-     * Compute line-of-sight and field-of-vision polygons for a given origin position and visibility radius.
-     * The line-of-sight polygon defines the unrestricted area of visibility for the source.
-     * The field-of-vision polygon defines the restricted area of visibility for the source.
-     * @param angle        - (default: `360`)
-     * @param density      - (default: `6`)
-     * @param rotation     - (default: `0`)
-     * @param unrestricted - (default: `false`)
-     */
-    static computeSight(
-      origin: Point,
-      radius: number,
-      {
-        angle,
-        density,
-        rotation,
-        unrestricted
-      }?: { angle?: number; density?: number; rotation?: number; unrestricted?: boolean }
-    ): { rays: Ray[]; los: PIXI.Polygon; fov: PIXI.Polygon };
   }
 
   namespace SightLayer {
     interface LayerOptions extends CanvasLayer.LayerOptions {
       name: 'sight';
-      zIndex: 400;
     }
   }
 }

package/src/foundry/foundry.js/pixi/containers/controlIcon.d.ts

@@ -27,6 +27,9 @@ declare class ControlIcon extends PIXI.Container {
 
   borderColor: number;
 
+  /**
+   * The color of the icon tint, if any
+   */
   tintColor: number | null;
 
   /**

package/src/foundry/foundry.js/pixi/containers/index.d.ts

@@ -9,6 +9,7 @@ import './cursor';
 import './doorControl';
 import './effectsCanvasGroup';
 import './interfaceCanvasGroup';
+import './objectHUD';
 import './placeableObject';
 import './placeableObjects';
 import './ruler';

package/src/foundry/foundry.js/pixi/containers/objectHUD.d.ts

@@ -0,0 +1,82 @@
+/**
+ * An extension of PIXI.Container used as the interface frame for a PlaceableObject on the ControlsLayer
+ *
+ * @see {@link PlaceableObject}
+ * @see {@link ControlsLayer}
+ */
+declare class ObjectHUD extends PIXI.Container {
+  constructor(object: PIXI.DisplayObject);
+
+  /**
+   * The object that this HUD container is linked to
+   */
+  object: PIXI.DisplayObject;
+
+  /**
+   * Use the linked object's transform matrix to easily synchronize position
+   */
+  transform: PIXI.Transform;
+
+  /** @override */
+  // @ts-expect-error this is a property in `PIXI.Container` but foundry overrides it as an accessor.
+  get visible(): boolean;
+  set visible(value: boolean);
+
+  /** @override */
+  // @ts-expect-error this is a property in `PIXI.Container` but foundry overrides it as an accessor.
+  get renderable(): boolean;
+  set renderable(value: boolean);
+
+  /**
+   * Display scrolling status text originating from this ObjectHUD container.
+   * @param content - The text content to display
+   * @param options - (default: `{}`)
+   * @returns The created PreciseText object which is scrolling
+   */
+  createScrollingText(
+    content: string,
+    options?: ObjectHUD.CreateScrollingTextOptions | undefined
+  ): Promise<PreciseText | null>;
+
+  /**
+   * Orchestrate the animation of the scrolling text in this HUD
+   * @param text     - The PrecisText instance to animate
+   * @param duration - A desired duration of animation
+   * @param dx       - A horizontal distance to animate the text
+   *                   (default: `0`)
+   * @param dy       - A vertical distance to animate the text
+   *                   (default: `0`)
+   * @internal
+   */
+  protected _animateScrollText(text: PreciseText, duration: number, dx?: number, dy?: number): Promise<void>;
+}
+
+type TextStyleProperties = Exclude<ConstructorParameters<typeof PIXI.TextStyle>[0], undefined>;
+
+declare namespace ObjectHUD {
+  interface CreateScrollingTextOptions extends TextStyleProperties {
+    /**
+     * The original anchor point where the text first appears
+     * @defaultValue `CONST.TEXT_ANCHOR_POINTS.CENTER`
+     */
+    anchor?: foundry.CONST.TEXT_ANCHOR_POINTS | undefined;
+
+    /**
+     * The direction in which the text scrolls
+     * @defaultValue `CONST.TEXT_ANCHOR_POINTS.TOP`
+     */
+    direction?: foundry.CONST.TEXT_ANCHOR_POINTS | undefined;
+
+    /**
+     * The duration of the scrolling effect in milliseconds
+     * @defaultValue `2000`
+     */
+    duration?: number | undefined;
+
+    /**
+     * An amount of randomization between 0 and 1 to apply to the initial Position
+     * @defaultValue `0`
+     */
+    jitter?: number | undefined;
+  }
+}

package/src/foundry/foundry.js/pixi/containers/placeableObjects/ambientLight.d.ts

@@ -11,7 +11,7 @@ declare global {
     /**
      * A reference to the PointSource object which defines this light source area of effect
      */
-    source: PointSource;
+    source: LightSource;
 
     /**
      * A reference to the ControlIcon used to configure this light
@@ -25,6 +25,11 @@ declare global {
     /** @override */
     get bounds(): NormalizedRectangle;
 
+    /**
+     * A convenience accessor to the LightData configuration object
+     */
+    get config(): foundry.data.LightData;
+
     /**
      * Test whether a specific AmbientLight source provides global illumination
      */
@@ -53,6 +58,9 @@ declare global {
     /** @override */
     draw(): Promise<this>;
 
+    /** @override */
+    destroy(options?: Parameters<PlaceableObject['destroy']>[0]): void;
+
     /**
      * Draw the ControlIcon for the AmbientLight
      * @internal
@@ -74,12 +82,9 @@ declare global {
 
     /**
      * Update the source object associated with this light
-     * @param defer   - Defer refreshing the LightingLayer to manually call that refresh later.
-     *                  (default: `false`)
-     * @param deleted - Indicate that this light source has been deleted.
-     *                  (default: `false`)
+     * @param options - (default: `{}}`)
      */
-    updateSource({ defer, deleted }?: { defer?: boolean; deleted?: boolean }): null | void;
+    updateSource(options?: AmbientLight.UpdateSourceOptions | undefined): void;
 
     /** @override */
     protected _onCreate(
@@ -116,4 +121,20 @@ declare global {
     /** @override */
     protected _onDragLeftCancel(event: MouseEvent): void;
   }
+
+  namespace AmbientLight {
+    interface UpdateSourceOptions {
+      /**
+       * Defer refreshing the LightingLayer to manually call that refresh later.
+       * @defaultValue `false`
+       */
+      defer?: boolean | undefined;
+
+      /**
+       * Indicate that this light source has been deleted.
+       * @defaultValue `false`
+       */
+      deleted?: boolean | undefined;
+    }
+  }
 }

package/src/foundry/foundry.js/pixi/containers/placeableObjects/ambientSound.d.ts

@@ -13,6 +13,11 @@ declare global {
      */
     sound: Sound | null;
 
+    /**
+     * A SoundSource object which manages the area of effect for this ambient sound
+     */
+    source: SoundSource;
+
     /** @override */
     static embeddedName: 'AmbientSound';
 
@@ -31,9 +36,9 @@ declare global {
     get bounds(): Rectangle;
 
     /**
-     * A convenience accessor for the sound type
+     * The named identified for the source object associated with this ambient sound
      */
-    get type(): 'l' | 'g';
+    get sourceId(): string;
 
     /**
      * A convenience accessor for the sound radius in pixels
@@ -54,6 +59,9 @@ declare global {
     /** @override */
     draw(): Promise<this>;
 
+    /** @override */
+    destroy(options?: Parameters<PlaceableObject['destroy']>[0]): void;
+
     /**
      * Draw the graphical preview of the audio source area of effect
      * @internal
@@ -76,9 +84,9 @@ declare global {
 
     /**
      * Compute the field-of-vision for an object, determining its effective line-of-sight and field-of-vision polygons
-     * @returns An object containing the rays, LOS polygon, and FOV polygon for the light
+     * @param options - (default: `{}`)
      */
-    updateSource(): { rays: null; los: null; fov: PIXI.Circle } | ReturnType<WallsLayer['computePolygon']>;
+    updateSource(options?: AmbientSound.UpdateSourceOptions | undefined): void;
 
     /** @override */
     protected _onCreate(
@@ -118,5 +126,19 @@ declare global {
        */
       fade: number;
     }
+
+    interface UpdateSourceOptions {
+      /**
+       * Defer refreshing the SoundsLayer to manually call that refresh later.
+       * @defaultValue `false`
+       */
+      defer?: boolean | undefined;
+
+      /**
+       * Indicate that this SoundSource has been deleted.
+       * @defaultValue `false`
+       */
+      deleted?: boolean | undefined;
+    }
   }
 }