@league-of-foundry-developers/foundry-vtt-types 9.280.1 → 12.331.2-beta

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

@@ -0,0 +1,250 @@
+import type { InexactPartial } from "../../../../types/utils.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 class BaseEffectSource<
+  SourceData extends BaseEffectSource.BaseEffectSourceData,
+  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.BaseEffectSourceOptions);
+
+  /**
+   * The type of source represented by this data structure.
+   * Each subclass must implement this attribute.
+   */
+  static sourceType: string;
+
+  /**
+   * The target collection into the effects canvas group.
+   */
+  static effectsCollection: string;
+
+  /**
+   * Effect source default data.
+   * @defaultValue
+   * ```js
+   * {
+   * x: 0,
+   * y: 0,
+   * elevation: 0,
+   * disabled: false
+   * }
+   * ```
+   */
+  static defaultData: BaseEffectSource.BaseEffectSourceData;
+
+  /**
+   * Some other object which is responsible for this source.
+   */
+  object: PlaceableObject | null;
+
+  /**
+   * The source id linked to this effect source.
+   */
+  readonly sourceId: string;
+
+  /**
+   * The data of this source.
+   */
+  data: SourceData;
+
+  /**
+   * The geometric shape of the effect source which is generated later.
+   */
+  shape: SourceShape;
+
+  /**
+   * A collection of boolean flags which control rendering and refresh behavior for the source.
+   */
+  protected _flags: Record<string, boolean | number>;
+
+  /**
+   * 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(): foundry.utils.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.
+   */
+  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
+   */
+  initialize(
+    data?: InexactPartial<SourceData>,
+    options?: InexactPartial<{
+      // The type def references a behaviors object that is not even passed into the function
+      /**
+       * Should source data be reset to default values before applying changes?
+       * @defaultValue `false`
+       */
+      reset?: boolean;
+    }>,
+  ): this;
+
+  /**
+   * Subclass specific data initialization steps.
+   * @param data - Provided data for configuration
+   */
+  _initialize(data: Partial<SourceData>): void;
+
+  /**
+   * Create the polygon shape (or shapes) for this source using configured data.
+   */
+  protected _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
+   */
+  protected _configure(changes: Partial<SourceData>): 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.
+   */
+  add(): void;
+
+  /**
+   * Remove this BaseEffectSource instance from the active collection.
+   */
+  remove(): void;
+
+  /**
+   * @deprecated since v11, will be removed in v13
+   * @remarks `"BaseEffectSource#sourceType is deprecated. Use BaseEffectSource.sourceType instead."`
+   */
+  get sourceType(): string;
+
+  /**
+   * @deprecated since v12, will be removed in v14
+   * @remarks `"BaseEffectSource#_createShape is deprecated in favor of BaseEffectSource#_createShapes."`
+   */
+  _createShape(): void;
+
+  /**
+   * @deprecated since v12, will be removed in v14
+   * @remarks `"BaseEffectSource#disabled is deprecated in favor of BaseEffectSource#data#disabled or BaseEffectSource#active depending on your use case."`
+   */
+  get disabled(): boolean;
+}
+
+declare namespace BaseEffectSource {
+  type AnyConstructor = typeof AnyBaseEffectSource;
+
+  interface BaseEffectSourceOptions {
+    /**
+     * An optional PlaceableObject which is responsible for this source
+     */
+    object?: PlaceableObject | undefined;
+    /**
+     * A unique ID for this source. This will be set automatically if an
+     * object is provided, otherwise is required.
+     */
+    sourceId?: string | undefined;
+  }
+
+  interface BaseEffectSourceData {
+    /**
+     * The x-coordinate of the source location
+     */
+    x: number;
+    /**
+     * The y-coordinate of the source location
+     */
+    y: number;
+    /**
+     * The elevation of the point source
+     */
+    elevation: number;
+    /**
+     * Whether or not the source is disabled
+     */
+    disabled: boolean;
+  }
+}
+
+declare abstract class AnyBaseEffectSource extends BaseEffectSource<any, any> {
+  constructor(arg0: never, ...args: never[]);
+}
+
+export default BaseEffectSource;

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

@@ -0,0 +1,159 @@
+import type { InexactPartial } from "../../../../types/utils.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,
+  SourceShape extends PIXI.Polygon = PIXI.Polygon,
+  RenderingLayers extends Record<string, RenderedEffectSource.RenderedEffectSourceLayer> = RenderedEffectSource.Layers,
+> extends RenderedEffectSource<SourceData, SourceShape, RenderingLayers> {
+  /** @defaultValue `"light"` */
+  static override sourceType: string;
+
+  /** @defaultValue `["animation.type", "walls"]` */
+  protected static override _initializeShaderKeys: string[];
+
+  /** @defaultValue `["dim", "bright", "attenuation", "alpha", "coloration", "color", "contrast", "saturation", "shadows", "luminosity"]` */
+  protected static override _refreshUniformsKeys: string[];
+
+  /**
+   * The corresponding lighting levels for dim light.
+   */
+  protected static _dimLightingLevel: foundry.CONST.LIGHTING_LEVELS;
+
+  /**
+   * The corresponding lighting levels for bright light.
+   */
+  protected static _brightLightingLevel: foundry.CONST.LIGHTING_LEVELS;
+
+  /**
+   * The corresponding animation config.
+   */
+  protected static get ANIMATIONS(): CONFIG.Canvas.LightSourceAnimationConfig;
+
+  /**
+   * @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
+   * }
+   * ```
+   */
+  static override defaultData: RenderedEffectSource.RenderedEffectSourceData;
+
+  /**
+   * A ratio of dim:bright as part of the source radius
+   */
+  ratio: number;
+
+  override _initialize(data: Partial<SourceData>): void;
+
+  override _updateColorationUniforms(): void;
+
+  override _updateIlluminationUniforms(): void;
+
+  override _updateBackgroundUniforms(): void;
+
+  override _updateCommonUniforms(shader: AbstractBaseShader): void;
+
+  /**
+   * 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;
+
+  /**
+   * 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?: InexactPartial<
+      RenderedEffectSource.AnimationOptions & {
+        /**
+         * Noise amplification (\>1) or dampening (\<1)
+         * @defaultValue `1`
+         */
+        amplification: number;
+      }
+    >,
+  ): 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?: InexactPartial<RenderedEffectSource.AnimationOptions>): void;
+
+  /**
+   * @deprecated since v12
+   */
+  get isDarkness(): boolean;
+}
+
+declare namespace BaseLightSource {
+  interface LightSourceData extends RenderedEffectSource.RenderedEffectSourceData {
+    /**
+     * 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;
+  }
+}
+
+export default BaseLightSource;

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

@@ -0,0 +1,47 @@
+import type BaseLightSource from "./base-light-source.d.mts";
+
+/**
+ * A specialized subclass of the BaseLightSource which is used to render global light source linked to the scene.
+ */
+export default class GlobalLightSource extends BaseLightSource {
+  /** @defaultValue `"GlobalLight"` */
+  static override sourceType: string;
+
+  /** @defaultValue `"lightSources"` */
+  static override effectsCollection: string;
+
+  /**
+   * @defaultValue
+   * ```js
+   * {
+   * ...super.defaultData,
+   * rotation: 0,
+   * angle: 360,
+   * attenuation: 0,
+   * priority: -Infinity,
+   * vision: false,
+   * walls: false,
+   * elevation: Infinity,
+   * darkness: {min: 0, max: 0}
+   * }
+   * ```
+   */
+  static override defaultData: BaseLightSource.LightSourceData;
+
+  /**
+   * Name of this global light source.
+   * @defaultValue GlobalLightSource.sourceType
+   */
+  name: string;
+
+  /**
+   * A custom polygon placeholder.
+   */
+  customPolygon: PIXI.Polygon | number[] | null;
+
+  override _createShapes(): void;
+
+  override _initializeSoftEdges(): void;
+
+  override _updateGeometry(): void;
+}

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

@@ -0,0 +1,77 @@
+import type BaseLightSource from "./base-light-source.d.mts";
+import type PointEffectSourceMixin from "./point-effect-source.d.mts";
+import type RenderedEffectSource from "./rendered-effect-source.d.mts";
+
+// TODO: Adjust after client/config.js is updated
+type LightSourceAnimationConfig = unknown;
+
+type DarknessSourceData = BaseLightSource.LightSourceData & PointEffectSourceMixin.PointEffectSourceData;
+
+// Interface causes errors
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+type DarknessLayers = {
+  darkness: RenderedEffectSource.RenderedEffectSourceLayer;
+};
+
+/**
+ * A specialized subclass of the BaseLightSource which renders a source of darkness as a point-based effect.
+ */
+export default class PointDarknessSource<
+  SourceData extends DarknessSourceData = DarknessSourceData,
+  SourceShape extends PointSourcePolygon = PointSourcePolygon,
+> extends PointEffectSourceMixin(BaseLightSource)<SourceData, SourceShape, DarknessLayers> {
+  /** @defaultValue `"darknessSources"` */
+  static override effectsCollection: string;
+
+  /** @defaultValue `LIGHTING_LEVELS.HALFDARK` */
+  static override _dimLightingLevel: foundry.CONST.LIGHTING_LEVELS;
+
+  /** @defaultValue `LIGHTING_LEVELS.DARKNESS` */
+  static override _brightLightingLevel: foundry.CONST.LIGHTING_LEVELS;
+
+  /** @defaultValue `CONFIG.Canvas.darknessAnimations` */
+  static get ANIMATIONS(): LightSourceAnimationConfig;
+
+  static override get _layers(): Record<string, foundry.canvas.sources.RenderedEffectSource.RenderedEffectLayerConfig>;
+
+  /**
+   * The optional geometric shape is solely utilized for visual representation regarding darkness sources.
+   * Used only when an additional radius is added for visuals.
+   */
+  protected _visualShape: SourceShape;
+
+  /**
+   * Padding applied on the darkness source shape for visual appearance only.
+   * Note: for now, padding is increased radius. It might evolve in a future release.
+   */
+  protected _padding: number;
+
+  /**
+   * The Edge instances added by this darkness source.
+   */
+  edges: foundry.canvas.edges.Edge[];
+
+  override _createShapes(): void;
+
+  override _configure(changes: Partial<SourceData>): void;
+
+  override _getPolygonConfiguration(): PointSourcePolygonConfig;
+
+  override _drawMesh(layerId: string): PIXI.Mesh | null;
+
+  override _updateGeometry(): void;
+
+  /**
+   * Update the uniforms of the shader on the darkness layer.
+   */
+  _updateDarknessUniforms(): void;
+
+  override _destroy(): void;
+
+  /**
+   * A convenience accessor to the darkness layer mesh.
+   * @deprecated since v12, until v14
+   * @remarks `"BaseLightSource#isDarkness is now obsolete. Use DarknessSource instead."`
+   */
+  get darkness(): PointSourceMesh;
+}

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

@@ -0,0 +1,93 @@
+import type { Mixin } from "../../../../types/utils.d.mts";
+import type BaseEffectSource from "./base-effect-source.d.mts";
+
+declare class PointEffectSource {
+  /** @privateRemarks All mixin classses should accept anything for its constructor. */
+  constructor(...args: any[]);
+
+  /**
+   * @defaultValue
+   * ```js
+   * {
+   * ...super.defaultData,
+   * radius: 0,
+   * externalRadius: 0,
+   * rotation: 0,
+   * angle: 360,
+   * walls: true
+   * }
+   * ```
+   */
+  static defaultData: PointEffectSourceMixin.PointEffectSourceData;
+
+  /**
+   * A convenience reference to the radius of the source.
+   */
+  get radius(): number;
+
+  _initialize(data: Partial<PointEffectSourceMixin.PointEffectSourceData>): void;
+
+  _initializeSoftEdges(): void;
+
+  /**
+   * Configure the parameters of the polygon that is generated for this source.
+   */
+  protected _getPolygonConfiguration(): PointSourcePolygonConfig;
+
+  _createShapes(): void;
+
+  _drawMesh(layerId: string): PIXI.Mesh | null;
+
+  _updateGeometry(): void;
+
+  /**
+   * @deprecated since v11, until v13
+   * @remarks `"The setter PointEffectSource#radius is deprecated. The radius should not be set anywhere except in PointEffectSource#_initialize."`
+   */
+  // eslint-disable-next-line @typescript-eslint/adjacent-overload-signatures
+  set radius(radius);
+
+  /**
+   * @deprecated since v11, until v13
+   * @remarks `"PointEffectSource#los is deprecated in favor of PointEffectSource#shape."`
+   * @privateRemarks Actual definition is get/set
+   */
+  los: PointSourcePolygon;
+}
+
+/**
+ * TODO - documentation required about what a PointEffectSource is.
+ * @privateRemarks the TODO is from foundry, update this class whenever the comments are done
+ */
+declare function PointEffectSourceMixin<BaseClass extends BaseEffectSource.AnyConstructor>(
+  Base: BaseClass,
+): Mixin<typeof PointEffectSource, BaseClass>;
+
+declare namespace PointEffectSourceMixin {
+  type AnyMixed = ReturnType<typeof PointEffectSourceMixin<BaseEffectSource.AnyConstructor>>;
+
+  interface PointEffectSourceData extends BaseEffectSource.BaseEffectSourceData {
+    /**
+     * The radius of the source
+     */
+    radius: number;
+    /**
+     * A secondary radius used for limited angles
+     */
+    externalRadius: number;
+    /**
+     * The angle of rotation for this point source
+     */
+    rotation: number;
+    /**
+     * The angle of emission for this point source
+     */
+    angle: number;
+    /**
+     * Whether or not the source is constrained by walls
+     */
+    walls: boolean;
+  }
+}
+
+export default PointEffectSourceMixin;

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

@@ -0,0 +1,43 @@
+import type BaseLightSource from "./base-light-source.d.mts";
+import type PointEffectSourceMixin from "./point-effect-source.d.mts";
+
+type LightSourceData = PointEffectSourceMixin.PointEffectSourceData & BaseLightSource.LightSourceData;
+
+/**
+ * A specialized subclass of the BaseLightSource which renders a source of light as a point-based effect.
+ */
+export default class PointLightSource<
+  SourceData extends LightSourceData = LightSourceData,
+  SourceShape extends PointSourcePolygon = PointSourcePolygon,
+> extends PointEffectSourceMixin(BaseLightSource)<SourceData, SourceShape> {
+  /** @defaultValue `"lightSources"` */
+  static override effectsCollection: string;
+
+  override _initialize(data: Partial<SourceData>): void;
+
+  override _createShapes(): void;
+
+  override _configure(changes: Partial<SourceData>): void;
+
+  override _getPolygonConfiguration(): PointSourcePolygonConfig;
+
+  /**
+   * Test whether this LightSource provides visibility to see a certain target object.
+   * @param config - The visibility test configuration
+   * @returns Is the target object visible to this source?
+   */
+  testVisibility(config: {
+    /** The sequence of tests to perform */
+    tests: CanvasVisibilityTest[];
+    /** The target object being tested */
+    object: PlaceableObject;
+  }): boolean;
+
+  /**
+   * Can this LightSource theoretically detect a certain object based on its properties?
+   * This check should not consider the relative positions of either object, only their state.
+   * @param target - The target object being tested
+   * @returns Can the target object theoretically be detected by this vision source?
+   */
+  _canDetectObject(target: PlaceableObject): boolean;
+}

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

@@ -0,0 +1,15 @@
+import type BaseEffectSource from "./base-effect-source.d.mts";
+import type PointEffectSourceMixin from "./point-effect-source.d.mts";
+
+type MovementSourceData = PointEffectSourceMixin.PointEffectSourceData & BaseEffectSource.BaseEffectSourceData;
+
+/**
+ * A specialized subclass of the BaseEffectSource which describes a movement-based source.
+ */
+export default class PointMovementSource<
+  SourceData extends MovementSourceData = MovementSourceData,
+  SourceShape extends PointSourcePolygon = PointSourcePolygon,
+> extends PointEffectSourceMixin(BaseEffectSource)<SourceData, SourceShape> {
+  /** @defaultValue `"move"` */
+  static override sourceType: string;
+}