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

package/src/foundry/client/canvas/perception/fog.d.mts

@@ -0,0 +1,157 @@
+import type EventEmitterMixin from "#common/utils/event-emitter.mjs";
+import type { FixedInstanceType, Identity } from "#utils";
+import type TextureExtractor from "#client/canvas/texture-extractor.d.mts";
+import type { SpriteMesh } from "#client/canvas/containers/_module.mjs";
+import type { CanvasVisibility } from "#client/canvas/groups/_module.d.mts";
+
+/**
+ * A fog of war management class which is the singleton canvas.fog instance.
+ */
+declare class FogManager extends EventEmitterMixin() {
+  /**
+   * The FogExploration document which applies to this canvas view
+   * @defaultValue `null`
+   */
+  exploration: FogExploration.Implementation | null;
+
+  /**
+   * Track whether we have pending fog updates which have not yet been saved to the database
+   * @defaultValue `false`
+   * @remarks Foundry marked `@internal`
+   */
+  protected _updated: boolean;
+
+  /**
+   * Texture extractor
+   * @remarks Only `undefined` before first `#initialize()`ation. Set to `null` if {@linkcode TextureExtractor} creation fails, and will not retry from that state.
+   */
+  get extractor(): TextureExtractor | undefined | null;
+
+  /**
+   * Define the number of fog refresh needed before the fog texture is extracted and pushed to the server.
+   * @defaultValue `70`
+   */
+  static COMMIT_THRESHOLD: number;
+
+  /**
+   * The exploration SpriteMesh which holds the fog exploration texture.
+   */
+  get sprite(): SpriteMesh;
+
+  /**
+   * The configured options used for the saved fog-of-war texture.
+   * @remarks Only `undefined` prior to the first time the canvas visibility layer is `#draw()`n
+   */
+  get textureConfiguration(): CanvasVisibility.TextureConfiguration | undefined;
+
+  /**
+   * Does the currently viewed Scene support Token field of vision?
+   */
+  // TODO: make `Scene.Implementation["tokenVision"]` when docsv2 is done
+  get tokenVision(): boolean;
+
+  /**
+   * Does the currently viewed Scene support fog of war exploration?
+   */
+  // TODO: make `Scene.Implementation["fog"]["exploration"]` when docsv2 is done
+  get fogExploration(): boolean;
+
+  /**
+   * Create the exploration display object with or without a provided texture.
+   * @privateRemarks Despite Foundry only typing this as returning `DisplayObject` in 12.331, it always returns a `SpriteMesh`
+   */
+  protected _createExplorationObject(tex?: PIXI.Texture | PIXI.RenderTexture | null): SpriteMesh;
+
+  /**
+   * Initialize fog of war - resetting it when switching scenes or re-drawing the canvas
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Clear the fog and reinitialize properties (commit and save in non reset mode)
+   */
+  clear(): Promise<void>;
+
+  /**
+   * Once a new Fog of War location is explored, composite the explored container with the current staging sprite.
+   * Once the number of refresh is \> to the commit threshold, save the fog texture to the database.
+   */
+  commit(): void;
+
+  /**
+   * Load existing fog of war data from local storage and populate the initial exploration sprite
+   */
+  load(): Promise<PIXI.Texture | void>;
+
+  /**
+   * Dispatch a request to reset the fog of war exploration status for all users within this Scene.
+   * Once the server has deleted existing FogExploration documents, the _onReset handler will re-draw the canvas.
+   */
+  reset(): Promise<void>;
+
+  /**
+   * Request a fog of war save operation.
+   * Note: if a save operation is pending, we're waiting for its conclusion.
+   */
+  save(): Promise<void>;
+
+  /**
+   * Extract fog data as a base64 string
+   */
+  protected _extractBase64(): Promise<string>;
+
+  /**
+   * Prepare the data that will be used to update the FogExploration document.
+   * @param base64Image - The extracted base64 image data
+   * @returns Exploration data to update
+   */
+  protected _prepareFogUpdateData(base64Image: string): FogExploration.UpdateData;
+
+  /**
+   * If fog of war data is reset from the server, deactivate the current fog and initialize the exploration.
+   * @remarks Foundry marked `@internal`, called externally in the `fogReset` socket handler
+   */
+  protected _handleReset(): Promise<void>;
+
+  /**
+   * @deprecated since v11, will be removed in v13
+   * @remarks "pending is deprecated and redirected to the exploration container"
+   */
+  get pending(): CanvasVisibility["explored"];
+
+  /**
+   * @deprecated since v11, will be removed in v13
+   * @remarks "revealed is deprecated and redirected to the exploration container"
+   */
+  get revealed(): CanvasVisibility["explored"];
+
+  /**
+   * @deprecated since v11, will be removed in v13
+   * @remarks "update is obsolete and always returns true. The fog exploration does not record position anymore."
+   *
+   * Both parameters are unused
+   */
+  update(source: any, force?: boolean | null): true;
+
+  /**
+   * @deprecated since v11, will be removed in v13
+   * @remarks "resolution is deprecated and redirected to CanvasVisibility#textureConfiguration"
+   *
+   * Probable Bug Note: Returns the entire `textureConfiguration` object, not just its `resolution` property
+   */
+  get resolution(): CanvasVisibility["textureConfiguration"];
+}
+
+declare namespace FogManager {
+  interface Any extends AnyFogManager {}
+  interface AnyConstructor extends Identity<typeof AnyFogManager> {}
+
+  type ConfiguredClass = CONFIG["Canvas"]["fogManager"];
+  type ConfiguredInstance = FixedInstanceType<ConfiguredClass>;
+}
+
+export default FogManager;
+
+declare abstract class AnyFogManager extends FogManager {
+  constructor(...args: never);
+}

package/src/foundry/client/canvas/perception/perception-manager.d.mts

@@ -0,0 +1,163 @@
+import type { InterfaceToObject, NullishProps } from "#utils";
+import { RenderFlagsMixin, RenderFlags, RenderFlag } from "#client/canvas/interaction/_module.mjs";
+
+/**
+ * A helper class which manages the refresh workflow for perception layers on the canvas.
+ * This controls the logic which batches multiple requested updates to minimize the amount of work required.
+ * A singleton instance is available as {@link Canvas.perception | `Canvas#perception`}.
+ */
+declare class PerceptionManager extends RenderFlagsMixin() {
+  static RENDER_FLAGS: InterfaceToObject<PerceptionManager.RENDER_FLAGS>;
+
+  static RENDER_FLAG_PRIORITY: "PERCEPTION";
+
+  // Note: This isn't a "real" override but `renderFlags` is set corresponding to the
+  // `RENDER_FLAGS` and so it has to be adjusted here.
+  renderFlags: RenderFlags<PerceptionManager.RENDER_FLAGS>;
+
+  applyRenderFlags(): void;
+
+  /**
+   * Update perception manager flags which configure which behaviors occur on the next frame render.
+   * @param flags - Flag values (true) to assign where the keys belong to PerceptionManager.FLAGS
+   */
+  update(flags: PerceptionManager.PassableFlags): void;
+
+  /**
+   * A helper function to perform an immediate initialization plus incremental refresh.
+   */
+  initialize(): void;
+
+  /**
+   * @deprecated since v12, will be removed in v14
+   * @remarks "PerceptionManager#refresh is deprecated in favor of assigning granular \"refresh flags\""
+   */
+  refresh(): void;
+}
+
+declare namespace PerceptionManager {
+  interface Any extends AnyPerceptionManager {}
+  type AnyConstructor = typeof AnyPerceptionManager;
+
+  type PassableFlags = NullishProps<RenderFlags>;
+
+  type RenderFlags = RenderFlagsMixin.ToBooleanFlags<RENDER_FLAGS>;
+
+  interface RENDER_FLAGS {
+    /**
+     * Recompute intersections between all registered edges. See {@link CanvasEdges#refresh}.
+     * @defaultValue `{}`
+     */
+    refreshEdges: RenderFlag<this, "refreshEdges">;
+
+    /**
+     * Re-initialize the entire lighting configuration. An aggregate behavior
+     * which does no work directly but propagates to set several other flags.
+     * @defaultValue `{ propagate: ["initializeDarknessSources", "initializeLightSources"] }`
+     */
+    initializeLighting: RenderFlag<this, "initializeLighting">;
+
+    /** @defaultValue `{ propagate: ["refreshLighting", "refreshVision", "refreshEdges"] }` */
+    initializeDarknessSources: RenderFlag<this, "initializeDarknessSources">;
+
+    /** @defaultValue `{ propagate: ["refreshLighting", "refreshVision"] }` */
+    initializeLightSources: RenderFlag<this, "initializeLightSources">;
+
+    /**
+     * Refresh the rendered appearance of lighting
+     * @defaultValue `{ propagate: ["refreshLightSources"] }`
+     */
+    refreshLighting: RenderFlag<this, "refreshLighting">;
+
+    /**
+     * Update the configuration of light sources
+     * @defaultValue `{}`
+     */
+    refreshLightSources: RenderFlag<this, "refreshLightSources">;
+
+    /**
+     * Re-initialize the entire vision modes. See {@link CanvasVisibility#initializeVisionMode}.
+     * @defaultValue `{ propagate: ["refreshVisionSources", "refreshLighting", "refreshPrimary"] }`
+     */
+    initializeVisionModes: RenderFlag<this, "initializeVisionModes">;
+
+    /**
+     * Re-initialize the entire vision configuration. See {@link CanvasVisibility#initializeSources}.
+     * @defaultValue `{ propagate: ["initializeVisionModes", "refreshVision"] }`
+     */
+    initializeVision: RenderFlag<this, "initializeVision">;
+
+    /**
+     * Refresh the rendered appearance of vision
+     * @defaultValue `{ propagate: ["refreshVisionSources", "refreshOcclusionMask"] }`
+     */
+    refreshVision: RenderFlag<this, "refreshVision">;
+
+    /**
+     * Update the configuration of vision sources
+     * @defaultValue `{}`
+     */
+    refreshVisionSources: RenderFlag<this, "refreshVisionSources">;
+
+    /**
+     * Refresh the contents of the PrimaryCanvasGroup mesh
+     * @defaultValue `{}`
+     */
+    refreshPrimary: RenderFlag<this, "refreshPrimary">;
+
+    /**
+     * Refresh occlusion
+     * @defaultValue `{propagate: ["refreshOcclusionStates", "refreshOcclusionMask"] }`
+     */
+    refreshOcclusion: RenderFlag<this, "refreshOcclusion">;
+
+    /** @defaultValue `{}` */
+    refreshOcclusionStates: RenderFlag<this, "refreshOcclusionStates">;
+
+    /** @defaultValue `{}` */
+    refreshOcclusionMask: RenderFlag<this, "refreshOcclusionMask">;
+
+    /**
+     * Re-initialize the entire ambient sound configuration. See {@link SoundsLayer#initializeSources}.
+     * @defaultValue `{ propagate: ["refreshSounds"] }`
+     */
+    initializeSounds: RenderFlag<this, "initializeSounds">;
+
+    /**
+     * Refresh the audio state of ambient sounds
+     * @defaultValue `{}`
+     */
+    refreshSounds: RenderFlag<this, "refreshSounds">;
+
+    /**
+     * Apply a fade duration to sound refresh workflow
+     * @defaultValue `{}`
+     */
+    soundFadeDuration: RenderFlag<this, "soundFadeDuration">;
+
+    /**
+     * @defaultValue `{ propagate: ["refreshOcclusion"] }`
+     * @deprecated since v12, will be removed in v14
+     */
+    refreshTiles: RenderFlag<this, "refreshTiles">;
+
+    /**
+     * @defaultValue `{ propagate: ["initializeLighting", "initializeVision"] }`
+     * @deprecated since v12, will be removed in v14
+     */
+    identifyInteriorWalls: RenderFlag<this, "identifyInteriorWalls">;
+
+    /**
+     * @defaultValue `{ propagate: ["refreshVision"] }`
+     * @deprecated since v11, will be removed in v13
+     * @remarks In v12 the flag remains, but the static method it would have triggered was removed prematurely (was listed as until v13 in v11)
+     */
+    forceUpdateFog: RenderFlag<this, "forceUpdateFog">;
+  }
+}
+
+export default PerceptionManager;
+
+declare abstract class AnyPerceptionManager extends PerceptionManager {
+  constructor(...args: never);
+}

package/src/foundry/client/canvas/perception/vision-mode.d.mts

@@ -0,0 +1,249 @@
+import type { Brand, ConcreteKeys, InterfaceToObject, SimpleMerge } from "#utils";
+import type { fields } from "#common/data/_module.d.mts";
+import type { DataSchema } from "#common/data/fields.d.mts";
+import type { AbstractBaseShader } from "#client/canvas/rendering/shaders/_module.d.mts";
+import DataField = foundry.data.fields.DataField;
+import type DataModel from "#common/abstract/data.d.mts";
+import type PointVisionSource from "#client/canvas/sources/point-vision-source.d.mts";
+
+declare class ShaderField<
+  const Options extends ShaderField.Options = ShaderField.DefaultOptions,
+  const AssignmentType = ShaderField.AssignmentType<Options>,
+  const InitializedType = ShaderField.InitializedType<Options>,
+  const PersistedType extends typeof AbstractBaseShader | null | undefined = ShaderField.InitializedType<Options>,
+> extends foundry.data.fields.DataField<Options, AssignmentType, InitializedType, PersistedType> {
+  /**
+   * @defaultValue
+   * ```typescript
+   * const defaults = super._defaults;
+   * defaults.nullable = true;
+   * defaults.initial = undefined;
+   * return defaults;
+   * ```
+   */
+  static override get _defaults(): ShaderField.DefaultOptions;
+
+  // TODO: _cast blatantly breaks inheritance so this is difficult to work with
+
+  /** @remarks The value provided to a ShaderField must be an AbstractBaseShader subclass. */
+  override _cast(value: unknown): AssignmentType; // typeof AbstractBaseShader;
+}
+
+declare namespace ShaderField {
+  type Options = DataField.Options<typeof AbstractBaseShader>;
+
+  type DefaultOptions = SimpleMerge<
+    DataField.DefaultOptions,
+    {
+      nullable: true;
+      initial: undefined;
+    }
+  >;
+
+  /**
+   * A helper type for the given options type merged into the default options of the BooleanField class.
+   * @template Opts - the options that override the default options
+   */
+  type MergedOptions<Opts extends Options> = SimpleMerge<DefaultOptions, Opts>;
+
+  /**
+   * A shorthand for the assignment type of a BooleanField class.
+   * @template Opts - the options that override the default options
+   */
+  // eslint-disable-next-line @typescript-eslint/no-deprecated
+  type AssignmentType<Opts extends Options> = DataField.DerivedAssignmentType<
+    typeof AbstractBaseShader,
+    MergedOptions<Opts>
+  >;
+
+  /**
+   * A shorthand for the initialized type of a BooleanField class.
+   * @template Opts - the options that override the default options
+   */
+  type InitializedType<Opts extends Options> = DataField.DerivedInitializedType<
+    typeof AbstractBaseShader,
+    MergedOptions<Opts>
+  >;
+}
+
+/**
+ * A Vision Mode which can be selected for use by a Token.
+ * The selected Vision Mode alters the appearance of various aspects of the canvas while that Token is the POV.
+ */
+declare class VisionMode extends foundry.abstract.DataModel<
+  VisionMode.Schema,
+  DataModel.Any | null,
+  InterfaceToObject<VisionMode.ExtraConstructorOptions>
+> {
+  // A constructor override has been omitted as there are no typing changes
+
+  static defineSchema(): VisionMode.Schema;
+
+  /** The lighting illumination levels which are supported. */
+  static LIGHTING_LEVELS: typeof foundry.CONST.LIGHTING_LEVELS;
+
+  /**
+   * Flags for how each lighting channel should be rendered for the currently active vision modes:
+   * - Disabled: this lighting layer is not rendered, the shaders does not decide.
+   * - Enabled: this lighting layer is rendered normally, and the shaders can choose if they should be rendered or not.
+   * - Required: the lighting layer is rendered, the shaders does not decide.
+   */
+  static LIGHTING_VISIBILITY: VisionMode.LightingVisibility;
+
+  /**
+   * A flag for whether this vision source is animated
+   * @defaultValue `false`
+   */
+  animated: boolean;
+
+  /**
+   * Does this vision mode enable light sources?
+   * True unless it disables lighting entirely.
+   */
+  get perceivesLight(): boolean;
+
+  /**
+   * Special activation handling that could be implemented by VisionMode subclasses
+   * @param source - Activate this VisionMode for a specific source
+   */
+  _activate(source: PointVisionSource.Any): void;
+
+  /**
+   * Special deactivation handling that could be implemented by VisionMode subclasses
+   * @param source - Deactivate this VisionMode for a specific source
+   */
+  _deactivate(source: PointVisionSource.Any): void;
+
+  /**
+   * Special handling which is needed when this Vision Mode is activated for a VisionSource.
+   * @param source - Activate this VisionMode for a specific source
+   */
+  activate(source: PointVisionSource.Any): void;
+
+  /**
+   * Special handling which is needed when this Vision Mode is deactivated for a VisionSource.
+   * @param source - Deactivate this VisionMode for a specific source
+   */
+  deactivate(source: PointVisionSource.Any): void;
+
+  /**
+   * An animation function which runs every frame while this Vision Mode is active.
+   * @param dt - The deltaTime passed by the PIXI Ticker
+   * @remarks Calls `RenderedEffectSource#animateTime` with `this` set to this `VisionMode`
+   */
+  animate(dt: number): void;
+}
+
+declare namespace VisionMode {
+  interface Any extends AnyVisionMode {}
+  type AnyConstructor = typeof AnyVisionMode;
+
+  type ConfiguredModes = ConcreteKeys<CONFIG["Canvas"]["visionModes"]>;
+
+  type LIGHTING_VISIBILITY = Brand<number, "VisionMode.LIGHTING_VISIBILITY">;
+
+  interface ExtraConstructorOptions {
+    animated?: boolean | undefined | null;
+  }
+
+  interface LightingVisibility {
+    /** Disabled: this lighting layer is not rendered, the shaders does not decide. */
+    DISABLED: 0 & LIGHTING_VISIBILITY;
+
+    /** Enabled: this lighting layer is rendered normally, and the shaders can choose if they should be rendered or not. */
+    ENABLED: 1 & LIGHTING_VISIBILITY;
+
+    /** Required: the lighting layer is rendered, the shaders does not decide. */
+    REQUIRED: 2 & LIGHTING_VISIBILITY;
+  }
+
+  type ShaderSchema = fields.SchemaField<{
+    shader: ShaderField;
+    uniforms: fields.ObjectField;
+  }>;
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+  type LightingSchema = {
+    visibility: fields.NumberField;
+    postProcessingModes: fields.ArrayField<fields.StringField>;
+    uniforms: fields.ObjectField;
+  };
+
+  type LightingSchemaField = fields.SchemaField<LightingSchema>;
+
+  type LightingLevels = Record<foundry.CONST.LIGHTING_LEVELS, foundry.CONST.LIGHTING_LEVELS>;
+  type LightingMultipliers = Record<foundry.CONST.LIGHTING_LEVELS, number>;
+
+  interface Schema extends DataSchema {
+    id: fields.StringField<{ blank: false }>;
+    label: fields.StringField<{ blank: false }>;
+    tokenConfig: fields.BooleanField<{ initial: true }>;
+    canvas: fields.SchemaField<{
+      shader: ShaderField;
+      uniforms: fields.ObjectField;
+    }>;
+    lighting: fields.SchemaField<{
+      background: LightingSchemaField;
+      coloration: LightingSchemaField;
+      illumination: LightingSchemaField;
+      levels: fields.ObjectField<
+        {
+          validate: (o: unknown) => boolean;
+          validationError: "may only contain a mapping of keys from VisionMode.LIGHTING_LEVELS";
+        },
+        LightingLevels,
+        LightingLevels,
+        LightingLevels
+      >;
+      multipliers: fields.ObjectField<
+        {
+          validate: (o: unknown) => boolean;
+          validationError: "must provide a mapping of keys from VisionMode.LIGHTING_LEVELS to numeric multiplier values";
+        },
+        LightingMultipliers,
+        LightingMultipliers,
+        LightingMultipliers
+      >;
+    }>;
+    vision: fields.SchemaField<{
+      background: ShaderSchema;
+      coloration: ShaderSchema;
+      illumination: ShaderSchema;
+      darkness: fields.SchemaField<{
+        adaptive: fields.BooleanField<{ initial: true }>;
+      }>;
+      defaults: fields.SchemaField<{
+        color: fields.ColorField<{ required: false; initial: undefined }>;
+        attenuation: fields.AlphaField<{ required: false; initial: undefined }>;
+        brightness: fields.NumberField<{
+          required: false;
+          initial: undefined;
+          nullable: false;
+          min: -1;
+          max: 1;
+        }>;
+        saturation: fields.NumberField<{
+          required: false;
+          initial: undefined;
+          nullable: false;
+          min: -1;
+          max: 1;
+        }>;
+        contrast: fields.NumberField<{
+          required: false;
+          initial: undefined;
+          nullable: false;
+          min: -1;
+          max: 1;
+        }>;
+      }>;
+      preferred: fields.BooleanField<{ initial: false }>;
+    }>;
+  }
+}
+
+export { VisionMode as default, ShaderField };
+
+declare class AnyVisionMode extends VisionMode {
+  constructor(...args: never);
+}

package/src/foundry/client/canvas/placeables/_module.d.mts

@@ -0,0 +1,20 @@
+// In Foundry itself this file contains re-exports of these other modules.
+// Therefore it has a runtime effect and uses `.mjs` instead of `.d.mts`.
+// While `.mts` could work, to avoid `import-x/no-unresolved` from erroring `.mjs` is used.
+/* eslint-disable import-x/extensions */
+
+export * as types from "./_types.mjs";
+
+export * as regions from "./regions/_module.mjs";
+export * as tokens from "./tokens/_module.mjs";
+
+export { default as PlaceableObject } from "./placeable-object.mjs";
+export { default as Drawing } from "./drawing.mjs";
+export { default as Note } from "./note.mjs";
+export { default as Region } from "./region.mjs";
+export { default as Tile } from "./tile.mjs";
+export { default as Token } from "./token.mjs";
+export { default as MeasuredTemplate } from "./template.mjs";
+export { default as Wall } from "./wall.mjs";
+export { default as AmbientLight } from "./light.mjs";
+export { default as AmbientSound } from "./sound.mjs";

package/src/foundry/client/canvas/placeables/_types.d.mts

@@ -0,0 +1,16 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+
+// After seeing that none of these types add anything or are even exported a
+// very reasonable question may be: Why on earth does this file exist?
+//
+// Well this is the file in which Foundry defines these types. We don't house
+// them here because it has poor discoverability. It's also just nice to
+// have as reference to keep us synced with the latest version of Foundry.
+
+export {};
+
+type RingColorBand = foundry.canvas.placeables.tokens.TokenRing.ColorBand;
+
+type DynamicRingId = string;
+
+type RingData = foundry.canvas.placeables.tokens.TokenRing.RingData;