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

package/src/foundry/client/pixi/layers/controls/hud.d.mts

@@ -0,0 +1,114 @@
+export {};
+
+declare global {
+  /**
+   * @deprecated since v10, will be removed in v12
+   * @remarks `"The SynchronizedTransform class is deprecated and should no longer be used."`
+   */
+  class SynchronizedTransform extends PIXI.Transform {
+    constructor(transform: PIXI.Transform);
+
+    /**
+     * A list of attributes from the transform reference which should be synchronized
+     * @defaultValue
+     * ```javascript
+     * [
+     *   "localTransform", "position", "scale", "pivot", "skew", "_rotation",
+     *   "_cx", "_sx", "_cy", "_sy", "_localID", "_currentLocalID"
+     * ];
+     * ```
+     */
+    static synchronizedAttributes: string[];
+
+    /**
+     * A Transform instance which defines the reference point for the worldTransform
+     */
+    get reference(): PIXI.Transform;
+
+    set reference(value: PIXI.Transform);
+
+    /** @internal */
+    protected _reference: PIXI.Transform;
+
+    /** @internal */
+    protected _syncLocalID: number;
+
+    override updateTransform(parentTransform: PIXI.Transform): void;
+
+    override updateLocalTransform(): void;
+  }
+
+  /**
+   * @deprecated since v10, will be removed in v12
+   * @remarks `"The ObjectHUD class is deprecated and should no longer be used."`
+   */
+  class ObjectHUD extends PIXI.Container {
+    constructor(object: PIXI.DisplayObject);
+
+    /**
+     * The object that this HUD container is linked to
+     */
+    object: PIXI.DisplayObject;
+
+    /**
+     * Use the linked object's transform matrix to easily synchronize position
+     */
+    transform: PIXI.Transform;
+
+    // @ts-expect-error this is a property in `PIXI.Container` but foundry overrides it as an accessor.
+    override get visible(): boolean;
+    override set visible(value: boolean);
+
+    // @ts-expect-error this is a property in `PIXI.Container` but foundry overrides it as an accessor.
+    override get renderable(): boolean;
+    override set renderable(value: boolean);
+
+    /**
+     * @deprecated since v10, will be removed in v12
+     * @remarks `"You are calling ObjectHUD#createScrollingText which has been migrated and refactored to CanvasInterfaceGroup#createScrollingText"`
+     */
+    createScrollingText(content: string, options?: ObjectHUD.CreateScrollingTextOptions): Promise<PreciseText | null>;
+
+    /**
+     * Orchestrate the animation of the scrolling text in this HUD
+     * @param text     - The PrecisText instance to animate
+     * @param duration - A desired duration of animation
+     * @param dx       - A horizontal distance to animate the text
+     *                   (default: `0`)
+     * @param dy       - A vertical distance to animate the text
+     *                   (default: `0`)
+     * @internal
+     */
+    protected _animateScrollText(text: PreciseText, duration: number, dx?: number, dy?: number): Promise<void>;
+  }
+
+  type TextStyleProperties = Exclude<ConstructorParameters<typeof PIXI.TextStyle>[0], undefined>;
+
+  namespace ObjectHUD {
+    interface CreateScrollingTextOptions extends TextStyleProperties {
+      /**
+       * The original anchor point where the text first appears
+       * @defaultValue `CONST.TEXT_ANCHOR_POINTS.CENTER`
+       */
+      anchor?: foundry.CONST.TEXT_ANCHOR_POINTS | undefined;
+
+      /**
+       * The direction in which the text scrolls
+       * @defaultValue `CONST.TEXT_ANCHOR_POINTS.TOP`
+       */
+      direction?: foundry.CONST.TEXT_ANCHOR_POINTS | undefined;
+
+      /**
+       * The duration of the scrolling effect in milliseconds
+       * @defaultValue `2000`
+       */
+      duration?: number | undefined;
+
+      /**
+       * An amount of randomization between 0 and 1 to apply to the initial Position
+       * @defaultValue `0`
+       */
+      jitter?: number | undefined;
+    }
+  }
+}

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

@@ -0,0 +1,5 @@
+import "./cursor.d.mts";
+import "./door.d.mts";
+import "./hud.d.mts";
+import "./layer.d.mts";
+import "./ruler.d.mts";

package/src/foundry/client/pixi/layers/controls/layer.d.mts

@@ -0,0 +1,229 @@
+import type { InexactPartial } from "../../../../../types/utils.d.mts";
+import type { LineIntersection } from "../../../../common/utils/geometry.d.mts";
+
+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 InteractionLayer {
+    constructor();
+
+    /**
+     * @privateRemarks This is not overridden in foundry but reflects the real behavior.
+     */
+    static get instance(): Canvas["controls"];
+
+    /**
+     * A container of DoorControl instances
+     * @defaultValue `this.addChild(new PIXI.Container())`
+     */
+    doors: PIXI.Container;
+
+    /**
+     * A container of HUD interface elements
+     * @defaultValue `this.addChild(new PIXI.Container())`
+     */
+    hud: PIXI.Container;
+
+    /**
+     * A container of cursor interaction elements.
+     * Contains cursors, rulers, interaction rectangles, and pings
+     * @defaultValue `this.addChild(new PIXI.Container())`
+     */
+    cursors: PIXI.Container;
+
+    /**
+     * Ruler tools, one per connected user
+     * @defaultValue `this.addChild(new PIXI.Container())`
+     */
+    rulers: PIXI.Container;
+
+    /**
+     * A graphics instance used for drawing debugging visualization
+     * @defaultValue `this.addChild(new PIXI.Graphics())`
+     */
+    debug: PIXI.Graphics;
+
+    /**
+     * Canvas selection rectangle
+     * @defaultValue `undefined`
+     */
+    select: PIXI.Graphics | undefined;
+
+    /**
+     * A mapping of user IDs to Cursor instances for quick access
+     * @defaultValue `{}`
+     */
+    protected _cursors: Record<string, Cursor>;
+
+    /**
+     * A convenience mapping of user IDs to Ruler instances for quick access
+     * @internal
+     * @defaultValue `{}`
+     */
+    protected _rulers: Record<string, Ruler>;
+
+    /**
+     * The positions of any offscreen pings we are tracking.
+     * @internal
+     */
+    protected _offscreenPings: Record<string, Point>;
+
+    override options: ControlsLayer.LayerOptions;
+
+    static override get layerOptions(): ControlsLayer.LayerOptions;
+
+    /**
+     * A convenience accessor to the Ruler for the active game user
+     */
+    get ruler(): ReturnType<ControlsLayer["getRulerForUser"]>;
+
+    /**
+     * Get the Ruler display for a specific User ID
+     */
+    getRulerForUser(userId: string): Ruler | null;
+
+    override _draw(): Promise<void>;
+
+    override _tearDown(): Promise<void>;
+
+    /**
+     * Draw the cursors container
+     */
+    drawCursors(): void;
+
+    /**
+     * Create and add Ruler graphics instances for every game User.
+     */
+    drawRulers(): void;
+
+    /**
+     * Draw door control icons to the doors container.
+     */
+    drawDoors(): void;
+
+    /**
+     * Draw the select rectangle given an event originated within the base canvas layer
+     * @param coords - The rectangle coordinates of the form `{x, y, width, height}`
+     */
+    drawSelect(coords: { x: number; y: number; width: number; height: number }): void;
+
+    override _deactivate(): void;
+
+    /**
+     * Handle mousemove events on the game canvas to broadcast activity of the user's cursor position
+     */
+    protected _onMouseMove(event: PIXI.FederatedEvent): void;
+
+    /**
+     * Handle pinging the canvas.
+     * @param event   - The triggering canvas interaction event.
+     * @param origin  - The local canvas coordinates of the mousepress.
+     */
+    protected _onLongPress(event: PIXI.FederatedEvent, origin: PIXI.Point): void;
+
+    /**
+     * Handle the canvas panning to a new view.
+     */
+    protected _onCanvasPan(): void;
+
+    /**
+     * Create and draw the Cursor object for a given User
+     * @param user - The User document for whom to draw the cursor Container
+     */
+    drawCursor(user: User.ConfiguredInstance): Cursor;
+
+    /**
+     * Update the cursor when the user moves to a new position
+     * @param user     - The User for whom to update the cursor
+     * @param position - The new cursor position
+     */
+    updateCursor(user: User.ConfiguredInstance, position: Point | null): void;
+
+    /**
+     * Update display of an active Ruler object for a user given provided data
+     */
+    updateRuler(user: User.ConfiguredInstance, rulerData: Parameters<Ruler["update"]>[0] | null): void;
+
+    /**
+     * Handle a broadcast ping.
+     * @param user     - The user who pinged.
+     * @param position - The position on the canvas that was pinged.
+     * @param data     - The broadcast ping data.
+     * @returns @see Ping#animate
+     */
+    handlePing(user: User.ConfiguredInstance, position: PIXI.Point, data?: User.PingData): Promise<boolean>;
+
+    /**
+     * Draw a ping at the edge of the viewport, pointing to the location of an off-screen ping.
+     * @param position - The co-ordinates of the off-screen ping.
+     * @param options  - Additional options to configure how the ping is drawn.
+     * @returns @see {@link Ping#animate}
+     */
+    drawOffscreenPing(
+      position: PIXI.Point,
+      options?: InexactPartial<
+        PingOptions & {
+          /**
+           * The style of ping to draw, from CONFIG.Canvas.pings.
+           * @defaultValue `"arrow"`
+           */
+          style?: string;
+
+          /**
+           * The user who pinged.
+           */
+          user?: User.ConfiguredInstance;
+        }
+      >,
+    ): Promise<boolean>;
+
+    /**
+     * Draw a ping on the canvas
+     * @param position - The position on the canvas that was pinged.
+     * @param options  - Additional options to configure how the ping is drawn.
+     * @returns @see {@link Ping#animate}
+     */
+    drawPing(
+      position: PIXI.Point,
+      options?: PingOptions & {
+        /**
+         * The style of ping to draw, from CONFIG.Canvas.pings.
+         * @defaultValue `"pulse"`
+         */
+        style?: string;
+
+        /**
+         * The user who pinged.
+         */
+        user?: User.ConfiguredInstance;
+      },
+    ): Promise<boolean>;
+
+    /**
+     * Given an off-screen co-ordinate, determine the closest point at the edge of the viewport to that co-ordinate.
+     * @param position - The off-screen co-ordinate.
+     * @returns The closest point at the edge of the viewport to that
+     *          co-ordinate and a ray cast from the centre of the
+     *          screen towards it.
+     * @internal
+     */
+    protected _findViewportIntersection(position: Point): {
+      ray: Ray;
+
+      intersection: LineIntersection | null;
+    };
+  }
+
+  namespace ControlsLayer {
+    interface LayerOptions extends InteractionLayer.LayerOptions {
+      name: "controls";
+      zIndex: 1000;
+    }
+  }
+}

package/src/foundry/client/pixi/layers/controls/ruler.d.mts

@@ -0,0 +1,316 @@
+import type { InexactPartial, ValueOf } from "../../../../../types/utils.d.mts";
+
+declare global {
+  interface RulerMeasurementSegment {
+    /** The Ray which represents the point-to-point line segment */
+    ray: Ray;
+
+    /** The text object used to display a label for this segment */
+    label: PreciseText;
+
+    /** The measured distance of the segment */
+    distance: number;
+
+    /** The string text displayed in the label */
+    text: string;
+
+    /** Is this segment the last one? */
+    last: boolean;
+  }
+
+  interface RulerData {
+    /** The ruler measurement state. */
+    _state: Ruler["_state"];
+
+    /** A unique name for the ruler containing the owning user's ID. */
+    name: string;
+
+    /** The current point the ruler has been extended to. */
+    destination: PIXI.Point;
+
+    /** The class name of this ruler instance. */
+    class: string;
+
+    /** Additional waypoints along the ruler's length, including the starting point. */
+    waypoints: PIXI.Point[];
+  }
+
+  /**
+   * The Ruler - used to measure distances and trigger movements
+   */
+  class Ruler extends PIXI.Container {
+    /**
+     * @param user  - The User for whom to construct the Ruler instance
+     * @param color - (default: `null`)
+     */
+    constructor(user?: User.ConfiguredInstance | null, { color }?: { color?: number | null });
+
+    /**
+     * Record the User which this Ruler references
+     * @defaultValue `game.user`
+     */
+    user: User.ConfiguredInstance;
+
+    /**
+     * The ruler name - used to differentiate between players
+     * @defaultValue `"Ruler." + user.id`
+     */
+    name: string;
+
+    /**
+     * The ruler color - by default the color of the active user
+     * @defaultValue `foundry.utils.colorStringToHex(this.user.data.color) || 0x42F4E2`
+     */
+    color: Color;
+
+    /**
+     * This Array tracks individual waypoints along the ruler's measured path.
+     * The first waypoint is always the origin of the route.
+     * @defaultValue `[]`
+     */
+    waypoints: PIXI.Point[];
+
+    /**
+     * The Ruler element is a Graphics instance which draws the line and points of the measured path
+     */
+    ruler: PIXI.Graphics;
+
+    /**
+     * The Labels element is a Container of Text elements which label the measured path
+     */
+    labels: PIXI.Container;
+
+    /**
+     * Track the current measurement state
+     * @defaultValue `Ruler.STATES.INACTIVE`
+     */
+    protected _state: ValueOf<(typeof Ruler)["STATES"]>;
+
+    /**
+     * The current destination point at the end of the measurement
+     * @defaultValue `{x: undefined, y: undefined}`
+     */
+    destination: PIXI.Point | null;
+
+    /**
+     * The array of most recently computed ruler measurement segments
+     */
+    segments: RulerMeasurementSegment[];
+
+    /**
+     * The computed total distance of the Ruler.
+     */
+    totalDistance: number;
+
+    /**
+     * An enumeration of the possible Ruler measurement states.
+     */
+    static STATES: {
+      INACTIVE: 0;
+      STARTING: 1;
+      MEASURING: 2;
+      MOVING: 3;
+    };
+
+    /**
+     * Is the ruler ready for measure?
+     */
+    static get canMeasure(): boolean;
+
+    /**
+     * Is the Ruler being actively used to measure distance?
+     */
+    get active(): boolean;
+
+    /**
+     * Get a GridHighlight layer for this Ruler
+     */
+    get highlightLayer(): GridHighlight;
+
+    /**
+     * Clear display of the current Ruler
+     */
+    clear(): void;
+
+    /**
+     * Measure the distance between two points and render the ruler UI to illustrate it
+     * @param destination - The destination point to which to measure
+     */
+    measure(
+      destination: Point,
+      {
+        gridSpaces,
+        force,
+      }?: InexactPartial<{
+        /**
+         * Restrict measurement only to grid spaces
+         * @defaultValue `true`
+         */
+        gridSpaces: boolean;
+        /**
+         * Do the measure whatever is the destination point?
+         * @defaultValue `false`
+         */
+        force: boolean;
+      }>,
+    ): Ruler.Segment[];
+
+    /**
+     * While measurement is in progress, update the destination to be the central point of the target grid space.
+     * @param destination - The current pixel coordinates of the mouse movement
+     * @returns The destination point, a center of a grid space
+     */
+    protected _getMeasurementDestination(destination: Point): Point;
+
+    /**
+     * Translate the waypoints and destination point of the Ruler into an array of Ray segments.
+     * @returns The segments of the measured path
+     */
+    protected _getMeasurementSegments(): RulerMeasurementSegment[];
+
+    /**
+     * Compute the distance of each segment and the total distance of the measured path.
+     * @param gridSpaces - Base distance on the number of grid spaces moved?
+     */
+    protected _computeDistance(gridSpaces: boolean): void;
+
+    /**
+     * Get the text label for a segment of the measured path
+     */
+    protected _getSegmentLabel(segment: RulerMeasurementSegment, totalDistance: number): string;
+
+    /**
+     * Draw each segment of the measured path.
+     */
+    protected _drawMeasuredPath(): void;
+
+    /**
+     * Highlight the measurement required to complete the move in the minimum number of discrete spaces
+     */
+    protected _highlightMeasurementSegment(segment: RulerMeasurementSegment): void;
+
+    /**
+     * Determine whether a SPACE keypress event entails a legal token movement along a measured ruler
+     *
+     * @returns An indicator for whether a token was successfully moved or not. If True the event should be
+     *          prevented from propagating further, if False it should move on to other handlers.
+     */
+    moveToken(): Promise<false | undefined>;
+
+    /**
+     * Acquire a Token, if any, which is eligible to perform a movement based on the starting point of the Ruler
+     */
+    protected _getMovementToken(): Token.ConfiguredInstance | null | undefined;
+
+    /**
+     * Test whether a Token is allowed to execute a measured movement path.
+     * @param token - The Token being tested
+     * @returns Whether the movement is allowed
+     * @throws  A specific Error message used instead of returning false
+     */
+    protected _canMove(token: Token): true;
+
+    /**
+     * Animate piecewise Token movement along the measured segment path.
+     * @param token - The Token being animated
+     * @returns A Promise which resolves once all animation is completed
+     */
+    protected _animateMovement(token: Token): Promise<void>;
+
+    /**
+     * Update Token position and configure its animation properties for the next leg of its animation.
+     * @param token       - The Token being updated
+     * @param segment     - The measured segment being moved
+     * @param destination - The adjusted destination coordinate
+     * @returns A Promise which resolves once the animation for this segment is done
+     */
+    protected _animateSegment(token: Token, segment: RulerMeasurementSegment, destination: Point): Promise<unknown>;
+
+    /**
+     * An method which can be extended by a subclass of Ruler to define custom behaviors before a confirmed movement.
+     * @param token - The Token that will be moving
+     */
+    protected _preMove(token: Token): Promise<void>;
+
+    /**
+     * An event which can be extended by a subclass of Ruler to define custom behaviors before a confirmed movement.
+     * @param token - The Token that finished moving
+     */
+    protected _postMove(token: Token): Promise<void>;
+
+    /**
+     * Handle the beginning of a new Ruler measurement workflow
+     * @param event - The drag start event
+     * @see Canvas._onDragLeftStart
+     */
+    protected _onDragStart(event: PIXI.FederatedEvent): void;
+
+    /**
+     * Handle left-click events on the Canvas during Ruler measurement.
+     * @param event - The pointer-down event
+     * @see Canvas._onClickLeft
+     */
+    protected _onClickLeft(event: PIXI.FederatedEvent): void;
+
+    /**
+     * Handle right-click events on the Canvas during Ruler measurement.
+     * @param event - The pointer-down event
+     * @see Canvas._onClickRight
+     */
+    protected _onClickRight(event: PIXI.FederatedEvent): boolean | void;
+
+    /**
+     * Continue a Ruler measurement workflow for left-mouse movements on the Canvas.
+     * @param event - The mouse move event
+     * @see Canvas._onDragLeftMove
+     */
+    protected _onMouseMove(event: PIXI.FederatedEvent): void;
+
+    /**
+     * Conclude a Ruler measurement workflow by releasing the left-mouse button.
+     * @param event - The pointer-up event
+     * @see Canvas._onDragLeftDrop
+     */
+    protected _onMouseUp(event: PIXI.FederatedEvent): void;
+
+    /**
+     * Handle the addition of a new waypoint in the Ruler measurement path
+     * @remarks point is intentionally typed as Point because it is called with event.data.origin and only uses x and y
+     */
+    protected _addWaypoint(point: Point): void;
+
+    /**
+     * Handle the removal of a waypoint in the Ruler measurement path
+     * @param point - The current cursor position to snap to
+     * @param snap  - Snap exactly to grid spaces?
+     *                (default: `true`)
+     */
+    protected _removeWaypoint(point: PIXI.Point, { snap }?: { snap?: boolean }): void;
+
+    /**
+     * Handle the conclusion of a Ruler measurement workflow
+     */
+    protected _endMeasurement(): void;
+
+    /**
+     * Package Ruler data to an object which can be serialized to a string.
+     */
+    toJSON(): RulerData;
+
+    /**
+     * Update a Ruler instance using data provided through the cursor activity socket
+     * @param data - Ruler data with which to update the display
+     */
+    update(data: ReturnType<Ruler["toJSON"]>): void;
+  }
+
+  namespace Ruler {
+    interface Segment {
+      distance: number;
+      label: PIXI.DisplayObject;
+      last: boolean;
+      ray: Ray;
+      text: string;
+    }
+  }
+}

package/src/foundry/client/pixi/layers/effects/background-effects.d.mts

@@ -0,0 +1,34 @@
+export {};
+
+declare global {
+  /**
+   * A layer of background alteration effects which change the appearance of the primary group render texture.
+   */
+  class CanvasBackgroundAlterationEffects extends CanvasLayer {
+    /**
+     * A collection of effects which provide background vision alterations.
+     * @defaultValue `vision.sortableChildren = true`
+     */
+    vision: PIXI.Container;
+
+    /**
+     * A collection of effects which provide background preferred vision alterations.
+     * @defaultValue `visionPreferred.sortableChildren = true`
+     */
+    visionPreferred: PIXI.Container;
+
+    /**
+     * A collection of effects which provide other background alterations.
+     */
+    lighting: PIXI.Container;
+
+    protected override _draw(options?: Record<string, unknown>): Promise<void>;
+
+    protected override _tearDown(options?: Record<string, unknown>): Promise<void>;
+
+    /**
+     * Clear background alteration effects vision and lighting containers
+     */
+    clear(): void;
+  }
+}