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

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

@@ -1,15 +1,12 @@
-import type { InexactPartial } from "../../../../../types/utils.d.mts";
+import type { HandleEmptyObject, Identity, InexactPartial, IntentionalPartial, NullishProps } from "fvtt-types/utils";
 
 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) {
+  class WeatherEffects extends FullCanvasObjectMixin(CanvasLayer) {
     /**
-     * @privateRemarks This is not overridden in foundry but reflects the real behavior.
+     * @privateRemarks This is not overridden in foundry but reflects the real behavior, due to `layerOptions.name` being `"effects"`
      */
     static get instance(): Canvas["effects"];
 
@@ -25,13 +22,13 @@ declare global {
 
     /**
      * The container in which effects are added.
-     * @defaultValue `undefined`
+     * @remarks Only `undefined` prior to first draw
      */
     weatherEffects: PIXI.Container | undefined;
 
     /**
      * The container in which suppression meshed are added.
-     * @defaultValue `undefined`
+     * @remarks Only `undefined` prior to first draw
      */
     suppression: PIXI.Container | undefined;
 
@@ -40,6 +37,7 @@ declare global {
      */
     static override get layerOptions(): WeatherEffects.LayerOptions;
 
+    /** @privateRemarks Types-only override to sync with static `layerOptions` */
     override options: WeatherEffects.LayerOptions;
 
     /**
@@ -51,19 +49,18 @@ declare global {
      * 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.
+     * @privateRemarks In practice this is always `undefined`, as it is not initialized to a value and never gets set anywhere in core in v12.331
      */
-    terrainMaskConfig: WeatherEffects.WeatherTerrainMaskConfiguration | undefined;
+    terrainMaskConfig: WeatherEffects.MaskConfiguration | 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.
+     * @privateRemarks In practice this is always `undefined`, as it is not initalized to a value and never gets set anywhere in core in v12.331.
+     * Passed as `this.occlusionMaskConfig || { enabled: true }` where it is used.
      */
-    occlusionMaskConfig: WeatherEffects.WeatherOcclusionMaskConfiguration | undefined;
+    occlusionMaskConfig: WeatherEffects.MaskConfiguration | undefined;
 
     /**
      * The inverse occlusion mask filter bound to this container.
@@ -72,16 +69,17 @@ declare global {
 
     /**
      * The elevation of this object.
-     * @throws The setter throws an error if passed NaN
+     * @defaultValue `Infinity`
+     * @throws If `NaN` is passed to the setter
      */
     get elevation(): number;
 
-    set elevation(value: number);
+    set elevation(value);
 
     /**
      * 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
+     * @throws If `NaN` is passed to the setter
      */
     get sortLayer(): number;
 
@@ -90,34 +88,33 @@ declare global {
     /**
      * 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
+     * @throws If `NaN` is passed to the setter
      */
     get sort(): number;
 
-    set sort(value: number);
+    set sort(value);
 
     /**
      * 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
+     * @throws If `NaN` is passed to the setter
      */
     get zIndex(): number;
 
-    set zIndex(value: number);
+    set zIndex(value);
 
-    protected override _draw(options?: DrawOptions): Promise<void>;
+    protected override _draw(options: HandleEmptyObject<WeatherEffects.DrawOptions>): Promise<void>;
 
-    protected override _tearDown(options?: TearDownOptions): Promise<void>;
+    protected override _tearDown(options: HandleEmptyObject<WeatherEffects.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;
+    initializeEffects(weatherEffectsConfig?: WeatherEffects.AmbienceConfiguration | null): void;
 
     /**
      * Clear the weather container.
+     * @remarks Just calls `initializeEffects(null)`
      */
     clearEffects(): void;
 
@@ -126,10 +123,9 @@ declare global {
      * @param context - The shader context
      * @param config  - Occlusion masking options
      */
-    protected static configureOcclusionMask(
+    static configureOcclusionMask(
       context: PIXI.Shader,
-      /** @remarks Can't be NullishProps because `texture` is only checked for `!== undefined` */
-      config?: InexactPartial<WeatherEffects.WeatherOcclusionMaskConfiguration>,
+      config?: WeatherEffects.MaskConfiguration, // not:null (destructured)
     ): void;
 
     /**
@@ -137,10 +133,9 @@ declare global {
      * @param context - The shader context
      * @param config  - Terrain masking options
      */
-    protected static configureTerrainMask(
+    static configureTerrainMask(
       context: PIXI.Shader,
-      /** @remarks Can't be NullishProps because `texture` is only checked for `!== undefined` */
-      config?: InexactPartial<WeatherEffects.WeatherTerrainMaskConfiguration>,
+      config?: WeatherEffects.MaskConfiguration, // not:null (destructured)
     ): void;
 
     /**
@@ -151,9 +146,11 @@ declare global {
   }
 
   namespace WeatherEffects {
-    type AnyConstructor = typeof AnyWeatherEffects;
+    interface Any extends AnyWeatherEffects {}
+    interface AnyConstructor extends Identity<typeof AnyWeatherEffects> {}
 
     interface LayerOptions extends CanvasLayer.LayerOptions {
+      /** @remarks This causes `WeatherEffect.instance` to be the `EffectsCanvasGroup` */
       name: "effects";
     }
 
@@ -161,67 +158,142 @@ declare global {
 
     interface TearDownOptions extends CanvasLayer.TearDownOptions {}
 
-    interface WeatherTerrainMaskConfiguration {
+    /**
+     * @internal
+     * @privateRemarks If `WeatherEffects#occlusionMaskConfig` or `#terrainMaskConfig` were *ever* set, i.e
+     * if this interface was ever used for more than a parameter type, it would have a base interface with
+     * no optionality/nullishness applied. Luckily it's not.
+     */
+    type _MaskConfiguration = NullishProps<{
       /**
        * 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;
-
+      reverse: boolean;
+    }> &
+      InexactPartial<{
+        /**
+         * An RGBA array of channel weights applied to the mask texture.
+         * @defaultValue `[0, 0, 1, 0]`
+         * @remarks Can't be `null` as it only has a parameter default.
+         */
+        channelWeights: [r: number, b: number, g: number, a: number];
+
+        /**
+         * A texture which defines the mask region.
+         * @remarks Can't be `null` because of an `!== undefined` check.
+         *
+         * If not provided, the shader being modified will have its `uniforms.useTerrain` or `.useOcclusion` set `false`
+         */
+        texture: PIXI.Texture | PIXI.RenderTexture;
+      }>;
+
+    interface MaskConfiguration extends _MaskConfiguration {}
+
+    type AmbienceFilterConfiguration = IntentionalPartial<{
       /**
-       * A texture which defines the mask region.
+       * Enable a layer-wide occlusion filter unless it is explicitly disabled by the effect configuration
+       * @remarks The above should for clarity say `ambience configuration` instead of `effect configuration`;
+       * Individual effects of this ambience can enable occlusion on themselves if this is set false, but
+       * cannot disable layer-wide occlusion if this is `true`
+       *
+       * @privateRemarks Checked for `!== false`, so allowing nullish values that get handled as `true` would be confusing
        */
-      texture: PIXI.Texture | PIXI.RenderTexture;
-    }
-
-    interface WeatherOcclusionMaskConfiguration {
+      enabled: boolean;
+    }> &
+      NullishProps<{
+        /**
+         * @defaultValue `PIXI.BLEND_MODES.NORMAL`
+         * @remarks The blend mode applied to the `WeatherEffects#occlusionFilter`
+         */
+        blendMode: PIXI.BLEND_MODES;
+      }>;
+
+    /** @internal */
+    type _CommonEffectConfiguration = NullishProps<{
       /**
-       * Enable or disable this mask.
-       * @defaultValue `false`
+       * @defaultValue `CONST.CANVAS_PERFORMANCE_MODES.LOW`
+       * @remarks The minimum required performance level to render this effect
        */
-      enabled: boolean;
+      performanceLevel: CONST.CANVAS_PERFORMANCE_MODES;
 
       /**
-       * An RGBA array of channel weights applied to the mask texture.
-       * @defaultValue `[0, 0, 1, 0]`
+       * @defaultValue The index of this effect in its array
+       * @remarks Applied to the constructed `effectClass`. None of the effects in core ambience definitions provide one.
        */
-      channelWeights: [r: number, b: number, g: number, a: number];
+      zIndex: number;
 
       /**
-       * If the mask should be reversed.
-       * @defaultValue `false`
+       * @defaultValue `PIXI.BLEND_MODES.NORMAL`
+       * @remarks Applied to the constructed `effectClass`
        */
-      reverse: boolean;
+      blendMode: PIXI.BLEND_MODES;
+    }>;
+
+    interface ParticleEffectConfiguration extends _CommonEffectConfiguration {
+      id: string;
+
+      effectClass: ParticleEffect.AnyConstructor;
 
       /**
-       * A texture which defines the mask region.
+       * @remarks Despite the corresponding `ParticleEffect#constructor` parameter being `={}`, construction will
+       * throw if this isn't a non-empty object, **except** in the case of the only core `extends ParticleEffect`
+       * class, {@link AutumnLeavesWeatherEffect | `AutumnLeavesWeatherEffect`}, which overrides the relevant method and always uses its static
+       * `LEAF_CONFIG` property instead; accounting for this is the only reason the property is optional
        */
-      texture: PIXI.Texture | PIXI.RenderTexture;
+      config: PIXI.particles.EmitterConfigV3;
     }
 
-    /**
-     * @privateRemarks types inferred from usage
-     */
-    interface WeatherEffectsConfig {
-      effects: WeatherEffects[];
+    interface SpecificallyAutumnLeavesConfiguration {
+      id: string;
+
+      effectClass: AutumnLeavesWeatherEffect.AnyConstructor;
+
+      /** @remarks {@link AutumnLeavesWeatherEffect | `AutumnLeavesWeatherEffect`} overrides {@link ParticleEffect.getParticleEmitters | `ParticleEffect#getParticleEmitters`} -- the method that would throw when passed an empty config -- to not take any parameters and always use */
+      config?: never;
+    }
+
+    interface WeatherShaderEffectConfiguration extends _CommonEffectConfiguration {
+      id: string;
+
+      effectClass: WeatherShaderEffect.AnyConstructor;
+
+      shaderClass: AbstractWeatherShader.AnyConstructor;
+
+      /** @remarks Can't be `null` because it gets `Object.entries()`ed with only a parameter default */
+      config?: WeatherShaderEffect.Configuration | undefined;
+    }
+
+    type EffectConfiguration =
+      | SpecificallyAutumnLeavesConfiguration
+      | ParticleEffectConfiguration
+      | WeatherShaderEffectConfiguration;
+
+    /** @internal */
+    type _AmbienceConfiguration = NullishProps<{
+      /** @remarks Properties of `filter` are always accessed with optional chaining in v12.331  */
+      filter: AmbienceFilterConfiguration;
+    }>;
+
+    interface AmbienceConfiguration extends _AmbienceConfiguration {
+      /** @remarks Should match the key for this ambience in the parent object (`CONFIG.Canvas.weatherEffects`) */
+      id: string;
+
+      /** @remarks A localization key to display in the Configure Scene sheet */
+      label: string;
 
-      filter: PIXI.Filter;
+      /** @remarks One or more effect definitions */
+      effects: EffectConfiguration[];
     }
   }
 }
 
 declare abstract class AnyWeatherEffects extends WeatherEffects {
-  constructor(arg0: never, ...args: never[]);
+  constructor(...args: never);
 }

package/src/foundry/client/pixi/layers/grid/highlight.d.mts

@@ -1,4 +1,4 @@
-export {};
+import type { Identity } from "fvtt-types/utils";
 
 declare global {
   /**
@@ -15,7 +15,7 @@ declare global {
     /**
      * Track distinct positions which have already been highlighted
      */
-    positions: Set<string>;
+    positions: Set<GridHighlight.PositionString>;
 
     /**
      * Record a position that is highlighted and return whether or not it should be rendered
@@ -27,7 +27,17 @@ declare global {
 
     override clear(): this;
 
-    /** @privateRemarks Foundry handles this by passing `(...args)` directly to super, but it only takes the one */
-    override destroy(options?: PIXI.DisplayObject.DestroyOptions): void;
+    override destroy(options?: PIXI.IDestroyOptions | boolean): void;
   }
+
+  namespace GridHighlight {
+    interface Any extends AnyGridHightlight {}
+    interface AnyConstructor extends Identity<typeof AnyGridHightlight> {}
+
+    type PositionString = `${number},${number}`;
+  }
+}
+
+declare abstract class AnyGridHightlight extends GridHighlight {
+  constructor(...args: never);
 }