@league-of-foundry-developers/foundry-vtt-types 13.340.0 → 13.340.1

package/src/foundry/client-esm/canvas/sources/point-vision-source.d.mts

@@ -1,6 +1,6 @@
 import type RenderedEffectSource from "./rendered-effect-source.d.mts";
 import type PointEffectSourceMixin from "./point-effect-source.d.mts";
-import type { IntentionalPartial } from "fvtt-types/utils";
+import type { AnyObject, FixedInstanceType, Identity, IntentionalPartial, RequiredProps } from "fvtt-types/utils";
 
 /**
  * A specialized subclass of RenderedEffectSource which represents a source of point-based vision.
@@ -14,10 +14,10 @@ declare class PointVisionSource<
   static override sourceType: string;
 
   /** @defaultValue `["visionMode", "blinded"]` */
-  static override _initializeShaderKeys: string[];
+  protected static override _initializeShaderKeys: string[];
 
   /** @defaultValue `["radius", "color", "attenuation", "brightness", "contrast", "saturation", "visionMode"]` */
-  static override _refreshUniformsKeys: string[];
+  protected static override _refreshUniformsKeys: string[];
 
   /**
    * The corresponding lighting levels for dim light.
@@ -40,46 +40,53 @@ declare class PointVisionSource<
    * @defaultValue
    * ```js
    * {
-   * ...super.defaultData,
-   * contrast: 0,
-   * attenuation: 0.5,
-   * saturation: 0,
-   * brightness: 0,
-   * visionMode: "basic",
-   * lightRadius: null
+   *   ...super.defaultData,
+   *   contrast: 0,
+   *   attenuation: 0.5,
+   *   saturation: 0,
+   *   brightness: 0,
+   *   visionMode: "basic",
+   *   lightRadius: null
    * }
    * ```
    */
   static override defaultData: PointVisionSource.SourceData;
 
   /** @remarks Overrides `Adaptive*Shader` references with `*VisionShader` ones */
-  static get _layers(): Record<string, RenderedEffectSource.LayerConfig>;
+  protected static get _layers(): Record<string, RenderedEffectSource.LayerConfig>;
 
   /**
    * The vision mode linked to this VisionSource
+   * @remarks Foundry types this as `| null`, and initializes to `= null` in the class body,
+   * but then sets it to `CONFIG.Canvas.visionModes[this.data.visionMode]` during actual
+   * initialization, so it'll either be a defined `VisionMode` or `undefined`
    */
-  visionMode: VisionMode | null;
+  visionMode: VisionMode | undefined;
 
   /**
    * The vision mode activation flag for handlers
-   * @internal
+   * @remarks Foundry marked `@internal`.
+   *
+   * Read and set externally in {@link VisionMode.activate | `VisionMode#activate`} and {@link VisionMode.deactivate | `VisionMode#deactivate`}
    */
-  _visionModeActivated: boolean;
+  protected _visionModeActivated: boolean;
 
   /**
    * The unconstrained LOS polygon.
+   * @remarks Initialization includes `this.los = this.shape` in `#_createShapes()`
    */
-  los: PointSourcePolygon;
+  los: SourceShape;
 
   /**
    * The polygon of light perception.
+   * @remarks Initialization includes `this.light = this._createLightPolygon()` in `#_createShapes()`
    */
-  light: PointSourcePolygon;
+  light: SourceShape;
 
   /**
    * An alias for the shape of the vision source.
    */
-  get fov(): PIXI.Polygon | PointSourcePolygon;
+  get fov(): SourceShape;
 
   /**
    * If this vision source background is rendered into the lighting container.
@@ -107,27 +114,29 @@ declare class PointVisionSource<
    * Records of blinding strings with a boolean value.
    * By default, if any of this record is true, the source is blinded.
    */
-  blinded: Record<string, boolean>;
+  blinded: PointVisionSource.BlindedReasons;
 
   /**
    * Data overrides that could happen with blindness vision mode.
+   * @remarks Initialized in the class to `{}`, but filled in during actual initialization (`#_updateVisionMode` via `#_createShapes`)
    */
-  visionModeOverrides: object;
+  visionModeOverrides: PointVisionSource.VisionModeOverrides;
 
-  override _initialize(data: IntentionalPartial<SourceData>): void;
+  protected override _initialize(data: IntentionalPartial<SourceData>): void;
 
-  override _createShapes(): void;
+  protected override _createShapes(): void;
 
   /**
    * Responsible for assigning the Vision Mode and calling the activation and deactivation handlers.
    */
   protected _updateVisionMode(): void;
 
-  override _configure(changes: IntentionalPartial<SourceData>): void;
+  // TODO: Flatten<IntentionalPartial<SourceData>>
+  protected override _configure(changes: AnyObject): void;
 
-  override _configureLayer(layer: RenderedEffectSource.SourceLayer, layerId: string): void;
+  protected override _configureLayer(layer: RenderedEffectSource.SourceLayer, layerId: string): void;
 
-  override _getPolygonConfiguration(): PointSourcePolygon.Config;
+  protected override _getPolygonConfiguration(): PointVisionSource.PolygonConfig;
 
   /**
    * Creates the polygon that represents light perception.
@@ -135,7 +144,7 @@ declare class PointVisionSource<
    * instead the LOS polygon of this vision source is returned.
    * @returns The new polygon or `this.los`.
    */
-  protected _createLightPolygon(): PointSourcePolygon;
+  protected _createLightPolygon(): SourceShape;
 
   /**
    * Create a restricted FOV polygon by limiting the radius of the unrestricted LOS polygon.
@@ -143,59 +152,71 @@ declare class PointVisionSource<
    * instead the LOS polygon of this vision source is returned.
    * @returns The new polygon or `this.los`.
    */
-  protected _createRestrictedPolygon(): PointSourcePolygon;
+  protected _createRestrictedPolygon(): SourceShape;
 
-  override _configureShaders(): Record<keyof RenderingLayers, typeof AdaptiveVisionShader>;
+  protected override _configureShaders(): Record<keyof RenderingLayers, AdaptiveVisionShader.AnyConstructor>;
 
-  override _updateColorationUniforms(): void;
+  protected override _updateColorationUniforms(): void;
 
-  override _updateIlluminationUniforms(): void;
+  protected override _updateIlluminationUniforms(): void;
 
-  override _updateBackgroundUniforms(): void;
+  protected override _updateBackgroundUniforms(): void;
 
-  override _updateCommonUniforms(shader: AbstractBaseShader): void;
+  protected override _updateCommonUniforms(shader: AbstractBaseShader): void;
 
   /**
    * Update layer uniforms according to vision mode uniforms, if any.
    * @param shader     - The shader being updated.
    * @param vmUniforms - The targeted layer.
    */
-  protected _updateVisionModeUniforms(shader: AdaptiveVisionShader, vmUniforms: AbstractBaseShader.Uniforms): void;
+  protected _updateVisionModeUniforms(
+    shader: AdaptiveVisionShader,
+    vmUniforms: Array<[string, AbstractBaseShader.UniformValue]>,
+  ): void;
 }
 
 declare namespace PointVisionSource {
-  type Any = PointVisionSource<SourceData>;
-
-  type AnyConstructor = typeof AnyPointVisionSource;
+  interface Any extends AnyPointVisionSource {}
+  interface AnyConstructor extends Identity<typeof AnyPointVisionSource> {}
 
   interface SourceData extends RenderedEffectSource.SourceData, PointEffectSourceMixin.SourceData {
     /**
      * The amount of contrast
+     * @defaultValue `0`
      */
     contrast: number;
 
     /**
      * Strength of the attenuation between bright, dim, and dark
+     * @defaultValue `0.5`
      */
     attenuation: number;
 
     /**
      * The amount of color saturation
+     * @defaultValue `0`
      */
     saturation: number;
 
     /**
-     * The vision brightness.
+     * The vision brightness
+     * @defaultValue `0`.
      */
     brightness: number;
 
     /**
      * The vision mode.
+     * @defaultValue `"basic"`
      */
-    visionMode: string;
+    visionMode: VisionMode.ConfiguredModes;
 
     /**
      * The range of light perception.
+     * @defaultValue `null`
+     * @remarks `null` is treated as `0` for `get LightRadius()` purposes, and while this
+     * will be `null` in `.defaultData`, `PointVisionSource#_initialize` will replace it
+     * with `Math.max(canvas.dimensions.maxR, this.data.externalRadius)` if it's not
+     * otherwise specified
      */
     lightRadius: number | null;
 
@@ -204,10 +225,34 @@ declare namespace PointVisionSource {
      */
     blinded: boolean;
   }
+
+  /** @privateRemarks Foundry types the property this is for as just `object` */
+  interface VisionModeOverrides {
+    colorRGB: Color.RGBColorVector | null;
+    brightness: number;
+    contrast: number;
+    saturation: number;
+    attenuation: number;
+  }
+
+  /** @privateRemarks Foundry types this as just the Record, but only ever checks the one key */
+  interface BlindedReasons extends Record<string, boolean | undefined> {
+    darkness?: boolean;
+  }
+
+  interface PolygonConfig
+    extends RequiredProps<PointEffectSourceMixin.PolygonConfig, "radius" | "useThreshold" | "includeDarkness"> {}
+
+  type ConfiguredClass = CONFIG["Canvas"]["visionSourceClass"];
+  type ConfiguredInstance = FixedInstanceType<ConfiguredClass>;
 }
 
-declare abstract class AnyPointVisionSource extends PointVisionSource {
-  constructor(arg0: never, ...args: never[]);
+declare abstract class AnyPointVisionSource extends PointVisionSource<
+  PointVisionSource.SourceData,
+  PointSourcePolygon,
+  RenderedEffectSource.Layers
+> {
+  constructor(...args: never);
 }
 
 export default PointVisionSource;

package/src/foundry/client-esm/canvas/sources/rendered-effect-source.d.mts

@@ -1,17 +1,20 @@
-import type { InexactPartial, IntentionalPartial } from "fvtt-types/utils";
+import type { AnyObject, Identity, InexactPartial, IntentionalPartial, NullishProps } from "fvtt-types/utils";
 import type BaseEffectSource from "./base-effect-source.d.mts";
+import type BaseLightSource from "./base-light-source.d.mts";
 
 /**
  * An abstract class which extends the base PointSource to provide common functionality for rendering.
  * This class is extended by both the LightSource and VisionSource subclasses.
  */
-declare class RenderedEffectSource<
+declare abstract class RenderedEffectSource<
   SourceData extends RenderedEffectSource.SourceData = RenderedEffectSource.SourceData,
   SourceShape extends PIXI.Polygon = PIXI.Polygon,
   RenderingLayers extends Record<string, RenderedEffectSource.SourceLayer> = RenderedEffectSource.Layers,
 > extends BaseEffectSource<SourceData, SourceShape> {
   /**
    * Keys of the data object which require shaders to be re-initialized.
+   * @privateRemarks Presumably, allowing this to contain `"animation.type"` in `BaseLightSource` is why
+   * `#_configure` is passed flattened data
    */
   protected static _initializeShaderKeys: string[];
 
@@ -36,11 +39,11 @@ declare class RenderedEffectSource<
    * @defaultValue
    * ```js
    * {
-   * ...super.defaultData,
-   * animation: {},
-   * seed: null,
-   * preview: false,
-   * color: null
+   *   ...super.defaultData,
+   *   animation: {},
+   *   seed: null,
+   *   preview: false,
+   *   color: null
    * }
    * ```
    */
@@ -50,7 +53,7 @@ declare class RenderedEffectSource<
    * The animation configuration applied to this source
    * @defaultValue `{}`
    */
-  animation: RenderedEffectSource.AnimationConfig;
+  animation: RenderedEffectSource.StoredAnimationConfig;
 
   /**
    * Track the status of rendering layers
@@ -60,7 +63,7 @@ declare class RenderedEffectSource<
   /**
    * The color of the source as an RGB vector.
    */
-  colorRGB: [number, number, number] | null;
+  colorRGB: Color.RGBColorVector | null;
 
   /**
    * PIXI Geometry generated to draw meshes.
@@ -97,23 +100,25 @@ declare class RenderedEffectSource<
    */
   get illumination(): PointSourceMesh;
 
-  override _initialize(data: IntentionalPartial<SourceData>): void;
+  protected override _initialize(data: IntentionalPartial<SourceData>): void;
 
   /**
    * Decide whether to render soft edges with a blur.
    */
   protected _initializeSoftEdges(): void;
 
-  override _configure(changes: IntentionalPartial<SourceData>): void;
+  // TODO: Flatten<IntentionalPartial<SourceData>>
+  protected override _configure(changes: AnyObject): void;
 
   /**
    * Configure which shaders are used for each rendered layer.
    * @privateRemarks Foundry marks this as private then overrides it in `PointVisionSource`
    */
-  protected _configureShaders(): Record<keyof RenderingLayers, typeof AdaptiveLightingShader>;
+  protected _configureShaders(): Record<keyof RenderingLayers, AdaptiveLightingShader.AnyConstructor>;
 
   /**
    * Specific configuration for a layer.
+   * @remarks Is a no-op in `RenderedEffectSource`
    */
   protected _configureLayer(layer: RenderedEffectSource.SourceLayer, layerId: string): void;
 
@@ -126,15 +131,16 @@ declare class RenderedEffectSource<
 
   /**
    * Render the containers used to represent this light source within the LightingLayer
+   * @remarks Will error if called prior to initialization
    */
-  drawMeshes(): Record<keyof RenderingLayers, PIXI.Mesh | null>;
+  drawMeshes(): Record<keyof RenderingLayers, PointSourceMesh | null>;
 
   /**
    * Create a Mesh for a certain rendered layer of this source.
    * @param layerId - The layer key in layers to draw
    * @returns The drawn mesh for this layer, or null if no mesh is required
    */
-  protected _drawMesh(layerId: string): PIXI.Mesh | null;
+  protected _drawMesh(layerId: string): PointSourceMesh | null;
 
   /**
    * Update shader uniforms used by every rendered layer.
@@ -161,8 +167,8 @@ declare class RenderedEffectSource<
   /**
    * Animate the PointSource, if an animation is enabled and if it currently has rendered containers.
    * @param dt - Delta time.
-   * @privateRemarks In core this will return `void`, as the `this.animation.animation` function will  be a {@link BaseLightSource.LightAnimationFunction}
-   * and in fact most of the time will be `RenderedEffectSource#animateTime`, but it could technically be set to any function
+   * @privateRemarks In core this will return `void`, as the `this.animation.animation` function will  be a {@link foundry.canvas.sources.BaseLightSource.LightAnimationFunction | `BaseLightSource.LightAnimationFunction`}
+   * and in fact most of the time will be {@link foundry.canvas.sources.RenderedEffectSource.animateTime | `RenderedEffectSource#animateTime`}, but it could technically be set to any function
    */
   animate(dt: number): this["animation"]["animation"] extends (...args: infer _1) => infer Return ? Return : void;
 
@@ -177,7 +183,7 @@ declare class RenderedEffectSource<
    * Get corrected level according to level and active vision mode data.
    * @returns The corrected level.
    */
-  static getCorrectedLevel(level: foundry.CONST.LIGHTING_LEVELS): number;
+  static getCorrectedLevel(level: foundry.CONST.LIGHTING_LEVELS): foundry.CONST.LIGHTING_LEVELS;
 
   /**
    * Get corrected color according to level, dim color, bright color and background color.
@@ -186,7 +192,7 @@ declare class RenderedEffectSource<
     level: foundry.CONST.LIGHTING_LEVELS,
     colorDim: Color,
     colorBright: Color,
-    colorBackground?: Color,
+    colorBackground?: Color | null,
   ): Color;
 
   /**
@@ -203,28 +209,37 @@ declare class RenderedEffectSource<
 }
 
 declare namespace RenderedEffectSource {
-  type Any = RenderedEffectSource<any, any, any>;
-
-  type AnyConstructor = typeof AnyRenderedEffectSource;
+  interface Any extends AnyRenderedEffectSource {}
+  interface AnyConstructor extends Identity<typeof AnyRenderedEffectSource> {}
 
   interface SourceData extends BaseEffectSource.SourceData {
     /**
      * An animation configuration for the source
+     * @defaultValue `{}`
      */
-    animation: object;
+    animation: StoredAnimationConfig;
 
     /**
      * A color applied to the rendered effect
+     * @defaultValue `null`
+     * @remarks Foundry types as `number`, but it gets passed to `Color.from()`
+     *
+     * If `null`, Foundry will use the associated shader's `.defaultUniforms.color`
      */
-    color: number | null;
+    color: Color.Source | null;
 
     /**
      * An integer seed to synchronize (or de-synchronize) animations
+     * @defaultValue `null`
+     * @remarks This will remain null in `#data` if not specified, which will lead to `Math.floor(Math.random() * 100000)`
+     *
+     * If specified, takes precedence over `RenderedEffectSource#animation.seed`
      */
     seed: number | null;
 
     /**
      * Is this source a temporary preview?
+     * @defaultValue `false`
      */
     preview: boolean;
   }
@@ -241,14 +256,14 @@ declare namespace RenderedEffectSource {
     /**
      * The animation speed, from 0 to 10
      * @defaultValue `5`
-     * @remarks Can't be null due to only having default via signature
+     * @remarks Can't be `null` as it only has a parameter default
      */
     speed: number;
 
     /**
      * The animation intensity, from 1 to 10
      * @defaultValue `5`
-     * @remarks Can't be null due to only having default via signature
+     * @remarks Can't be `null` as it only has a parameter default
      */
     intensity: number;
 
@@ -259,52 +274,107 @@ declare namespace RenderedEffectSource {
     reverse: boolean | null;
   }>;
 
-  /** Shared options for the {@link AnimationFunction}s provided by `_Source` classes */
+  /** Shared options for the {@link RenderedEffectSource.AnimationFunction | `AnimationFunction`}s provided by {@link foundry.canvas.sources.RenderedEffectSource | `RenderedEffectSource`} and subclasses */
   interface AnimationFunctionOptions extends _AnimationFunctionOptions {}
 
-  type AnimationConfig = InexactPartial<{
+  /**
+   * Properties *every* core-provided config has
+   * @internal
+   */
+  interface _AnimationConfigBase {
     /**
      * The human-readable (localized) label for the animation
+     * @remarks Despite the above, all of the core-provided configs provide a localization
+     * key here, not localized text.
      */
     label: string;
 
     /**
      * The animation function that runs every frame
-     * @privateRemarks TODO: Figure out if there's a better way to define the function
+     * @privateRemarks Eventually called with `animation?.call()`, but at no point is a default provided,
+     * and not having one is nonsensical.
+     */
+    animation: AnimationFunction | BaseLightSource.LightAnimationFunction;
+  }
+
+  /** @internal */
+  type _Seed = NullishProps<{
+    /**
+     * The animation seed
+     * @defaultValue `Math.floor(Math.random() * 100000)`
+     * @remarks No Foundry-provided config specifies this, but it would be respected if set
      */
-    animation: RenderedEffectSource.AnimationFunction;
+    seed: number;
+  }>;
 
+  /**
+   * Each Foundry-provided entry in `CONFIG.Canvas.lightAnimations` provides at least a `colorationShader`,
+   * but any properties not provided will be backfilled by `|| this.layers[layer].defaultShader`
+   * @internal
+   */
+  type _AnimationConfigLightingShaders = NullishProps<{
     /**
      * A custom illumination shader used by this animation
+     * @defaultValue `AdaptiveIlluminationShader`
      */
-    illuminationShader: typeof AdaptiveIlluminationShader;
+    illuminationShader: AdaptiveIlluminationShader.AnyConstructor;
 
     /**
      * A custom coloration shader used by this animation
+     * @defaultValue `AdaptiveColorationShader`
      */
-    colorationShader: typeof AdaptiveColorationShader;
+    colorationShader: AdaptiveColorationShader.AnyConstructor;
 
     /**
      * A custom background shader used by this animation
+     * @defaultValue `AdaptiveBackgroundShader`
      */
-    backgroundShader: typeof AdaptiveBackgroundShader;
+    backgroundShader: AdaptiveBackgroundShader.AnyConstructor;
+  }> & { darknessShader?: never };
 
+  /**
+   * Foundry's typedef lists `darknessShader` as required, and every core-provided config
+   * has one specified, but it has a default just like the lighting shaders
+   * @internal
+   */
+  interface _AnimationConfigDarknessShaders {
     /**
      * A custom darkness shader used by this animation
+     * @defaultValue `AdaptiveDarknessShader`
      */
-    darknessShader: typeof AdaptiveDarknessShader;
+    darknessShader: AdaptiveDarknessShader.AnyConstructor;
 
-    /**
-     * The animation seed
-     */
-    seed: number;
+    illuminationShader?: never;
+    colorationShader?: never;
+    backgroundShader?: never;
+  }
 
+  /**
+   * `this.animation.time` always gets set by `RenderedEffectSource#animateTime`,
+   * which all animation functions end up calling
+   * @internal
+   */
+  type _AnimationConfigComputed = InexactPartial<{
     /**
      * The animation time
+     * @remarks Always computed, never specified in `CONFIG`
      */
     time: number;
   }>;
 
+  interface LightAnimationConfig extends _AnimationConfigBase, _Seed, _AnimationConfigLightingShaders {}
+
+  interface StoredLightAnimationConfig extends IntentionalPartial<LightAnimationConfig>, _AnimationConfigComputed {}
+
+  interface DarknessAnimationConfig extends _AnimationConfigBase, _Seed, _AnimationConfigDarknessShaders {}
+
+  interface StoredDarknessAnimationConfig
+    extends IntentionalPartial<DarknessAnimationConfig>,
+      _AnimationConfigComputed {}
+
+  type AnimationConfig = LightAnimationConfig | DarknessAnimationConfig;
+
+  type StoredAnimationConfig = StoredLightAnimationConfig | StoredDarknessAnimationConfig;
   /**
    * @remarks The properties `mesh` and `shader` from `LayerConfig` are not documented as being part of the typedef. They are given values
    * during initialization *if* the Source has a valid `Placeable` as its `object`. `vmUniforms` is only provided a value for `PointVisionSource` layers.
@@ -335,7 +405,7 @@ declare namespace RenderedEffectSource {
      */
     shader: AdaptiveLightingShader | undefined;
 
-    /** @remarks Foundry does not include this in the typedef but is in the initalization of `RenderedEffectSource#layers` */
+    /** @remarks Foundry does not include this in the typedef but is in the initialization of `RenderedEffectSource#layers` */
     vmUniforms: AbstractBaseShader.Uniforms | undefined;
   }
 
@@ -343,7 +413,7 @@ declare namespace RenderedEffectSource {
     /**
      * The default shader used by this layer
      */
-    defaultShader: typeof AdaptiveLightingShader;
+    defaultShader: AdaptiveLightingShader.AnyConstructor;
 
     /**
      * The blend mode used by this layer
@@ -360,8 +430,12 @@ declare namespace RenderedEffectSource {
   };
 }
 
-declare abstract class AnyRenderedEffectSource extends RenderedEffectSource<any, any, any> {
-  constructor(arg0: never, ...args: never[]);
+declare abstract class AnyRenderedEffectSource extends RenderedEffectSource<
+  RenderedEffectSource.SourceData,
+  PIXI.Polygon,
+  RenderedEffectSource.Layers
+> {
+  constructor(...args: never);
 }
 
 export default RenderedEffectSource;