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

package/src/foundry/client/pixi/layers/effects/illumination-effects.d.mts

@@ -0,0 +1,151 @@
+import type { NullishProps } from "../../../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * A CanvasLayer for displaying illumination visual effects
+   */
+  class CanvasIlluminationEffects<
+    DrawOptions extends CanvasIlluminationEffects.DrawOptions = CanvasIlluminationEffects.DrawOptions,
+    TearDownOptions extends CanvasIlluminationEffects.TearDownOptions = CanvasIlluminationEffects.TearDownOptions,
+  > extends CanvasLayer<DrawOptions, TearDownOptions> {
+    /**
+     * The filter used to mask visual effects on this layer
+     */
+    filter: VisualEffectsMaskingFilter | undefined;
+
+    /**
+     * The container holding the lights.
+     */
+    lights: PIXI.Container;
+
+    /**
+     * A minimalist texture that holds the background color.
+     */
+    backgroundColorTexture: PIXI.Texture;
+
+    /**
+     * The base line mesh.
+     */
+    baselineMesh: SpriteMesh;
+
+    /**
+     * The cached container holding the illumination meshes.
+     */
+    darknessLevelMeshes: DarknessLevelContainer;
+
+    /**
+     * To know if dynamic darkness level is active on this scene.
+     */
+    get hasDynamicDarknessLevel(): boolean;
+
+    /**
+     * The illumination render texture.
+     */
+    get renderTexture(): PIXI.RenderTexture;
+
+    /**
+     * Set or retrieve the illumination background color.
+     */
+    set backgroundColor(color: number);
+
+    /**
+     * Clear illumination effects container
+     */
+    clear(): void;
+
+    /**
+     * Invalidate the cached container state to trigger a render pass.
+     * @param force - Force cached container invalidation?
+     *                (default: `false`)
+     */
+    invalidateDarknessLevelContainer(force: boolean): void;
+
+    /**
+     * Create the background color texture used by illumination point source meshes.
+     * 1x1 single pixel texture.
+     * @returns The background color texture.
+     * @defaultValue
+     * ```js
+     * PIXI.Texture.fromBuffer(new Float32Array(3), 1, 1, {
+     *      type: PIXI.TYPES.FLOAT,
+     *      format: PIXI.FORMATS.RGB,
+     *      wrapMode: PIXI.WRAP_MODES.CLAMP,
+     *      scaleMode: PIXI.SCALE_MODES.NEAREST,
+     *      mipmap: PIXI.MIPMAP_MODES.OFF
+     * })
+     * ```
+     */
+    protected _createBackgroundColorTexture(): PIXI.Texture;
+
+    override render(renderer: PIXI.Renderer): void;
+
+    protected override _draw(options?: DrawOptions): Promise<void>;
+
+    protected override _tearDown(options?: TearDownOptions): Promise<void>;
+
+    /**
+     * @deprecated since v11, will be removed in v13
+     * @remarks "CanvasIlluminationEffects#updateGlobalLight has been deprecated."
+     */
+    updateGlobalLight(): false;
+
+    /**
+     * @deprecated since v12, will be removed in v14
+     */
+    background: null;
+
+    /**
+     * @deprecated since v12, will be removed in v14
+     * @remarks `"CanvasIlluminationEffects#globalLight has been deprecated without replacement. Check the canvas.environment.globalLightSource.active instead."`
+     */
+    get globalLight(): boolean;
+  }
+
+  namespace CanvasIlluminationEffects {
+    type AnyConstructor = typeof AnyCanvasIlluminationEffects;
+
+    interface DrawOptions extends CanvasLayer.DrawOptions {}
+
+    interface TearDownOptions extends CanvasLayer.TearDownOptions {}
+  }
+
+  /**
+   * Cached container used for dynamic darkness level. Display objects (of any type) added to this cached container will
+   * contribute to computing the darkness level of the masked area. Only the red channel is utilized, which corresponds
+   * to the desired darkness level. Other channels are ignored.
+   */
+  class DarknessLevelContainer extends CachedContainer {
+    /**
+     * @defaultValue
+     * ```js
+     * {
+     *  scaleMode: PIXI.SCALE_MODES.NEAREST,
+     *  format: PIXI.FORMATS.RED,
+     *  multisample: PIXI.MSAA_QUALITY.NONE,
+     *  mipmap: PIXI.MIPMAP_MODES.OFF
+     * }
+     * ```
+     */
+    static override textureConfiguration: NullishProps<{
+      multisample: PIXI.MSAA_QUALITY;
+      scaleMode: PIXI.SCALE_MODES;
+      format: PIXI.FORMATS;
+      mipmap: PIXI.MIPMAP_MODES;
+    }>;
+
+    /** @privateRemarks Including to protect duck typing due to overall similarities b/w DarknessLevelContainer and CachedContainer */
+    #onChildChange(): void;
+  }
+
+  namespace DarknessLevelContainer {
+    type AnyConstructor = typeof AnyCanvasIlluminationEffects;
+  }
+}
+
+declare abstract class AnyCanvasIlluminationEffects extends CanvasIlluminationEffects {
+  constructor(arg0: never, ...args: never[]);
+}
+
+declare abstract class AnyDarknessLevelContainer extends DarknessLevelContainer {
+  constructor(arg0: never, ...args: never[]);
+}

package/src/foundry/client/pixi/layers/effects/index.d.mts

@@ -0,0 +1,7 @@
+import "./background-effects.d.mts";
+import "./coloration-effects.d.mts";
+import "./darkness-effects.d.mts";
+import "./illumination-effects.d.mts";
+import "./visibility.d.mts";
+import "./weather-effects.d.mts";
+import "./weather/particles/index.d.mts";

package/src/foundry/client/pixi/layers/effects/visibility.d.mts

@@ -0,0 +1,225 @@
+import type { EmptyObject, InexactPartial, ValueOf } from "../../../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * The visibility Layer which implements dynamic vision, lighting, and fog of war
+   * This layer uses an event-driven workflow to perform the minimal required calculation in response to changes.
+   * @see {@link PointSource}
+   */
+  class CanvasVisibility<
+    DrawOptions extends CanvasVisibility.DrawOptions = CanvasVisibility.DrawOptions,
+    TearDownOptions extends CanvasVisibility.TearDownOptions = CanvasVisibility.TearDownOptions,
+  > extends CanvasLayer<DrawOptions, TearDownOptions> {
+    /**
+     * The currently revealed vision.
+     */
+    vision: CanvasVisionMask.CanvasVisionContainer | undefined;
+
+    /**
+     * The exploration container which tracks exploration progress.
+     */
+    explored: PIXI.Container | undefined;
+
+    /**
+     * The optional visibility overlay sprite that should be drawn instead of the unexplored color in the fog of war.
+     */
+    visibilityOverlay: PIXI.Sprite | undefined;
+
+    /**
+     * The active vision source data object
+     * @defaultValue
+     * ```js
+     * {
+     *    source: undefined,
+     *    activeLightingOptions: {}
+     * }
+     * ```
+     */
+    visionModeData: {
+      source: foundry.canvas.sources.PointVisionSource.Any | null | undefined;
+      activeLightingOptions: VisionMode["_source"]["lighting"] | EmptyObject;
+    };
+
+    /**
+     * Define whether each lighting layer is enabled, required, or disabled by this vision mode.
+     * The value for each lighting channel is a number in LIGHTING_VISIBILITY
+     * ```js
+     * {
+     *   background: VisionMode.LIGHTING_VISIBILITY.ENABLED,
+     *    illumination: VisionMode.LIGHTING_VISIBILITY.ENABLED,
+     *    coloration: VisionMode.LIGHTING_VISIBILITY.ENABLED,
+     *    darkness: VisionMode.LIGHTING_VISIBILITY.ENABLED,
+     *    any: true
+     * }
+     * ```
+     */
+    lightingVisibility: {
+      illumination: CanvasVisibility.LightingVisibility;
+      background: CanvasVisibility.LightingVisibility;
+      coloration: CanvasVisibility.LightingVisibility;
+      darkness: CanvasVisibility.LightingVisibility;
+      any: boolean;
+    };
+
+    /**
+     * A status flag for whether the layer initialization workflow has succeeded.
+     */
+    get initialized(): boolean;
+
+    /**
+     * Indicates whether containment filtering is required when rendering vision into a texture
+     */
+    protected get needsContainment(): boolean;
+
+    /**
+     * Does the currently viewed Scene support Token field of vision?
+     */
+    get tokenVision(): Scene.ConfiguredInstance["tokenVision"];
+
+    /**
+     * The configured options used for the saved fog-of-war texture.
+     */
+    get textureConfiguration(): VisibilityTextureConfiguration | undefined;
+
+    /**
+     * Optional overrides for exploration sprite dimensions.
+     *
+     * @privateRemarks Foundry types this parameter as `FogTextureConfiguration`, and
+     * unlike the other place they used this type seeming in error, only `rect`'s
+     * `x, y, width, height` properties are accessed, so I'm assuming they meant Rectangle
+     */
+    set explorationRect(rect: Canvas.Rectangle);
+
+    /**
+     * Initialize all Token vision sources which are present on this layer
+     */
+    initializeSources(): void;
+
+    /**
+     * Initialize the vision mode.
+     */
+    initializeVisionMode(): void;
+
+    protected override _draw(options?: DrawOptions): Promise<void>;
+
+    protected override _tearDown(options?: TearDownOptions): Promise<void>;
+
+    /**
+     * Update the display of the sight layer.
+     * Organize sources into rendering queues and draw lighting containers for each source
+     */
+    refresh(): void;
+
+    /**
+     * Update vision (and fog if necessary)
+     */
+    refreshVisibility(): void;
+
+    /**
+     * Reset the exploration container with the fog sprite
+     */
+    resetExploration(): void;
+
+    /**
+     * Restrict the visibility of certain canvas assets (like Tokens or DoorControls) based on the visibility polygon
+     * These assets should only be displayed if they are visible given the current player's field of view
+     */
+    restrictVisibility(): void;
+
+    /**
+     * Test whether a target 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 options - Additional options which modify visibility testing.
+     * @returns Whether the point is currently visible.
+     */
+    testVisibility(
+      point: Canvas.Point,
+      /**
+       * @remarks Can't be NullishProps because `tolerance` gets passed directly to `_createVisibilityTestConfig`,
+       * where a default is provided only for `undefined` with `{ tolerance=2 }`, which must be numeric
+       * */
+      options?: InexactPartial<{
+        /**
+         * 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.
+         */
+        tolerance: number;
+
+        /**
+         * An optional reference to the object whose visibility is being tested
+         */
+        object: PlaceableObject | null;
+      }>,
+    ): boolean;
+
+    /**
+     * Create the visibility test config.
+     * @param point   - The point in space to test, an object with coordinates x and y.
+     * @param options - Additional options which modify visibility testing.
+     */
+    _createVisibilityTestConfig(
+      point: Canvas.Point,
+      /** @remarks Can't be NullishProps because a default for `tolerance` is provided only for `undefined` with `{ tolerance=2 }`, which must be numeric */
+      options?: InexactPartial<{
+        /**
+         * 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
+         */
+        object: PlaceableObject | null;
+      }>,
+    ): CanvasVisibilityTestConfig;
+
+    /**
+     * @deprecated since v11, will be removed in v13
+     * @remarks `"fogOverlay is deprecated in favor of visibilityOverlay"`
+     */
+    get fogOverlay(): this["visibilityOverlay"];
+  }
+
+  namespace CanvasVisibility {
+    type AnyConstructor = typeof AnyCanvasVisibility;
+
+    type LightingVisibility = ValueOf<typeof VisionMode.LIGHTING_VISIBILITY>;
+
+    interface DrawOptions extends CanvasLayer.DrawOptions {}
+
+    interface TearDownOptions extends CanvasLayer.TearDownOptions {}
+  }
+
+  /**
+   * @privateRemarks This is name foundry has for the return tyoe of `CanvasVisibility#configureVisibilityTexture`
+   * The FogTextureConfiguration references seem to be in error
+   */
+  interface VisibilityTextureConfiguration {
+    resolution: number;
+    width: number;
+    height: number;
+    mipmap: PIXI.MIPMAP_MODES;
+    multisample: PIXI.MSAA_QUALITY;
+    scaleMode: PIXI.SCALE_MODES;
+    alphaMode: PIXI.ALPHA_MODES;
+    format: PIXI.FORMATS;
+  }
+
+  interface CanvasVisibilityTest {
+    point: PIXI.Point;
+    los: Map<foundry.canvas.sources.PointVisionSource.Any, boolean>;
+  }
+
+  interface CanvasVisibilityTestConfig {
+    object: PlaceableObject | null;
+    tests: CanvasVisibilityTest[];
+  }
+}
+
+declare abstract class AnyCanvasVisibility extends CanvasVisibility {
+  constructor(arg0: never, ...args: never[]);
+}

package/src/foundry/client/pixi/layers/effects/weather/particles/effect.d.mts

@@ -0,0 +1,47 @@
+export {};
+
+declare global {
+  /**
+   * An interface for defining particle-based weather effects
+   */
+  class ParticleEffect extends FullCanvasObjectMixin(PIXI.Container) {
+    /**
+     * @param options - Options passed to the getParticleEmitters method which can be used to customize values of the emitter configuration.
+     *                  (default: `{}`)
+     */
+    constructor(options: PIXI.particles.EmitterConfigV3);
+
+    parent: PIXI.Container;
+
+    emitters: PIXI.particles.Emitter[];
+
+    /**
+     * Create an emitter instance which automatically updates using the shared PIXI.Ticker
+     * @param config - The emitter configuration
+     * @returns The created Emitter instance
+     */
+    createEmitter(config: PIXI.particles.EmitterConfigV3): PIXI.particles.Emitter;
+
+    /**
+     * Get the particle emitters which should be active for this particle effect.
+     * This base class creates a single emitter using the explicitly provided configuration.
+     * Subclasses can override this method for more advanced configurations.
+     * @param options - Options provided to the ParticleEffect constructor which can be used to customize
+     *                  configuration values for created emitters. (default: `{}`)
+     * @throws An error if `foundry.utils.isEmpty(options)`
+     */
+    getParticleEmitters(options: PIXI.particles.EmitterConfigV3): PIXI.particles.Emitter[];
+
+    override destroy(options?: PIXI.DisplayObject.DestroyOptions): void;
+
+    /**
+     * Begin animation for the configured emitters.
+     */
+    play(): void;
+
+    /**
+     * Stop animation for the configured emitters.
+     */
+    stop(): void;
+  }
+}

package/src/foundry/client/pixi/layers/effects/weather/particles/index.d.mts

@@ -0,0 +1,2 @@
+import "./effect.d.mts";
+import "./leaves.d.mts";

package/src/foundry/client/pixi/layers/effects/weather/particles/leaves.d.mts

@@ -0,0 +1,20 @@
+export {};
+
+declare global {
+  /**
+   * A full-screen weather effect which renders gently falling autumn leaves.
+   */
+  class AutumnLeavesWeatherEffect extends ParticleEffect {
+    /**
+     * @defaultValue `"WEATHER.AutumnLeaves"`
+     */
+    static label: string;
+
+    /**
+     * Configuration for the particle emitter for falling leaves
+     */
+    static LEAF_CONFIG: PIXI.particles.EmitterConfigV3;
+
+    override getParticleEmitters(): PIXI.particles.Emitter[];
+  }
+}

package/src/foundry/client/pixi/layers/effects/weather-effects.d.mts

@@ -0,0 +1,227 @@
+import type { InexactPartial } from "../../../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * A CanvasLayer for displaying visual effects like weather, transitions, flashes, or more
+   */
+  class WeatherEffects<
+    DrawOptions extends WeatherEffects.DrawOptions = WeatherEffects.DrawOptions,
+    TearDownOptions extends WeatherEffects.TearDownOptions = WeatherEffects.TearDownOptions,
+  > extends FullCanvasObjectMixin(CanvasLayer) {
+    /**
+     * @privateRemarks This is not overridden in foundry but reflects the real behavior.
+     */
+    static get instance(): Canvas["effects"];
+
+    /**
+     * @defaultValue `true`
+     */
+    override sortableChildren: boolean;
+
+    /**
+     * @defaultValue `"none"`
+     */
+    override eventMode: PIXI.EventMode;
+
+    /**
+     * The container in which effects are added.
+     * @defaultValue `undefined`
+     */
+    weatherEffects: PIXI.Container | undefined;
+
+    /**
+     * The container in which suppression meshed are added.
+     * @defaultValue `undefined`
+     */
+    suppression: PIXI.Container | undefined;
+
+    /**
+     * @defaultValue `foundry.utils.mergeObject(super.layerOptions, { name: "effects" })`
+     */
+    static override get layerOptions(): WeatherEffects.LayerOptions;
+
+    override options: WeatherEffects.LayerOptions;
+
+    /**
+     * Array of weather effects linked to this weather container.
+     */
+    effects: Map<string, Array<ParticleEffect | WeatherShaderEffect>>;
+
+    /**
+     * A default configuration of the terrain mask that is automatically applied to any shader-based weather effects.
+     * This configuration is automatically passed to WeatherShaderEffect#configureTerrainMask upon construction.
+     *
+     * @privateRemarks This property is checked and conditionally passed in two places in this file,
+     * but never set as far as I can tell. It is not initialized to a value.
+     */
+    terrainMaskConfig: WeatherEffects.WeatherTerrainMaskConfiguration | undefined;
+
+    /**
+     * A default configuration of the terrain mask that is automatically applied to any shader-based weather effects.
+     * This configuration is automatically passed to WeatherShaderEffect#configureTerrainMask upon construction.
+     *
+     * @privateRemarks This property is passed to `WeatherEffects.configureOcclusionMask` in two places, but both times
+     * as `this.occlusionMaskConfig || {enabled: true}`, and it is never set as far as I can tell.
+     */
+    occlusionMaskConfig: WeatherEffects.WeatherOcclusionMaskConfiguration | undefined;
+
+    /**
+     * The inverse occlusion mask filter bound to this container.
+     */
+    occlusionFilter: WeatherOcclusionMaskFilter;
+
+    /**
+     * The elevation of this object.
+     * @throws The setter throws an error if passed NaN
+     */
+    get elevation(): number;
+
+    set elevation(value: number);
+
+    /**
+     * A key which resolves ties amongst objects at the same elevation of different layers.
+     * @defaultValue `PrimaryCanvasGroup.SORT_LAYERS.WEATHER`
+     * @throws The setter throws an error if passed NaN
+     */
+    get sortLayer(): number;
+
+    set sortLayer(value);
+
+    /**
+     * A key which resolves ties amongst objects at the same elevation within the same layer.
+     * @defaultValue `0`
+     * @throws The setter throws an error if passed NaN
+     */
+    get sort(): number;
+
+    set sort(value: number);
+
+    /**
+     * A key which resolves ties amongst objects at the same elevation within the same layer and same sort.
+     * @throws The setter throws an error if passed NaN
+     */
+    get zIndex(): number;
+
+    set zIndex(value: number);
+
+    protected override _draw(options?: DrawOptions): Promise<void>;
+
+    protected override _tearDown(options?: TearDownOptions): Promise<void>;
+
+    /**
+     * Initialize the weather container from a weather config object.
+     * @param weatherEffectsConfig - Weather config object (or null/undefined to clear the container).
+     *
+     * @privateRemarks Foundry has this typed as just `object`, but explicitly calls it with null and implicitly with undefined
+     */
+    initializeEffects(weatherEffectsConfig?: WeatherEffects.WeatherEffectsConfig | null | undefined): void;
+
+    /**
+     * Clear the weather container.
+     */
+    clearEffects(): void;
+
+    /**
+     * Set the occlusion uniforms for this weather shader.
+     * @param context - The shader context
+     * @param config  - Occlusion masking options
+     */
+    protected static configureOcclusionMask(
+      context: PIXI.Shader,
+      /** @remarks Can't be NullishProps because `texture` is only checked for `!== undefined` */
+      config?: InexactPartial<WeatherEffects.WeatherOcclusionMaskConfiguration>,
+    ): void;
+
+    /**
+     * Set the terrain uniforms for this weather shader.
+     * @param context - The shader context
+     * @param config  - Terrain masking options
+     */
+    protected static configureTerrainMask(
+      context: PIXI.Shader,
+      /** @remarks Can't be NullishProps because `texture` is only checked for `!== undefined` */
+      config?: InexactPartial<WeatherEffects.WeatherTerrainMaskConfiguration>,
+    ): void;
+
+    /**
+     * @deprecated since v11, will be removed in v13
+     * @remarks `"The WeatherContainer at canvas.weather.weather is deprecated and combined with the layer itself."`
+     */
+    get weather(): this;
+  }
+
+  namespace WeatherEffects {
+    type AnyConstructor = typeof AnyWeatherEffects;
+
+    interface LayerOptions extends CanvasLayer.LayerOptions {
+      name: "effects";
+    }
+
+    interface DrawOptions extends CanvasLayer.DrawOptions {}
+
+    interface TearDownOptions extends CanvasLayer.TearDownOptions {}
+
+    interface WeatherTerrainMaskConfiguration {
+      /**
+       * Enable or disable this mask.
+       * @defaultValue `false`
+       */
+      enabled: boolean;
+
+      /**
+       * An RGBA array of channel weights applied to the mask texture.
+       * @defaultValue `[1, 0, 0, 0]`
+       */
+      channelWeights: [r: number, b: number, g: number, a: number];
+
+      /**
+       * If the mask should be reversed.
+       * @defaultValue `false`
+       */
+      reverse?: boolean | undefined;
+
+      /**
+       * A texture which defines the mask region.
+       */
+      texture: PIXI.Texture | PIXI.RenderTexture;
+    }
+
+    interface WeatherOcclusionMaskConfiguration {
+      /**
+       * Enable or disable this mask.
+       * @defaultValue `false`
+       */
+      enabled: boolean;
+
+      /**
+       * An RGBA array of channel weights applied to the mask texture.
+       * @defaultValue `[0, 0, 1, 0]`
+       */
+      channelWeights: [r: number, b: number, g: number, a: number];
+
+      /**
+       * If the mask should be reversed.
+       * @defaultValue `false`
+       */
+      reverse: boolean;
+
+      /**
+       * A texture which defines the mask region.
+       */
+      texture: PIXI.Texture | PIXI.RenderTexture;
+    }
+
+    /**
+     * @privateRemarks types inferred from usage
+     */
+    interface WeatherEffectsConfig {
+      effects: WeatherEffects[];
+
+      filter: PIXI.Filter;
+    }
+  }
+}
+
+declare abstract class AnyWeatherEffects extends WeatherEffects {
+  constructor(arg0: never, ...args: never[]);
+}