Merge pull request #2995 from League-of-Foundry-Developers/point-effe…

…ct-sources-v12

Point effect sources v12

src/foundry/client-esm/applications/api/application.d.mts

@@ -1,4 +1,11 @@
-import type { MustConform, AnyObject, DeepPartial, EmptyObject, InexactPartial, MaybePromise } from "../../../../utils/index.d.mts";
+import type {
+  MustConform,
+  AnyObject,
+  DeepPartial,
+  EmptyObject,
+  InexactPartial,
+  MaybePromise,
+} from "../../../../utils/index.d.mts";
 import type EventEmitterMixin from "../../../common/utils/event-emitter.d.mts";
 
 // TODO: Investigate use of DeepPartial vs Partial vs InexactPartial

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

@@ -1,4 +1,4 @@
-import type { InexactPartial } from "../../../../utils/index.d.mts";
+import type { NullishProps, IntentionalPartial } from "../../../../utils/index.d.mts";
 
 /**
  * TODO - Re-document after ESM refactor.
@@ -14,15 +14,16 @@ import type { InexactPartial } from "../../../../utils/index.d.mts";
  * ```
  * @privateRemarks The TODO is foundry's
  */
-declare class BaseEffectSource<
-  SourceData extends BaseEffectSource.BaseEffectSourceData,
+declare abstract class BaseEffectSource<
+  SourceData extends BaseEffectSource.SourceData,
   SourceShape extends PIXI.Polygon,
 > {
   /**
    * An effect source is constructed by providing configuration options.
    * @param options - Options which modify the base effect source instance
+   * @remarks Passing a PlaceableObject is deprecated, and will be removed in v13
    */
-  constructor(options?: BaseEffectSource.BaseEffectSourceOptions);
+  constructor(options?: BaseEffectSource.SourceOptions | PlaceableObject);
 
   /**
    * The type of source represented by this data structure.
@@ -47,7 +48,7 @@ declare class BaseEffectSource<
    * }
    * ```
    */
-  static defaultData: BaseEffectSource.BaseEffectSourceData;
+  static defaultData: BaseEffectSource.SourceData;
 
   /**
    * Some other object which is responsible for this source.
@@ -56,8 +57,9 @@ declare class BaseEffectSource<
 
   /**
    * The source id linked to this effect source.
+   * @remarks Foundry types this as Readonly<string>, but does nothing to that effect at runtime
    */
-  readonly sourceId: string;
+  sourceId: string | undefined;
 
   /**
    * The data of this source.
@@ -66,8 +68,9 @@ declare class BaseEffectSource<
 
   /**
    * The geometric shape of the effect source which is generated later.
+   * @remarks This only isn't `undefined` in subclasses implementing `_createShapes()`, usually via {@link PointEffectSourceMixin}
    */
-  shape: SourceShape;
+  shape: SourceShape | undefined;
 
   /**
    * A collection of boolean flags which control rendering and refresh behavior for the source.
@@ -129,22 +132,25 @@ declare class BaseEffectSource<
    * @returns The initialized source
    */
   initialize(
-    data?: InexactPartial<SourceData>,
-    options?: InexactPartial<{
-      // The type def references a behaviors object that is not even passed into the function
+    data?: NullishProps<SourceData>,
+    /** @privateRemarks Foundry describes an `options.behaviors` key, but it is neither checked for nor used at runtime */
+    options?: NullishProps<{
       /**
        * Should source data be reset to default values before applying changes?
        * @defaultValue `false`
        */
-      reset?: boolean;
+      reset: boolean;
     }>,
   ): this;
 
   /**
    * Subclass specific data initialization steps.
    * @param data - Provided data for configuration
    */
-  _initialize(data: Partial<SourceData>): void;
+  _initialize(
+    /** @remarks IntentionalPartial because `this.initialize` has filtered invalid keys and replaced any nullish values before calling this */
+    data: IntentionalPartial<SourceData>,
+  ): void;
 
   /**
    * Create the polygon shape (or shapes) for this source using configured data.
@@ -155,8 +161,9 @@ declare class BaseEffectSource<
    * Subclass specific configuration steps. Occurs after data initialization and shape computation.
    * Only called if the source is attached and not disabled.
    * @param changes - Changes to the source data which were applied
+   * @remarks This is actually passed *flattened* partial data
    */
-  protected _configure(changes: Partial<SourceData>): void;
+  protected _configure(changes: IntentionalPartial<SourceData>): void;
 
   /**
    * Refresh the state and uniforms of the source.
@@ -211,19 +218,25 @@ declare class BaseEffectSource<
 declare namespace BaseEffectSource {
   type AnyConstructor = typeof AnyBaseEffectSource;
 
-  interface BaseEffectSourceOptions {
+  /** @internal */
+  type _SourceOptions = NullishProps<{
     /**
      * An optional PlaceableObject which is responsible for this source
      */
-    object?: PlaceableObject | undefined;
+    object: PlaceableObject;
+  }>;
+
+  interface SourceOptions extends _SourceOptions {
     /**
      * A unique ID for this source. This will be set automatically if an
      * object is provided, otherwise is required.
+     * @remarks The above is misleading; sourceId will *not* be inferred if you pass in `{object: PlaceableObject}`,
+     * only if you pass a `PlaceableObject` *instead* of an options object to the constructor.
      */
-    sourceId?: string | undefined;
+    sourceId?: string;
   }
 
-  interface BaseEffectSourceData {
+  interface SourceData {
     /**
      * The x-coordinate of the source location
      */

src/foundry/client-esm/canvas/sources/base-light-source.d.mts

@@ -1,13 +1,13 @@
-import type { InexactPartial } from "../../../../utils/index.d.mts";
+import type { InexactPartial, IntentionalPartial } from "../../../../utils/index.d.mts";
 import type RenderedEffectSource from "./rendered-effect-source.d.mts";
 
 /**
  * A specialized subclass of BaseEffectSource which deals with the rendering of light or darkness.
  */
-declare class BaseLightSource<
-  SourceData extends BaseLightSource.LightSourceData = BaseLightSource.LightSourceData,
+declare abstract class BaseLightSource<
+  SourceData extends BaseLightSource.SourceData = BaseLightSource.SourceData,
   SourceShape extends PIXI.Polygon = PIXI.Polygon,
-  RenderingLayers extends Record<string, RenderedEffectSource.RenderedEffectSourceLayer> = RenderedEffectSource.Layers,
+  RenderingLayers extends Record<string, RenderedEffectSource.SourceLayer> = RenderedEffectSource.Layers,
 > extends RenderedEffectSource<SourceData, SourceShape, RenderingLayers> {
   /** @defaultValue `"light"` */
   static override sourceType: string;
@@ -20,18 +20,22 @@ declare class BaseLightSource<
 
   /**
    * The corresponding lighting levels for dim light.
+   * @defaultValue `foundry.CONST.LIGHTING_LEVELS.DIM`
    */
   protected static _dimLightingLevel: foundry.CONST.LIGHTING_LEVELS;
 
   /**
    * The corresponding lighting levels for bright light.
+   * @defaultValue `foundry.CONST.LIGHTING_LEVELS.BRIGHT`
    */
   protected static _brightLightingLevel: foundry.CONST.LIGHTING_LEVELS;
 
   /**
    * The corresponding animation config.
+   * @remarks More broad than it should be to accomodate {@link foundry.canvas.sources.PointDarknessSource}
+   * TODO: Reevaluate after CONFIG has been gone over
    */
-  protected static get ANIMATIONS(): CONFIG.Canvas.LightSourceAnimationConfig;
+  protected static get ANIMATIONS(): typeof CONFIG.Canvas.lightAnimations | typeof CONFIG.Canvas.darknessAnimations;
 
   /**
    * @defaultValue
@@ -52,14 +56,14 @@ declare class BaseLightSource<
    * }
    * ```
    */
-  static override defaultData: RenderedEffectSource.RenderedEffectSourceData;
+  static override defaultData: BaseLightSource.SourceData;
 
   /**
    * A ratio of dim:bright as part of the source radius
    */
   ratio: number;
 
-  override _initialize(data: Partial<SourceData>): void;
+  override _initialize(data: IntentionalPartial<SourceData>): void;
 
   override _updateColorationUniforms(): void;
 
@@ -69,12 +73,18 @@ declare class BaseLightSource<
 
   override _updateCommonUniforms(shader: AbstractBaseShader): void;
 
+  /** @remarks This property is undocumented, and only defined during `_updateCommonUniforms` */
+  cachededAttentuation?: number;
+
+  /** @remarks This property is undocumented, and only defined during `_updateCommonUniforms` */
+  computedAttentuation?: number;
+
   /**
    * An animation with flickering ratio and light intensity.
    * @param dt      - Delta time
    * @param options - Additional options which modify the torch animation
    */
-  animateTorch(dt: number, options?: InexactPartial<RenderedEffectSource.AnimationOptions>): void;
+  animateTorch(dt: number, options?: RenderedEffectSource.AnimationFunctionOptions): void;
 
   /**
    * An animation with flickering ratio and light intensity
@@ -83,77 +93,105 @@ declare class BaseLightSource<
    */
   animateFlickering(
     dt: number,
-    options?: InexactPartial<
-      RenderedEffectSource.AnimationOptions & {
+    options?: RenderedEffectSource.AnimationFunctionOptions &
+      InexactPartial<{
         /**
          * Noise amplification (\>1) or dampening (\<1)
          * @defaultValue `1`
          */
         amplification: number;
-      }
-    >,
+      }>,
   ): void;
 
+  /**
+   * @remarks This property will be generated on any class that is `animateFlickering`'s `this` when it is called.
+   * Foundry does not document it.
+   */
+  _noise?: SmoothNoise;
+
   /**
    * A basic "pulse" animation which expands and contracts.
    * @param dt      - Delta time
    * @param options - Additional options which modify the pulse animation
    */
-  animatePulse(dt: number, options?: InexactPartial<RenderedEffectSource.AnimationOptions>): void;
+  animatePulse(dt: number, options?: RenderedEffectSource.AnimationFunctionOptions): void;
 
   /**
-   * @deprecated since v12
+   * @deprecated since v12, until v14
+   * @remarks "BaseLightSource#isDarkness is now obsolete. Use DarknessSource instead."
    */
   get isDarkness(): boolean;
 }
 
 declare namespace BaseLightSource {
-  interface LightSourceData extends RenderedEffectSource.RenderedEffectSourceData {
+  type AnyConstructor = typeof AnyBaseLightSource;
+
+  type LightAnimationFunction = (
+    this: BaseLightSource,
+    dt: number,
+    options?: RenderedEffectSource.AnimationFunctionOptions,
+  ) => void;
+
+  interface SourceData extends RenderedEffectSource.SourceData {
     /**
      * An opacity for the emitted light, if any
      */
     alpha: number;
+
     /**
      * The allowed radius of bright vision or illumination
      */
     bright: number;
+
     /**
      * The coloration technique applied in the shader
      */
     coloration: number;
+
     /**
      * The amount of contrast this light applies to the background texture
      */
     contrast: number;
+
     /**
      * The allowed radius of dim vision or illumination
      */
     dim: number;
+
     /**
      * Strength of the attenuation between bright, dim, and dark
      */
     attenuation: number;
+
     /**
      * The luminosity applied in the shader
      */
     luminosity: number;
+
     /**
      * The amount of color saturation this light applies to the background texture
      */
     saturation: number;
+
     /**
      * The depth of shadows this light applies to the background texture
      */
     shadows: number;
+
     /**
      * Whether or not this source provides a source of vision
      */
     vision: boolean;
+
     /**
      * Strength of this source to beat or not negative/positive sources
      */
     priority: number;
   }
 }
 
+declare abstract class AnyBaseLightSource extends BaseLightSource {
+  constructor(arg0: never, ...args: never[]);
+}
+
 export default BaseLightSource;

src/foundry/client-esm/canvas/sources/global-light-source.d.mts

@@ -26,16 +26,18 @@ export default class GlobalLightSource extends BaseLightSource {
    * }
    * ```
    */
-  static override defaultData: BaseLightSource.LightSourceData;
+  static override defaultData: BaseLightSource.SourceData;
 
   /**
    * Name of this global light source.
-   * @defaultValue GlobalLightSource.sourceType
+   * @defaultValue `GlobalLightSource.sourceType`
    */
   name: string;
 
   /**
    * A custom polygon placeholder.
+   * @defaultValue `null`
+   * @remarks This is not set anywhere in Foundry code, so will always be null barring system/module/user action
    */
   customPolygon: PIXI.Polygon | number[] | null;
 
@@ -44,4 +46,6 @@ export default class GlobalLightSource extends BaseLightSource {
   override _initializeSoftEdges(): void;
 
   override _updateGeometry(): void;
+
+  override _updateCommonUniforms(shader: AbstractBaseShader): void;
 }