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

package/src/foundry/client/pixi/perception/fog.d.mts

@@ -0,0 +1,102 @@
+export {};
+
+declare global {
+  /**
+   * A fog of war management class which is the singleton canvas.fog instance.
+   */
+  class FogManager {
+    /**
+     * The FogExploration document which applies to this canvas view
+     * @defaultValue `null`
+     */
+    exploration: FogExploration | null;
+
+    /**
+     * Define the number of fog refresh needed before the fog texture is extracted and pushed to the server.
+     */
+    static COMMIT_THRESHOLD: 70;
+
+    /**
+     * The exploration SpriteMesh which holds the fog exploration texture.
+     */
+    get sprite(): SpriteMesh;
+
+    /**
+     * The configured options used for the saved fog-of-war texture.
+     */
+    get textureConfiguration(): FogTextureConfiguration;
+
+    /**
+     * Does the currently viewed Scene support Token field of vision?
+     */
+    get tokenVision(): boolean;
+
+    /**
+     * Does the currently viewed Scene support fog of war exploration?
+     */
+    get fogExploration(): boolean;
+
+    /**
+     * Initialize fog of war - resetting it when switching scenes or re-drawing the canvas
+     */
+    initialize(): Promise<void>;
+
+    /**
+     * Clear the fog and reinitialize properties (commit and save in non reset mode)
+     */
+    clear(): Promise<void>;
+
+    /**
+     * Once a new Fog of War location is explored, composite the explored container with the current staging sprite.
+     * Once the number of refresh is \> to the commit threshold, save the fog texture to the database.
+     */
+    commit(): void;
+
+    /**
+     * Load existing fog of war data from local storage and populate the initial exploration sprite
+     */
+    load(): Promise<PIXI.Texture | void>;
+
+    /**
+     * Dispatch a request to reset the fog of war exploration status for all users within this Scene.
+     * Once the server has deleted existing FogExploration documents, the _onReset handler will re-draw the canvas.
+     */
+    reset(): Promise<void>;
+
+    /**
+     * Request a fog of war save operation.
+     * Note: if a save operation is pending, we're waiting for its conclusion.
+     */
+    save(): Promise<void>;
+
+    /**
+     * If fog of war data is reset from the server, deactivate the current fog and initialize the exploration.
+     * @internal
+     */
+    _handleReset(): Promise<void>;
+
+    /**
+     * @deprecated since v11, will be removed in v13
+     * @remarks pending is deprecated and redirected to the exploration container
+     */
+    get pending(): CanvasVisibility["explored"];
+
+    /**
+     * @deprecated since v11, will be removed in v13
+     * @remarks revealed is deprecated and redirected to the exploration container
+     */
+    get revealed(): CanvasVisibility["explored"];
+
+    /**
+     * @deprecated since v11, will be removed in v13
+     * @remarks update is obsolete and always returns true. The fog exploration does not record position anymore.
+     */
+    update(source: any, force: boolean): true;
+
+    /**
+     * @deprecated since v11, will be removed in v13
+     * @remarks resolution is deprecated and redirected to CanvasVisibility#textureConfiguration
+     */
+    get resolution(): CanvasVisibility["textureConfiguration"];
+  }
+}

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

@@ -0,0 +1,7 @@
+import "./clockwise-sweep.d.mts";
+import "./color-manager.d.mts";
+import "./detection-mode.d.mts";
+import "./fog.d.mts";
+import "./perception-manager.d.mts";
+import "./vision-mode.d.mts";
+import "./weiler-atherton-clipping.d.mts";

package/src/foundry/client/pixi/perception/perception-manager.d.mts

@@ -0,0 +1,166 @@
+import type { DeepPartial } from "../../../../types/utils.d.mts";
+
+declare global {
+  interface PerceptionManagerFlags {
+    /** Re-initialize the entire lighting configuration */
+    initializeLighting: boolean;
+
+    /** Refresh the rendered appearance of lighting */
+    refreshLighting: boolean;
+
+    /** Update the configuration of light sources */
+    refreshLightSources: boolean;
+
+    /** Re-initialize the entire vision configuration */
+    initializeVision: boolean;
+
+    /** Update the configuration of vision sources */
+    refreshVisionSources: boolean;
+
+    /** Refresh the rendered appearance of vision */
+    refreshVision: boolean;
+
+    /** Re-initialize the entire ambient sound configuration */
+    initializeSounds: boolean;
+
+    /** Refresh the audio state of ambient sounds */
+    refreshSounds: boolean;
+
+    /** Apply a fade duration to sound refresh workflow */
+    soundFadeDuration: boolean;
+
+    /** Refresh the visual appearance of tiles */
+    refreshTiles: boolean;
+
+    /** Refresh the contents of the PrimaryCanvasGroup mesh */
+    refreshPrimary: boolean;
+  }
+
+  /**
+   * A helper class which manages the refresh workflow for perception layers on the canvas.
+   * This controls the logic which batches multiple requested updates to minimize the amount of work required.
+   * A singleton instance is available as canvas#perception.
+   * @see Canvas#perception
+   */
+  class PerceptionManager extends RenderFlagsMixin(Object) {
+    static RENDER_FLAGS: {
+      /** @defaultValue `{ propagate: ["refreshLighting", "refreshVision"] }` */
+      initializeLighting: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{ propagate: ["refreshLightSources"] }` */
+      refreshLighting: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{}` */
+      refreshLightSources: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{}` */
+      refreshVisionSources: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{}` */
+      refreshPrimary: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{ propagate: ["refreshVision", "refreshTiles", "refreshLighting", "refreshLightSources", "refreshPrimary"] }` */
+      initializeVision: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{ propagate: ["refreshVisionSources"] }` */
+      refreshVision: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{ propagate: ["refreshSounds"] }` */
+      initializeSounds: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{}` */
+      refreshSounds: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{ propagate: ["refreshLightSources", "refreshVisionSources"] }` */
+      refreshTiles: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{}` */
+      soundFadeDuration: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{ propagate: ["initializeLighting", "initializeVision"] }` */
+      identifyInteriorWalls: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{ propagate: ["refreshVision"] }` */
+      forceUpdateFog: RenderFlag<PerceptionManagerFlags>;
+    };
+
+    static RENDER_FLAG_PRIORITY: "PERCEPTION";
+
+    applyRenderFlags(): void;
+
+    /**
+     * A shim mapping which supports backwards compatibility for old-style (V9 and before) perception manager flags.
+     */
+    static COMPATIBILITY_MAPPING: {
+      "lighting.initialize": "initializeLighting";
+      "lighting.refresh": "refreshLighting";
+      "sight.initialize": "initializeVision";
+      "sight.refresh": "refreshVision";
+      "sounds.initialize": "initializeSounds";
+      "sounds.refresh": "refreshSounds";
+      "sounds.fade": "soundFadeDuration";
+      "foreground.refresh": "refreshTiles";
+    };
+
+    /**
+     * Update perception manager flags which configure which behaviors occur on the next frame render.
+     * @param flags - Flag values (true) to assign where the keys belong to PerceptionManager.FLAGS
+     * @param v2    - Opt-in to passing v2 flags, otherwise a backwards compatibility shim will be applied
+     *                (default: `true`)
+     */
+    update(flags: Partial<PerceptionManagerFlags>, v2?: boolean): void;
+
+    /**
+     * A helper function to perform an immediate initialization plus incremental refresh.
+     */
+    initialize(): ReturnType<this["update"]>;
+
+    /**
+     * A helper function to perform an incremental refresh only.
+     */
+    refresh(): ReturnType<this["update"]>;
+
+    /**
+     * @deprecated since v10, will be removed in v12
+     * @remarks PerceptionManager#cancel is renamed to PerceptionManager#deactivate
+     * @remarks PerceptionManager#deactivate does not actually exist as of v11
+     */
+    cancel(): void;
+
+    /**
+     * @deprecated since v10, will be removed in v12
+     * @remarks PerceptionManager#schedule is replaced by PerceptionManager#update
+     */
+    schedule(options?: DeepPartial<PerceptionManager.Options>): void;
+
+    /**
+     * @deprecated since v11
+     * @remarks forceUpdateFog flag is now obsolete and has no replacement. The fog is now always updated when the visibility is refreshed
+     */
+    static forceUpdateFog(): void;
+  }
+
+  namespace PerceptionManager {
+    /** @deprecated Old flag structure */
+    interface Options {
+      lighting: {
+        initialize: boolean;
+        refresh: boolean;
+      };
+      sight: {
+        initialize: boolean;
+        refresh: boolean;
+        skipUpdateFog: boolean;
+        forceUpdateFog: boolean;
+      };
+      sounds: {
+        initialize: boolean;
+        refresh: boolean;
+        fade: boolean;
+      };
+      foreground: {
+        refresh: boolean;
+      };
+    }
+  }
+}

package/src/foundry/client/pixi/perception/vision-mode.d.mts

@@ -0,0 +1,197 @@
+import type { AnyObject, InexactPartial, SimpleMerge, ValueOf } from "../../../../types/utils.d.mts";
+import type { fields } from "../../../common/data/module.d.mts";
+
+declare global {
+  class ShaderField<
+    const Options extends ShaderField.Options = ShaderField.DefaultOptions,
+    const AssignmentType = ShaderField.AssignmentType<Options>,
+    const InitializedType = ShaderField.InitializedType<Options>,
+    const PersistedType extends typeof AbstractBaseShader | null | undefined = ShaderField.InitializedType<Options>,
+  > extends foundry.data.fields.DataField<Options, AssignmentType, InitializedType, PersistedType> {
+    /**
+     * @defaultValue
+     * ```typescript
+     * const defaults = super._defaults;
+     * defaults.nullable = true;
+     * defaults.initial = undefined;
+     * return defaults;
+     * ```
+     */
+    static override get _defaults(): ShaderField.DefaultOptions;
+
+    // TODO: _cast blatantly breaks inheritance so this is difficult to work with
+    /** @remarks The value provided to a ShaderField must be an AbstractBaseShader subclass. */
+    override _cast(value: any): Exclude<InitializedType, undefined | null>; // typeof AbstractBaseShader;
+  }
+
+  /**
+   * A Vision Mode which can be selected for use by a Token.
+   * The selected Vision Mode alters the appearance of various aspects of the canvas while that Token is the POV.
+   */
+  class VisionMode extends foundry.abstract.DataModel<VisionMode.Schema> {
+    /**
+     * Construct a Vision Mode using provided configuration parameters and callback functions.
+     * @param data    - Data which fulfills the model defined by the VisionMode schema.
+     * @param options - Additional options passed to the DataModel constructor.
+     */
+    constructor(data: InexactPartial<any>, options?: AnyObject);
+
+    static defineSchema(): VisionMode.Schema;
+
+    /** The lighting illumination levels which are supported. */
+    static LIGHTING_LEVELS: {
+      DARKNESS: -2;
+      HALFDARK: -1;
+      UNLIT: 0;
+      DIM: 1;
+      BRIGHT: 2;
+      BRIGHTEST: 3;
+    };
+
+    /**
+     * Flags for how each lighting channel should be rendered for the currently active vision modes:
+     * - Disabled: this lighting layer is not rendered, the shaders does not decide.
+     * - Enabled: this lighting layer is rendered normally, and the shaders can choose if they should be rendered or not.
+     * - Required: the lighting layer is rendered, the shaders does not decide.
+     */
+    static LIGHTING_VISIBILITY: {
+      DISABLED: 0;
+      ENABLED: 1;
+      REQUIRED: 2;
+    };
+
+    /**
+     * A flag for whether this vision source is animated
+     * @defaultValue `false`
+     */
+    animated: boolean;
+
+    /**
+     * Special activation handling that could be implemented by VisionMode subclasses
+     * @param source - Activate this VisionMode for a specific source
+     */
+    _activate(source: foundry.canvas.sources.PointVisionSource.Any): void;
+
+    /**
+     * Special deactivation handling that could be implemented by VisionMode subclasses
+     * @param source - Deactivate this VisionMode for a specific source
+     */
+    _deactivate(source: foundry.canvas.sources.PointVisionSource.Any): void;
+
+    /**
+     * Special handling which is needed when this Vision Mode is activated for a VisionSource.
+     * @param source - Activate this VisionMode for a specific source
+     */
+    activate(source: foundry.canvas.sources.PointVisionSource.Any): void;
+
+    /**
+     * Special handling which is needed when this Vision Mode is deactivated for a VisionSource.
+     * @param source - Deactivate this VisionMode for a specific source
+     */
+    deactivate(source: foundry.canvas.sources.PointVisionSource.Any): void;
+
+    /**
+     * An animation function which runs every frame while this Vision Mode is active.
+     * @param dt - The deltaTime passed by the PIXI Ticker
+     */
+    animate(dt: number): void;
+  }
+
+  namespace ShaderField {
+    type Options = DataFieldOptions<typeof AbstractBaseShader>;
+
+    type DefaultOptions = SimpleMerge<
+      foundry.data.fields.DataField.DefaultOptions,
+      {
+        nullable: true;
+        initial: undefined;
+      }
+    >;
+
+    /**
+     * A helper type for the given options type merged into the default options of the BooleanField class.
+     * @typeParam Opts - the options that override the default options
+     */
+    type MergedOptions<Opts extends Options> = SimpleMerge<DefaultOptions, Opts>;
+
+    /**
+     * A shorthand for the assignment type of a BooleanField class.
+     * @typeParam Opts - the options that override the default options
+     */
+    type AssignmentType<Opts extends Options> = foundry.data.fields.DataField.DerivedAssignmentType<
+      typeof AbstractBaseShader,
+      MergedOptions<Opts>
+    >;
+
+    /**
+     * A shorthand for the initialized type of a BooleanField class.
+     * @typeParam Opts - the options that override the default options
+     */
+    type InitializedType<Opts extends Options> = foundry.data.fields.DataField.DerivedInitializedType<
+      typeof AbstractBaseShader,
+      MergedOptions<Opts>
+    >;
+  }
+
+  namespace VisionMode {
+    type ShaderSchema = fields.SchemaField<{
+      shader: ShaderField;
+      uniforms: fields.ObjectField;
+    }>;
+
+    type LightingSchema = fields.SchemaField<{
+      visibility: fields.NumberField;
+      postProcessingModes: fields.ArrayField<fields.StringField>;
+      uniforms: fields.ObjectField;
+    }>;
+
+    type LightingLevels = Record<
+      ValueOf<typeof VisionMode.LIGHTING_LEVELS>,
+      ValueOf<typeof VisionMode.LIGHTING_LEVELS>
+    >;
+    type LightingMultipliers = Record<ValueOf<typeof VisionMode.LIGHTING_LEVELS>, number>;
+
+    interface Schema extends DataSchema {
+      id: fields.StringField<{ blank: false }>;
+      label: fields.StringField<{ blank: false }>;
+      tokenConfig: fields.BooleanField<{ initial: true }>;
+      canvas: fields.SchemaField<{
+        shader: ShaderField;
+        uniforms: fields.ObjectField;
+      }>;
+      lighting: fields.SchemaField<{
+        background: LightingSchema;
+        coloration: LightingSchema;
+        illumination: LightingSchema;
+        levels: fields.ObjectField<
+          {
+            validate: (o: unknown) => boolean;
+            validationError: "may only contain a mapping of keys from VisionMode.LIGHTING_LEVELS";
+          },
+          LightingLevels,
+          LightingLevels,
+          LightingLevels
+        >;
+        multipliers: fields.ObjectField<
+          {
+            validate: (o: unknown) => boolean;
+            validationError: "must provide a mapping of keys from VisionMode.LIGHTING_LEVELS to numeric multiplier values";
+          },
+          LightingMultipliers,
+          LightingMultipliers,
+          LightingMultipliers
+        >;
+      }>;
+      vision: fields.SchemaField<{
+        background: ShaderSchema;
+        coloration: ShaderSchema;
+        illumination: ShaderSchema;
+        darkness: fields.SchemaField<{
+          adaptive: fields.BooleanField<{ initial: true }>;
+        }>;
+        defaults: fields.ObjectField;
+        preferred: fields.BooleanField<{ initial: false }>;
+      }>;
+    }
+  }
+}

package/src/foundry/client/pixi/perception/weiler-atherton-clipping.d.mts

@@ -0,0 +1,152 @@
+import type { InexactPartial, ValueOf } from "../../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * 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/
+   */
+  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
+     *                        (default: `0`)
+     * @param clipOpts      - Object passed to the clippingObject methods toPolygon and pointsBetween
+     *                        (default: `{}`)
+     */
+    constructor(
+      polygon: PIXI.Polygon,
+      clipObject: PIXI.Rectangle | PIXI.Circle,
+      clipType?: ValueOf<(typeof WeilerAthertonClipper)["CLIP_TYPES"]>,
+      clipOpts?: WeilerAthertonClipper.ClipOpts,
+    );
+
+    /**
+     * The supported clip types.
+     * Values are equivalent to those in ClipperLib.ClipType.
+     */
+    static readonly CLIP_TYPES: Readonly<{
+      INTERSECT: 0;
+      UNION: 1;
+    }>;
+
+    /**
+     * The supported intersection types.
+     */
+    static readonly INTERSECTION_TYPES: Readonly<{
+      OUT_IN: -1;
+      IN_OUT: 1;
+      TANGENT: 0;
+    }>;
+
+    polygon: PIXI.Polygon;
+
+    clipObject: PIXI.Rectangle | PIXI.Circle;
+
+    /**
+     * Configuration settings
+     * @param clipType  - One of CLIP_TYPES
+     * @param clipOpts  - Object passed to the clippingObject methods
+     *                    toPolygon and pointsBetween
+     * @defaultValue `{}`
+     */
+    config: {
+      clipType?: typeof WeilerAthertonClipper.CLIP_TYPES;
+      clipOpts?: WeilerAthertonClipper.ClipOpts;
+    };
+
+    /**
+     * 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: WeilerAthertonClipper.ClipOpts,
+    ): 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: WeilerAthertonClipper.ClipOpts,
+    ): 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
+     * @returns Array of polygons and clipObjects
+     */
+    static combine(
+      polygon: PIXI.Polygon,
+      clipObject: PIXI.Rectangle | PIXI.Circle,
+      options?: InexactPartial<{
+        /**
+         * One of CLIP_TYPES
+         * @defaultValue `0`
+         */
+        clipType: ValueOf<typeof WeilerAthertonClipper.CLIP_TYPES>;
+
+        /**
+         * If the WeilerAtherton constructor could mutate or not the subject polygon points
+         */
+        canMutate: boolean;
+
+        /**
+         * Options passed to the WeilerAthertonClipper constructor
+         */
+        clipOpts: WeilerAthertonClipper.ClipOpts;
+      }>,
+    ): PIXI.Polygon[];
+
+    /**
+     * 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: typeof WeilerAthertonClipper.CLIP_TYPES,
+      clipOpts: WeilerAthertonClipper.ClipOpts,
+    ): PIXI.Polygon[];
+  }
+
+  namespace WeilerAthertonClipper {
+    type ClipOpts = PIXI.Circle.PointsForArcOptions;
+  }
+}