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

package/src/foundry/client/pixi/layers/placeables/drawings.d.mts

@@ -0,0 +1,111 @@
+export {};
+
+declare global {
+  /**
+   * The DrawingsLayer subclass of PlaceablesLayer.
+   */
+  class DrawingsLayer<
+    DrawOptions extends DrawingsLayer.DrawOptions = DrawingsLayer.DrawOptions,
+    TearDownOptions extends CanvasLayer.TearDownOptions = CanvasLayer.TearDownOptions,
+  > extends PlaceablesLayer<"Drawing", DrawOptions, TearDownOptions> {
+    /**
+     * @privateRemarks This is not overridden in foundry but reflects the real behavior.
+     */
+    static get instance(): Canvas["drawings"];
+
+    /**
+     * @privateRemarks This is not overridden in foundry but reflects the real behavior.
+     */
+    override options: DrawingsLayer.LayerOptions;
+
+    /**
+     * @defaultValue
+     * ```
+     * mergeObject(super.layerOptions, {
+     *   name: "drawings"
+     *   controllableObjects: true,
+     *   rotatableObjects: true,
+     *   zIndex: 500
+     * })
+     * ```
+     */
+    static override get layerOptions(): DrawingsLayer.LayerOptions;
+
+    static override documentName: "Drawing";
+
+    /**
+     * The named game setting which persists default drawing configuration for the User
+     */
+    static DEFAULT_CONFIG_SETTING: "defaultDrawingConfig";
+
+    graphics: Collection<Drawing>;
+
+    override get hud(): Exclude<Canvas["hud"], undefined>["drawing"];
+
+    override get hookName(): string;
+
+    override getSnappedPoint(point: Canvas.Point): Canvas.Point;
+
+    /**
+     * Render a configuration sheet to configure the default Drawing settings
+     */
+    configureDefault(): void;
+
+    override _deactivate(): void;
+
+    override _draw(options?: DrawOptions): Promise<void>;
+
+    /**
+     * Get initial data for a new drawing.
+     * Start with some global defaults, apply user default config, then apply mandatory overrides per tool.
+     * @param origin - The initial coordinate
+     * @returns The new drawing data
+     * @remarks This is used from DrawingConfig and hence public on purpose.
+     */
+    _getNewDrawingData(origin: Canvas.Point): foundry.documents.BaseDrawing.ConstructorData;
+
+    protected override _onClickLeft(event: PIXI.FederatedEvent): void;
+
+    protected override _onClickLeft2(event: PIXI.FederatedEvent): void;
+
+    /**
+     * @throws A `DataModelValidationError` if document creation fails
+     */
+    protected override _onDragLeftStart(event: PIXI.FederatedEvent): void;
+
+    protected override _onDragLeftMove(event: PIXI.FederatedEvent): void;
+
+    /**
+     * Handling of mouse-up events which conclude a new object creation after dragging
+     * @remarks Foundry notes this as \@private
+     */
+    protected _onDragLeftDrop(event: PIXI.FederatedEvent): void;
+
+    protected override _onDragLeftCancel(event: PointerEvent): void;
+
+    protected override _onClickRight(event: PIXI.FederatedEvent): void;
+
+    /**
+     * Use an adaptive precision depending on the size of the grid
+     * @deprecated since v12 until v14
+     */
+    get gridPrecision(): 0 | 8 | 16;
+  }
+
+  namespace DrawingsLayer {
+    type AnyConstructor = typeof AnyDrawingsLayer;
+
+    interface DrawOptions extends CanvasLayer.DrawOptions {}
+
+    interface LayerOptions extends PlaceablesLayer.LayerOptions<"Drawing"> {
+      name: "drawings";
+      controllableObjects: true;
+      rotatableObjects: true;
+      zIndex: 500;
+    }
+  }
+}
+
+declare abstract class AnyDrawingsLayer extends DrawingsLayer {
+  constructor(arg0: never, ...args: never[]);
+}

package/src/foundry/client/pixi/layers/placeables/index.d.mts

@@ -0,0 +1,8 @@
+import "./drawings.d.mts";
+import "./lighting.d.mts";
+import "./notes.d.mts";
+import "./sounds.d.mts";
+import "./templates.d.mts";
+import "./tiles.d.mts";
+import "./tokens.d.mts";
+import "./walls.d.mts";

package/src/foundry/client/pixi/layers/placeables/lighting.d.mts

@@ -0,0 +1,83 @@
+export {};
+
+/**
+ * The Lighting Layer which ambient light sources as part of the CanvasEffectsGroup.
+ */
+declare global {
+  class LightingLayer<
+    DrawOptions extends LightingLayer.DrawOptions = LightingLayer.DrawOptions,
+    TearDownOptions extends LightingLayer.TearDownOptions = LightingLayer.TearDownOptions,
+  > extends PlaceablesLayer<"AmbientLight", DrawOptions, TearDownOptions> {
+    /**
+     * @privateRemarks This is not overridden in foundry but reflects the real behavior.
+     */
+    static get instance(): Canvas["lighting"];
+
+    static override documentName: "AmbientLight";
+
+    /**
+     * @privateRemarks This is not overridden in foundry but reflects the real behavior.
+     */
+    override options: LightingLayer.LayerOptions;
+
+    /**
+     * @defaultValue
+     * ```
+     * foundry.utils.mergeObject(super.layerOptions, {
+     *  name: "lighting",
+     *  rotatableObjects: true,
+     *  zIndex: 900
+     * })
+     * ```
+     */
+    static override get layerOptions(): LightingLayer.LayerOptions;
+
+    override get hookName(): string;
+
+    override _draw(options?: DrawOptions): Promise<void>;
+
+    override _tearDown(options?: TearDownOptions): Promise<void>;
+
+    /**
+     * Refresh the fields of all the ambient lights on this scene.
+     */
+    refreshFields(): void;
+
+    override _activate(): void;
+
+    protected override _canDragLeftStart(user: User.ConfiguredInstance, event: PIXI.FederatedEvent): boolean;
+
+    protected override _onDragLeftStart(event: PIXI.FederatedEvent): void;
+
+    protected override _onDragLeftMove(event: PIXI.FederatedEvent): void;
+
+    protected override _onDragLeftCancel(event: PointerEvent): void;
+
+    // @ts-expect-error Foundry is changing the return type here from Promise<PlaceableObject[]> to just Promise<AmbientLight>
+    protected _onMouseWheel(event: WheelEvent): ReturnType<AmbientLight.ConfiguredInstance["rotate"]>;
+
+    /**
+     * Actions to take when the darkness level of the Scene is changed
+     * @param event - An event
+     */
+    protected _onDarknessChange(event: PIXI.FederatedEvent): void;
+  }
+
+  namespace LightingLayer {
+    type AnyConstructor = typeof AnyLightingLayer;
+
+    interface DrawOptions extends PlaceablesLayer.DrawOptions {}
+
+    interface TearDownOptions extends PlaceablesLayer.TearDownOptions {}
+
+    interface LayerOptions extends PlaceablesLayer.LayerOptions<"AmbientLight"> {
+      name: "lighting";
+      rotatableObjects: true;
+      zIndex: 900;
+    }
+  }
+}
+
+declare abstract class AnyLightingLayer extends LightingLayer {
+  constructor(arg0: never, ...args: never[]);
+}

package/src/foundry/client/pixi/layers/placeables/notes.d.mts

@@ -0,0 +1,110 @@
+import type { InexactPartial } from "../../../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * The Notes Layer which contains Note canvas objects
+   */
+  class NotesLayer<
+    DrawOptions extends NotesLayer.DrawOptions = NotesLayer.DrawOptions,
+    TearDownOptions extends PlaceablesLayer.TearDownOptions = PlaceablesLayer.TearDownOptions,
+  > extends PlaceablesLayer<"Note", DrawOptions, TearDownOptions> {
+    /**
+     * @privateRemarks This is not overridden in foundry but reflects the real behavior.
+     */
+    static get instance(): Canvas["notes"];
+
+    /**
+     * @defaultValue
+     * ```
+     * foundry.utils.mergeObject(super.layerOptions, {
+     *  name: "notes",
+     *  zIndex: 800
+     * })
+     * ```
+     */
+    static override get layerOptions(): NotesLayer.LayerOptions;
+
+    /**
+     * @privateRemarks This is not overridden in foundry but reflects the real behavior.
+     */
+    override options: NotesLayer.LayerOptions;
+
+    static override documentName: "Note";
+
+    /**
+     * The named core setting which tracks the toggled visibility state of map notes
+     */
+    static TOGGLE_SETTING: "notesDisplayToggle";
+
+    override get hookName(): string;
+
+    override interactiveChildren: boolean;
+
+    override _deactivate(): void;
+
+    override _draw(options?: DrawOptions): Promise<void>;
+
+    /**
+     * Register game settings used by the NotesLayer
+     */
+    static registerSettings(): void;
+
+    /**
+     * Visually indicate in the Scene Controls that there are visible map notes present in the Scene.
+     */
+    hintMapNotes(): void;
+
+    /**
+     * Pan to a given note on the layer.
+     * @param note    - The note to pan to.
+     * @param options - Options which modify the pan operation.
+     * @returns A Promise which resolves once the pan animation has concluded.
+     */
+    panToNote(
+      note: Note,
+      /** @remarks Can't be NullishProps because `duration` is passed to `canvas.animatePan` which only provides a default for `undefined` with `{ duration=250 }`, and must be numeric */
+      options?: InexactPartial<{
+        /**
+         * The resulting zoom level.
+         * @defaultValue `1.5`
+         */
+        scale: number;
+
+        /**
+         * The speed of the pan animation in milliseconds.
+         * @defaultValue `250`
+         */
+        duration: number;
+      }>,
+    ): Promise<void>;
+
+    protected override _onClickLeft(event: PIXI.FederatedEvent): Promise<Note | void>;
+
+    /**
+     * Handle JournalEntry document drop data
+     */
+    protected _onDropData(event: DragEvent, data: NotesLayer.DropData): Promise<false | Note>;
+  }
+
+  namespace NotesLayer {
+    type AnyConstructor = typeof AnyNotesLayer;
+
+    interface DrawOptions extends PlaceablesLayer.DrawOptions {}
+
+    interface LayerOptions extends PlaceablesLayer.LayerOptions<"Note"> {
+      name: "notes";
+      zIndex: 800;
+    }
+
+    interface DropData<DocType extends "JournalEntry" | "JournalEntryPage" = "JournalEntry" | "JournalEntryPage">
+      extends Canvas.DropPosition {
+      type: DocType;
+      uuid: string;
+      anchor: DocType extends "JournalEntryPage" ? { name: string } : undefined;
+    }
+  }
+}
+
+declare abstract class AnyNotesLayer extends NotesLayer {
+  constructor(arg0: never, ...args: never[]);
+}

package/src/foundry/client/pixi/layers/placeables/sounds.d.mts

@@ -0,0 +1,320 @@
+import type { IntentionalPartial } from "../../../../../types/helperTypes.d.mts";
+import type { InexactPartial, NullishProps } from "../../../../../types/utils.d.mts";
+import type { AmbientSoundEffect } from "../../../../common/documents/_types.d.mts";
+
+declare global {
+  /**
+   * This Canvas Layer provides a container for AmbientSound objects.
+   */
+  class SoundsLayer<
+    DrawOptions extends SoundsLayer.DrawOptions = SoundsLayer.DrawOptions,
+    TearDownOptions extends SoundsLayer.TearDownOptions = SoundsLayer.TearDownOptions,
+  > extends PlaceablesLayer<"AmbientSound", DrawOptions, TearDownOptions> {
+    /**
+     * @privateRemarks This is not overridden in foundry but reflects the real behavior.
+     */
+    static get instance(): Canvas["sounds"];
+
+    /**
+     * Track whether to actively preview ambient sounds with mouse cursor movements
+     * @defaultValue `false`
+     */
+    livePreview: boolean;
+
+    /**
+     * A mapping of ambient audio sources which are active within the rendered Scene
+     * @defaultValue `new foundry.utils.Collection()`
+     */
+    sources: foundry.utils.Collection<foundry.canvas.sources.PointSoundSource>;
+
+    /**
+     * @privateRemarks This is not overridden in foundry but reflects the real behavior.
+     */
+    override options: SoundsLayer.LayerOptions;
+
+    /**
+     * @defaultValue
+     * ```
+     * foundry.utils.mergeObject(super.layerOptions, {
+     *  name: "sounds",
+     *  zIndex: 900
+     * })
+     * ```
+     * */
+
+    static override get layerOptions(): SoundsLayer.LayerOptions;
+
+    static override documentName: "AmbientSound";
+
+    override get hookName(): string;
+
+    override _draw(options?: DrawOptions): Promise<void>;
+
+    override _tearDown(options?: TearDownOptions): Promise<void>;
+
+    override _activate(): void;
+
+    /**
+     * Initialize all AmbientSound sources which are present on this layer
+     */
+    initializeSources(): void;
+
+    /**
+     * Update all AmbientSound effects in the layer by toggling their playback status.
+     * Sync audio for the positions of tokens which are capable of hearing.
+     * @param options - Additional options forwarded to AmbientSound synchronization
+     *                  (defaultValue: `{}`)
+     */
+    refresh(
+      options?: NullishProps<{
+        /**
+         * A duration in milliseconds to fade volume transition
+         */
+        fade: number;
+      }>,
+    ): number | void;
+
+    /**
+     * Preview ambient audio for a given mouse cursor position
+     * @param position - The cursor position to preview
+     */
+    previewSound(position: Canvas.Point): void;
+
+    /**
+     * Terminate playback of all ambient audio sources
+     */
+    stopAll(): void;
+
+    /**
+     * Get an array of listener positions for Tokens which are able to hear environmental sound.
+     */
+    getListenerPositions(): Canvas.Point[];
+
+    /**
+     * Sync the playing state and volume of all AmbientSound objects based on the position of listener points
+     * @param listeners - Locations of listeners which have the capability to hear
+     * @param options   - Additional options forwarded to AmbientSound synchronization
+     *                    (defaultValue: `{}`)
+     */
+    protected _syncPositions(
+      listeners: Canvas.Point[],
+      options?: NullishProps<{
+        /**
+         * A duration in milliseconds to fade volume transition
+         */
+        fade: number;
+      }>,
+    ): void;
+
+    /**
+     * Configure playback by assigning the muffled state and final playback volume for the sound.
+     * This method should mutate the config object by assigning the volume and muffled properties.
+     * @param config - A playback configuration object
+     */
+    protected _configurePlayback(config: SoundsLayer.AmbientSoundPlaybackConfig): void;
+
+    /**
+     * Actions to take when the darkness level of the Scene is changed
+     * @param  event - The darkness-changing event
+     */
+    protected _onDarknessChange(event: PIXI.FederatedEvent): void;
+
+    /**
+     * Play a one-shot Sound originating from a predefined point on the canvas.
+     * The sound plays locally for the current client only.
+     * To play a sound for all connected clients use SoundsLayer#emitAtPosition.
+     * @param src     - The sound source path to play
+     * @param origin  - The canvas coordinates from which the sound originates
+     * @param radius  - The radius of effect in distance units
+     * @param options - Additional options which configure playback
+     * @returns  A Promise which resolves to the played Sound, or null
+     *
+     * @example Play the sound of a trap springing
+     * ```js
+     * const src = "modules/my-module/sounds/spring-trap.ogg";
+     * const origin = {x: 5200, y: 3700};  // The origin point for the sound
+     * const radius = 30;                  // Audible in a 30-foot radius
+     * await canvas.sounds.playAtPosition(src, origin, radius);
+     * ```
+     *
+     * @example A Token casts a spell
+     * ```js
+     * const src = "modules/my-module/sounds/spells-sprite.ogg";
+     * const origin = token.center;         // The origin point for the sound
+     * const radius = 60;                   // Audible in a 60-foot radius
+     * await canvas.sounds.playAtPosition(src, origin, radius, {
+     *   walls: false,                      // Not constrained by walls with a lowpass muffled effect
+     *   muffledEffect: {type: "lowpass", intensity: 6},
+     *   sourceData: {
+     *     angle: 120,                      // Sound emitted at a limited angle
+     *     rotation: 270                    // Configure the direction of sound emission
+     *   }
+     *   playbackOptions: {
+     *     loopStart: 12,                   // Audio sprite timing
+     *     loopEnd: 16,
+     *     fade: 300,                      // Fade-in 300ms
+     *     onended: () => console.log("Do something after the spell sound has played")
+     *   }
+     * });
+     * ```
+     */
+    playAtPosition(
+      src: string,
+      origin: Canvas.Point,
+      radius: number,
+      /** @remarks Can't be NullishProps because a default for `volume` is provided only for `undefined` with `{ volume=1 }`, which must be numeric */
+      options?: InexactPartial<SoundsLayer.PlayAtPositionOptions>,
+    ): Promise<foundry.audio.Sound | null>;
+
+    /**
+     * Emit playback to other connected clients to occur at a specified position.
+     * @param args - Arguments passed to SoundsLayer#playAtPosition
+     * @returns  A Promise which resolves once playback for the initiating client has completed
+     */
+    emitAtPosition(...args: Parameters<this["playAtPosition"]>): ReturnType<this["playAtPosition"]>;
+
+    /**
+     * Handle mouse cursor movements which may cause ambient audio previews to occur
+     */
+    protected _onMouseMove(): void;
+
+    protected override _onDragLeftStart(event: PIXI.FederatedEvent): void;
+
+    protected override _onDragLeftMove(event: PIXI.FederatedEvent): void;
+
+    protected override _onDragLeftDrop(event: PIXI.FederatedEvent): void;
+
+    protected override _onDragLeftCancel(event: PointerEvent): void;
+
+    /**
+     * Handle PlaylistSound document drop data.
+     * @param event - The drag drop event
+     * @param data  - The dropped transfer data.
+     */
+    protected _onDropData(
+      event: DragEvent,
+      data: SoundsLayer.DropData,
+    ): Promise<ReturnType<PlaceablesLayer<"AmbientSound">["_createPreview"]> | false>;
+  }
+
+  namespace SoundsLayer {
+    type AnyConstructor = typeof AnySoundsLayer;
+
+    interface DrawOptions extends PlaceablesLayer.DrawOptions {}
+
+    interface TearDownOptions extends PlaceablesLayer.TearDownOptions {}
+
+    interface LayerOptions extends PlaceablesLayer.LayerOptions<"AmbientSound"> {
+      name: "sounds";
+      zIndex: 900;
+    }
+
+    interface DropData extends Canvas.DropPosition {
+      type: "PlaylistSound";
+      uuid: string;
+    }
+
+    interface PlayAtPositionOptions {
+      /**
+       * The maximum volume at which the effect should be played
+       * @defaultValue `1.0`
+       */
+      volume: number;
+
+      /**
+       * Should volume be attenuated by distance?
+       * @defaultValue `true`
+       */
+      easing: boolean;
+
+      /**
+       * Should the sound be constrained by walls?
+       * @defaultValue `true`
+       */
+      walls: boolean;
+
+      /**
+       * Should the sound always be played for GM users regardless of actively controlled tokens?
+       * @defaultValue `true`
+       */
+      gmAlways: boolean;
+
+      /** A base sound effect to apply to playback */
+      baseEffect: AmbientSoundEffect;
+
+      /** A muffled sound effect to apply to playback, a sound may only be muffled if it is not constrained by walls */
+      muffledEffect: AmbientSoundEffect;
+
+      /**
+       * Additional data passed to the SoundSource constructor
+       * @remarks IntentionalPartial because this is spread into an object with existing keys
+       */
+      sourceData: IntentionalPartial<PointSourceData>;
+
+      /** Additional options passed to Sound#play */
+      playbackOptions: foundry.audio.Sound.PlaybackOptions;
+    }
+
+    interface AmbientSoundPlaybackConfig {
+      /**
+       * The Sound node which should be controlled for playback
+       */
+      sound: foundry.audio.Sound;
+
+      /**
+       * The SoundSource which defines the area of effect for the sound
+       */
+      source: foundry.canvas.sources.PointSoundSource;
+
+      /**
+       * An AmbientSound object responsible for the sound, or undefined
+       */
+      object: AmbientSound | undefined;
+
+      /**
+       * The coordinates of the closest listener or undefined if there is none
+       */
+      listener: Canvas.Point | undefined;
+
+      /**
+       * The minimum distance between a listener and the AmbientSound origin
+       */
+      distance: number;
+
+      /**
+       * Is the closest listener muffled
+       */
+      muffled: boolean;
+
+      /**
+       * Is playback constrained or muffled by walls?
+       */
+      walls: boolean;
+
+      /**
+       * The final volume at which the Sound should be played
+       */
+      volume: number;
+    }
+  }
+}
+
+/**
+ * @privateRemarks This is the only place in v12 (and v13 as of 332) where this v11 type is still used
+ */
+interface PointSourceData {
+  x: number;
+  y: number;
+  elevation: number;
+  z: number | null;
+  radius: number;
+  externalRadius: number;
+  rotation: number;
+  angle: number;
+  walls: boolean;
+  disabled: boolean;
+}
+
+declare abstract class AnySoundsLayer extends SoundsLayer {
+  constructor(arg0: never, ...args: never[]);
+}

package/src/foundry/client/pixi/layers/placeables/templates.d.mts

@@ -0,0 +1,72 @@
+export {};
+
+/**
+ * This Canvas Layer provides a container for MeasuredTemplate objects.
+ * @see {@link MeasuredTemplate}
+ */
+declare global {
+  class TemplateLayer<
+    DrawOptions extends TemplateLayer.DrawOptions = TemplateLayer.DrawOptions,
+    TearDownOptions extends PlaceablesLayer.TearDownOptions = PlaceablesLayer.TearDownOptions,
+  > extends PlaceablesLayer<"MeasuredTemplate", DrawOptions, TearDownOptions> {
+    /**
+     * @privateRemarks This is not overridden in foundry but reflects the real behavior.
+     */
+    static get instance(): Canvas["templates"];
+
+    /**
+     * @privateRemarks This is not overridden in foundry but reflects the real behavior.
+     */
+    override options: TemplateLayer.LayerOptions;
+
+    /**
+     * @defaultValue
+     * ```
+     * mergeObject(super.layerOptions, {
+     *   name: "templates",
+     *   rotatableObjects: true,
+     *   zIndex: 400
+     * })
+     * ```
+     */
+    static override get layerOptions(): TemplateLayer.LayerOptions;
+
+    static override documentName: "MeasuredTemplate";
+
+    override get hookName(): string;
+
+    override _deactivate(): void;
+
+    override _draw(options?: DrawOptions): Promise<void>;
+
+    /**
+     * Register game settings used by the TemplatesLayer
+     */
+    static registerSettings(): void;
+
+    protected override _onDragLeftStart(event: PIXI.FederatedEvent): void;
+
+    protected override _onDragLeftMove(event: PIXI.FederatedEvent): void;
+
+    // @ts-expect-error Foundry is changing the return type here from Promise<PlaceableObject[]> to Promise<MeasuredTemplate>
+    protected override _onMouseWheel(
+      event: WheelEvent,
+    ): ReturnType<MeasuredTemplate.ConfiguredInstance["rotate"]> | void;
+  }
+
+  namespace TemplateLayer {
+    type AnyConstructor = typeof AnyTemplateLayer;
+
+    interface DrawOptions extends PlaceablesLayer.DrawOptions {}
+
+    interface LayerOptions extends PlaceablesLayer.LayerOptions<"MeasuredTemplate"> {
+      name: "templates";
+      rotatableObjects: true;
+      zIndex: 400;
+    }
+  }
+}
+
+declare abstract class AnyTemplateLayer extends TemplateLayer {
+  constructor(arg0: never, ...args: never[]);
+}