@league-of-foundry-developers/foundry-vtt-types 13.340.1 → 13.345.1-beta.20250704.94554

package/src/foundry/client/canvas/placeables/tokens/ring.d.mts

@@ -0,0 +1,290 @@
+import type { Brand, FixedInstanceType, Identity, InitializedOn } from "#utils";
+import type { DynamicRingData } from "./_module.d.mts";
+import type { CanvasAnimation } from "#client/canvas/animation/_module.d.mts";
+import type { PrimarySpriteMesh } from "#client/canvas/primary/_module.d.mts";
+import type { Token } from "#client/canvas/placeables/_module.d.mts";
+
+/**
+ * Dynamic Token Ring Manager.
+ */
+declare class TokenRing {
+  /** A `TokenRing` is constructed by providing a reference to a `Token` object. */
+  constructor(token: Token.Implementation);
+
+  /** The effects which could be applied to a token ring (using bitwise operations) */
+  static effects: TokenRing.Effects;
+
+  /**
+   * Is the token rings framework enabled? Will be `null` if the system hasn't initialized yet.
+   * @remarks {@link TokenRing.initialize | `CONFIG.Token.ring.ringClass.initialize`} is called inside {@linkcode Canvas.initialize}, which is called between the `setup` and `ready` hooks.
+   */
+  static get initialized(): InitializedOn<true, "ready", true | null>;
+
+  /**
+   * Token Rings sprite sheet base texture.
+   * @remarks Only `undefined` prior to first canvas draw; set in {@linkcode createAssetsUVs}
+   */
+  static baseTexture: PIXI.BaseTexture | undefined;
+
+  /**
+   * Rings and background textures UVs and center offset.
+   * @remarks Only `undefined` prior to first canvas draw; set in {@linkcode createAssetsUVs}
+   */
+  static texturesData: Record<string, TokenRing.TextureData> | undefined;
+
+  /**
+   * The token ring shader class definition.
+   * @remarks Set in {@link TokenRing.initialize | `initialize`}
+   */
+  static tokenRingSamplerShader: InitializedOn<DynamicRingData["framework"]["shaderClass"], "ready">;
+
+  /** Initialize the Token Rings system, registering the batch plugin and patching `PrimaryCanvasGroup#addToken`. */
+  static initialize(): void;
+
+  /** Create texture UVs for each asset into the token rings sprite sheet. */
+  static createAssetsUVs(): void;
+
+  /**
+   * Get the UVs array for a given texture name and scale correction.
+   * @param name              - Name of the texture we want to get UVs.
+   * @param scaleCorrection   - The scale correction applied to UVs. (default: `1`)
+   */
+  // scaleCorrection: not null (parameter default only, casting to 0 produces nonsense)
+  static getTextureUVs(name: string, scaleCorrection?: number): Float32Array;
+
+  /**
+   * Get ring and background names for a given size.
+   * @param size  - The size to match (grid size dimension)
+   * @remarks `size` is in units of grid _spaces_, the core rings provide spritesheet frames for `0.5`, `1`, `2`, `3`, and `4`,
+   * and the value core passes in its only call is `Math.min(this.token.document.width ?? 1, this.token.document.height ?? 1)`.
+   * Values between provided sizes will use the closest available size provided.
+   */
+  static getRingDataBySize(size: number): TokenRing.RingData;
+
+  /**
+   * @remarks Not initialized to a value, this gets set in {@link TokenRing.configureSize | TokenRing.configureSize`}.
+   * After initialization (`ready`), this will only be `undefined` if the current spritesheet provides no frames
+   */
+  ringName: TokenRing.RingData["ringName"];
+
+  /**
+   * @remarks Not initialized to a value, this gets set in {@linkcode TokenRing.configureSize}.
+   * After initialization (`ready`), this will only be `undefined` if the current spritesheet provides no frames
+   */
+  bkgName: TokenRing.RingData["bkgName"];
+
+  ringUVs: InitializedOn<Float32Array, "ready">;
+
+  bkgUVs: InitializedOn<Float32Array, "ready">;
+
+  /**
+   * Little endian format =\> BBGGRR
+   * @defaultValue `0xFFFFFF`
+   */
+  ringColorLittleEndian: number;
+
+  /**
+   * Little endian format =\> BBGGRR
+   * @defaultValue `0xFFFFFF`
+   */
+  bkgColorLittleEndian: number;
+
+  /**
+   * @defaultValue `null`
+   * @remarks Cannot be `undefined` as core explicitly checks for `null`.
+   */
+  defaultRingColorLittleEndian: TokenRing.RingData["defaultRingColorLittleEndian"];
+
+  /**
+   * @defaultValue `null`
+   * @remarks Cannot be `undefined` as core explicitly checks for `null`.
+   */
+  defaultBackgroundColorLittleEndian: TokenRing.RingData["defaultBackgroundColorLittleEndian"];
+
+  /**
+   * @defaultValue `0`
+   * @remarks A bitmask of {@link TokenRing.Effects | `effects`}
+   */
+  effects: number;
+
+  /**
+   * @defaultValue `1`
+   */
+  scaleCorrection: number;
+
+  /**
+   * @defaultValue `1`
+   */
+  scaleAdjustmentX: number;
+
+  /**
+   * @defaultValue `1`
+   */
+  scaleAdjustmentY: number;
+
+  /**
+   * @defaultValue `1`
+   */
+  subjectScaleAdjustment: TokenRing.RingData["subjectScaleAdjustment"];
+
+  /**
+   * @defaultValue `1`
+   */
+  textureScaleAdjustment: number;
+
+  /**
+   * @remarks Not initialized to a value, this gets set in {@link TokenRing.configureSize | `configureSize`}.
+   * After initialization (`ready`), this will only be `undefined` if the current spritesheet provides no frames
+   */
+  colorBand: TokenRing.RingData["colorBand"];
+
+  /**
+   * Reference to the token that should be animated
+   * @remarks This getter is the return of calling {@link WeakRef.deref | `deref`} on the stored {@linkcode WeakRef}
+   * of the Token passed at construction; If the Token has been garbage collected, will return undefined.
+   */
+  get token(): Token.Implementation | undefined;
+
+  /**
+   * Configure the sprite mesh.
+   * @param mesh  - The mesh to which TokenRing functionality is configured.
+   */
+  configure(mesh: PrimarySpriteMesh): void;
+
+  /** Clear configuration pertaining to token ring from the mesh. */
+  clear(): void;
+
+  /** Configure token ring size. */
+  configureSize(): void;
+
+  /** Configure the token ring visuals properties. */
+  configureVisuals(): void;
+
+  /**
+   * Flash the ring briefly with a certain color.
+   * @param color            - Color to flash.
+   * @param animationOptions - Options to customize the animation. (default: `{}`)
+   * @remarks Only returns `Promise<void>` if `color` is `NaN`ish
+   */
+  flashColor(Color: Color, animationOptions?: TokenRing.FlashColorOptions | null): Promise<boolean | void>;
+
+  /**
+   * Create an easing function that spikes in the center. Ideal duration is around 1600ms.
+   * @param spikePct  - Position on [0,1] where the spike occurs. (default: `0.5`)
+   */
+  // spikePct: not null (used as divisor)
+  static createSpikeEasing(spikePct?: number): CanvasAnimation.EasingFunction;
+
+  /**
+   * Easing function that produces two peaks before returning to the original value. Ideal duration is around 500ms.
+   * @param pt  - The proportional animation timing on [0,1].
+   * @returns   - The eased animation progress on [0,1].
+   */
+  static easeTwoPeaks(pt: number): number;
+
+  /**
+   * To avoid breaking dnd5e.
+   * @deprecated since v12
+   * @remarks No deprecation warning or end of deprecation period provided, method body completely empty
+   */
+  configureMesh(): void;
+
+  /**
+   * To avoid breaking dnd5e.
+   * @deprecated since v12
+   * @remarks No deprecation warning or end of deprecation period provided, method body completely empty
+   */
+  configureNames(): void;
+}
+
+declare namespace TokenRing {
+  interface Any extends AnyTokenRing {}
+  interface AnyConstructor extends Identity<typeof AnyTokenRing> {}
+
+  interface ConfiguredClass extends Identity<CONFIG["Token"]["ring"]["ringClass"]> {}
+  interface ConfiguredInstance extends FixedInstanceType<ConfiguredClass> {}
+
+  /** @remarks Overrides for default values */
+  interface FlashColorOptions extends CanvasAnimation.AnimateOptions {
+    /**
+     * @defaultValue `1600`
+     * @remarks Can't be `null` because it only has a parameter default, and is used as a divisor in `CanvasAnimation.#animateFrame`
+     */
+    duration?: number;
+
+    /** @defaultValue `PIXI.UPDATE_PRIORITY.HIGH` */
+    priority?: PIXI.UPDATE_PRIORITY | null | undefined;
+
+    /** @defaultValue `TokenRing.createSpikeEasing(0.15)` */
+    easing?: CanvasAnimation.EasingFunction | null | undefined;
+  }
+
+  interface TextureData {
+    UVs: Float32Array;
+    center: { x: number; y: number };
+  }
+
+  /**
+   * @remarks {@link TokenRing.configureSize | `configureSize`} effectively calls `Object.assign(this, RingData)`
+   */
+  interface RingData {
+    ringName: string | undefined;
+
+    bkgName: string | undefined;
+
+    colorBand: ColorBand | undefined;
+
+    /**
+     * @remarks This property comes from the spritesheet JSON and is included with the frame entries in the `##ringData`
+     * private array, but is stripped out of the return of {@link TokenRing.getRingDataBySize | `getRingDataBySize`},
+     * and thus never gets assigned as a property to the `TokenRing` instance in {@link TokenRing.configureSize | `configureSize`}
+     */
+    gridTarget?: number;
+
+    defaultRingColorLittleEndian: number | null;
+
+    defaultBackgroundColorLittleEndian: number | null;
+
+    subjectScaleAdjustment: number | null;
+  }
+
+  /** The start and end radii of the token ring color band. */
+  interface ColorBand {
+    /**
+     * The starting normalized radius of the token ring color band.
+     * @defaultValue `0.59`
+     * @remarks Default only applies if spritesheet frame omits `colorBand` entirely
+     */
+    startRadius: number;
+
+    /**
+     * The ending normalized radius of the token ring color band.
+     * @defaultValue `0.7225`
+     * @remarks Default only applies if spritesheet frame omits `colorBand` entirely
+     */
+    endRadius: number;
+  }
+
+  type EFFECTS = Brand<number, "TokenRing.effects">;
+
+  interface Effects {
+    readonly DISABLED: 0x00 & EFFECTS;
+
+    readonly ENABLED: 0x01 & EFFECTS;
+
+    readonly RING_PULSE: 0x02 & EFFECTS;
+
+    readonly RING_GRADIENT: 0x04 & EFFECTS;
+
+    readonly BKG_WAVE: 0x08 & EFFECTS;
+
+    /** @remarks Foundry comments "or spectral pulse effect" */
+    readonly INVISIBILITY: 0x10 & EFFECTS;
+  }
+}
+
+declare abstract class AnyTokenRing extends TokenRing {
+  constructor(...args: never);
+}
+
+export default TokenRing;

package/src/foundry/client/canvas/placeables/tokens/ruler.d.mts

@@ -0,0 +1,219 @@
+import type { Identity } from "#utils";
+import type { BaseTokenRuler } from "./_module.d.mts";
+
+declare class TokenRuler extends BaseTokenRuler {
+  #TokenRuler: true;
+
+  /**
+   * A handlebars template used to render each waypoint label.
+   */
+  static WAYPOINT_LABEL_TEMPLATE: string;
+
+  protected override _onVisibleChange(): void;
+
+  /**
+   * Configure the properties of the outline.
+   * Called in {@linkcode TokenRuler.draw | TokenRuler#draw}.
+   * @returns The thickness in pixels and the color
+   */
+  protected _configureOutline(): TokenRuler.Outline;
+
+  /**
+   * Configure the properties of the dash line.
+   * Called in {@linkcode TokenRuler.draw | TokenRuler#draw}.
+   * @returns The dash in pixels, the gap in pixels, and the speed in pixels per second
+   */
+  protected _configureDashLine(): TokenRuler.DashLine;
+
+  draw(): Promise<void>;
+
+  clear(): void;
+
+  destroy(): void;
+
+  refresh(rulerData: TokenRuler.Data): void;
+
+  /**
+   * Get the context used to render a ruler waypoint label.
+   */
+  protected _getWaypointLabelContext(
+    waypoint: TokenRuler.Waypoint,
+    state: TokenRuler.State,
+  ): TokenRuler.WaypointContext | void;
+
+  /**
+   * Get the style of the waypoint at the given waypoint.
+   * @param waypoint - The waypoint
+   * @returns The radius, color, and alpha of the waypoint. If the radius is 0, no waypoint marker is drawn.
+   */
+  protected _getWaypointStyle(waypoint: TokenRuler.Waypoint): TokenRuler.WaypointStyle;
+
+  /**
+   * Get the style of the segment from the previous to the given waypoint.
+   * @param waypoint - The waypoint
+   * @returns The line width, color, and alpha of the segment.  If the width is 0, no segment is drawn.
+   */
+  protected _getSegmentStyle(waypoint: TokenRuler.Waypoint): TokenRuler.SegmentStyle;
+
+  /**
+   * Get the style to be used to highlight the grid offset.
+   * @param waypoint - The waypoint
+   * @param offset   - An occupied grid offset at the given waypoint that is to be highlighted
+   * @returns The color, alpha, texture, and texture matrix to be used to draw the grid space.
+   *          If the alpha is 0, the grid space is not highlighted.
+   */
+  protected _getGridHighlightStyle(
+    waypoint: TokenRuler.Waypoint,
+    offset: foundry.grid.BaseGrid.Offset3D,
+  ): TokenRuler.GridHighlightStyle;
+}
+
+declare namespace TokenRuler {
+  interface Any extends AnyTokenRuler {}
+  interface AnyConstructor extends Identity<typeof AnyTokenRuler> {}
+
+  interface Outline {
+    thickness: number;
+    color: PIXI.ColorSource;
+  }
+
+  interface DashLine {
+    dash: number;
+    gap: number;
+    speed: number;
+  }
+
+  interface Data {
+    /**
+     * The waypoints that were already passed by the Token
+     */
+    passedWaypoints: foundry.canvas.placeables.Token.MeasuredMovementWaypoint[];
+
+    /**
+     * The waypoints that the Token will try move to next
+     */
+    pendingWaypoints: foundry.canvas.placeables.Token.MeasuredMovementWaypoint[];
+
+    /**
+     * Movement planned by Users
+     */
+    plannedMovement: Record<string, foundry.canvas.placeables.Token.PlannedMovement>;
+  }
+
+  interface WaypointData {
+    /** The config of the movement action */
+    actionConfig: CONFIG.Token.MovementActionConfig;
+
+    /** The ID of movement, or null if planned movement. */
+    movementId: string | null;
+
+    /** The index of the waypoint, which is equal to the number of explicit waypoints from the first to this waypoint. */
+    index: number;
+
+    /** The stage this waypoint belongs to */
+    stage: "passed" | "pending" | "planned";
+
+    /** Is this waypoint hidden? */
+    hidden: boolean;
+
+    /** Is this waypoint unreachable? */
+    unreachable: boolean;
+
+    /** The center point of the Token at this waypoint. */
+    center: PIXI.Point;
+
+    /** The size of the Token in pixels at this waypoint. */
+    size: {
+      width: number;
+      height: number;
+    };
+
+    /** The ray from the center point of previous to the center point of this waypoint, or null if there is no previous waypoint. */
+    ray: foundry.canvas.geometry.Ray | null;
+
+    /** The measurements at this waypoint. */
+    measurement: foundry.grid.BaseGrid.MeasurePathResultWaypoint;
+
+    /** The previous waypoint, if any. */
+    previous: Waypoint | null;
+
+    /** The next waypoint, if any. */
+    next: Waypoint | null;
+  }
+
+  /**
+   * @remarks This is not intended to be mutated, so foundry has marked it DeepReadonly,
+   * but there's no programmatic block on mutation
+   */
+  type Waypoint = Omit<TokenDocument.MeasuredMovementWaypoint, "movementId"> & WaypointData;
+
+  /**
+   * @remarks Intended to be extended by subclasses that need to track additional info between waypoints
+   * Importantly, this is *not* saved to the token's movement data, instead it is merely mutated locally.
+   */
+  interface State {
+    hasElevation: boolean;
+    previousElevation: number;
+  }
+
+  /**
+   * @remarks Fed into the template
+   */
+  interface WaypointContext {
+    action: string;
+    cssClass: string;
+    secret: boolean;
+    units: string;
+    uiScale: number;
+    position: {
+      x: number;
+      y: number;
+    };
+    distance: SegmentDistance;
+    cost: SegmentCost;
+    elevation: ElevationContext;
+  }
+
+  interface SegmentDistance {
+    total: string;
+    delta?: string | undefined;
+  }
+
+  interface SegmentCost {
+    total: string;
+    units: string;
+    delta?: string | undefined;
+  }
+
+  interface ElevationContext {
+    total: number;
+    icon: string;
+    hidden: boolean;
+    delta?: string | undefined;
+  }
+
+  interface WaypointStyle {
+    radius: number;
+    color?: PIXI.ColorSource | undefined;
+    alpha?: number | undefined;
+  }
+
+  interface SegmentStyle {
+    width: number;
+    color?: PIXI.ColorSource | undefined;
+    alpha?: number | undefined;
+  }
+
+  interface GridHighlightStyle {
+    color?: PIXI.ColorSource | undefined;
+    alpha?: number | undefined;
+    texture?: PIXI.Texture | undefined;
+    matrix?: PIXI.Matrix | null | undefined;
+  }
+}
+
+export default TokenRuler;
+
+declare abstract class AnyTokenRuler extends TokenRuler {
+  constructor(...args: never);
+}

package/src/foundry/client/canvas/placeables/tokens/targets.d.mts

@@ -0,0 +1,50 @@
+import type { Identity } from "#utils";
+import type { Token } from "#client/canvas/placeables/_module.d.mts";
+
+// This class exists make it as sound as possible to override these parts of the class and make them
+// completely unrelated. It's done this way specifically to avoid situations with broken inheritance.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+declare class LenientSet<T> extends globalThis.Set<T> {
+  add(value: T): any;
+  delete(value: T): any;
+}
+
+declare const Set: typeof LenientSet;
+
+/**
+ * A subclass of Set which manages the Token ids which the User has targeted.
+ * @see {@link User.targets | `User#targets`}
+ */
+declare class UserTargets extends Set<Token.Implementation> {
+  constructor(user: UserTargets["user"]);
+
+  user: User.Implementation;
+
+  /**
+   * Return the Token IDs which are user targets
+   */
+  get ids(): string[];
+
+  /**
+   * @remarks Returns void, but Set<T>.add returns boolean
+   */
+  override add(token: Token.Implementation): void;
+
+  override clear(): void;
+
+  /**
+   * @remarks Returns void, but Set<T>.delete returns boolean
+   */
+  override delete(token: Token.Implementation): void;
+}
+
+declare namespace UserTargets {
+  interface Any extends AnyUserTargets {}
+  interface AnyConstructor extends Identity<typeof AnyUserTargets> {}
+}
+
+export default UserTargets;
+
+declare abstract class AnyUserTargets extends UserTargets {
+  constructor(...args: never);
+}

package/src/foundry/client/canvas/placeables/tokens/turn-marker-data.d.mts

@@ -0,0 +1,17 @@
+import type { Identity } from "#utils";
+import type { DataModel } from "#common/abstract/_module.d.mts";
+
+declare class TurnMarkerData extends DataModel<TurnMarkerData.Schema> {}
+
+declare namespace TurnMarkerData {
+  interface Any extends AnyTurnMarkerData {}
+  interface AnyConstructor extends Identity<typeof AnyTurnMarkerData> {}
+
+  interface Schema extends foundry.data.fields.DataSchema {}
+}
+
+export default TurnMarkerData;
+
+declare abstract class AnyTurnMarkerData extends TurnMarkerData {
+  constructor(...args: never);
+}

package/src/foundry/client/canvas/placeables/tokens/turn-marker.d.mts

@@ -0,0 +1,16 @@
+import type { Identity } from "#utils";
+
+declare class TokenTurnMarker extends PIXI.Container {
+  #TokenTurnMarker: true;
+}
+
+declare namespace TokenTurnMarker {
+  interface Any extends AnyTokenTurnMarker {}
+  interface AnyConstructor extends Identity<typeof AnyTokenTurnMarker> {}
+}
+
+export default TokenTurnMarker;
+
+declare abstract class AnyTokenTurnMarker extends TokenTurnMarker {
+  constructor(...args: never);
+}