@league-of-foundry-developers/foundry-vtt-types 0.8.9-9 → 9.245.0

package/src/foundry/foundry.js/canvas.d.ts

@@ -13,7 +13,7 @@ import { BaseScene } from '../common/documents.mjs';
  * @example <caption>Example Canvas commands</caption>
  * ```typescript
  * canvas.ready; // Is the canvas ready for use?
- * canvas.scene; // The currently viewed Scene entity.
+ * canvas.scene; // The currently viewed Scene document.
  * canvas.dimensions; // The dimensions of the current Scene.
  * canvas.draw(); // Completely re-draw the game canvas (this is usually unnecessary).
  * canvas.pan(x, y, zoom); // Pan the canvas to new coordinates and scale.
@@ -72,6 +72,11 @@ declare global {
      */
     initialized: boolean;
 
+    /**
+     * A promise that resolves when the canvas is first initialized and ready.
+     */
+    initializing: Promise<void> | null;
+
     /**
      * Track the timestamp of the last stage zoom operation
      * @defaultValue `0`
@@ -107,16 +112,44 @@ declare global {
      */
     blurFilters: PIXI.filters.BlurFilter[];
 
+    /**
+     * A reference to the MouseInteractionManager that is currently controlling pointer-based interaction, or null.
+     */
+    currentMouseManager: MouseInteractionManager<PIXI.Container> | null;
+
+    /**
+     * Record framerate performance data
+     */
+    fps: {
+      /** @defaultValue `[]` */
+      values: number[];
+
+      /** @defaultValue `0` */
+      last: number;
+
+      /** @defaultValue `0` */
+      average: number;
+
+      /** @defaultValue `0` */
+      render: number;
+
+      /** @defaultValue `document.getElementById("fps")` */
+      element: HTMLElement;
+
+      /** @defaultValue `undefined` */
+      fn: TickerCallback<void> | undefined;
+    };
+
     /**
      * The singleton interaction manager instance which handles mouse interaction on the Canvas.
      */
     mouseInteractionManager: MouseInteractionManager<PIXI.Container> | undefined;
 
     /**
-     * A reference to the MouseInteractionManager that is currently controlling pointer-based interaction, or null.
-     * @defaultValue `null`
+     * The renderer screen dimensions.
+     * @defaultValue `[0, 0]`
      */
-    currentMouseManager: MouseInteractionManager<PIXI.Container> | null;
+    screenDimensions: [x: number, y: number];
 
     /**
      * Initialize the Canvas by creating the HTML element and PIXI application.
@@ -125,39 +158,53 @@ declare global {
      */
     initialize(): void;
 
-    app: PIXI.Application | undefined;
+    app?: PIXI.Application;
+
+    stage?: PIXI.Container;
 
-    stage: PIXI.Container | undefined;
+    protected _dragDrop?: DragDrop;
 
-    protected _dragDrop: DragDrop | undefined;
+    outline?: PIXI.Graphics;
 
-    background: BackgroundLayer | undefined;
+    msk?: PIXI.Graphics;
 
-    drawings: DrawingsLayer | undefined;
+    readonly primary?: PrimaryCanvasGroup;
 
-    grid: GridLayer | undefined;
+    readonly effects?: EffectsCanvasGroup;
 
-    walls: WallsLayer | undefined;
+    readonly interface?: InterfaceCanvasGroup;
 
-    templates: TemplateLayer | undefined;
+    readonly background?: BackgroundLayer;
 
-    notes: NotesLayer | undefined;
+    readonly drawings?: DrawingsLayer;
 
-    tokens: TokenLayer | undefined;
+    readonly grid?: GridLayer;
 
-    foreground: ForegroundLayer | undefined;
+    readonly walls?: WallsLayer;
 
-    sounds: SoundsLayer | undefined;
+    readonly templates?: TemplateLayer;
 
-    lighting: LightingLayer | undefined;
+    readonly notes?: NotesLayer;
 
-    sight: SightLayer | undefined;
+    readonly tokens?: TokenLayer;
 
-    effects: EffectsLayer | undefined;
+    readonly foreground?: ForegroundLayer;
 
-    controls: ControlsLayer | undefined;
+    readonly sounds?: SoundsLayer;
 
-    msk: PIXI.Graphics | undefined;
+    readonly lighting?: LightingLayer;
+
+    readonly sight?: SightLayer;
+
+    readonly weather?: WeatherLayer;
+
+    readonly controls?: ControlsLayer;
+
+    /**
+     * Display warnings for known performance issues which may occur due to the user's hardware or browser configuration
+     * @internal
+     */
+    protected _displayPerformanceWarnings(): void;
 
     /**
      * The id of the currently displayed Scene.
@@ -180,10 +227,10 @@ declare global {
     get activeLayer(): CanvasLayer | null;
 
     /**
-     * Create the layers of the game Canvas.
-     * @param stage - The primary canvas stage
+     * Initialize the group containers of the game Canvas.
+     * @internal
      */
-    protected _createLayers(stage: PIXI.Container): void;
+    protected _createGroups(): void;
 
     /**
      * When re-drawing the canvas, first tear down or discontinue some existing processes
@@ -197,6 +244,15 @@ declare global {
      */
     draw(scene?: InstanceType<ConfiguredDocumentClass<typeof Scene>>): Promise<this>;
 
+    performance?: PerformanceSettings;
+
+    /**
+     * Get the value of a GL parameter
+     * @param parameter - The GL parameter to retrieve
+     * @returns The returned value type depends of the parameter to retrieve
+     */
+    getGLParameter(parameter: string): unknown;
+
     /**
      * Get the canvas active dimensions based on the size of the scene's map.
      * We expand the image size by a factor of 1.5 and round to the nearest 2x grid size.
@@ -206,6 +262,12 @@ declare global {
      */
     static getDimensions(data: Canvas.DimensionsData): Canvas.Dimensions;
 
+    /**
+     * Configure performance settings for hte canvas application based on the selected performance mode
+     * @internal
+     */
+    protected _configurePerformanceMode(): PerformanceSettings;
+
     /**
      * Once the canvas is drawn, initialize control, visibility, and audio states
      */
@@ -229,25 +291,6 @@ declare global {
      */
     protected _initializeTokenControl(): void;
 
-    /**
-     * Get a reference to the a specific CanvasLayer by it's name
-     * @param layerName - The name of the canvas layer to get
-     */
-    getLayer(layerName: 'BackgroundLayer'): BackgroundLayer | null;
-    getLayer(layerName: 'DrawingsLayer'): DrawingsLayer | null;
-    getLayer(layerName: 'GridLayer'): GridLayer | null;
-    getLayer(layerName: 'WallsLayer'): WallsLayer | null;
-    getLayer(layerName: 'TemplateLayer'): TemplateLayer | null;
-    getLayer(layerName: 'NotesLayer'): NotesLayer | null;
-    getLayer(layerName: 'TokenLayer'): TokenLayer | null;
-    getLayer(layerName: 'ForegroundLayer'): ForegroundLayer | null;
-    getLayer(layerName: 'SoundsLayer'): SoundsLayer | null;
-    getLayer(layerName: 'LightingLayer'): LightingLayer | null;
-    getLayer(layerName: 'SightLayer'): SightLayer | null;
-    getLayer(layerName: 'EffectsLayer'): EffectsLayer | null;
-    getLayer(layerName: 'ControlsLayer'): ControlsLayer | null;
-    getLayer(layerName: string): CanvasLayer | null;
-
     /**
      * Given an embedded object name, get the canvas layer for that object
      */
@@ -261,6 +304,22 @@ declare global {
      */
     activateLayer(layerName: LayerName): void;
 
+    /**
+     * Activate framerate tracking by adding an HTML element to the display and refreshing it every frame.
+     */
+    activateFPSMeter(): void;
+
+    /**
+     * Deactivate framerate tracking by canceling ticker updates and removing the HTML element.
+     */
+    deactivateFPSMeter(): void;
+
+    /**
+     * Measure average framerate per second over the past 30 frames
+     * @internal
+     */
+    protected _measureFPS(): void;
+
     /**
      * Pan the canvas to a certain \{x,y\} coordinate and a certain zoom level
      * @param options - (default: `{}`)
@@ -285,6 +344,11 @@ declare global {
      */
     recenter(coordinates?: PanView): ReturnType<this['animatePan']>;
 
+    /**
+     * Highlight objects on any layers which are visible
+     */
+    highlightObjects(active: boolean): void;
+
     /**
      * Get the constrained zoom scale parameter which is allowed by the maxZoom parameter
      * @param x     - The requested x-coordinate
@@ -305,6 +369,12 @@ declare global {
      */
     protected updateBlur(scale?: number): void;
 
+    /**
+     * Sets the background color.
+     * @param color - The color to set the canvas background to.
+     */
+    setBackgroundColor(color: string): void;
+
     /**
      * Attach event listeners to the game canvas to handle click and interaction events
      */
@@ -420,9 +490,25 @@ declare global {
     triggerPendingOperations(): void;
 
     /**
-     * @deprecated since 0.8.2
-     */
-    initializeSources(): void;
+     * Get a reference to the a specific CanvasLayer by it's name
+     * @param layerName - The name of the canvas layer to get
+     *                    (unused)
+     * @deprecated since v9, will be deleted in v10
+     */
+    getLayer(layerName: any): {
+      BackgroundLayer: Canvas['background'];
+      DrawingsLayer: Canvas['drawings'];
+      GridLayer: Canvas['grid'];
+      TemplateLayer: Canvas['templates'];
+      TokenLayer: Canvas['tokens'];
+      WallsLayer: Canvas['walls'];
+      LightingLayer: Canvas['lighting'];
+      WeatherLayer: Canvas['weather'];
+      SightLayer: Canvas['sight'];
+      SoundsLayer: Canvas['sounds'];
+      NotesLayer: Canvas['notes'];
+      ControlsLayer: Canvas['controls'];
+    };
   }
 
   namespace Canvas {
@@ -455,6 +541,27 @@ declare global {
   }
 }
 
+type TickerCallback<T> = (this: T, dt: number) => any;
+
+interface PerformanceSettings {
+  mode: foundry.CONST.CANVAS_PERFORMANCE_MODES;
+  blur: {
+    enabled: boolean;
+    illumination: boolean;
+  };
+  mipmap: 'ON' | 'OFF';
+  msaa: boolean;
+  fps: number;
+  tokenAnimation: boolean;
+  lightAnimation: boolean;
+  textures: {
+    enabled: boolean;
+    maxSize: number;
+    p2Steps: number;
+    p2StepsMax: number;
+  };
+}
+
 interface PanView {
   /**
    * The x-coordinate of the pan destination

package/src/foundry/foundry.js/canvasAnimation.d.ts

@@ -1,3 +1,17 @@
+interface CanvasAnimationData {
+  /** The animation function being executed each frame */
+  fn: (dt: number) => void;
+
+  /** The object context within which animation occurs */
+  context: PIXI.DisplayObject;
+
+  /** A Promise which resolves once the animation is complete */
+  promise: Promise<boolean>;
+
+  /** The resolution function, allowing animation to be ended early */
+  resolve: (value: boolean) => void;
+}
+
 /**
  * A helper class providing utility methods for PIXI Canvas animation
  */
@@ -8,9 +22,7 @@ declare class CanvasAnimation {
    * Track an object of active animations by name, context, and function
    * This allows a currently playing animation to be referenced and terminated
    */
-  static animations: Partial<
-    Record<string, { fn: (dt: number) => void; context: PIXI.Container; resolve: (value: boolean) => void }>
-  >;
+  static animations: Record<string, CanvasAnimationData>;
 
   /**
    * Apply a linear animation from the current value of some attribute to a new value
@@ -39,9 +51,16 @@ declare class CanvasAnimation {
    */
   static animateLinear(
     attributes: CanvasAnimation.Attribute[],
-    options?: Partial<LinearAnimationOptions>
+    options?: InexactPartial<LinearAnimationOptions>
   ): Promise<boolean>;
 
+  /**
+   * Retrieve an animation currently in progress by its name
+   * @param name - The animation name to retrieve
+   * @returns The animation data, or undefined
+   */
+  static getAnimation(name: string): CanvasAnimationData | undefined;
+
   /**
    * If an animation using a certain name already exists, terminate it
    * @param name - The animation name to terminate
@@ -75,7 +94,7 @@ declare class CanvasAnimation {
    */
   protected static _animateFrame(
     deltaTime: number,
-    resolve: (value: boolean) => void,
+    resolve: CanvasAnimationData['resolve'],
     reject: (reason?: any) => void,
     attributes: CanvasAnimation.Attribute[],
     duration: number,
@@ -85,8 +104,12 @@ declare class CanvasAnimation {
 
 declare namespace CanvasAnimation {
   interface Attribute {
-    parent: any;
     attribute: string;
+    d?: number;
+    delta?: number;
+    done?: number;
+    parent: any;
+    remaining?: number;
     to: number;
   }
 }
@@ -95,7 +118,7 @@ interface LinearAnimationOptions {
   /**
    * An animation context to use which defines scope
    */
-  context: PIXI.Container;
+  context: PIXI.DisplayObject;
 
   /**
    * Provide a unique animation name which may be referenced later
@@ -117,7 +140,7 @@ interface LinearAnimationOptions {
 type TickFunction = (dt: number, attributes: CanvasAnimation.Attribute[]) => void;
 type TransitionFunction = (
   dt: number,
-  resolve: (value: boolean) => void,
+  resolve: CanvasAnimationData['resolve'],
   reject: (reason?: any) => void,
   attributes: CanvasAnimation.Attribute[],
   duration: number,

package/src/foundry/foundry.js/canvasDocumentMixin.d.ts

@@ -27,6 +27,13 @@ declare class CanvasDocumentMixin<T extends foundry.abstract.Document<any, any>>
    */
   protected _object: PlaceableObject | null; // TODO: Replace with InstanceType<ObjectClass<T>> | null once the circular reference problem has been solved
 
+  /**
+   * Has this object been deliberately destroyed as part of the deletion workflow?
+   * @internal
+   * @defaultValue `false`
+   */
+  protected _destroyed: boolean;
+
   /**
    * A lazily constructed PlaceableObject instance which can represent this Document on the game canvas.
    */

package/src/foundry/foundry.js/clientDocumentMixin.d.ts

@@ -55,7 +55,7 @@ export declare class ClientDocumentMixin<T extends foundry.abstract.Document<any
    *
    * @example <caption>A Document may belong to a Folder</caption>
    * ```typescript
-   * let folder = game.folders.entities[0];
+   * let folder = game.folders.contents[0];
    * let actor = await Actor.create({name: "New Actor", folder: folder.id});
    * console.log(actor.data.folder); // folder.id;
    * console.log(actor.folder); // folder;
@@ -86,7 +86,7 @@ export declare class ClientDocumentMixin<T extends foundry.abstract.Document<any
 
   /**
    * Return the permission level that the current game User has over this Document.
-   * See the CONST.ENTITY_PERMISSIONS object for an enumeration of these levels.
+   * See the CONST.DOCUMENT_PERMISSION_LEVELS object for an enumeration of these levels.
    *
    * @example
    * ```typescript
@@ -95,7 +95,7 @@ export declare class ClientDocumentMixin<T extends foundry.abstract.Document<any
    * actor.permission; // 2
    * ```
    */
-  get permission(): ValueOf<typeof CONST.ENTITY_PERMISSIONS>;
+  get permission(): ValueOf<typeof CONST.DOCUMENT_PERMISSION_LEVELS>;
 
   /**
    * Lazily obtain a FormApplication instance used to configure this Document, or null if no sheet is available.
@@ -133,7 +133,7 @@ export declare class ClientDocumentMixin<T extends foundry.abstract.Document<any
   /**
    * Prepare all embedded Document instances which exist within this primary Document.
    */
-  prepareEmbeddedEntities(): void;
+  prepareEmbeddedDocuments(): void;
 
   /**
    * Apply transformations or derivations to the values of the source data object.
@@ -273,18 +273,21 @@ export declare class ClientDocumentMixin<T extends foundry.abstract.Document<any
    * Choose a name and a type from a select menu of types.
    * @param data    - Initial data with which to populate the creation form
    *                  (default: `{}`)
-   * @param options - Positioning and sizing options for the resulting dialog
+   * @param context - Additional context options or dialog positioning options
    *                  (default: `{}`)
-   * @returns A Promise which resolves to the created Document
+   * @returns A Promise which resolves to the created Document, or null if the dialog was
+   *          closed.
    */
   static createDialog<T extends DocumentConstructor>(
     this: T,
-    data?: DeepPartial<
-      | ConstructorDataType<InstanceType<T>['data']>
-      | (ConstructorDataType<InstanceType<T>['data']> & Record<string, unknown>)
-    >,
-    options?: Dialog.Options
-  ): Promise<InstanceType<ConfiguredDocumentClass<T>> | undefined>;
+    data?:
+      | DeepPartial<
+          | ConstructorDataType<InstanceType<T>['data']>
+          | (ConstructorDataType<InstanceType<T>['data']> & Record<string, unknown>)
+        >
+      | undefined,
+    context?: (Pick<DocumentModificationContext, 'parent' | 'pack'> & Partial<Dialog.Options>) | undefined
+  ): Promise<InstanceType<ConfiguredDocumentClass<T>> | null | undefined>;
 
   /**
    * Present a Dialog form to confirm deletion of this Document.
@@ -292,18 +295,19 @@ export declare class ClientDocumentMixin<T extends foundry.abstract.Document<any
    *                  (default: `{}`)
    * @returns A Promise which resolves to the deleted Document
    */
-  deleteDialog(options?: Dialog.Options): Promise<this | undefined>;
+  deleteDialog(options?: Partial<Dialog.Options> | undefined): Promise<this | false | null | undefined>;
 
   /**
-   * Export entity data to a JSON file which can be saved by the client and later imported into a different session.
+   * Export document data to a JSON file which can be saved by the client and later imported into a different session.
+   * @param options - Additional options passed to the {@link ClientDocumentMixin#toCompendium} method
    */
-  exportToJSON(): void;
+  exportToJSON(options?: CompendiumExportOptions): void;
 
   /**
    * A helper function to handle obtaining the relevant Document from dropped data provided via a DataTransfer event.
    * The dropped data could have:
    * 1. A compendium pack and entry id
-   * 2. A World Entity _id
+   * 2. A World Document _id
    * 3. A data object explicitly provided
    *
    * @param data    - The data object extracted from a DataTransfer event
@@ -332,104 +336,55 @@ export declare class ClientDocumentMixin<T extends foundry.abstract.Document<any
    * Transform the Document data to be stored in a Compendium pack.
    * Remove any features of the data which are world-specific.
    * This function is asynchronous in case any complex operations are required prior to exporting.
-   * @param pack - A specific pack being exported to
+   * @param pack    - A specific pack being exported to
+   *                  (unused)
+   * @param options - Additional options which modify how the document is converted
+   *                  (default: `{}`)
    * @returns A data object of cleaned data suitable for compendium import
    */
-  toCompendium(pack?: CompendiumCollection<CompendiumCollection.Metadata>): Omit<
-    T['data']['_source'],
-    '_id' | 'folder' | 'permission'
-  > & {
+  toCompendium(
+    pack?: CompendiumCollection<CompendiumCollection.Metadata> | null,
+    options?: CompendiumExportOptions
+  ): Omit<T['data']['_source'], '_id' | 'folder' | 'permission'> & {
     permission?: T['data']['_source']['permission'];
   };
 
   /**
-   * @deprecated since 0.8.0
-   */
-  get _id(): T['id'];
-
-  /**
-   * @deprecated since 0.8.0
-   */
-  static get config(): any;
-
-  /**
-   * @deprecated since 0.8.0
-   */
-  get entity(): T['documentName'];
-
-  /**
-   * @deprecated since 0.8.0
-   */
-  get owner(): this['isOwner'];
-
-  /**
-   * @deprecated since 0.8.0
-   */
-  hasPerm(
-    user: foundry.documents.BaseUser,
-    permission: keyof typeof foundry.CONST.ENTITY_PERMISSIONS | foundry.CONST.EntityPermission,
-    exact?: boolean
-  ): ReturnType<T['testUserPermission']>;
-
-  /**
-   * @deprecated since 0.8.0
+   * @deprecated since v9 - Use prepareEmbeddedDocuments instead.
    */
-  static update<T extends DocumentConstructor>(
-    this: T,
-    updates?:
-      | Array<
-          DeepPartial<
-            | ConstructorDataType<InstanceType<T>['data']>
-            | (ConstructorDataType<InstanceType<T>['data']> & Record<string, unknown>)
-          > & { _id: string }
-        >
-      | (DeepPartial<
-          | ConstructorDataType<InstanceType<T>['data']>
-          | (ConstructorDataType<InstanceType<T>['data']> & Record<string, unknown>)
-        > & { _id: string }),
-    options?: DocumentModificationContext & foundry.utils.MergeObjectOptions
-  ): Promise<InstanceType<ConfiguredDocumentClass<T>>[]>;
+  prepareEmbeddedEntities(): void;
+}
 
+interface CompendiumExportOptions {
   /**
-   * @deprecated since 0.8.0
+   * Clear the flags object
+   * @defaultValue `false`
    */
-  static delete<T extends DocumentConstructor>(
-    this: T,
-    ids?: string[],
-    options?: DocumentModificationContext
-  ): Promise<InstanceType<ConfiguredDocumentClass<T>>[]>;
+  clearFlags: boolean;
 
   /**
-   * @deprecated since 0.8.0
+   * Clear the currently assigned folder and sort order
+   * @defaultValue `true`
    */
-  getEmbeddedEntity(...args: Parameters<T['getEmbeddedDocument']>): ReturnType<T['getEmbeddedDocument']>;
+  clearSort: boolean;
 
   /**
-   * @deprecated since 0.8.0
+   * Clear document permissions
+   * @defaultValue `true`
    */
-  createEmbeddedEntity(
-    documentName: string,
-    data?: Record<string, unknown> | Array<Record<string, unknown>>,
-    options?: DocumentModificationContext
-  ): ReturnType<T['createEmbeddedDocuments']>;
+  clearPermissions: boolean;
 
   /**
-   * @deprecated since 0.8.0
+   * Clear fields which store document state
+   * @defaultValue `true`
    */
-  updateEmbeddedEntity(
-    documentName: string,
-    data?: Array<Record<string, unknown>> | Record<string, unknown>,
-    options?: DocumentModificationContext
-  ): ReturnType<T['updateEmbeddedDocuments']>;
+  clearState: boolean;
 
   /**
-   * @deprecated since 0.8.0
+   * Retain the current Document id
+   * @defaultValue `false`
    */
-  deleteEmbeddedEntity(
-    documentName: string,
-    ids: string[] | string,
-    options: DocumentModificationContext
-  ): ReturnType<T['deleteEmbeddedDocuments']>;
+  keepId: boolean;
 }
 
 interface SortOptions<T> {

package/src/foundry/foundry.js/clientDocuments/activeEffect.d.ts

@@ -1,5 +1,6 @@
+import { ConfiguredDocumentClass } from '../../../types/helperTypes';
 import { DocumentModificationOptions } from '../../common/abstract/document.mjs';
-import { ConfiguredDocumentClass, ConstructorDataType } from '../../../types/helperTypes';
+import type { ActiveEffectDataConstructorData } from '../../common/data/data.mjs/activeEffectData.js';
 import { EffectChangeData } from '../../common/data/data.mjs/effectChangeData';
 
 declare global {
@@ -133,7 +134,7 @@ declare global {
     protected _getSourceName(): Promise<string>;
 
     protected _preCreate(
-      data: ConstructorDataType<foundry.data.ActiveEffectData>,
+      data: ActiveEffectDataConstructorData,
       options: DocumentModificationOptions,
       user: foundry.documents.BaseUser
     ): Promise<void>;