@league-of-foundry-developers/foundry-vtt-types 12.331.3-beta → 12.331.5

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

@@ -1,17 +1,15 @@
-import type { NullishProps } from "../../../../../types/utils.d.mts";
+import type { HandleEmptyObject, Identity } from "#utils";
 
 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> {
+  class CanvasIlluminationEffects extends CanvasLayer {
     /**
      * The filter used to mask visual effects on this layer
+     * @remarks Only `undefined` prior to first draw
      */
-    filter: VisualEffectsMaskingFilter | undefined;
+    filter: VisualEffectsMaskingFilter.ConfiguredInstance | undefined;
 
     /**
      * The container holding the lights.
@@ -45,8 +43,12 @@ declare global {
 
     /**
      * Set or retrieve the illumination background color.
+     * @remarks Foundry types this as `number` but it gets passed to {@link Color.from}
      */
-    set backgroundColor(color: number);
+    set backgroundColor(color: Color.Source);
+
+    /** @remarks This getter doesn't actually exist, it's only here to correct the type inferred from the setter */
+    get backgroundColor(): undefined;
 
     /**
      * Clear illumination effects container
@@ -58,7 +60,7 @@ declare global {
      * @param force - Force cached container invalidation?
      *                (default: `false`)
      */
-    invalidateDarknessLevelContainer(force: boolean): void;
+    invalidateDarknessLevelContainer(force?: boolean | null): void;
 
     /**
      * Create the background color texture used by illumination point source meshes.
@@ -79,9 +81,9 @@ declare global {
 
     override render(renderer: PIXI.Renderer): void;
 
-    protected override _draw(options?: DrawOptions): Promise<void>;
+    protected override _draw(options: HandleEmptyObject<CanvasIlluminationEffects.DrawOptions>): Promise<void>;
 
-    protected override _tearDown(options?: TearDownOptions): Promise<void>;
+    protected override _tearDown(options: HandleEmptyObject<CanvasIlluminationEffects.TearDownOptions>): Promise<void>;
 
     /**
      * @deprecated since v11, will be removed in v13
@@ -91,18 +93,20 @@ declare global {
 
     /**
      * @deprecated since v12, will be removed in v14
+     * @remarks "CanvasIlluminationEffects#background is now obsolete."
      */
-    background: null;
+    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."`
+     * @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 Any extends AnyCanvasIlluminationEffects {}
+    interface AnyConstructor extends Identity<typeof AnyCanvasIlluminationEffects> {}
 
     interface DrawOptions extends CanvasLayer.DrawOptions {}
 
@@ -126,26 +130,22 @@ declare global {
      * }
      * ```
      */
-    static override textureConfiguration: NullishProps<{
-      multisample: PIXI.MSAA_QUALITY;
-      scaleMode: PIXI.SCALE_MODES;
-      format: PIXI.FORMATS;
-      mipmap: PIXI.MIPMAP_MODES;
-    }>;
+    static override textureConfiguration: CachedContainer.TextureConfiguration;
 
     /** @privateRemarks Including to protect duck typing due to overall similarities b/w DarknessLevelContainer and CachedContainer */
     #onChildChange(): void;
   }
 
   namespace DarknessLevelContainer {
-    type AnyConstructor = typeof AnyCanvasIlluminationEffects;
+    interface Any extends AnyDarknessLevelContainer {}
+    interface AnyConstructor extends Identity<typeof AnyDarknessLevelContainer> {}
   }
 }
 
 declare abstract class AnyCanvasIlluminationEffects extends CanvasIlluminationEffects {
-  constructor(arg0: never, ...args: never[]);
+  constructor(...args: never);
 }
 
 declare abstract class AnyDarknessLevelContainer extends DarknessLevelContainer {
-  constructor(arg0: never, ...args: never[]);
+  constructor(...args: never);
 }

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

@@ -1,22 +1,21 @@
-import type { EmptyObject, InexactPartial, ValueOf } from "../../../../../types/utils.d.mts";
+import type { HandleEmptyObject, Identity, InexactPartial, IntentionalPartial, NullishProps } from "#utils";
 
 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}
+   * @see {@link PointSource | `PointSource`}
    */
-  class CanvasVisibility<
-    DrawOptions extends CanvasVisibility.DrawOptions = CanvasVisibility.DrawOptions,
-    TearDownOptions extends CanvasVisibility.TearDownOptions = CanvasVisibility.TearDownOptions,
-  > extends CanvasLayer<DrawOptions, TearDownOptions> {
+  class CanvasVisibility extends CanvasLayer {
     /**
      * The currently revealed vision.
+     * @remarks Only `undefined` prior to first draw
      */
     vision: CanvasVisionMask.CanvasVisionContainer | undefined;
 
     /**
      * The exploration container which tracks exploration progress.
+     * @remarks Only `undefined` prior to first draw
      */
     explored: PIXI.Container | undefined;
 
@@ -25,6 +24,9 @@ declare global {
      */
     visibilityOverlay: PIXI.Sprite | undefined;
 
+    /** @remarks Doesn't exist until it's set on draw */
+    filter?: VisibilityFilter.ConfiguredInstance;
+
     /**
      * The active vision source data object
      * @defaultValue
@@ -35,10 +37,7 @@ declare global {
      * }
      * ```
      */
-    visionModeData: {
-      source: foundry.canvas.sources.PointVisionSource.Any | null | undefined;
-      activeLightingOptions: VisionMode["_source"]["lighting"] | EmptyObject;
-    };
+    visionModeData: CanvasVisibility.VisionModeData;
 
     /**
      * Define whether each lighting layer is enabled, required, or disabled by this vision mode.
@@ -53,13 +52,7 @@ declare global {
      * }
      * ```
      */
-    lightingVisibility: {
-      illumination: CanvasVisibility.LightingVisibility;
-      background: CanvasVisibility.LightingVisibility;
-      coloration: CanvasVisibility.LightingVisibility;
-      darkness: CanvasVisibility.LightingVisibility;
-      any: boolean;
-    };
+    lightingVisibility: CanvasVisibility.LightingVisibility;
 
     /**
      * A status flag for whether the layer initialization workflow has succeeded.
@@ -68,27 +61,32 @@ declare global {
 
     /**
      * Indicates whether containment filtering is required when rendering vision into a texture
+     * @remarks Foundry marked `@internal`
      */
-    protected get needsContainment(): boolean;
+    get needsContainment(): boolean;
 
     /**
      * Does the currently viewed Scene support Token field of vision?
      */
-    get tokenVision(): Scene.ConfiguredInstance["tokenVision"];
+    get tokenVision(): Scene.Implementation["tokenVision"];
 
     /**
      * The configured options used for the saved fog-of-war texture.
+     * @remarks Only `undefined` before first `#draw()`
      */
-    get textureConfiguration(): VisibilityTextureConfiguration | undefined;
+    get textureConfiguration(): CanvasVisibility.TextureConfiguration | 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
+     * @privateRemarks Foundry types this parameter as `FogTextureConfiguration` in v12.331 which is plainly wrong even if it didn't not exist
+     * v13.335 types as `PIXI.Rectangle | undefined`, but only x/y/width/height are ever accessed, and only then if this has been set to something
+     * other than `undefined`, and in fact nothing in core ever does.
      */
-    set explorationRect(rect: Canvas.Rectangle);
+    set explorationRect(rect: Canvas.Rectangle | undefined);
+
+    /** @remarks This getter doesn't actually exist, it's only here to correct the type inferred from the setter */
+    get explorationRect(): undefined;
 
     /**
      * Initialize all Token vision sources which are present on this layer
@@ -100,9 +98,9 @@ declare global {
      */
     initializeVisionMode(): void;
 
-    protected override _draw(options?: DrawOptions): Promise<void>;
+    protected override _draw(options: HandleEmptyObject<CanvasVisibility.DrawOptions>): Promise<void>;
 
-    protected override _tearDown(options?: TearDownOptions): Promise<void>;
+    protected override _tearDown(options: HandleEmptyObject<CanvasVisibility.TearDownOptions>): Promise<void>;
 
     /**
      * Update the display of the sight layer.
@@ -134,48 +132,19 @@ declare global {
      */
     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;
-      }>,
+      options?: CanvasVisibility.TestVisibilityOptions, // not:null (destructured when passed to _createVisibilityTestConfig)
     ): 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.
+     * @remarks Foundry marked `@internal`
      */
-    _createVisibilityTestConfig(
+    protected _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;
+      options?: CanvasVisibility.CreateTestConfigOptions, // not:null (destructured)
+    ): CanvasVisibility.TestConfig;
 
     /**
      * @deprecated since v11, will be removed in v13
@@ -185,41 +154,92 @@ declare global {
   }
 
   namespace CanvasVisibility {
-    type AnyConstructor = typeof AnyCanvasVisibility;
-
-    type LightingVisibility = ValueOf<typeof VisionMode.LIGHTING_VISIBILITY>;
+    interface Any extends AnyCanvasVisibility {}
+    interface AnyConstructor extends Identity<typeof AnyCanvasVisibility> {}
 
     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;
-  }
+    type TestObject = PlaceableObject.Any | null;
 
-  interface CanvasVisibilityTest {
-    point: PIXI.Point;
-    los: Map<foundry.canvas.sources.PointVisionSource.Any, boolean>;
-  }
+    interface VisionModeData {
+      source: foundry.canvas.sources.PointVisionSource.Any | null | undefined;
+      activeLightingOptions: IntentionalPartial<VisionMode["lighting"]>;
+    }
+
+    interface LightingVisibility {
+      illumination: VisionMode.LIGHTING_VISIBILITY;
+      background: VisionMode.LIGHTING_VISIBILITY;
+      coloration: VisionMode.LIGHTING_VISIBILITY;
+      darkness: VisionMode.LIGHTING_VISIBILITY;
+      /** @remarks Only set `false` if all other keys are `VisionMode.LIGHTING_VISIBILITY.DISABLED` */
+      any: boolean;
+    }
+
+    interface TestVisibilityOptions extends CreateTestConfigOptions {}
+
+    /** @internal */
+    type _CreateTestConfigOptions = 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`
+       * @remarks Can't be `null` because it only has a parameter default
+       */
+      tolerance: number;
+
+      /**
+       * An optional reference to the object whose visibility is being tested
+       * @defaultValue `null`
+       */
+      object: TestObject;
+    }>;
 
-  interface CanvasVisibilityTestConfig {
-    object: PlaceableObject | null;
-    tests: CanvasVisibilityTest[];
+    interface CreateTestConfigOptions extends _CreateTestConfigOptions {}
+
+    /** @internal */
+    type _TestConfigOptional = NullishProps<{
+      /**
+       * The target object
+       * @defaultValue `null`
+       * @remarks Only checked in `#_canDetect` for `instanceof Token`
+       */
+      object: TestObject;
+    }>;
+
+    /** @internal */
+    interface _TestConfigRequired {
+      /** An array of visibility tests */
+      tests: CanvasVisibility.Test[];
+    }
+
+    interface TestConfig extends _TestConfigRequired, _TestConfigOptional {}
+
+    interface Test {
+      point: Canvas.Point;
+      elevation: number;
+      los: Map<foundry.canvas.sources.PointVisionSource.Any, boolean>;
+    }
+
+    /**
+     * @privateRemarks This is a fixed subset of `PIXI.IBaseTextureOptions` that `CanvasVisibility##createTextureConfiguration` produces.
+     * Since it's generated by a private method and stored in a private property, it's not meaningfully extensible (`canvas.visibility.textureConfiguration.foo = "bar"` doesn't count)
+     */
+    interface TextureConfiguration {
+      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;
+    }
   }
 }
 
 declare abstract class AnyCanvasVisibility extends CanvasVisibility {
-  constructor(arg0: never, ...args: never[]);
+  constructor(...args: never);
 }

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

@@ -1,4 +1,4 @@
-export {};
+import type { Identity } from "#utils";
 
 declare global {
   /**
@@ -8,11 +8,10 @@ declare global {
     /**
      * @param options - Options passed to the getParticleEmitters method which can be used to customize values of the emitter configuration.
      *                  (default: `{}`)
+     * @remarks Despite being an `={}` parameter, construction will throw if it is passed (or defaults to via omission) an empty object
      */
     constructor(options: PIXI.particles.EmitterConfigV3);
 
-    parent: PIXI.Container;
-
     emitters: PIXI.particles.Emitter[];
 
     /**
@@ -28,11 +27,12 @@ declare global {
      * 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)`
+     * @throws If `options` is passed as (or defaults to via omission) an empty object
+     * @remarks Despite its name, this method only takes a single config object and only returns a single-element array.
      */
     getParticleEmitters(options: PIXI.particles.EmitterConfigV3): PIXI.particles.Emitter[];
 
-    override destroy(options?: PIXI.DisplayObject.DestroyOptions): void;
+    override destroy(options?: PIXI.IDestroyOptions | boolean): void;
 
     /**
      * Begin animation for the configured emitters.
@@ -44,4 +44,13 @@ declare global {
      */
     stop(): void;
   }
+
+  namespace ParticleEffect {
+    interface Any extends AnyParticleEffect {}
+    interface AnyConstructor extends Identity<typeof AnyParticleEffect> {}
+  }
+}
+
+declare abstract class AnyParticleEffect extends ParticleEffect {
+  constructor(...args: never);
 }

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

@@ -1,20 +1,49 @@
-export {};
+import type { Identity } from "#utils";
 
 declare global {
   /**
    * A full-screen weather effect which renders gently falling autumn leaves.
    */
   class AutumnLeavesWeatherEffect extends ParticleEffect {
+    /**
+     * @remarks `options` is completely unused in this subclass, as it gets passed to `#getParticleEmitters`, which, unlike super's method, takes no arguments
+     */
+    constructor(options?: PIXI.particles.EmitterConfigV3 | null);
     /**
      * @defaultValue `"WEATHER.AutumnLeaves"`
+     * @remarks A localization key. Appears to be unused in v12.331, probably vestigial, is identical to the
+     * `label` for the AmbienceConfig containing this effect in `CONFIG.Canvas.weatherEffects`
      */
     static label: string;
 
     /**
      * Configuration for the particle emitter for falling leaves
+     * @remarks Not a complete EmitterConfigV3; the `frequency` and `pos` required keys are omitted. `frequency` is set
+     * up in `#getParticleEmitters`, but `pos` is not; it is erroneously marked as required in the interface,
+     * see https://github.com/pixijs-userland/particle-emitter/issues/219
      */
-    static LEAF_CONFIG: PIXI.particles.EmitterConfigV3;
+    static LEAF_CONFIG: AutumnLeavesWeatherEffect.LeafConfig;
 
+    /** @remarks This does not take a config paramater, unlike its parent class; uses `static LEAF_CONFIG` on this class instead */
     override getParticleEmitters(): PIXI.particles.Emitter[];
   }
+
+  namespace AutumnLeavesWeatherEffect {
+    interface Any extends AnyAutumnLeavesWeatherEffect {}
+    interface AnyConstructor extends Identity<typeof AnyAutumnLeavesWeatherEffect> {}
+
+    /** @internal */
+    interface _EmitterConfigOptionalProperties {
+      pos?: PIXI.particles.EmitterConfigV3["pos"];
+      frequency?: PIXI.particles.EmitterConfigV3["frequency"];
+    }
+
+    interface LeafConfig
+      extends Omit<PIXI.particles.EmitterConfigV3, keyof _EmitterConfigOptionalProperties>,
+        _EmitterConfigOptionalProperties {}
+  }
+}
+
+declare abstract class AnyAutumnLeavesWeatherEffect extends AutumnLeavesWeatherEffect {
+  constructor(...args: never);
 }