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

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

@@ -0,0 +1,212 @@
+import type { InexactPartial, ValueOf } from "../../../../types/utils.d.mts";
+import type { fields } from "../../../common/data/module.d.mts";
+import type { TokenDetectionMode } from "../../../common/documents/_types.d.mts";
+
+declare global {
+  namespace DetectionMode {
+    interface Schema extends DataSchema {
+      id: fields.StringField<{ blank: false }>;
+      label: fields.StringField<{ blank: false }>;
+      tokenConfig: fields.BooleanField<{ initial: true }>;
+      walls: fields.BooleanField<{ initial: true }>;
+      angle: fields.BooleanField<{ initial: true }>;
+      type: fields.NumberField<{
+        initial: typeof DetectionMode.DETECTION_TYPES.SIGHT;
+        choices: ValueOf<typeof DetectionMode.DETECTION_TYPES>[];
+      }>;
+    }
+  }
+
+  /**
+   * A Detection Mode which can be associated with any kind of sense/vision/perception.
+   * A token could have multiple detection modes.
+   */
+  class DetectionMode extends foundry.abstract.DataModel<DetectionMode.Schema> {
+    static override defineSchema(): DetectionMode.Schema;
+
+    /**
+     * Get the detection filter pertaining to this mode.
+     */
+    static getDetectionFilter(): PIXI.Filter | undefined;
+
+    /**
+     * An optional filter to apply on the target when it is detected with this mode.
+     */
+    static _detectionFilter: PIXI.Filter | undefined;
+
+    /**
+     * The type of the detection mode.
+     * @see CONST.WALL_RESTRICTION_TYPES
+     */
+    static DETECTION_TYPES: {
+      /** Sight, and anything depending on light perception */
+      SIGHT: 0;
+      /** What you can hear. Includes echolocation for bats per example */
+      SOUND: 1;
+      /** This is mostly a sense for touch and vibration, like tremorsense, movement detection, etc. */
+      MOVE: 2;
+      /** Can't fit in other types (smell, life sense, trans-dimensional sense, sense of humor...) */
+      OTHER: 3;
+    };
+
+    /**
+     * The identifier of the basic sight detection mode.
+     */
+    static BASIC_MODE_ID: "basicSight";
+
+    /**
+     * Test visibility of a target object or array of points for a specific vision source.
+     * @param visionSource  - The vision source being tested
+     * @param mode          - The detection mode configuration
+     * @param config        - The visibility test configuration
+     * @returns   Is the test target visible?
+     */
+    testVisibility(
+      visionSource: foundry.canvas.sources.PointVisionSource.Any,
+      mode: TokenDetectionMode,
+      { object, tests }: InexactPartial<CanvasVisibilityTestConfig>,
+    ): boolean;
+
+    /**
+     * Can this VisionSource theoretically detect a certain object based on its properties?
+     * This check should not consider the relative positions of either object, only their state.
+     * @param visionSource - The vision source being tested
+     * @param target       - The target object being tested
+     * @returns Can the target object theoretically be detected by this vision source?
+     */
+    protected _canDetect(visionSource: foundry.canvas.sources.PointVisionSource.Any, target: PlaceableObject): boolean;
+
+    /**
+     * Evaluate a single test point to confirm whether it is visible.
+     * Standard detection rules require that the test point be both within LOS and within range.
+     * @param visionSource - The vision source being tested
+     * @param mode         - The detection mode configuration
+     * @param target       - The target object being tested
+     * @param test         - The test case being evaluated
+     */
+    protected _testPoint(
+      visionSource: foundry.canvas.sources.PointVisionSource.Any,
+      mode: TokenDetectionMode,
+      target: PlaceableObject,
+      test: CanvasVisibilityTest,
+    ): boolean;
+
+    /**
+     * Test whether the line-of-sight requirement for detection is satisfied.
+     * Always true if the detection mode bypasses walls, otherwise the test point must be contained by the LOS polygon.
+     * The result of is cached for the vision source so that later checks for other detection modes do not repeat it.
+     * @param visionSource    - The vision source being tested
+     * @param mode            - The detection mode configuration
+     * @param target          - The target object being tested
+     * @param test            - The test case being evaluated
+     * @returns Is the LOS requirement satisfied for this test?
+     */
+    protected _testLOS(
+      visionSource: foundry.canvas.sources.PointVisionSource.Any,
+      mode: TokenDetectionMode,
+      target: PlaceableObject,
+      test: CanvasVisibilityTest,
+    ): boolean;
+
+    /**
+     * Test whether the target is within the vision angle.
+     * @param visionSource    - The vision source being tested
+     * @param mode            - The detection mode configuration
+     * @param target          - The target object being tested
+     * @param test            - The test case being evaluated
+     * @returns Is the point within the vision angle?
+     */
+    protected _testAngle(
+      visionSource: foundry.canvas.sources.PointVisionSource.Any,
+      mode: TokenDetectionMode,
+      target: PlaceableObject,
+      test: CanvasVisibilityTest,
+    ): boolean;
+
+    /**
+     * Verify that a target is in range of a source.
+     * @param visionSource    - The vision source being tested
+     * @param mode            - The detection mode configuration
+     * @param target          - The target object being tested
+     * @param test            - The test case being evaluated
+     * @returns Is the target within range?
+     */
+    protected _testRange(
+      visionSource: foundry.canvas.sources.PointVisionSource.Any,
+      mode: TokenDetectionMode,
+      target: PlaceableObject,
+      test: CanvasVisibilityTest,
+    ): boolean;
+  }
+
+  /**
+   * This detection mode tests whether the target is visible due to being illuminated by a light source.
+   * By default tokens have light perception with an infinite range if light perception isn't explicitely
+   * configured.
+   */
+  class DetectionModeLightPerception extends DetectionMode {
+    protected override _canDetect(
+      visionSource: foundry.canvas.sources.PointVisionSource.Any,
+      target: PlaceableObject,
+    ): boolean;
+
+    protected override _testPoint(
+      visionSource: foundry.canvas.sources.PointVisionSource.Any,
+      mode: TokenDetectionMode,
+      target: PlaceableObject,
+      test: CanvasVisibilityTest,
+    ): boolean;
+  }
+
+  /**
+   * A special detection mode which models a form of darkvision (night vision).
+   * This mode is the default case which is tested first when evaluating visibility of objects.
+   * It is also a special case, in that it is the only detection mode which considers the area of distant light sources.
+   */
+  class DetectionModeBasicSight extends DetectionMode {
+    protected override _canDetect(
+      visionSource: foundry.canvas.sources.PointVisionSource.Any,
+      target: PlaceableObject,
+    ): boolean;
+  }
+
+  /**
+   * Detection mode that see invisible creatures.
+   * This detection mode allows the source to:
+   * - See/Detect the invisible target as if visible.
+   * - The "See" version needs sight and is affected by blindness
+   */
+  class DetectionModeInvisibility extends DetectionMode {
+    static override getDetectionFilter(): PIXI.Filter | undefined;
+
+    protected override _canDetect(
+      visionSource: foundry.canvas.sources.PointVisionSource.Any,
+      target: PlaceableObject,
+    ): boolean;
+  }
+
+  /**
+   * Detection mode that see creatures in contact with the ground.
+   */
+  class DetectionModeTremor extends DetectionMode {
+    static override getDetectionFilter(): PIXI.Filter | undefined;
+
+    protected override _canDetect(
+      visionSource: foundry.canvas.sources.PointVisionSource.Any,
+      target: PlaceableObject,
+    ): boolean;
+  }
+
+  /**
+   * Detection mode that see ALL creatures (no blockers).
+   * If not constrained by walls, see everything within the range.
+   */
+  class DetectionModeAll extends DetectionMode {
+    static override getDetectionFilter(): PIXI.Filter | undefined;
+
+    protected override _canDetect(
+      visionSource: foundry.canvas.sources.PointVisionSource.Any,
+      target: PlaceableObject,
+    ): boolean;
+  }
+}

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

@@ -0,0 +1,130 @@
+import type { DisplayObject } from "pixi.js";
+
+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;
+
+    /**
+     * Track whether we have pending fog updates which have not yet been saved to the database
+     * @defaultValue `false`
+     */
+    _updated: boolean;
+
+    /**
+     * Texture extractor
+     */
+    get extractor(): TextureExtractor;
+
+    /**
+     * 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(): VisibilityTextureConfiguration;
+
+    /**
+     * 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;
+
+    /**
+     * Create the exploration display object with or without a provided texture.
+     */
+    protected _createExplorationObject(tex?: PIXI.Texture | PIXI.RenderTexture): DisplayObject;
+
+    /**
+     * 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>;
+
+    /**
+     * Extract fog data as a base64 string
+     */
+    protected _extractBase64(): Promise<string>;
+
+    /**
+     * Prepare the data that will be used to update the FogExploration document.
+     * @param base64Image - The extracted base64 image data
+     * @returns Exploration data to update
+     */
+    protected _prepareFogUpdateData(base64Image: string): foundry.documents.BaseFogExploration.UpdateData;
+
+    /**
+     * 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,6 @@
+import "./clockwise-sweep.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,167 @@
+export {}
+
+declare global {
+  interface PerceptionManagerFlags {
+    /**
+     * Re-initialize the entire lighting configuration. An aggregate behavior
+     * which does no work directly but propagates to set several other flags.
+     */
+    initializeLighting: boolean;
+
+    /** Re-initialize the entire vision configuration. See {@link CanvasVisibility#initializeSources}. */
+    initializeVision: boolean;
+
+    /** Re-initialize the entire vision modes. See {@link CanvasVisibility#initializeVisionMode}. */
+    initializeVisionModes: boolean;
+
+    /** Re-initialize the entire ambient sound configuration. See {@link SoundsLayer#initializeSources}. */
+    initializeSounds: boolean;
+
+    /** Recompute intersections between all registered edges. See {@link CanvasEdges#refresh}. */
+    refreshEdges: boolean;
+
+    /** Refresh the rendered appearance of lighting */
+    refreshLighting: boolean;
+
+    /** Update the configuration of light sources */
+    refreshLightSources: boolean;
+
+    /** Refresh occlusion */
+    refreshOcclusion: boolean;
+
+    /** Refresh the contents of the PrimaryCanvasGroup mesh */
+    refreshPrimary: boolean;
+
+    /** Refresh the audio state of ambient sounds */
+    refreshSounds: boolean;
+
+    /** Refresh the rendered appearance of vision */
+    refreshVision: boolean;
+
+    /** Update the configuration of vision sources */
+    refreshVisionSources: boolean;
+
+    /** Apply a fade duration to sound refresh workflow */
+    soundFadeDuration: 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 {@link Canvas#perception}.
+   */
+  class PerceptionManager extends RenderFlagsMixin(Object) {
+    static RENDER_FLAGS: {
+      /** @defaultValue `{}` */
+      refreshEdges: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{propagate: ["refreshLighting", "refreshVision"]}` */
+      initializeLighting: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{propagate: ["refreshLighting", "refreshVision", "refreshEdges"]}` */
+      initializeDarknessSources: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{propagate: ["refreshLighting", "refreshVision"]}` */
+      initializeLightSources: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{propagate: ["refreshLightSources"]}` */
+      refreshLighting: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{}` */
+      refreshLightSources: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{propagate: ["refreshVisionSources", "refreshLighting", "refreshPrimary"]}` */
+      initializeVisionModes: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{propagate: ["refreshVision", "refreshTiles", "refreshLighting", "refreshLightSources", "refreshPrimary"]}` */
+      initializeVision: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{propagate: ["refreshVisionSources", "refreshOcclusionMask"]}` */
+      refreshVision: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{}` */
+      refreshVisionSources: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{}` */
+      refreshPrimary: RenderFlag<PerceptionManagerFlags>;
+
+      /** `{propagate: ["refreshOcclusionStates", "refreshOcclusionMask"]}` */
+      refreshOcclusion: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{}` */
+      refreshOcclusionStates: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{}` */
+      refreshOcclusionMask: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{ propagate: ["refreshSounds"] }` */
+      initializeSounds: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{}` */
+      refreshSounds: RenderFlag<PerceptionManagerFlags>;
+
+      /** @defaultValue `{}` */
+      soundFadeDuration: RenderFlag<PerceptionManagerFlags>;
+
+      /** @deprecated since v12, will be removed in v14 */
+      refreshTiles: RenderFlag<PerceptionManagerFlags>;
+
+      /** @deprecated since v12, will be removed in v14 */
+      identifyInteriorWalls: RenderFlag<PerceptionManagerFlags>;
+
+      /** @deprecated since v12, will be removed in v14 */
+      forceUpdateFog: RenderFlag<PerceptionManagerFlags>;
+    };
+
+    static RENDER_FLAG_PRIORITY: "PERCEPTION";
+
+    applyRenderFlags(): void;
+
+    /**
+     * 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
+     */
+    update(flags: Partial<PerceptionManagerFlags>): void;
+
+    /**
+     * A helper function to perform an immediate initialization plus incremental refresh.
+     */
+    initialize(): ReturnType<this["update"]>;
+
+    /**
+     * @deprecated since v12, will be removed in v14
+     * @remarks `"PerceptionManager#refresh is deprecated in favor of assigning granular "refresh flags"`
+     */
+    refresh(): ReturnType<this["update"]>;
+
+    /**
+     * @deprecated since v11, will be removed in v13
+     * @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;
+      };
+    }
+  }
+}