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

package/src/foundry/client/canvas/groups/canvas-group-mixin.d.mts

@@ -0,0 +1,178 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import type { FixedInstanceType, HandleEmptyObject, Identity, PrettifyType, RemoveIndexSignatures } from "#utils";
+import type { Canvas } from "#client/canvas/_module.d.mts";
+import type { CanvasLayer } from "#client/canvas/layers/_module.d.mts";
+
+declare const DynamicClass: new <_Computed extends object>(...args: never) => _Computed;
+
+// @ts-expect-error - This is a workaround to allow for dynamic top level properties in a class.
+declare class LayersClass<
+  Group extends CanvasGroupMixin.LayerGroup | NoLayerGroup,
+  Instance extends object = RemoveIndexSignatures<CanvasGroupMixin.LayersFor<Group>>,
+> extends DynamicClass<Instance> {}
+
+// Note(LukeAbby): This interface has been separated out to simplify the constructor edge cases.
+// By avoiding having the instance side it makes the class more malleable and allows generics.
+interface CanvasGroupStatic<Group extends CanvasGroupMixin.LayerGroup | NoLayerGroup> {
+  /**
+   * The name of this canvas group
+   * @remarks Foundry marked as abstract
+   */
+  groupName: Group extends NoLayerGroup ? undefined : Group;
+
+  /**
+   * If this canvas group should teardown non-layers children.
+   * @defaultValue `true`
+   */
+  tearDownChildren: boolean;
+}
+
+declare class CanvasGroup<
+  Group extends CanvasGroupMixin.LayerGroup | NoLayerGroup,
+  DrawOptions extends CanvasGroupMixin.DrawOptions = CanvasGroupMixin.DrawOptions,
+  TearDownOptions extends CanvasGroupMixin.TearDownOptions = CanvasGroupMixin.TearDownOptions,
+> extends LayersClass<Group> {
+  /** @privateRemarks All mixin classses should accept anything for its constructor. */
+  constructor(...args: any[]);
+
+  /** @defaultValue `true` */
+  sortableChildren: boolean;
+
+  /**
+   * The canonical name of the canvas group is the name of the constructor that is the immediate child of the defined base class.
+   */
+  get name(): string;
+
+  /**
+   * The name used by hooks to construct their hook string.
+   * Note: You should override this getter if hookName should not return the class constructor name.
+   */
+  get hookName(): string;
+
+  /**
+   * A mapping of CanvasLayer classes which belong to this group.
+   * @remarks Default value defined by this._createLayers, which is called in the constructor, and   pulls from CONFIG.Canvas.layers
+   */
+  layers: CanvasGroupMixin.LayersFor<Group>;
+
+  /**
+   * Create CanvasLayer instances which belong to the canvas group.
+   */
+  protected _createLayers(): CanvasGroupMixin.LayersFor<Group>;
+
+  /** Draw the canvas group and all its component layers. */
+  draw(options?: HandleEmptyObject<DrawOptions>): Promise<this>;
+
+  /**
+   * Draw the canvas group and all its component layers.
+   */
+  protected _draw(options?: HandleEmptyObject<DrawOptions>): Promise<void>;
+
+  /**
+   * Remove and destroy all layers from the base canvas.
+   */
+  tearDown(options: HandleEmptyObject<TearDownOptions>): Promise<this>;
+
+  /**
+   * Remove and destroy all layers from the base canvas.
+   */
+  protected _tearDown(options: HandleEmptyObject<TearDownOptions>): Promise<void>;
+}
+
+declare const _NoLayerGroup: unique symbol;
+type NoLayerGroup = typeof _NoLayerGroup;
+
+type ApplyGroup<
+  BaseClass extends CanvasGroupMixin.BaseClass,
+  Group extends CanvasGroupMixin.LayerGroup | NoLayerGroup,
+> = CanvasGroupStatic<Group> &
+  (new <DrawOptions extends CanvasGroupMixin.DrawOptions, TearDownOptions extends CanvasGroupMixin.TearDownOptions>(
+    ...args: ConstructorParameters<BaseClass>
+  ) => CanvasGroup<Group, DrawOptions, TearDownOptions> & FixedInstanceType<BaseClass>);
+
+/**
+ * A mixin which decorates any container with base canvas common properties.
+ * @param ContainerClass - The parent Container class being mixed.
+ */
+declare function CanvasGroupMixin<
+  BaseClass extends CanvasGroupMixin.BaseClass,
+  // In `_createLayers` the code assigns top level properties to the class.
+  // This is why Group exists.`
+  Group extends CanvasGroupMixin.LayerGroup | NoLayerGroup = NoLayerGroup,
+>(ContainerClass: BaseClass): CanvasGroupMixin.Mix<BaseClass, Group>;
+
+declare global {
+  /**
+   * @deprecated since v12, until 14
+   * @remarks "`BaseCanvasMixin` is deprecated in favor of {@linkcode foundry.canvas.groups.CanvasGroupMixin}"
+   */
+  const BaseCanvasMixin: typeof CanvasGroupMixin;
+}
+
+declare namespace CanvasGroupMixin {
+  // Note(LukeAbby): This doesn't just use `Mix` because piecing together an `AnyMixed` type is
+  // more subtle than typical here. Specifically
+  interface AnyMixedConstructor extends Identity<typeof AnyCanvasGroup> {}
+  interface AnyMixed extends AnyCanvasGroup {}
+
+  type BaseClass = PIXI.Container.AnyConstructor;
+
+  type Mix<
+    BaseClass extends CanvasGroupMixin.BaseClass,
+    Group extends CanvasGroupMixin.LayerGroup | NoLayerGroup,
+  > = BaseClass & ApplyGroup<BaseClass, Group>;
+
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface DrawOptions {}
+
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface TearDownOptions {}
+
+  interface Layers {
+    readonly [key: string]: CanvasLayer;
+  }
+
+  type LayerGroup = keyof CONFIG["Canvas"]["groups"];
+
+  type LayersFor<T extends LayerGroup | NoLayerGroup> = PrettifyType<
+    _FilterOutNever<{
+      readonly [K in keyof typeof Canvas.layers]: (typeof Canvas.layers)[K] extends {
+        readonly layerClass?: abstract new (...args: infer _1) => infer LayerInstance extends CanvasLayer;
+        readonly group?: T;
+      }
+        ? LayerInstance
+        : never;
+    }>
+  >;
+
+  /** @internal */
+  type _FilterOutNever<T> = {
+    [K in keyof T as [T[K]] extends [never] ? never : K]: T[K];
+  };
+
+  /**
+   * @deprecated Replaced by {@linkcode CanvasGroupMixin.Mix}.
+   */
+  export import Mixed = CanvasGroupMixin.Mix;
+}
+
+export default CanvasGroupMixin;
+
+declare abstract class InnerAnyCanvasGroup extends CanvasGroup<
+  NoLayerGroup,
+  CanvasGroupMixin.DrawOptions,
+  CanvasGroupMixin.TearDownOptions
+> {
+  constructor(...args: never);
+}
+
+declare class MixableContainer extends PIXI.Container {
+  constructor(...args: any[]);
+}
+
+declare const MergedCanvasGroup: typeof MixableContainer & typeof InnerAnyCanvasGroup & CanvasGroupStatic<any>;
+
+// Note(LukeAbby) It's more involved than typical to get a proper `AnyCanvasGroup` type because
+// static side and instance side have been split apart and mixing `PIXI.Container` has to be done
+// carefully.
+declare abstract class AnyCanvasGroup extends MergedCanvasGroup {}

package/src/foundry/client/canvas/groups/effects.d.mts

@@ -0,0 +1,248 @@
+import type { HandleEmptyObject, Identity, NullishProps } from "#utils";
+import type { Canvas } from "#client/canvas/_module.d.mts";
+import type { CanvasAnimation } from "#client/canvas/animation/_module.d.mts";
+import type { AbstractBaseShader } from "#client/canvas/rendering/shaders/_module.d.mts";
+import type { VisualEffectsMaskingFilter } from "#client/canvas/rendering/filters/_module.d.mts";
+import type { CanvasGroupMixin } from "#client/canvas/groups/_module.d.mts";
+import type * as layers from "#client/canvas/layers/_module.d.mts";
+
+declare module "#configuration" {
+  namespace Hooks {
+    interface CanvasGroupConfig {
+      EffectsCanvasGroup: EffectsCanvasGroup.Any;
+    }
+  }
+}
+
+/**
+ * A container group which contains visual effects rendered above the primary group.
+ *
+ * TODO:
+ *  The effects canvas group is now only performing shape initialization, logic that needs to happen at
+ *  the placeable or object level is now their burden.
+ *  - [DONE] Adding or removing a source from the EffectsCanvasGroup collection.
+ *  - [TODO] A change in a darkness source should re-initialize all overlaping light and vision source.
+ *
+ * ### Hook Events
+ * - {@linkcode hookEvents.lightingRefresh}
+ */
+declare class EffectsCanvasGroup<
+  DrawOptions extends EffectsCanvasGroup.DrawOptions = EffectsCanvasGroup.DrawOptions,
+  TearDownOptions extends EffectsCanvasGroup.TearDownOptions = EffectsCanvasGroup.TearDownOptions,
+> extends CanvasGroupMixin(PIXI.Container)<DrawOptions, TearDownOptions> {
+  /**
+   * Whether to currently animate light sources.
+   * @defaultValue `true`
+   */
+  animateLightSources: boolean;
+
+  /**
+   * Whether to currently animate vision sources.
+   * @defaultValue `true`
+   */
+  animateVisionSources: boolean;
+
+  /**
+   * A mapping of light sources which are active within the rendered Scene.
+   */
+  lightSources: Collection<foundry.canvas.sources.PointLightSource>;
+
+  /**
+   * A mapping of darkness sources which are active within the rendered Scene.
+   */
+  darknessSources: Collection<foundry.canvas.sources.PointDarknessSource>;
+
+  /**
+   * A Collection of vision sources which are currently active within the rendered Scene.
+   */
+  visionSources: Collection<foundry.canvas.sources.PointVisionSource.Any>;
+
+  /**
+   * A set of vision mask filters used in visual effects group
+   */
+  visualEffectsMaskingFilters: Set<VisualEffectsMaskingFilter>;
+
+  /**
+   * Iterator for all light and darkness sources.
+   */
+  allSources(): Generator<
+    foundry.canvas.sources.PointDarknessSource | foundry.canvas.sources.PointLightSource,
+    void,
+    undefined
+  >;
+
+  override _createLayers(): Record<string, layers.CanvasLayer>;
+
+  /**
+   * A layer of background alteration effects which change the appearance of the primary group render texture.
+   */
+  background: layers.CanvasBackgroundAlterationEffects;
+
+  /**
+   * A layer which adds illumination-based effects to the scene.
+   */
+  illumination: layers.CanvasIlluminationEffects;
+
+  /**
+   * A layer which adds color-based effects to the scene.
+   */
+  coloration: layers.CanvasColorationEffects;
+
+  /**
+   * A layer which adds darkness effects to the scene.
+   */
+  darkness: layers.CanvasDarknessEffects;
+
+  /**
+   * Clear all effects containers and animated sources.
+   */
+  clearEffects(): void;
+
+  protected override _draw(options: HandleEmptyObject<DrawOptions>): Promise<void>;
+
+  /**
+   * Initialize positive light sources which exist within the active Scene.
+   * Packages can use the "initializeLightSources" hook to programmatically add light sources.
+   */
+  initializeLightSources(): void;
+
+  /**
+   * Re-initialize the shapes of all darkness sources in the Scene.
+   * This happens before initialization of light sources because darkness sources contribute additional edges which
+   * limit perception.
+   * Packages can use the "initializeDarknessSources" hook to programmatically add darkness sources.
+   */
+  initializeDarknessSources(): void;
+
+  /**
+   * Refresh the state and uniforms of all light sources and darkness sources objects.
+   */
+  refreshLightSources(): void;
+
+  /**
+   * Refresh the state and uniforms of all VisionSource objects.
+   */
+  refreshVisionSources(): void;
+
+  /**
+   * Refresh the active display of lighting.
+   */
+  refreshLighting(): void;
+
+  /**
+   * Test whether the point is inside light.
+   * @param point     - The point.
+   * @param elevation - The elevation of the point.
+   * @returns Is inside light?
+   */
+  testInsideLight(point: Canvas.Point, elevation: number): boolean;
+
+  /**
+   * Test whether the point is inside darkness.
+   * @param point     - The point.
+   * @param elevation - The elevation of the point.
+   * @returns Is inside darkness?
+   * @remarks Foundry does not use the `elevation` parameter
+   */
+  testInsideDarkness(point: Canvas.Point, _elevation?: number): boolean;
+
+  /**
+   * Get the darkness level at the given point.
+   * @param point     - The point.
+   * @param elevation - The elevation of the point.
+   * @returns The darkness level.
+   */
+  getDarknessLevel(point: Canvas.Point, elevation: number): number;
+
+  override _tearDown(options: HandleEmptyObject<TearDownOptions>): Promise<void>;
+
+  /**
+   * Activate vision masking for visual effects
+   * @param enabled - Whether to enable or disable vision masking
+   *                  (default: `true`)
+   */
+  toggleMaskingFilters(enabled?: boolean): void;
+
+  /**
+   * Activate post-processing effects for a certain effects channel.
+   * @param filterMode          - The filter mode to target.
+   * @param postProcessingModes - The post-processing modes to apply to this filter.
+   * @param uniforms            - The uniforms to update.
+   */
+  activatePostProcessingFilters(
+    filterMode: VisualEffectsMaskingFilter.FILTER_MODES,
+    postProcessingModes?: VisualEffectsMaskingFilter.PostProcessModes,
+    uniforms?: AbstractBaseShader.Uniforms,
+  ): void;
+
+  /**
+   * Reset post-processing modes on all Visual Effects masking filters.
+   */
+  resetPostProcessingFilters(): void;
+
+  /**
+   * Activate light source animation for AmbientLight objects within this layer
+   */
+  activateAnimation(): void;
+
+  /**
+   * Deactivate light source animation for AmbientLight objects within this layer
+   */
+  deactivateAnimation(): void;
+
+  /**
+   * Animate a smooth transition of the darkness overlay to a target value.
+   * Only begin animating if another animation is not already in progress.
+   * @param target - The target darkness level between 0 and 1
+   * @returns A Promise which resolves once the animation is complete
+   */
+  animateDarkness(target?: number, options?: EffectsCanvasGroup.AnimateDarknessOptions): CanvasAnimation.AnimateReturn;
+
+  /**
+   * @deprecated since v12, until v14
+   * @remarks "EffectsCanvasGroup#visibility has been deprecated and moved to Canvas#visibility."
+   */
+  get visibility(): Canvas["visibility"];
+
+  /**
+   * @deprecated since v12, until v14
+   * @remarks "EffectsCanvasGroup#globalLightSource has been deprecated and moved to EnvironmentCanvasGroup#globalLightSource."
+   */
+  get globalLightSource(): Canvas["environment"]["globalLightSource"];
+
+  /**
+   * @deprecated since v12
+   * @remarks "EffectsCanvasGroup#updateGlobalLightSource has been deprecated and is part of EnvironmentCanvasGroup#initialize workflow."
+   */
+  updateGlobalLightSource(): void;
+}
+
+declare namespace EffectsCanvasGroup {
+  interface Any extends AnyEffectsCanvasGroup {}
+  interface AnyConstructor extends Identity<typeof AnyEffectsCanvasGroup> {}
+
+  /** @internal */
+  type _AnimateDarknessOptions = NullishProps<{
+    /**
+     * The desired animation time in milliseconds. Default is 10 seconds
+     * @defaultValue `10000`
+     * @remarks Only has a parameter default; `null` is effectively `0`, resulting in no animation, just instant darkness
+     */
+    duration: number;
+  }>;
+
+  interface AnimateDarknessOptions extends _AnimateDarknessOptions {}
+
+  interface DrawOptions extends CanvasGroupMixin.DrawOptions {}
+
+  interface TearDownOptions extends CanvasGroupMixin.TearDownOptions {}
+}
+
+export default EffectsCanvasGroup;
+
+declare abstract class AnyEffectsCanvasGroup extends EffectsCanvasGroup<
+  EffectsCanvasGroup.DrawOptions,
+  EffectsCanvasGroup.TearDownOptions
+> {
+  constructor(...args: never);
+}

package/src/foundry/client/canvas/groups/environment.d.mts

@@ -0,0 +1,137 @@
+import type { HandleEmptyObject, Identity, InexactPartial, NullishProps } from "#utils";
+import type { CanvasGroupMixin } from "#client/canvas/groups/_module.d.mts";
+
+declare module "#configuration" {
+  namespace Hooks {
+    interface CanvasGroupConfig {
+      EnvironmentCanvasGroup: EnvironmentCanvasGroup.Any;
+    }
+  }
+}
+
+/**
+ * A container group which contains the primary canvas group and the effects canvas group.
+ */
+declare class EnvironmentCanvasGroup<
+  DrawOptions extends EnvironmentCanvasGroup.DrawOptions = EnvironmentCanvasGroup.DrawOptions,
+  TearDownOptions extends EnvironmentCanvasGroup.TearDownOptions = EnvironmentCanvasGroup.TearDownOptions,
+> extends CanvasGroupMixin<typeof PIXI.Container, "environment">(PIXI.Container)<DrawOptions, TearDownOptions> {
+  /**
+   * The global light source attached to the environment
+   * @remarks This is `defineProperty`'d as non-writable and non-configurable at construction
+   */
+  readonly globalLightSource: foundry.canvas.sources.GlobalLightSource.ConfiguredInstance;
+
+  /**
+   * Should this group tear down its non-layer children?
+   * @defaultValue `false`
+   */
+  static override tearDownChildren: boolean;
+
+  /**
+   * Colors exposed by the manager.
+   * @remarks Properties here are only `undefined` prior to `#initialize`ation
+   */
+  colors: EnvironmentCanvasGroup.Colors;
+
+  /**
+   * Weights used by the manager to compute colors.
+   * @remarks Properties here are only `undefined` prior to `#initialize`ation
+   */
+  weights: EnvironmentCanvasGroup.Weights;
+
+  /**
+   * Get the darkness level of this scene.
+   */
+  get darknessLevel(): number;
+
+  protected override _draw(options: HandleEmptyObject<DrawOptions>): Promise<void>;
+
+  /**
+   * Initialize the scene environment options.
+   * @remarks `@fires PIXI.FederatedEvent type: "darknessChange" - event: {environmentData: {darknessLevel, priorDarknessLevel}}`
+   */
+  initialize(config?: EnvironmentCanvasGroup.InitializeOptions): void;
+
+  /**
+   * @deprecated since v12, will be removed in v14
+   * @remarks `"EnvironmentCanvasGroup#darknessPenalty is deprecated without replacement. The darkness penalty is no longer applied on light and vision sources."`
+   */
+  get darknessPenalty(): 0;
+}
+
+declare namespace EnvironmentCanvasGroup {
+  interface Any extends AnyEnvironmentCanvasGroup {}
+  interface AnyConstructor extends Identity<typeof AnyEnvironmentCanvasGroup> {}
+
+  interface DrawOptions extends CanvasGroupMixin.DrawOptions {}
+
+  interface TearDownOptions extends CanvasGroupMixin.TearDownOptions {}
+
+  type ColorKeys =
+    | "darkness"
+    | "halfdark"
+    | "background"
+    | "dim"
+    | "bright"
+    | "ambientBrightest"
+    | "ambientDaylight"
+    | "ambientDarkness"
+    | "sceneBackground"
+    | "fogExplored"
+    | "fogUnexplored";
+
+  interface Colors extends Record<EnvironmentCanvasGroup.ColorKeys, Color | undefined> {}
+
+  type WeightKeys = "dark" | "halfdark" | "dim" | "bright";
+
+  interface Weights extends Record<EnvironmentCanvasGroup.WeightKeys, number | undefined> {}
+
+  /** @internal */
+  type _InitializeOptions = NullishProps<{
+    /** The background canvas color */
+    backgroundColor: Color.Source;
+
+    /** The brightest ambient color */
+    brightestColor: Color.Source;
+
+    /** The color of darkness */
+    darknessColor: Color.Source;
+
+    /** The ambient daylight color */
+    daylightColor: Color.Source;
+
+    /** The color applied to explored areas */
+    fogExploredColor: Color.Source;
+
+    /** The color applied to unexplored areas */
+    fogUnexploredColor: Color.Source;
+
+    /**
+     * @deprecated since v12 until v14
+     * @remarks "config.darknessLevel parameter into EnvironmentCanvasGroup#initialize is deprecated.
+     * You should pass the darkness level into config.environment.darknessLevel"
+     * @privateRemarks [sic]
+     */
+    darknessLevel: number;
+  }> &
+    InexactPartial<{
+      /**
+       * The scene environment data
+       * @defaultValue `{}`
+       * @remarks Can't be `null` as it only has a parameter default and has properties accessed
+       */
+      environment: NullishProps<Scene.EnvironmentData>;
+    }>;
+
+  interface InitializeOptions extends _InitializeOptions {}
+}
+
+export default EnvironmentCanvasGroup;
+
+declare abstract class AnyEnvironmentCanvasGroup extends EnvironmentCanvasGroup<
+  EnvironmentCanvasGroup.DrawOptions,
+  EnvironmentCanvasGroup.TearDownOptions
+> {
+  constructor(...args: never);
+}

package/src/foundry/client/canvas/groups/hidden.d.mts

@@ -0,0 +1,65 @@
+import type { HandleEmptyObject, Identity } from "#utils";
+import type { CanvasGroupMixin } from "#client/canvas/groups/_module.d.mts";
+
+declare module "#configuration" {
+  namespace Hooks {
+    interface CanvasGroupConfig {
+      HiddenCanvasGroup: foundry.canvas.groups.HiddenCanvasGroup.Any;
+    }
+  }
+}
+
+/**
+ * A specialized canvas group for rendering hidden containers before all others (like masks).
+ */
+declare class HiddenCanvasGroup<
+  DrawOptions extends HiddenCanvasGroup.DrawOptions = HiddenCanvasGroup.DrawOptions,
+  TearDownOptions extends HiddenCanvasGroup.TearDownOptions = HiddenCanvasGroup.TearDownOptions,
+> extends CanvasGroupMixin<typeof PIXI.Container, "hidden">(PIXI.Container)<DrawOptions, TearDownOptions> {
+  /**
+   * @defaultValue `"none"`
+   */
+  override eventMode: PIXI.EventMode;
+
+  /**
+   * The container which hold masks.
+   */
+  masks: PIXI.Container;
+
+  /**
+   * Add a mask to this group.
+   * @param name          - Name of the mask.
+   * @param displayObject - Display object to add.
+   * @param position      - Position of the mask.
+   * @throws If `displayObject` doesn't implement a `clear` method, or if `name` is an empty string
+   * @remarks `position` is not used if fasley
+   */
+  addMask(name: string, displayObject: PIXI.DisplayObject, position?: number | null): void;
+
+  /**
+   * Invalidate the masks: flag them for rerendering.
+   */
+  invalidateMasks(): void;
+
+  protected override _draw(options: HandleEmptyObject<DrawOptions>): Promise<void>;
+
+  protected override _tearDown(options: HandleEmptyObject<TearDownOptions>): Promise<void>;
+}
+
+declare namespace HiddenCanvasGroup {
+  interface Any extends AnyHiddenCanvasGroup {}
+  interface AnyConstructor extends Identity<typeof AnyHiddenCanvasGroup> {}
+
+  interface DrawOptions extends CanvasGroupMixin.DrawOptions {}
+
+  interface TearDownOptions extends CanvasGroupMixin.TearDownOptions {}
+}
+
+export default HiddenCanvasGroup;
+
+declare abstract class AnyHiddenCanvasGroup extends HiddenCanvasGroup<
+  HiddenCanvasGroup.DrawOptions,
+  HiddenCanvasGroup.TearDownOptions
+> {
+  constructor(...args: never);
+}