@league-of-foundry-developers/foundry-vtt-types 9.255.3 → 9.268.2

package/src/foundry/{foundry.js/pixi/containers/canvasLayers/placeablesLayers/lightingLayer.d.ts → client/pixi/layers/lighting.d.ts}

@@ -20,7 +20,7 @@ declare class LightingLayer extends PlaceablesLayer<'AmbientLight', LightingLaye
   /**
    * A mapping of light sources which are active within the rendered Scene
    */
-  sources: foundry.utils.Collection<PointSource>;
+  sources: foundry.utils.Collection<LightSource>;
 
   /**
    * Increment this whenever lighting channels are re-configured.
@@ -33,7 +33,7 @@ declare class LightingLayer extends PlaceablesLayer<'AmbientLight', LightingLaye
    * The currently displayed darkness level, which may override the saved Scene value
    * @defaultValue `0`
    */
-  protected darknessLevel: number;
+  darknessLevel: number;
 
   /**
    * The current client setting for whether global illumination is used or not
@@ -54,24 +54,24 @@ declare class LightingLayer extends PlaceablesLayer<'AmbientLight', LightingLaye
   illumination: PIXI.Container | null;
 
   /**
-   * A flag for whether the darkness level is currently animating
-   * @defaultValue `false`
+   * The background container which visualizes the background
+   * @defaultValue `null`
    */
-  protected _animating: boolean;
+  background: PIXI.Container | null;
 
   /**
    * An array of light sources which are currently animated
+   * @internal
    */
-  protected _animatedSources: PointSource[];
+  protected _animatedSources: LightSource[];
 
   /**
    * A mapping of different light level channels
    * @defaultValue `undefined`
    */
-  channels: Record<'background' | 'black' | 'bright' | 'canvas' | 'dark' | 'dim', LightChannel> | undefined;
+  channels: ChannelConfig | undefined;
 
-  /** @override */
-  static documentName: 'AmbientLight';
+  static override documentName: 'AmbientLight';
 
   /**
    * @remarks This is not overridden in foundry but reflects the real behavior.
@@ -79,42 +79,56 @@ declare class LightingLayer extends PlaceablesLayer<'AmbientLight', LightingLaye
   static get instance(): Canvas['lighting'];
 
   /**
-   * @override
    * @defaultValue
    * ```
    * foundry.utils.mergeObject(super.layerOptions, {
    *  name: "lighting",
    *  rotatableObjects: true,
-   *  quadtree: true,
    *  zIndex: 300
    * })
    * ```
    */
-  static get layerOptions(): LightingLayer.LayerOptions;
+  static override get layerOptions(): LightingLayer.LayerOptions;
 
   /**
+   * TODO: Significant portions of this method may no longer be needed
    * Configure the lighting channels which are inputs to the ShadowMap
+   * @internal
    */
-  protected _configureChannels(
-    darkness?: number | null
-  ): Record<'background' | 'black' | 'bright' | 'canvas' | 'dark' | 'dim', LightChannel>;
+  protected _configureChannels({
+    darkness,
+    backgroundColor
+  }?: {
+    /** Darkness level override. */
+    darkness?: number;
 
-  /**
-   * @override
-   */
-  draw(): Promise<this>;
+    /** Canvas background color override. */
+    backgroundColor?: number;
+  }): ChannelConfig;
+
+  override draw(): Promise<this>;
+
+  masks?: PIXI.Container;
 
   /**
    * Draw the coloration container which is responsible for rendering the visible hue of a light source.
    * Apply an additive blend to the entire container after each individual light source is blended via screen.
+   * @internal
    */
   protected _drawColorationContainer(): PIXI.Container;
 
   /**
    * Draw the illumination container which is responsible for displaying darkness and light.
+   * @internal
    */
   protected _drawIlluminationContainer(): PIXI.Container;
 
+  /**
+   * Draw the background container which is responsible for displaying altered background.
+   * @internal
+   */
+  protected _drawBackgroundContainer(): PIXI.Container;
+
   /**
    * Does this scene currently benefit from global illumination?
    */
@@ -129,10 +143,21 @@ declare class LightingLayer extends PlaceablesLayer<'AmbientLight', LightingLaye
    * Refresh the active display of the LightingLayer.
    * Update the scene background color, light sources, and darkness sources
    */
-  refresh(darkness?: number | undefined): void;
+  refresh({
+    darkness,
+    backgroundColor
+  }?: {
+    /**
+     * An override darkness level to which the layer should be temporarily
+     * rendered.
+     */
+    darkness?: number;
 
-  /** @override */
-  tearDown(): Promise<this>;
+    /** An override canvas background color. */
+    backgroundColor?: number;
+  }): void;
+
+  override tearDown(): Promise<this>;
 
   /**
    * Activate light source animation for AmbientLight objects within this layer
@@ -147,6 +172,7 @@ declare class LightingLayer extends PlaceablesLayer<'AmbientLight', LightingLaye
   /**
    * The ticker handler which manages animation delegation
    * @param dt - Delta time
+   * @internal
    */
   protected _animateSource(dt: number): void;
 
@@ -155,42 +181,49 @@ declare class LightingLayer extends PlaceablesLayer<'AmbientLight', LightingLaye
    * Only begin animating if another animation is not already in progress.
    * @param target   - The target darkness level between 0 and 1
    *                   (default: `1.0`)
-   * @param duration - The desired animation time in milliseconds. Default is 10 seconds
-   *                   (default: `10000`)
    * @returns A Promise which resolves once the animation is complete
    */
-  animateDarkness(target?: number, { duration }?: { duration?: number }): Promise<void>;
+  animateDarkness(
+    target?: number,
+    {
+      duration
+    }?: {
+      /**
+       * The desired animation time in milliseconds. Default is 10 seconds
+       * @defaultValue `10000`
+       */
+      duration?: number;
+    }
+  ): Promise<void>;
 
   /**
    * Actions to take when the darkness level of the Scene is changed
    * @param darkness - The new darkness level
    * @param prior    - The prior darkness level
+   * @internal
    */
   protected _onDarknessChange(darkness: number, prior: number): void;
 
-  /** @override */
-  protected _onDragLeftStart(event: PIXI.InteractionEvent): Promise<AmbientLight>;
+  protected override _onDragLeftStart(event: PIXI.InteractionEvent): Promise<AmbientLight>;
 
-  /** @override */
-  protected _onDragLeftMove(event: PIXI.InteractionEvent): void;
+  protected override _onDragLeftMove(event: PIXI.InteractionEvent): void;
 
-  /** @override */
-  protected _onDragLeftCancel(event: PointerEvent): void;
+  protected override _onDragLeftCancel(event: PointerEvent): void;
 
-  /** @override */
-  protected _onMouseWheel(event: WheelEvent): void | ReturnType<AmbientLight['rotate']>;
+  protected override _onMouseWheel(event: WheelEvent): void | ReturnType<AmbientLight['rotate']>;
 }
 
 declare namespace LightingLayer {
   interface LayerOptions extends PlaceablesLayer.LayerOptions<'AmbientLight'> {
     name: 'lighting';
-    rotatableObjects: true;
-    quadtree: true;
-    zIndex: 300;
   }
 }
 
-declare interface LightChannel {
+type ChannelConfig = Record<'canvas' | 'background' | 'black' | 'bright' | 'dark' | 'dim', LightChannel> & {
+  darkness: { level: number; rgb: [r: number, g: number, b: number] };
+};
+
+interface LightChannel {
   hex: number;
-  rgb: [number, number, number];
+  rgb: [r: number, g: number, b: number];
 }

package/src/foundry/client/pixi/layers/map.d.ts

@@ -0,0 +1,263 @@
+import {
+  ConfiguredDocumentClassForName,
+  ConfiguredObjectClassForName,
+  DataSourceForPlaceable
+} from '../../../../types/helperTypes';
+
+declare global {
+  /**
+   * A PlaceablesLayer designed for rendering the visual Scene for a specific vertical cross-section.
+   * Each MapLayer contains a single background image as well as an arbitrary number of Tile objects.
+   */
+  class MapLayer<Options extends MapLayer.LayerOptions = MapLayer.LayerOptions<'background'>> extends PlaceablesLayer<
+    'Tile',
+    Options
+  > {
+    /**
+     * @param data - (default: `{}`)
+     */
+    constructor(data?: MapLayerConstructorData);
+
+    /**
+     * The numeric Scene level to which this layer belongs
+     */
+    level: number;
+
+    /**
+     * The background source path
+     */
+    bgPath: string | undefined;
+
+    /**
+     * The layer background image
+     */
+    bg: PIXI.Sprite | undefined;
+
+    static documentName: 'Tile';
+
+    /**
+     * @remarks This is not overridden in foundry but reflects the real behavior.
+     * It returns the BackgroundLayer but ForegroundLayer has been added for subclasses.
+     */
+    static get instance(): Canvas['background'] | Canvas['foreground'];
+
+    /**
+     * @defaultValue
+     * ```typescript
+     * foundry.utils.mergeObject(super.layerOptions, {
+     *   name: 'background',
+     *   zIndex: 0,
+     *   controllableObjects: true,
+     *   rotatableObjects: true
+     * })
+     * ```
+     */
+    static get layerOptions(): MapLayer.LayerOptions;
+
+    /**
+     * Return the base HTML image or video element which is used to generate the background Sprite.
+     */
+    get bgSource(): HTMLImageElement | HTMLVideoElement | null;
+
+    get hud(): TileHUD;
+
+    /**
+     * Is the background texture used in this layer a video?
+     */
+    get isVideo(): boolean;
+
+    /**
+     * An array of Tile objects which are rendered within the objects container
+     */
+    get tiles(): InstanceType<ConfiguredObjectClassForName<'Tile'>>[];
+
+    deactivate(): this;
+
+    tearDown(): Promise<this>;
+
+    /**
+     * @remarks It returns Promise<this> but is overridden by a subclass in this way.
+     */
+    override draw(): Promise<this | undefined>;
+
+    /**
+     * Draw the background Sprite for the layer, aligning its dimensions with those configured for the canvas.
+     * @returns The rendered Sprite, or undefined if no background is present
+     */
+    protected _drawBackground(): PIXI.Sprite | undefined;
+
+    protected _onDragLeftStart(event: PIXI.InteractionEvent): Promise<void>;
+
+    protected _onDragLeftMove(event: PIXI.InteractionEvent): void;
+
+    protected _onDragLeftDrop(event: PIXI.InteractionEvent): void;
+
+    protected _onDragLeftCancel(event: PointerEvent): void;
+
+    /**
+     * Handle drop events for Tile data on the Tiles Layer
+     * @param event - The concluding drag event
+     * @param data - The extracted Tile data
+     */
+    protected _onDropData(
+      event: DragEvent,
+      data:
+        | { type: 'Tile'; img: string; tileSize?: number; x: number; y: number }
+        | ({ type: string } & Partial<Record<string, unknown>>)
+    ): Promise<InstanceType<ConfiguredDocumentClassForName<'Tile'>> | undefined>;
+
+    /**
+     * Prepare the data object when a new Tile is dropped onto the canvas
+     * @param event - The concluding drag event
+     * @param data  - The extracted Tile data
+     * @returns The prepared data to create
+     */
+    protected _getDropData(
+      event: DragEvent,
+      data: MapLayer.DropData
+    ): Promise<ConstructorParameters<typeof foundry.documents.BaseTile>[0]>;
+  }
+
+  namespace MapLayer {
+    interface LayerOptions<Name extends 'background' | 'foreground' = 'background' | 'foreground'>
+      extends PlaceablesLayer.LayerOptions<'Tile'> {
+      name: Name;
+    }
+
+    type DropData =
+      | { type: 'Tile'; img: string; tileSize?: number; x: number; y: number }
+      | ({ type: string } & Partial<Record<string, unknown>>);
+  }
+
+  /**
+   * An extension of the MapLayer that displays underfoot in the background of the Scene.
+   */
+  class BackgroundLayer extends MapLayer {
+    /**
+     * @remarks This is not overridden in foundry but reflects the real behavior.
+     */
+    static get instance(): Canvas['background'];
+
+    /**
+     * @remarks This is not overridden in foundry but reflects the real behavior.
+     */
+    static get layerOptions(): MapLayer.LayerOptions<'background'>;
+
+    /**
+     * The outline of the scene.
+     * Not rendered within the BackgroundLayer, but rather beneath it so it does not impact the PrimaryMesh texture.
+     */
+    outline: PIXI.Graphics | undefined;
+
+    /**
+     * Draw a background outline which emphasizes what portion of the canvas is playable space and what is buffer.
+     * @param outline - The outline graphics to use
+     */
+    drawOutline(outline: PIXI.Graphics): void;
+
+    getDocuments(): Exclude<this['documentCollection'], null> | InstanceType<ConfiguredDocumentClassForName<'Tile'>>[];
+
+    getZIndex(): number;
+
+    storeHistory(
+      type: PlaceablesLayer.HistoryEventType,
+      data: DataSourceForPlaceable<InstanceType<ConfiguredObjectClassForName<'Tile'>>>
+    ): void;
+  }
+
+  /**
+   * An extension of the MapLayer that displays overhead in the foreground of the Scene.
+   */
+  class ForegroundLayer extends MapLayer<MapLayer.LayerOptions<'foreground'>> {
+    /**
+     * @defaultValue
+     * ```typescript
+     * foundry.utils.mergeObject(super.layerOptions, {
+     *   name: "foreground"
+     * })
+     * ```
+     */
+    static get layerOptions(): MapLayer.LayerOptions<'foreground'>;
+
+    /**
+     * @remarks This is not overridden in foundry but reflects the real behavior.
+     */
+    static get instance(): Canvas['foreground'];
+
+    /**
+     * Get an array of overhead Tile objects which are roofs
+     */
+    get roofs(): InstanceType<ConfiguredObjectClassForName<'Tile'>>[];
+
+    /**
+     * Determine whether to display roofs
+     */
+    get displayRoofs(): boolean;
+
+    draw(): Promise<undefined>;
+
+    /**
+     * Draw the container used to cache the position of Token occlusion shapes to a RenderTexture
+     */
+    protected _drawOcclusionMask(): CachedContainer;
+
+    /**
+     * Perform one-time initialization actions which affect the foreground layer.
+     * These actions presume and require that the layer has already been drawn.
+     */
+    initialize(): void;
+
+    override activate(): this;
+
+    deactivate(): this;
+
+    tearDown(): Promise<this>;
+
+    getZIndex(): number;
+
+    getDocuments(): Exclude<this['documentCollection'], null> | InstanceType<ConfiguredDocumentClassForName<'Tile'>>[];
+
+    /**
+     * Refresh the display of tiles on the Foreground Layer depending on Token occlusion.
+     */
+    refresh(): void;
+
+    /**
+     * Add a roof sprite to the occlusion roof mask container
+     * @param tile - The roof tile being added
+     */
+    addRoofSprite(tile: InstanceType<ConfiguredObjectClassForName<'Tile'>>): void;
+
+    /**
+     * Remove a roof sprite from occlusion roof mask container
+     * @param tile - The roof tile being removed
+     */
+    removeRoofSprite(tile: InstanceType<ConfiguredObjectClassForName<'Tile'>>): void;
+
+    /**
+     * Update occlusion for all tiles on the foreground layer
+     */
+    updateOcclusion(): void;
+
+    /**
+     * Draw the container which caches token-based occlusion shapes
+     * @param tokens - The set of currently observed tokens
+     */
+    protected _drawOcclusionShapes(tokens: ConfiguredObjectClassForName<'Token'>[]): void;
+
+    protected _getDropData(
+      event: DragEvent,
+      data:
+        | { type: 'Tile'; img: string; tileSize?: number; x: number; y: number }
+        | ({ type: string } & Partial<Record<string, unknown>>)
+    ): Promise<ConstructorParameters<typeof foundry.documents.BaseTile>[0]>;
+  }
+}
+
+interface MapLayerConstructorData {
+  bgPath?: string;
+  /**
+   * @defaultValue `1`
+   */
+  level?: number;
+}

package/src/foundry/{foundry.js/pixi/containers/canvasLayers/placeablesLayers/notesLayer.d.ts → client/pixi/layers/notes.d.ts}

@@ -1,4 +1,4 @@
-import { DropData } from '../../../../clientDocumentMixin';
+import { DropData } from '../../data/abstract/client-document';
 
 declare global {
   /**
@@ -11,7 +11,6 @@ declare global {
     static get instance(): Canvas['notes'];
 
     /**
-     * @override
      * @defaultValue
      * ```
      * foundry.utils.mergeObject(super.layerOptions, {
@@ -22,32 +21,29 @@ declare global {
      * })
      * ```
      */
-    static get layerOptions(): NotesLayer.LayerOptions;
+    static override get layerOptions(): NotesLayer.LayerOptions;
 
-    /** @override */
-    static documentName: 'Note';
+    static override documentName: 'Note';
 
     /**
      * The named core setting which tracks the toggled visibility state of map notes
      */
     static TOGGLE_SETTING: 'notesDisplayToggle';
 
-    /** @override */
-    activate(): this;
+    override activate(): this;
 
-    /** @override */
-    deactivate(): this;
+    override deactivate(): this;
 
     /**
      * Register game settings used by the NotesLayer
      */
     static registerSettings(): void;
 
-    /** @override */
+    /** @remarks this method seems to be unused, see https://gitlab.com/foundrynet/foundryvtt/-/issues/7004 */
     protected _onMouseDown(event: PIXI.InteractionEvent): void;
 
     /**
-     * Handle JournalEntry entity drop data
+     * Handle JournalEntry document drop data
      */
     protected _onDropData(event: DragEvent, data: DropData<JournalEntry>): Promise<false | void>;
   }