@league-of-foundry-developers/foundry-vtt-types 13.340.1 → 13.345.1-beta.20250704.94554

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

@@ -0,0 +1,297 @@
+import type { IntentionalPartial, AnyObject, Identity, InexactPartial } from "#utils";
+import type * as placeables from "#client/canvas/placeables/_module.d.mts";
+import type { EnvironmentCanvasGroup } from "#client/canvas/groups/_module.d.mts";
+import type { Canvas } from "#client/canvas/_module.d.mts";
+
+/**
+ * TODO - Re-document after ESM refactor.
+ * An abstract base class which defines a framework for effect sources which originate radially from a specific point.
+ * This abstraction is used by the LightSource, VisionSource, SoundSource, and MovementSource subclasses.
+ *
+ * @example A standard PointSource lifecycle:
+ * ```js
+ * const source = new PointSource({object}); // Create the point source
+ * source.initialize(data);                  // Configure the point source with new data
+ * source.refresh();                         // Refresh the point source
+ * source.destroy();                         // Destroy the point source
+ * ```
+ * @privateRemarks The TODO is foundry's
+ */
+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
+   */
+  constructor(options?: BaseEffectSource.ConstructorOptions);
+
+  /**
+   * The type of source represented by this data structure.
+   * Each subclass must implement this attribute.
+   * @remarks Effectively abstract, must be defined by subclasses; `undefined` in `BaseEffectSource`
+   */
+  static sourceType: string | undefined;
+
+  /**
+   * The target collection into the effects canvas group.
+   * @abstract
+   * @remarks Is `undefined` in `BaseEffectSource`
+   */
+  static effectsCollection: string | undefined;
+
+  /**
+   * Effect source default data.
+   * @defaultValue
+   * ```js
+   * {
+   *   x: 0,
+   *   y: 0,
+   *   elevation: 0,
+   *   disabled: false
+   * }
+   * ```
+   */
+  static defaultData: BaseEffectSource.SourceData;
+
+  /**
+   * Some other object which is responsible for this source.
+   * @privateRemarks see {@linkcode BaseEffectSource.ConstructorOptions.object}
+   */
+  // TODO: 4th type param for this?
+  object: placeables.PlaceableObject.Any | EnvironmentCanvasGroup.Any | null;
+
+  /**
+   * The source id linked to this effect source.
+   * @remarks Foundry types this as Readonly<string>, but does nothing to that effect at runtime
+   */
+  sourceId: string | undefined;
+
+  /**
+   * The data of this source.
+   */
+  data: SourceData;
+
+  /**
+   * The geometric shape of the effect source which is generated later.
+   * @remarks This is `undefined` prior to the first call to {@linkcode BaseEffectSource.initialize | BaseEffectSource#Initialize}
+   *
+   * Only ever `number[]` in {@linkcode foundry.canvas.sources.GlobalLightSource}, and only if
+   * {@linkcode foundry.canvas.sources.GlobalLightSource.customPolygon | #customPolygon} is set
+   * to a `number[]` before initialization.
+   */
+  shape: SourceShape | number[] | undefined;
+
+  /**
+   * A collection of boolean flags which control rendering and refresh behavior for the source.
+   * @defaultValue `{}`
+   */
+  protected _flags: BaseEffectSource.Flags;
+
+  /**
+   * The x-coordinate of the point source origin.
+   */
+  get x(): number;
+
+  /**
+   * The y-coordinate of the point source origin.
+   */
+  get y(): number;
+
+  /**
+   * The elevation bound to this source.
+   */
+  get elevation(): number;
+
+  /**
+   * The EffectsCanvasGroup collection linked to this effect source.
+   */
+  get effectsCollection(): Collection<this>;
+
+  /**
+   * Returns the update ID associated with this source.
+   * The update ID is increased whenever the shape of the source changes.
+   */
+  get updateId(): number;
+
+  /**
+   * Is this source currently active?
+   * A source is active if it is attached to an effect collection and is not disabled or suppressed.
+   */
+  get active(): boolean;
+
+  /**
+   * Is this source attached to an effect collection?
+   */
+  get attached(): boolean;
+
+  /**
+   * Is this source temporarily suppressed?
+   */
+  get suppressed(): boolean;
+
+  /**
+   * Records of suppression strings with a boolean value.
+   * If any of this record is true, the source is suppressed.
+   * @defaultValue `{}`
+   */
+  suppression: Record<string, boolean>;
+
+  /**
+   * Initialize and configure the source using provided data.
+   * @param data    - Provided data for configuration
+   * @param options - Additional options which modify source initialization
+   * @returns The initialized source
+   * @privateRemarks This should be returning `this`, but allowing the Initialized overrides requires returning a specific class
+   */
+  initialize(
+    data?: InexactPartial<SourceData>,
+    options?: BaseEffectSource.InitializeOptions,
+  ): BaseEffectSource<SourceData, SourceShape>;
+
+  /**
+   * Subclass specific data initialization steps.
+   * @param data - Provided data for configuration
+   */
+  protected abstract _initialize(
+    /** @privateRemarks `IntentionalPartial` because `#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. */
+  protected abstract _createShapes(): void;
+
+  /**
+   * 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 Not actually abstract, but is a no-op in `BaseEffectSource`
+   * @privateRemarks This is actually passed *flattened* partial data, and while we were very close to having
+   * that be a non-issue, `RenderedEffectSource`'s data's `animation` and `GlobalLightSource`'s `darkness`
+   * properties are objects, so this can't just be `IntentionalPartial<SourceData>` until we have a `Flatten<>`
+   * type.
+   */
+  // TODO: Flatten<IntentionalPartial<SourceData>>
+  protected _configure(changes: AnyObject): void;
+
+  /**
+   * Refresh the state and uniforms of the source.
+   * Only active sources are refreshed.
+   */
+  refresh(): void;
+
+  /**
+   * Subclass-specific refresh steps.
+   */
+  protected _refresh(): void;
+
+  /**
+   * Steps that must be performed when the source is destroyed.
+   */
+  destroy(): void;
+
+  /**
+   * Subclass specific destruction steps.
+   */
+  protected _destroy(): void;
+
+  /**
+   * Add this BaseEffectSource instance to the active collection.
+   * @remarks
+   * @throws If this Source doesn't have a {@linkcode sourceId}
+   */
+  add(): void;
+
+  /**
+   * Remove this BaseEffectSource instance from the active collection.
+   */
+  remove(): void;
+
+  /**
+   * Test whether the point is contained within the shape of the source.
+   * @param point - The point.
+   * @returns Is inside the source?
+   */
+  testPoint(point: Canvas.ElevatedPoint): boolean;
+
+  #BaseEffectSource: true;
+}
+
+declare namespace BaseEffectSource {
+  interface Any extends AnyBaseEffectSource {}
+  interface AnyConstructor extends Identity<typeof AnyBaseEffectSource> {}
+
+  /** @internal */
+  type _ConstructorOptions = InexactPartial<{
+    /**
+     * An optional PlaceableObject which is responsible for this source
+     * @remarks The {@linkcode EnvironmentCanvasGroup} passes itself when creating the global light source during its construction,
+     * as an exception to Foundry's typing of just {@linkcode PlaceableObject}. Otherwise, is only ever {@linkcode placeables.AmbientLight | AmbientLight},
+     * {@linkcode placeables.AmbientSound | AmbientSound}, or {@linkcode placeables.Token | Token} in Foundry usage
+     */
+    object: placeables.PlaceableObject.Any | EnvironmentCanvasGroup.Any;
+
+    /**
+     * 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 **was** only inferred if you passed a `PlaceableObject`
+     * _instead_ of an options object to the constructor (which was a deprecated path removed in v13),
+     * _not_ if you pass in `{ object: PlaceableObject }`, where you're expected to also pass `sourceId`
+     * yourself, if you want it to be {@linkcode BaseEffectSource.add | added} to its
+     * {@linkcode BaseEffectSource.effectsCollection | #effectsCollection}
+     */
+    sourceId: string;
+  }>;
+
+  interface ConstructorOptions extends _ConstructorOptions {}
+
+  interface SourceData {
+    /**
+     * The x-coordinate of the source location
+     * @defaultValue `0`
+     */
+    x: number;
+
+    /**
+     * The y-coordinate of the source location
+     * @defaultValue `0`
+     */
+    y: number;
+
+    /**
+     * The elevation of the point source
+     * @defaultValue `0`
+     */
+    elevation: number;
+
+    /**
+     * Whether or not the source is disabled
+     * @defaultValue `false`
+     */
+    disabled: boolean;
+  }
+
+  /** @internal */
+  type _InitializeOptions = InexactPartial<{
+    /**
+     * Should source data be reset to default values before applying changes?
+     * @defaultValue `false`
+     */
+    reset: boolean;
+  }>;
+
+  interface InitializeOptions extends _InitializeOptions {}
+
+  /** @privateRemarks The `| number` is from Foundry's typing, but core only uses boolean flags in v12.331 */
+  interface Flags extends Record<string, boolean | number | undefined> {
+    renderSoftEdges?: boolean;
+    initializedMeshes?: boolean;
+    hasColor?: boolean;
+  }
+}
+
+export default BaseEffectSource;
+
+declare abstract class AnyBaseEffectSource extends BaseEffectSource<BaseEffectSource.SourceData, PIXI.Polygon> {
+  constructor(...args: never);
+}

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

@@ -0,0 +1,306 @@
+import type { Identity, InexactPartial, IntentionalPartial } from "#utils";
+import type RenderedEffectSource from "./rendered-effect-source.d.mts";
+import type BaseEffectSource from "./base-effect-source.d.mts";
+import type { AbstractBaseShader } from "#client/canvas/rendering/shaders/_module.d.mts";
+
+/**
+ * A specialized subclass of BaseEffectSource which deals with the rendering of light or darkness.
+ */
+declare abstract class BaseLightSource<
+  SourceData extends BaseLightSource.SourceData = BaseLightSource.SourceData,
+  SourceShape extends PIXI.Polygon = PIXI.Polygon,
+  RenderingLayers extends Record<string, RenderedEffectSource.LayerConfig> = BaseLightSource.Layers,
+> extends RenderedEffectSource<SourceData, SourceShape, RenderingLayers> {
+  /**
+   * @defaultValue `"light"`
+   * @privateRemarks left `string` here, with a real and fake override in {@linkcode foundry.canvas.sources.PointDarknessSource | PointDarknessSource}
+   * and {@linkcode foundry.canvas.sources.PointLightSource | PointLightSource} respectively
+   */
+  static override sourceType: string;
+
+  /** @defaultValue `["animation.type", "walls"]` */
+  protected static override _initializeShaderKeys: string[];
+
+  /**
+   * @defaultValue
+   * ```js
+   * [
+   *   "dim",
+   *   "bright",
+   *   "attenuation",
+   *   "alpha",
+   *   "coloration",
+   *   "color",
+   *   "contrast",
+   *   "saturation",
+   *   "shadows",
+   *   "luminosity",
+   * ]
+   * ```
+   */
+  protected static override _refreshUniformsKeys: string[];
+
+  /**
+   * The corresponding lighting levels for dim light.
+   * @defaultValue `CONST.LIGHTING_LEVELS.DIM`
+   */
+  protected static _dimLightingLevel: CONST.LIGHTING_LEVELS;
+
+  /**
+   * The corresponding lighting levels for bright light.
+   * @defaultValue `CONST.LIGHTING_LEVELS.BRIGHT`
+   */
+  protected static _brightLightingLevel: CONST.LIGHTING_LEVELS;
+
+  /**
+   * The corresponding animation config.
+   * @privateRemarks Only uses {@linkcode CONFIG.Canvas.lightAnimations} in {@linkcode BaseLightSource}, but
+   * {@linkcode foundry.canvas.sources.PointDarknessSource | PointDarknessSource} overrides to use
+   * `.darknessAnimations`, so the union is necessary
+   */
+  protected static get ANIMATIONS(): typeof CONFIG.Canvas.lightAnimations | typeof CONFIG.Canvas.darknessAnimations;
+
+  /**
+   * @defaultValue
+   * ```js
+   * {
+   *   background: {
+   *     defaultShader: AdaptiveBackgroundShader,
+   *     blendMode: "MAX_COLOR",
+   *   },
+   *   coloration: {
+   *     defaultShader: AdaptiveColorationShader,
+   *     blendMode: "SCREEN",
+   *   },
+   *   illumination: {
+   *     defaultShader: AdaptiveIlluminationShader,
+   *     blendMode: "MAX_COLOR",
+   *   },
+   * }
+   * ```
+   */
+  protected static override get _layers(): Record<string, RenderedEffectSource.LayerConfig>;
+
+  /**
+   * @defaultValue
+   * ```js
+   * {
+   *   ...super.defaultData,
+   *   priority: 0,
+   *   alpha: 0.5,
+   *   bright: 0,
+   *   coloration: 1,
+   *   contrast: 0,
+   *   dim: 0,
+   *   attenuation: 0.5,
+   *   luminosity: 0.5,
+   *   saturation: 0,
+   *   shadows: 0,
+   *   vision: false
+   * }
+   * ```
+   * @remarks See {@linkcode RenderedEffectSource.defaultData}
+   */
+  static override defaultData: BaseLightSource.SourceData;
+
+  /**
+   * A ratio of dim:bright as part of the source radius
+   * @defaultValue `1`
+   * @remarks Nothing in `BaseLightSource` or its subclasses sets this except {@linkcode foundry.canvas.sources.PointLightSource._configure | PointLightSource#_configure};
+   * for all other subclasses it is always `1`
+   */
+  ratio: number;
+
+  /**
+   * @privateRemarks Fake override to account for losing the ability to return `this` in {@linkcode BaseEffectSource.initialize | BaseEffectSource} and
+   * still have Initialized overrides. `BaseLightSource` has no properties that change type when initialized, as it doesn't implement `#_createShapes`
+   */
+  override initialize(
+    data?: InexactPartial<SourceData>,
+    options?: BaseEffectSource.InitializeOptions,
+  ): BaseLightSource<SourceData, SourceShape, RenderingLayers>;
+
+  protected override _initialize(data: IntentionalPartial<SourceData>): void;
+
+  protected override _updateColorationUniforms(): void;
+
+  protected override _updateIlluminationUniforms(): void;
+
+  protected override _updateBackgroundUniforms(): void;
+
+  protected override _updateCommonUniforms(shader: AbstractBaseShader): void;
+
+  /** @remarks Doesn't exist prior to initialization, but not guaranteed to exist after either. Ultimately set in {@linkcode BaseLightSource._updateCommonUniforms | #_updateCommonUniforms} */
+  cachedAttenuation?: number;
+
+  /** @remarks Doesn't exist prior to initialization, but not guaranteed to exist after either. Ultimately set in {@linkcode BaseLightSource._updateCommonUniforms | #_updateCommonUniforms} */
+  computedAttenuation?: 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?: RenderedEffectSource.AnimationFunctionOptions): void;
+
+  /**
+   * An animation with flickering ratio and light intensity
+   * @param dt      - Delta time
+   * @param options - Additional options which modify the flame animation
+   */
+  animateFlickering(dt: number, options?: BaseLightSource.AnimateFlickeringOptions): void;
+
+  /**
+   * 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?: RenderedEffectSource.AnimationFunctionOptions): void;
+
+  /**
+   * A sound-reactive animation that uses bass/mid/treble blending to control certain shader uniforms.
+   * "speed" is interpreted as how quickly we adapt to changes in audio. No time-based pulsing is used by default,
+   * but we incorporate dt into smoothing so that behavior is consistent across varying frame rates.
+   *
+   * @param dt      - The delta time since the last frame, in milliseconds.
+   * @param options - Additional options for customizing the audio reaction.
+   */
+  animateSoundPulse(dt: number, options?: BaseLightSource.AnimateSoundPulseOptions): void;
+
+  /**
+   * /**
+   * @deprecated "`BaseLightSource#isDarkness` is now obsolete. Use {@linkcode foundry.canvas.sources.PointDarknessSource | PointDarknessSource} instead." (since v12, until v14)
+   * @remarks Always returns `false`, typed as `boolean` to allow `PointDarknessSource` override
+   */
+  get isDarkness(): boolean;
+
+  #BaseLightSource: true;
+}
+
+declare namespace BaseLightSource {
+  interface Any extends AnyBaseLightSource {}
+  interface AnyConstructor extends Identity<typeof AnyBaseLightSource> {}
+
+  /** @remarks See {@linkcode BaseLightSource._layers} */
+  // Interface would require `RenderingLayers extends ... = InterfaceToObject<Layers>` in every subclass signature
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+  type Layers = {
+    background: RenderedEffectSource.SourceLayer;
+    coloration: RenderedEffectSource.SourceLayer;
+    illumination: RenderedEffectSource.SourceLayer;
+  };
+
+  type LightAnimationFunction = (
+    this: BaseLightSource.Any,
+    dt: number,
+    options?: RenderedEffectSource.AnimationFunctionOptions,
+  ) => void;
+
+  interface SourceData extends RenderedEffectSource.SourceData {
+    /**
+     * An opacity for the emitted light, if any
+     * @defaultValue `0.5`
+     */
+    alpha: number;
+
+    /**
+     * The allowed radius of bright vision or illumination
+     * @defaultValue `0`
+     */
+    bright: number;
+
+    /**
+     * The coloration technique applied in the shader
+     * @defaultValue `1`
+     */
+    coloration: number;
+
+    /**
+     * The amount of contrast this light applies to the background texture
+     * @defaultValue `0`
+     */
+    contrast: number;
+
+    /**
+     * The allowed radius of dim vision or illumination
+     * @defaultValue `0`
+     */
+    dim: number;
+
+    /**
+     * Strength of the attenuation between bright, dim, and dark
+     * @defaultValue `0.5`
+     */
+    attenuation: number;
+
+    /**
+     * The luminosity applied in the shader
+     * @defaultValue `0.5`
+     */
+    luminosity: number;
+
+    /**
+     * The amount of color saturation this light applies to the background texture
+     * @defaultValue `0`
+     */
+    saturation: number;
+
+    /**
+     * The depth of shadows this light applies to the background texture
+     * @defaultValue `0`
+     */
+    shadows: number;
+
+    /**
+     * Whether or not this source provides a source of vision
+     * @defaultValue `false`
+     */
+    vision: boolean;
+  }
+
+  /** @internal */
+  type _AnimateFlickeringOptions = InexactPartial<{
+    /**
+     * Noise amplification (\>1) or dampening (\<1)
+     * @defaultValue `1`
+     */
+    amplification: number;
+  }>;
+
+  interface AnimateFlickeringOptions extends RenderedEffectSource.AnimationFunctionOptions, _AnimateFlickeringOptions {}
+
+  /** @internal */
+  type _AnimateSoundPulseOptionsOptions = InexactPartial<{
+    /**
+     * A smoothing factor in `[0..10]`, effectively updates/second.
+     * @defaultValue `5`
+     */
+    speed: number;
+
+    /**
+     * A blend factor in `[0..10]` that transitions from bass (near `0`) to treble (near `10`)
+     * Mid frequencies dominate around `intensity=5`.
+     * @defaultValue `5`
+     */
+    intensity: number;
+
+    /**
+     * Whether to invert the final amplitude as 1 - amplitude.
+     * @defaultValue `false`
+     */
+    reverse: boolean;
+  }>;
+
+  /** @privateRemarks Different property descriptions, otherwise identical to {@linkcode RenderedEffectSource.AnimationFunctionOptions} */
+  interface AnimateSoundPulseOptions extends _AnimateSoundPulseOptionsOptions {}
+}
+
+declare abstract class AnyBaseLightSource extends BaseLightSource<
+  BaseLightSource.SourceData,
+  PIXI.Polygon,
+  BaseLightSource.Layers
+> {
+  constructor(...args: never);
+}
+
+export default BaseLightSource;