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

package/src/foundry/foundry.js/pixi/containers/canvasLayers/controlsLayer.d.ts

@@ -1,69 +1,76 @@
-/**
- * A CanvasLayer for displaying UI controls which are overlayed on top of other layers.
- *
- * We track three types of events:
- * 1) Cursor movement
- * 2) Ruler measurement
- * 3) Map pings
- */
-import { ConfiguredDocumentClass, ConfiguredObjectClassForName } from '../../../../../types/helperTypes';
+import { ConfiguredDocumentClass } from '../../../../../types/helperTypes';
 
 declare global {
+  /**
+   * A CanvasLayer for displaying UI controls which are overlayed on top of other layers.
+   *
+   * We track three types of events:
+   * 1) Cursor movement
+   * 2) Ruler measurement
+   * 3) Map pings
+   */
   class ControlsLayer extends CanvasLayer<ControlsLayer.LayerOptions> {
     constructor();
 
     /**
-     * Cursor position indicators
-     * @defaultValue `null`
+     * A container of DoorControl instances
+     * @defaultValue `this.addChild(new PIXI.Container())`
      */
-    cursors: PIXI.Container | null;
+    doors: PIXI.Container;
 
     /**
-     * A mapping of user IDs to Cursor instances for quick access
-     * @defaultValue `{}`
-     */
-    protected _cursors: Partial<Record<string, Cursor>>;
-
-    /**
-     * Door control icons
-     * @defaultValue `null`
+     * A container of HUD interface elements
+     * @defaultValue `this.addChild(new PIXI.Container())`
      */
-    doors: PIXI.Container | null;
+    hud: PIXI.Container;
 
     /**
-     * Status effect icons
-     * @remarks Always `null`
+     * A container of cursor interaction elements.
+     * Contains cursors, rulers, interaction rectangles, and pings
+     * @defaultValue `this.addChild(new PIXI.Container())`
      */
-    effects: null;
+    cursors: PIXI.Container;
 
     /**
      * Ruler tools, one per connected user
-     * @defaultValue `null`
+     * @defaultValue `this.addChild(new PIXI.Container())`
      */
-    rulers: PIXI.Container | null;
+    rulers: PIXI.Container;
 
     /**
-     * A convenience mapping of user IDs to Ruler instances for quick access
+     * A graphics instance used for drawing debugging visualization
+     * @defaultValue `this.addChild(new PIXI.Graphics())`
      */
-    protected _rulers: Partial<Record<string, Ruler>>;
+    debug: PIXI.Graphics;
 
     /**
      * Canvas selection rectangle
-     * @defaultValue `null`
+     * @defaultValue `undefined`
      */
-    select: PIXI.Graphics | null;
+    select: PIXI.Graphics | undefined;
 
-    // The controls layer is always interactive
-    interactiveChildren: true;
+    /**
+     * A mapping of user IDs to Cursor instances for quick access
+     * @defaultValue `{}`
+     */
+    protected _cursors: Record<string, Cursor>;
 
     /**
-     * @remarks This is not overridden in foundry but reflects the real behavior.
+     * A convenience mapping of user IDs to Ruler instances for quick access
+     * @internal
+     * @defaultValue `{}`
      */
-    static get instance(): undefined;
+    protected _rulers: Record<string, Ruler>;
 
     /**
      * @override
-     * @defaultValue `mergeObject(super.layerOptions, { name: "controls", zIndex: 1000 })`
+     * @defaultValue
+     * ```typescript
+     * foundry.utils.mergeObject(super.layerOptions, {
+     *   name: "controls",
+     *   zIndex: 1000
+     * })
+     * ```
      */
     static get layerOptions(): ControlsLayer.LayerOptions;
 
@@ -78,24 +85,18 @@ declare global {
     getRulerForUser(userId: string): Ruler | null;
 
     /** @override */
-    draw(): this;
-
-    /**
-     * Draw the cursors container
-     */
-    drawCursors(): void;
+    draw(): Promise<this>;
 
     /**
-     * Draw the Door controls container
+     * @override
+     * @remarks This breaks polymorphism. See https://gitlab.com/foundrynet/foundryvtt/-/issues/6939
      */
-    drawDoors(): void;
+    tearDown(): Promise<void>;
 
     /**
-     * Create a Door Control icon for a given Wall object
-     * @param wall - The Wall for which to create a DoorControl
-     * @returns The created DoorControl
+     * Draw the cursors container
      */
-    createDoorControl(wall: InstanceType<ConfiguredObjectClassForName<'Wall'>>): ReturnType<DoorControl['draw']> | null;
+    drawCursors(): void;
 
     /**
      * Draw Ruler tools
@@ -118,7 +119,7 @@ declare global {
 
     /**
      * Create and draw the Cursor object for a given User
-     * @param user - The User entity for whom to draw the cursor Container
+     * @param user - The User document for whom to draw the cursor Container
      */
     drawCursor(user: InstanceType<ConfiguredDocumentClass<typeof User>>): Cursor;
 

package/src/foundry/foundry.js/pixi/containers/canvasLayers/placeablesLayer.d.ts

@@ -1,9 +1,9 @@
 import {
   DataSourceForPlaceable,
-  ConfiguredDocumentClass,
   ConfiguredObjectClassForName,
   ConfiguredDocumentClassForName,
-  PlaceableDocumentType
+  PlaceableDocumentType,
+  ConstructorDataType
 } from '../../../../../types/helperTypes';
 import EmbeddedCollection from '../../../../common/abstract/embedded-collection.mjs';
 
@@ -78,6 +78,16 @@ declare global {
      */
     static documentName: PlaceableDocumentType;
 
+    /**
+     * Creation states affected to placeables during their construction.
+     */
+    static CREATION_STATES: Readonly<{
+      NONE: 0;
+      POTENTIAL: 1;
+      CONFIRMED: 2;
+      COMPLETED: 3;
+    }>;
+
     /**
      * Obtain a reference to the Collection of embedded Document instances within the currently viewed Scene
      */
@@ -130,7 +140,7 @@ declare global {
      */
     createObject(
       data: InstanceType<ConfiguredDocumentClassForName<DocumentName>>
-    ): InstanceType<ConfiguredObjectClassForName<DocumentName>>;
+    ): InstanceType<ConfiguredObjectClassForName<DocumentName>> | null;
 
     /** @override */
     tearDown(): Promise<this>;
@@ -141,6 +151,11 @@ declare global {
     /** @override */
     deactivate(): this;
 
+    /**
+     * Clear the contents of the preview container, restoring visibility of original (non-preview) objects.
+     */
+    clearPreviewContainer(): void;
+
     /**
      * Get a PlaceableObject contained in this layer by it's ID
      *
@@ -246,7 +261,7 @@ declare global {
      * @param transformation - An object of data or function to apply to all matched objects
      * @param condition      - A function which tests whether to target each object
      *                         (default: `null`)
-     * @param options        - Additional options passed to Entity.update
+     * @param options        - Additional options passed to Document.update
      *                         (default: `{}`)
      * @returns An array of updated data once the operation is complete
      */
@@ -268,6 +283,35 @@ declare global {
       options?: DocumentModificationContext
     ): Promise<Array<InstanceType<ConfiguredDocumentClassForName<DocumentName>>>>;
 
+    /**
+     * Get the world-transformed drop position.
+     * @returns Returns the transformed x, y co-ordinates, or false if the drag event was outside the canvas.
+     */
+    protected _canvasCoordinatesFromDrop(
+      event: DragEvent,
+      {
+        center
+      }?:
+        | {
+            /**
+             * Return the co-ordinates of the center of the nearest grid element.
+             * @defaultValue `true`
+             */
+            center?: boolean | undefined;
+          }
+        | undefined
+    ): [tx: number, ty: number] | false;
+
+    /**
+     * Create a preview of this layer's object type from a world document and show its sheet so it can be finalized.
+     * @param createData - The data to create the object with.
+     * @param position   - The position to render the sheet at.
+     */
+    protected _createPreview(
+      createData: ConstructorDataType<InstanceType<ConfiguredDocumentClassForName<DocumentName>>['data']>,
+      { top, left }: { top: number; left: number }
+    ): Promise<void>;
+
     /**
      * Handle left mouse-click events which originate from the Canvas stage and are dispatched to this Layer.
      * @param event - (unused)
@@ -327,35 +371,6 @@ declare global {
      *                (unused)
      */
     protected _onDeleteKey(event?: any): void;
-
-    /**
-     * @deprecated since 0.8.0
-     */
-    static get dataArray(): string;
-
-    /**
-     * @deprecated since 0.8.0
-     */
-    createMany(
-      data: Parameters<InstanceType<ConfiguredDocumentClass<typeof Scene>>['createEmbeddedDocuments']>[1],
-      options: Parameters<InstanceType<ConfiguredDocumentClass<typeof Scene>>['createEmbeddedDocuments']>[2]
-    ): ReturnType<InstanceType<ConfiguredDocumentClass<typeof Scene>>['createEmbeddedDocuments']>;
-
-    /**
-     * @deprecated since 0.8.0
-     */
-    updateMany(
-      data: Parameters<InstanceType<ConfiguredDocumentClass<typeof Scene>>['updateEmbeddedDocuments']>[1],
-      options: Parameters<InstanceType<ConfiguredDocumentClass<typeof Scene>>['updateEmbeddedDocuments']>[2]
-    ): ReturnType<InstanceType<ConfiguredDocumentClass<typeof Scene>>['updateEmbeddedDocuments']>;
-
-    /**
-     * @deprecated since 0.8.0
-     */
-    deleteMany(
-      data: Parameters<InstanceType<ConfiguredDocumentClass<typeof Scene>>['deleteEmbeddedDocuments']>[1],
-      options: Parameters<InstanceType<ConfiguredDocumentClass<typeof Scene>>['deleteEmbeddedDocuments']>[2]
-    ): ReturnType<InstanceType<ConfiguredDocumentClass<typeof Scene>>['deleteEmbeddedDocuments']>;
   }
 
   interface CanvasHistory<Placeable extends PlaceableObject> {
@@ -373,6 +388,8 @@ declare global {
   namespace PlaceablesLayer {
     type HistoryEventType = 'create' | 'update' | 'delete';
 
+    type CreationState = ValueOf<typeof PlaceablesLayer['CREATION_STATES']>;
+
     /**
      * @typeParam DocumentName - The key of the configuration which defines the object and document class.
      */
@@ -409,15 +426,9 @@ declare global {
 
       /**
        * Does this layer use a quadtree to track object positions?
-       * @defaultValue `false`
+       * @defaultValue `true`
        */
       quadtree: boolean;
-
-      /**
-       * The FormApplication class used to configure objects on this layer.
-       * @defaultValue `CONFIG[this.documentName].sheetClass`
-       */
-      sheetClass: ConstructorOf<FormApplication>;
     }
   }
 }

package/src/foundry/foundry.js/pixi/containers/canvasLayers/placeablesLayers/lightingLayer.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,21 +54,22 @@ 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';
@@ -85,7 +86,6 @@ declare class LightingLayer extends PlaceablesLayer<'AmbientLight', LightingLaye
    * foundry.utils.mergeObject(super.layerOptions, {
    *  name: "lighting",
    *  rotatableObjects: true,
-   *  quadtree: true,
    *  zIndex: 300
    * })
    * ```
@@ -93,28 +93,47 @@ declare class LightingLayer extends PlaceablesLayer<'AmbientLight', LightingLaye
   static 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;
+
+    /** 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,7 +148,19 @@ 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;
+
+    /** An override canvas background color. */
+    backgroundColor?: number;
+  }): void;
 
   /** @override */
   tearDown(): Promise<this>;
@@ -147,6 +178,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,16 +187,26 @@ 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;
 
@@ -184,13 +226,14 @@ declare class LightingLayer extends PlaceablesLayer<'AmbientLight', LightingLaye
 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/foundry.js/pixi/containers/canvasLayers/placeablesLayers/mapLayer.d.ts

@@ -119,9 +119,6 @@ declare global {
     interface LayerOptions<Name extends 'background' | 'foreground' = 'background' | 'foreground'>
       extends PlaceablesLayer.LayerOptions<'Tile'> {
       name: Name;
-      zIndex: 0;
-      controllableObjects: true;
-      rotatableObjects: true;
     }
 
     type DropData =

package/src/foundry/foundry.js/pixi/containers/canvasLayers/placeablesLayers/mapLayers/backgroundLayer.d.ts

@@ -20,16 +20,16 @@ declare global {
     static get layerOptions(): MapLayer.LayerOptions<'background'>;
 
     /**
-     * The outline of the scene
+     * 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(): Promise<this>;
-
     /**
      * 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
      */
-    protected _drawOutline(): PIXI.Graphics | undefined;
+    drawOutline(outline: PIXI.Graphics): void;
 
     getDocuments(): Exclude<this['documentCollection'], null> | InstanceType<ConfiguredDocumentClassForName<'Tile'>>[];
 

package/src/foundry/foundry.js/pixi/containers/canvasLayers/placeablesLayers/mapLayers/foregroundLayer.d.ts

@@ -37,6 +37,15 @@ declare global {
      */
     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>;
@@ -50,6 +59,18 @@ declare global {
      */
     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
      */

package/src/foundry/foundry.js/pixi/containers/canvasLayers/placeablesLayers/notesLayer.d.ts

@@ -47,7 +47,7 @@ declare global {
     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>;
   }

package/src/foundry/foundry.js/pixi/containers/canvasLayers/placeablesLayers/soundsLayer.d.ts

@@ -9,6 +9,12 @@ declare class SoundsLayer extends PlaceablesLayer<'AmbientSound', SoundsLayer.La
    */
   livePreview: boolean;
 
+  /**
+   * A mapping of ambient audio sources which are active within the rendered Scene
+   * @defaultValue `new foundry.utils.Collection()`
+   */
+  sources: foundry.utils.Collection<SoundSource>;
+
   /**
    * @remarks This is not overridden in foundry but reflects the real behavior.
    */
@@ -97,9 +103,11 @@ declare class SoundsLayer extends PlaceablesLayer<'AmbientSound', SoundsLayer.La
   protected _onDragLeftCancel(event: PointerEvent): void;
 
   /**
-   * @deprecated since 0.8.2
+   * Handle PlaylistSound document drop data.
+   * @param event - The drag drop event
+   * @param data  - The dropped transfer data.
    */
-  update(options?: { fade?: number }): ReturnType<this['refresh']>;
+  protected _onDropData(event: DragEvent, data: unknown): Promise<void>;
 }
 
 declare namespace SoundsLayer {

package/src/foundry/foundry.js/pixi/containers/canvasLayers/placeablesLayers/tokenLayer.d.ts

@@ -75,18 +75,36 @@ declare global {
 
     /**
      * Target all Token instances which fall within a coordinate rectangle.
-     *
-     * @param x             - The top-left x-coordinate of the selection rectangle
-     * @param y             - The top-left y-coordinate of the selection rectangle
-     * @param width         - The width of the selection rectangle
-     * @param height        - The height of the selection rectangle
-     * @param releaseOthers - Whether or not to release other targeted tokens
-     *                        (default: `true`)
      * @returns The number of Token instances which were targeted.
      */
     targetObjects(
-      { x, y, width, height }: { x: number; y: number; width: number; height: number },
-      { releaseOthers }?: { releaseOthers?: boolean }
+      {
+        x,
+        y,
+        width,
+        height
+      }: {
+        /** The top-left x-coordinate of the selection rectangle */
+        x: number;
+
+        /** The top-left y-coordinate of the selection rectangle */
+        y: number;
+
+        /** The width of the selection rectangle */
+        width: number;
+
+        /** The height of the selection rectangle */
+        height: number;
+      },
+      {
+        releaseOthers
+      }?: {
+        /**
+         * Whether or not to release other targeted tokens
+         * @defaultValue `true`
+         */
+        releaseOthers?: boolean;
+      }
     ): number;
 
     /**
@@ -105,21 +123,21 @@ declare global {
      *                  (default: `true`)
      * @param  combat - A Combat encounter from which to add or remove the Token
      *                  (default: `null`)
-     * @param  token  - A specific Token which is the origin of the group toggle request
-     *                  (default: `null`)
-     * @returns The updated Combat encounter
-     * @remarks Returns the created Combatants or undefined if there is no combat and one can't be created
-     *          or the combat if the user is no GM and wants to remove combatants.
+     * @returns The Combatants added or removed
      */
     toggleCombat(
       state?: boolean,
       combat?: InstanceType<ConfiguredDocumentClass<typeof Combat>> | null,
-      { token }?: { token?: InstanceType<ConfiguredObjectClassForName<'Token'>> | null }
-    ): Promise<
-      | InstanceType<ConfiguredDocumentClass<typeof Combat>>
-      | InstanceType<ConfiguredDocumentClass<typeof Combatant>>[]
-      | void
-    >;
+      {
+        token
+      }?: {
+        /**
+         * A specific Token which is the origin of the group toggle request
+         * @defaultValue `null`
+         */
+        token?: InstanceType<ConfiguredObjectClassForName<'Token'>> | null;
+      }
+    ): Promise<InstanceType<ConfiguredDocumentClass<typeof Combatant>>[]>;
 
     /**
      * Get the tab cycle order for tokens by sorting observable tokens based on their distance from top-left.
@@ -138,6 +156,9 @@ declare global {
       event: DragEvent,
       data: TokenLayer.DropData
     ): Promise<void | false | InstanceType<ConfiguredObjectClassForName<'Token'>>>;
+
+    /** @override */
+    protected _onClickLeft(event: PIXI.InteractionEvent): void;
   }
 
   namespace TokenLayer {