@league-of-foundry-developers/foundry-vtt-types 9.255.2 → 9.268.1

package/src/foundry/{foundry.js/pixi/containers/placeableObjects → client/pixi/placeables}/token.d.ts

@@ -1,5 +1,9 @@
-import { ConfiguredDocumentClass, ConfiguredDocumentClassForName } from '../../../../../types/helperTypes';
-import { DocumentModificationOptions } from '../../../../common/abstract/document.mjs';
+import {
+  ConfiguredDocumentClass,
+  ConfiguredDocumentClassForName,
+  ConfiguredObjectClassForName
+} from '../../../../types/helperTypes';
+import { DocumentModificationOptions } from '../../../common/abstract/document.mjs';
 
 declare global {
   /**
@@ -25,22 +29,36 @@ declare global {
     protected _validPosition: { x: number; y: number };
 
     /**
-     * Track the set of User entities which are currently targeting this Token
+     * Track the set of User documents which are currently targeting this Token
      */
     targeted: Set<User>;
 
     /**
-     * A reference to the PointSource object which defines this vision source area of effect
+     * A reference to the VisionSource object which defines this vision source area of effect
      */
     vision: VisionSource;
 
     /**
-     * A reference to the PointSource object which defines this light source area of effect
+     * A reference to the LightSource object which defines this light source area of effect
      */
     light: LightSource;
 
-    /** @override */
-    static get embeddedName(): 'Token';
+    /**
+     * A linked ObjectHUD element which is synchronized with the location and visibility of this Token
+     * @defaultValue `new ObjectHUD(this);`
+     */
+    hud: Token.ObjectHUD;
+
+    /** @defaultValue `undefined` */
+    texture?: PIXI.Texture | null;
+
+    /** @defaultValue `undefined` */
+    border?: PIXI.Graphics;
+
+    /** @defaultValue `undefined` */
+    icon?: PIXI.Sprite;
+
+    static override embeddedName: 'Token';
 
     /**
      * Establish an initial velocity of the token based on it's direction of facing.
@@ -77,8 +95,7 @@ declare global {
      */
     readonly name: string;
 
-    /** @override */
-    get bounds(): Rectangle;
+    override get bounds(): Rectangle;
 
     /**
      * Translate the token's grid width into a pixel width based on the canvas size
@@ -95,6 +112,16 @@ declare global {
      */
     get center(): ReturnType<this['getCenter']>;
 
+    /**
+     * The HTML source element for the primary Tile texture
+     */
+    get sourceElement(): HTMLImageElement | HTMLVideoElement | undefined;
+
+    /**
+     * Does this Tile depict an animated video texture?
+     */
+    get isVideo(): boolean;
+
     /**
      * An indicator for whether or not this token is currently involved in the active combat encounter.
      */
@@ -121,6 +148,11 @@ declare global {
      */
     get isVisible(): boolean;
 
+    /**
+     * The animation name used for Token movement
+     */
+    get movementAnimationName(): string;
+
     /**
      * Test whether the Token has sight (or blindness) at any radius
      */
@@ -155,22 +187,39 @@ declare global {
 
     /**
      * Update the light and vision source objects associated with this Token
-     * @param defer       - Defer refreshing the SightLayer to manually call that refresh later.
-     *                      (default: `false`)
-     * @param deleted     - Indicate that this light source has been deleted.
-     *                      (default: `false`)
-     * @param noUpdateFog - Never update the Fog exploration progress for this update.
-     *                      (default: `false`)
+     * @param options - (default: `{}}`)
      */
-    updateSource({ defer, deleted, noUpdateFog }?: { defer?: boolean; deleted?: boolean; noUpdateFog?: boolean }): void;
+    updateSource(options?: Token.UpdateSourceOptions | undefined): void;
+
+    /**
+     * Update an emitted light source associated with this Token.
+     * @param options - (default `{}`)
+     */
+    updateLightSource(options?: Token.UpdateLightSourceOptions | undefined): void;
+
+    /**
+     * Update an Token vision source associated for this token.
+     * @param options - (default `{}`)
+     */
+    updateVisionSource(options?: Token.UpdateVisionSourceOptions | undefined): void;
 
     /**
      * Test whether this Token is a viable vision source for the current User
+     * @internal
      */
     protected _isVisionSource(): boolean;
 
-    /** @override */
-    draw(): Promise<this>;
+    override clear(): this;
+
+    override draw(): Promise<this>;
+
+    /**
+     * Draw the HUD container which provides an interface for managing this Token
+     * @internal
+     */
+    protected _drawHUD(): Token.InitializedObjectHUD;
+
+    override destroy(options?: Parameters<PlaceableObject['destroy']>[0]): void;
 
     /**
      * Apply initial sanitizations to the provided input data to ensure that a Token has valid required attributes.
@@ -187,31 +236,62 @@ declare global {
      */
     protected _drawIcon(): Promise<PIXI.Sprite>;
 
+    /**
+     * Play video for this Token (if applicable).
+     * @param playing - Should the Token video be playing?
+     *                  (default: `true`)
+     * @param options - Additional options for modifying video playback
+     *                  (default: `{}`)
+     */
+    play(playing?: boolean | undefined, options?: Token.PlayOptions | undefined): void;
+
+    /**
+     * Unlink the playback of this video token from the playback of other tokens which are using the same base texture.
+     * @param source - The video element source
+     * @internal
+     */
+    protected _unlinkVideoPlayback(source: HTMLVideoElement): Promise<void>;
+
     /**
      * Update display of the Token, pulling latest data and re-rendering the display of Token components
      */
     refresh(): this;
 
+    /**
+     * Size and display the Token Icon
+     * @internal
+     */
+    protected _refreshIcon(): void;
+
     /**
      * Draw the Token border, taking into consideration the grid type and border color
+     * @internal
      */
     protected _refreshBorder(): void;
 
     /**
      * Get the hex color that should be used to render the Token border
      * @returns The hex color used to depict the border color
+     * @internal
      */
     protected _getBorderColor(): number | null;
 
+    /**
+     * Refresh the display of the Token HUD interface.
+     */
+    refreshHUD(): void;
+
     /**
      * Refresh the target indicators for the Token.
      * Draw both target arrows for the primary User as well as indicator pips for other Users targeting the same Token.
+     * @internal
      */
     protected _refreshTarget(): void;
 
     /**
      * Refresh the display of Token attribute bars, rendering latest resource data
      * If the bar attribute is valid (has a value and max), draw the bar. Otherwise hide it.
+     * @internal
      */
     drawBars(): void;
 
@@ -221,7 +301,7 @@ declare global {
      * @param bar    - The Bar container
      * @param data   - Resource data for this bar
      */
-    protected _drawBar(number: number, bar: PIXI.Graphics, data: ReturnType<Token['getBarAttribute']>): void;
+    protected _drawBar(number: number, bar: PIXI.Graphics, data: ReturnType<TokenDocument['getBarAttribute']>): void;
 
     /**
      * Draw the token's nameplate as a text object
@@ -231,14 +311,18 @@ declare global {
 
     /**
      * Draw a text tooltip for the token which can be used to display Elevation or a resource value
+     * @returns The text object used to render the tooltip
+     * @internal
      */
-    drawTooltip(): void;
+    protected _drawTooltip(): PreciseText;
 
     /**
      * Return the text which should be displayed in a token's tooltip field
+     * @internal
      */
     protected _getTooltipText(): string;
 
+    /** @internal */
     protected _getTextStyle(): PIXI.TextStyle;
 
     /**
@@ -248,11 +332,14 @@ declare global {
 
     /**
      * Draw the overlay effect icon
+     * @param options - (default: `{}`)
+     * @internal
      */
-    protected _drawOverlay({ src, tint }?: { src?: string; tint?: number }): Promise<void>;
+    protected _drawOverlay(options?: Token.DrawOverlayOptions | undefined): Promise<void>;
 
     /**
      * Draw a status effect icon
+     * @internal
      */
     protected _drawEffect(src: string, i: number, bg: PIXI.Graphics, w: number, tint: number): Promise<void>;
 
@@ -260,6 +347,7 @@ declare global {
      * Helper method to determine whether a token attribute is viewable under a certain mode
      * @param mode - The mode from CONST.TOKEN_DISPLAY_MODES
      * @returns Is the attribute viewable?
+     * @internal
      */
     protected _canViewMode(mode: foundry.CONST.TOKEN_DISPLAY_MODES): boolean;
 
@@ -271,6 +359,7 @@ declare global {
 
     /**
      * Animate the continual revealing of Token vision during a movement animation
+     * @internal
      */
     protected _onMovementFrame(
       dt: number,
@@ -288,6 +377,7 @@ declare global {
      * @param source - (default: `false`)
      * @param sound  - (default: `false`)
      * @param fog    - (default: `false`)
+     * @internal
      */
     protected _animatePerceptionFrame({
       source,
@@ -315,10 +405,9 @@ declare global {
      * @param releaseOthers - (default: `true`)
      * @param pan           - (default: `false`)
      */
-    protected _onControl({ releaseOthers, pan }?: { releaseOthers?: boolean; pan?: boolean }): void;
+    protected override _onControl({ releaseOthers, pan }?: { releaseOthers?: boolean; pan?: boolean }): void;
 
-    /** @override */
-    protected _onRelease(
+    protected override _onRelease(
       options: PlaceableObject.ReleaseOptions
     ): Promise<InstanceType<ConfiguredDocumentClass<typeof TokenDocument>>> | undefined;
 
@@ -345,39 +434,25 @@ declare global {
      *                  (defaultValue: `{}`)
      * @returns The Token after animation has completed
      */
-    setPosition(x: number, y: number, options?: PositionOptions): Promise<this>;
+    setPosition(x: number, y: number, options?: Token.PositionOptions): Promise<this>;
 
     /**
      * Update the Token velocity auto-regressively, shifting increasing weight towards more recent movement
      * Employ a magic constant chosen to minimize (effectively zero) the likelihood of trigonometric edge cases
      * @param ray - The proposed movement ray
      * @returns An updated velocity with directional memory
+     * @internal
      */
     protected _updateVelocity(ray: Ray): Token.Velocity;
 
     /**
      * Set this Token as an active target for the current game User
-     * @param targeted       - Is the Token now targeted?
-     *                         (default: `true`)
-     * @param user           - Assign the token as a target for a specific User
-     *                         (default: `null` which will use the current user)
-     * @param releaseOthers  - Release other active targets for the same player?
-     *                         (default: `true`)
-     * @param groupSelection - Is this target being set as part of a group selection workflow?
-     *                         (default: `false`)
-     */
-    setTarget(
-      targeted?: boolean,
-      {
-        user,
-        releaseOthers,
-        groupSelection
-      }?: {
-        user?: InstanceType<ConfiguredDocumentClass<typeof User>> | null;
-        releaseOthers?: boolean;
-        groupSelection?: boolean;
-      }
-    ): void;
+     * @param targeted - Is the Token now targeted?
+     *                   (default: `true`)
+     * @param context  - Additional context options
+     *                   (default `{}`)
+     */
+    setTarget(targeted?: boolean, context?: Token.SetTargetContext | undefined): void;
 
     /**
      * Add or remove the currently controlled Tokens from the active combat encounter
@@ -387,7 +462,7 @@ declare global {
     toggleCombat(combat?: InstanceType<ConfiguredDocumentClass<typeof Combat>>): Promise<this>;
 
     /**
-     * Toggle an active effect by it's texture path.
+     * Toggle an active effect by its texture path.
      * Copy the existing Array in order to ensure the update method detects the data as changed.
      *
      * @param effect  - The texture file-path of the effect icon to toggle on the Token.
@@ -397,19 +472,12 @@ declare global {
      */
     toggleEffect(
       effect: string | ConstructorParameters<ConfiguredDocumentClassForName<'ActiveEffect'>>[0],
-      options?: EffectToggleOptions
-    ): Promise<boolean>;
-
-    /**
-     * A helper function to toggle a status effect which includes an Active Effect template
-     */
-    protected _toggleActiveEffect(
-      effectData: ConstructorParameters<ConfiguredDocumentClassForName<'ActiveEffect'>>[0],
-      { overlay }?: { overlay?: boolean }
+      options?: Token.EffectToggleOptions | undefined
     ): Promise<boolean>;
 
     /**
      * A helper function to toggle the overlay status icon on the Token
+     * @internal
      */
     protected _toggleOverlayEffect(texture: string, { active }?: { active: boolean }): Promise<this>;
 
@@ -436,95 +504,68 @@ declare global {
      */
     getLightRadius(units: number): number;
 
-    /** @override */
-    protected _getShiftedPosition(dx: number, dy: number): { x: number; y: number };
+    protected override _getShiftedPosition(dx: number, dy: number): { x: number; y: number };
 
-    /**
-     * Extend the PlaceableObject.rotate method to prevent rotation if the Token is in the midst of a movement animation
-     * @returns Actually a Promise<void>
-     */
-    rotate(angle: number, snap: number): Promise<this>;
+    override rotate(...args: Parameters<PlaceableObject['rotate']>): Promise<this>;
 
-    /** @override */
-    protected _onCreate(
+    protected override _onCreate(
       options: InstanceType<ConfiguredDocumentClass<typeof TokenDocument>>['data']['_source'],
       userId: DocumentModificationOptions
     ): void;
 
-    /** @override */
-    protected _onUpdate(
+    protected override _onUpdate(
       data?: DeepPartial<InstanceType<ConfiguredDocumentClass<typeof TokenDocument>>['data']['_source']>,
       options?: DocumentModificationOptions & { animate?: boolean },
       userId?: string
     ): void;
 
-    /** @override */
-    protected _onDelete(options?: DocumentModificationOptions, userId?: string): void;
+    protected override _onDelete(options?: DocumentModificationOptions, userId?: string): void;
 
-    /** @override */
-    protected _canControl(
+    protected override _canControl(
       user?: InstanceType<ConfiguredDocumentClass<typeof User>>,
       event?: PIXI.InteractionEvent
     ): boolean;
 
-    /** @override */
-    protected _canHUD(user: InstanceType<ConfiguredDocumentClass<typeof User>>, event?: PIXI.InteractionEvent): boolean;
+    protected override _canHUD(
+      user: InstanceType<ConfiguredDocumentClass<typeof User>>,
+      event?: PIXI.InteractionEvent
+    ): boolean;
 
-    /** @override */
-    protected _canConfigure(
+    protected override _canConfigure(
       user?: InstanceType<ConfiguredDocumentClass<typeof User>>,
       event?: PIXI.InteractionEvent
     ): true;
 
-    /** @override */
-    protected _canHover(user?: InstanceType<ConfiguredDocumentClass<typeof User>>, event?: PIXI.InteractionEvent): true;
+    protected override _canHover(
+      user?: InstanceType<ConfiguredDocumentClass<typeof User>>,
+      event?: PIXI.InteractionEvent
+    ): true;
 
-    /** @override */
-    protected _canView(
+    protected override _canView(
       user?: InstanceType<ConfiguredDocumentClass<typeof User>>,
       event?: PIXI.InteractionEvent
     ): boolean;
 
-    /** @override */
-    protected _canDrag(user: InstanceType<ConfiguredDocumentClass<typeof User>>, event: PIXI.InteractionEvent): boolean;
-
-    /** @override */
-    protected _onHoverIn(event: PIXI.InteractionEvent, options?: { hoverOutOthers?: boolean }): void;
-
-    /** @override */
-    protected _onHoverOut(event: PIXI.InteractionEvent): false | void;
+    protected override _canDrag(
+      user: InstanceType<ConfiguredDocumentClass<typeof User>>,
+      event: PIXI.InteractionEvent
+    ): boolean;
 
-    /** @override */
-    protected _onClickLeft(event: PIXI.InteractionEvent): void;
+    protected override _onHoverIn(event: PIXI.InteractionEvent, options?: { hoverOutOthers?: boolean }): void;
 
-    /** @override */
-    protected _onClickLeft2(event?: PIXI.InteractionEvent): void;
+    protected override _onHoverOut(event: PIXI.InteractionEvent): false | void;
 
-    /** @override */
-    protected _onClickRight2(event: PIXI.InteractionEvent): void;
+    protected override _onClickLeft(event: PIXI.InteractionEvent): void;
 
-    /** @override */
-    protected _onDragLeftDrop(event: PIXI.InteractionEvent): Promise<any>;
+    protected override _onClickLeft2(event?: PIXI.InteractionEvent): void;
 
-    /** @override */
-    protected _onDragLeftMove(event: PIXI.InteractionEvent): void;
+    protected override _onClickRight2(event: PIXI.InteractionEvent): void;
 
-    /**
-     * @deprecated since 0.8.0
-     */
-    static fromActor(
-      actor: InstanceType<ConfiguredDocumentClass<typeof Actor>>,
-      tokenData?: InstanceType<ConfiguredDocumentClass<typeof TokenDocument>>['data']['_source']
-    ): never;
+    protected override _onDragLeftDrop(event: PIXI.InteractionEvent): Promise<any>;
 
-    /**
-     * @deprecated since 0.8.0
-     */
-    getBarAttribute(
-      barName: string,
-      { alternative }?: { alternative?: string }
-    ): ReturnType<this['document']['getBarAttribute']>;
+    protected override _onDragLeftMove(event: PIXI.InteractionEvent): void;
 
+    protected override _onDragLeftCancel(event: MouseEvent): void;
     /**
      * @remarks This does not exist in foundry. It marks the controlIcon as not used because `Token` does never store a value here.
      */
@@ -542,27 +583,140 @@ declare global {
       dy: number;
       sy: number;
     }
-  }
-}
 
-interface PositionOptions {
-  /**
-   * Animate the movement path
-   * @defaultValue `true`
-   */
-  animate?: boolean;
-}
+    /** The UI frame container which depicts Token metadata and status, displayed in the ControlsLayer. */
+    interface ObjectHUD extends globalThis.ObjectHUD {
+      /** Token health bars */
+      bars?: PIXI.Container;
 
-interface EffectToggleOptions {
-  /**
-   * Force a certain active state for the effect
-   * @defaultValue `false`
-   */
-  active?: boolean;
+      /** Token nameplate */
+      nameplate?: PreciseText;
+
+      /** Token elevation tooltip */
+      tooltip?: PreciseText;
+
+      /** Token status effects */
+      effects?: PIXI.Container;
+
+      /** Token target marker */
+      target?: PIXI.Graphics;
+    }
+
+    type InitializedObjectHUD = RequiredProps<ObjectHUD, 'bars' | 'nameplate' | 'tooltip' | 'effects' | 'target'>;
+
+    interface UpdateLightSourceOptions {
+      /**
+       * Defer refreshing the LightingLayer to manually call that refresh later.
+       * @defaultValue `false`
+       */
+      defer?: boolean | undefined;
+
+      /**
+       * Indicate that this light source has been deleted.
+       * @defaultValue `false`
+       */
+      deleted?: boolean | undefined;
+    }
+
+    interface UpdateVisionSourceOptions {
+      /**
+       * Defer refreshing the SightLayer to manually call that refresh later.
+       * @defaultValue `false`
+       */
+      defer?: boolean | undefined;
+
+      /**
+       * Indicate that this vision source has been deleted.
+       * @defaultValue `false`
+       */
+      deleted?: boolean | undefined;
+
+      /**
+       * Never update the Fog exploration progress for this update.
+       * @defaultValue `false`
+       */
+      skipUpdateFog?: boolean | undefined;
+    }
+
+    type UpdateSourceOptions = UpdateLightSourceOptions & UpdateVisionSourceOptions;
+
+    interface PlayOptions {
+      /**
+       * Should the video loop?
+       * @defaultValue `true`
+       */
+      loop?: boolean | undefined;
+
+      /**
+       * A specific timestamp between 0 and the video duration to begin playback
+       * @defaultValue `0`
+       */
+      offset?: number | undefined;
+
+      /**
+       * Desired volume level of the video's audio channel (if any)
+       * @defaultValue `0`
+       */
+      volume?: number | undefined;
+    }
+
+    interface DrawOverlayOptions {
+      src?: string | undefined;
+      tint?: number | undefined;
+    }
+
+    interface PositionOptions {
+      /**
+       * Animate the movement path
+       * @defaultValue `true`
+       */
+      animate?: boolean;
+
+      /**
+       * Automatically re-center the view if token movement goes off-screen
+       * @defaultValue `true`
+       */
+      recenter?: boolean | undefined;
+    }
+
+    interface EffectToggleOptions {
+      /**
+       * Force a certain active state for the effect
+       * @defaultValue `false`
+       */
+      active?: boolean | undefined;
+
+      /**
+       * Whether to set the effect as the overlay effect?
+       * @defaultValue `false`
+       */
+      overlay?: boolean | undefined;
+    }
+
+    interface SetTargetContext {
+      /**
+       * Assign the token as a target for a specific User
+       * @defaultValue `null`
+       */
+      user?: InstanceType<ConfiguredDocumentClass<typeof User>> | null | undefined;
+
+      /**
+       * Release other active targets for the same player?
+       * @defaultValue `true`
+       */
+      releaseOthers?: boolean | undefined;
+
+      /**
+       * Is this target being set as part of a group selection workflow?
+       * @defaultValue `Is this target being set as part of a group selection workflow?`
+       */
+      groupSelection?: boolean | undefined;
+    }
+  }
 
   /**
-   * Whether to set the effect as the overlay effect?
-   * @defaultValue `false`
+   * A "secret" global to help debug attributes of the currently controlled Token.
+   * This is only for debugging, and may be removed in the future, so it's not safe to use.
    */
-  overlay?: boolean;
+  let _token: InstanceType<ConfiguredObjectClassForName<'Token'>> | null;
 }