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

package/src/foundry/client/pixi/placeables/primary-canvas-objects/occludable-object.d.mts

@@ -0,0 +1,175 @@
+import type { Mixin } from "../../../../../types/utils.d.mts";
+import type { OCCLUSION_MODES } from "../../../../common/constants.d.mts";
+
+declare class OccludableObject {
+  /** @privateRemarks All mixin classses should accept anything for its constructor. */
+  constructor(...args: any[]);
+
+  /**
+   * @defaultValue
+   * ```js
+   * return foundry.utils.mergeObject(super.defaultData, {
+   *    roof: false,
+   *    occlusion: {
+   *        mode: CONST.OCCLUSION_MODES.NONE,
+   *        alpha: 0,
+   *        radius: null
+   *    }
+   * })
+   * ```
+   */
+  static get defaultData(): OccludableObjectData;
+
+  /**
+   * Contains :
+   * - the bounds of the texture data
+   * - the cached mapping of non-transparent pixels (if roof)
+   * - the filtered render texture (if roof)
+   */
+  protected _textureData: {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+    pixels: Uint8Array;
+    texture: PIXI.RenderTexture;
+  };
+
+  /**
+   * A flag which tracks whether the primary canvas object is currently in an occluded state.
+   * @defaultValue `false`
+   */
+  occluded: boolean;
+
+  /**
+   * Force or cancel the rendering of the PCO depth. If undefined, the underlying logic decide.
+   * @defaultValue `false`
+   */
+  forceRenderDepth: boolean;
+
+  /**
+   * Is this occludable object... occludable?
+   */
+  get isOccludable(): boolean;
+
+  /**
+   * Should this PCO render its depth?
+   */
+  get shouldRenderDepth(): boolean;
+
+  /**
+   * Debounce assignment of the PCO occluded state to avoid cases like animated token movement which can rapidly
+   * change PCO appearance.
+   * Uses a 50ms debounce threshold.
+   */
+  debounceSetOcclusion: (occluded: boolean) => void;
+
+  /**
+   * Compute and returns the normal and occlusion alpha for this occludable object.
+   */
+  protected _getOcclusionAlpha(): { alphaNormal: number; alphaOccluded: number };
+
+  /**
+   * Refresh the appearance of the occlusion state for tiles which are affected by a Token beneath them.
+   */
+  refreshOcclusion(): void;
+
+  /**
+   * Render the depth of this primary canvas object.
+   */
+  renderDepthData(renderer: PIXI.Renderer): void;
+
+  /**
+   * Process the PCO texture :
+   * Use the texture to create a cached mapping of pixel alpha for this Tile with real base texture size.
+   * Cache the bounding box of non-transparent pixels for the un-rotated shape.
+   */
+  updateTextureData(): { minX: number; minY: number; maxX: number; maxY: number; pixels: Uint8Array | undefined };
+
+  /**
+   * Test whether a specific Token occludes this PCO.
+   * Occlusion is tested against 9 points, the center, the four corners-, and the four cardinal directions
+   * @param token   - The Token to test
+   * @param options - Additional options that affect testing
+   * @returns Is the Token occluded by the PCO?
+   */
+  testOcclusion(
+    token: Token,
+    options?: {
+      /** Test corners of the hit-box in addition to the token center? */
+      corners?: boolean;
+    },
+  ): boolean;
+
+  /**
+   * Test whether the PCO pixel data contains a specific point in canvas space
+   * @param alphaThreshold - Value from which the pixel is taken into account, in the range [0, 1].
+   *                         (default: `0.75`)
+   */
+  containsPixel(x: number, y: number, alphaThreshold?: number): boolean;
+
+  /**
+   * Get alpha value at specific canvas coordinate.
+   * @returns The alpha value (-1 if outside of the bounds) or null if no mesh or texture is present.
+   */
+  getPixelAlpha(x: number, y: number): number | null;
+
+  /**
+   * Get PCO alpha map texture coordinate with canvas coordinate
+   * @param testX - Canvas x coordinate.
+   * @param testY - Canvas y coordinate.
+   * @returns The texture `{x, y}` coordinates, or null if not able to do the conversion.
+   */
+  protected _getTextureCoordinate(testX: number, testY: number): { x: number; y: number } | null;
+
+  /**
+   * Compute the alpha-based bounding box for the tile, including an angle of rotation.
+   * @internal
+   */
+  protected _getAlphaBounds(): PIXI.Rectangle;
+
+  /**
+   * @deprecated since v11, will be removed in v13
+   * @remarks "PrimaryCanvasObject#renderOcclusion is deprecated in favor of PrimaryCanvasObject#renderDepth"
+   */
+  renderOcclusion(renderer: PIXI.Renderer): void;
+}
+
+declare global {
+  interface OccludableObjectData extends PrimaryCanvasObjectData {
+    /**
+     * The PCO is considered as a roof?
+     * @defaultValue false
+     */
+    roof: boolean;
+
+    /** The occlusion object for this PCO */
+    occlusion: {
+      /** @defaultValue `CONST.OCCLUSION_MODES.NONE` */
+      mode: OCCLUSION_MODES;
+      /** @defaultValue `0` */
+      alpha: number;
+      /** @defaultValue `null` */
+      radius: number | null;
+    };
+  }
+
+  /**
+   * A mixin which decorates a DisplayObject with depth and/or occlusion properties.
+   * @param DisplayObject - The parent DisplayObject class being mixed
+   * @returns A DisplayObject subclass mixed with OccludableObject features
+   */
+  // It's vaguely nonsensical that OccludableObjectMixin extends PrimaryCanvasObjectMixin because PrimaryCanvasObjectMixin's first parameter is incompatible.
+  // It mostly works at runtime because the defaults will be used.
+  function OccludableObjectMixin<BaseClass extends OccludableObjectMixin.BaseClass>(
+    DisplayObject: BaseClass,
+  ): Mixin<typeof OccludableObject, Mixin<PrimaryCanvasObjectMixin.MixinClass, BaseClass>>;
+
+  namespace OccludableObjectMixin {
+    interface BaseClass extends SpriteMeshClass {
+      new (texture: PIXI.Texture): SpriteMesh;
+    }
+  }
+}
+
+type SpriteMeshClass = typeof SpriteMesh;

package/src/foundry/client/pixi/placeables/primary-canvas-objects/primary-canvas-object.d.mts

@@ -0,0 +1,159 @@
+import type { DisplayObject } from "pixi.js";
+import type { Mixin } from "../../../../../types/utils.d.mts";
+import type Document from "../../../../common/abstract/document.d.mts";
+
+declare class PrimaryCanvasObject {
+  /** @privateRemarks All mixin classses should accept anything for its constructor. */
+  constructor(...args: any[]);
+
+  /**
+   * The PlaceableObject which is rendered to the PrimaryCanvasGroup (or undefined if no object is associated)
+   */
+  object: PlaceableObject;
+
+  /**
+   * Universal data object for this mesh.
+   */
+  data: PrimaryCanvasObjectData;
+
+  /**
+   * @defaultValue
+   * ```js
+   * {
+   *    x: 0,
+   *    y: 0,
+   *    z: 0,
+   *    width: 0,
+   *    height: 0,
+   *    alpha: 1,
+   *    rotation: 0,
+   *    hidden: false,
+   *    elevation: undefined,
+   *    sort: 0,
+   *    texture: {
+   *        scaleX: 1,
+   *        scaleY: 1,
+   *        src: null,
+   *        tint: null
+   *    }
+   * };
+   * ```
+   */
+  static defaultData: PrimaryCanvasObjectData;
+
+  /**
+   * An elevation in distance units which defines how this Object is sorted relative to its siblings.
+   */
+  get elevation(): number;
+
+  /**
+   * A sort key which resolves ties amongst objects at the same elevation.
+   */
+  get sort(): number;
+
+  /**
+   * A convenient reference to a Document associated with this display object, if any.
+   */
+  get document(): InstanceType<ReturnType<typeof ClientDocumentMixin>> | null;
+
+  /**
+   * Initialize data using an explicitly provided data object or a canvas document.
+   * @param data - Provided data or canvas document.
+   */
+  initialize(data?: PrimaryCanvasObjectData | Document.Any): void;
+
+  /**
+   * Map the document data to an object and process some properties.
+   * @param data - The document data.
+   * @returns The updated data object.
+   */
+  protected _getCanvasDocumentData(data: Document.Any): unknown;
+
+  /**
+   * Initialize sorting of this PCO. Perform checks and call the primary group sorting if necessary.
+   * @param sort - The sort value. Must be a finite number or undefined (in this case, it is ignored)
+   */
+  protected _initializeSorting(sort: number): void;
+
+  destroy(...args: any[]): void;
+
+  /**
+   * Synchronize the appearance of this ObjectMesh with the properties of its represented Document.
+   * @remarks Marked as abstract
+   */
+  refresh(): void;
+
+  /**
+   * Synchronize the position of the ObjectMesh using the position of its represented Document.
+   * @remarks Marked as abstract
+   */
+  setPosition(...args: any[]): void;
+
+  /**
+   * Synchronize the bounds of the ObjectMesh into the primary group quadtree.
+   */
+  updateBounds(): void;
+}
+
+declare global {
+  interface PrimaryCanvasObjectData {
+    /** The x-coordinate of the PCO location */
+    x: number;
+
+    /** The y-coordinate of the PCO location */
+    y: number;
+
+    /** The z-index of the PCO */
+    z: number;
+
+    /** The width of the PCO */
+    width: number;
+
+    /** The height of the PCO */
+    height: number;
+
+    /** The alpha of this PCO */
+    alpha: number;
+
+    /** The rotation of this PCO */
+    rotation: number;
+
+    /** The PCO is hidden? */
+    hidden: boolean;
+
+    /** The elevation of the PCO */
+    elevation: number;
+
+    /** The sort key that resolves ties among the same elevation */
+    sort: number;
+
+    /** The data texture values */
+    texture: PIXI.RenderTexture;
+  }
+
+  /**
+   * A mixin which decorates a DisplayObject with additional properties expected for rendering in the PrimaryCanvasGroup.
+   * @param DisplayObject - The parent DisplayObject class being mixed
+   * @returns A DisplayObject subclass mixed with PrimaryCanvasObject features
+   */
+  function PrimaryCanvasObjectMixin<BaseClass extends PrimaryCanvasObjectMixin.BaseClass>(
+    DisplayObject: BaseClass,
+  ): Mixin<typeof PrimaryCanvasObject, BaseClass>;
+
+  namespace PrimaryCanvasObjectMixin {
+    type BaseClass = PrimaryCanvasObjectMixinBaseClass;
+
+    type MixinClass = typeof PrimaryCanvasObject;
+  }
+}
+
+type DisplayObjectClass = typeof DisplayObject;
+
+interface PrimaryCanvasObjectMixinBaseClass extends DisplayObjectClass {
+  new (
+    // Foundry technically requires the first parameter to be compatible but actually usage ignores this constraint.
+    // placeableObjectOrData: PlaceableObject | Document.Any | IntentionalPartial<PrimaryCanvasObjectData>,
+    arg0: never,
+    ...args: never[]
+  ): DisplayObject;
+}

package/src/foundry/client/pixi/placeables/primary-canvas-objects/tile-mesh.d.mts

@@ -0,0 +1,52 @@
+import type Document from "../../../../common/abstract/document.d.mts";
+
+declare global {
+  /**
+   * A SpriteMesh which visualizes a Tile object in the PrimaryCanvasGroup.
+   */
+  class TileMesh extends OccludableObjectMixin(SpriteMesh) {
+    override refresh(): void;
+
+    override setPosition(x: number, y: number): void;
+
+    override updateBounds(): void;
+
+    protected override _getCanvasDocumentData(data: Document.Any): unknown;
+  }
+
+  /**
+   * A special case subclass of PIXI.TilingSprite which is used in cases where the tile texture needs to repeat.
+   * This should eventually be refactored in favor of a more generalized TilingMesh.
+   * FIXME: Workaround until we have our custom TilingMesh class.
+   */
+  // @ts-expect-error There's some property mismatches on Foundry's end but this class is going away in v12 anyways
+  class TileSprite extends OccludableObjectMixin(PIXI.TilingSprite) {
+    constructor(...args: any[]);
+
+    override setShaderClass(): void;
+
+    override renderDepthData(): void;
+
+    /**
+     * @remarks Always returns false
+     */
+    override get isOccludable(): boolean;
+
+    /**
+     * @remarks Always returns false
+     */
+    override get shouldRenderDepth(): boolean;
+
+    override shader: PIXI.MeshMaterial;
+
+    /**
+     * @remarks Monkey patch copied from TileMesh.refresh()
+     */
+    override refresh(): void;
+
+    /**
+     * @remarks Monkey patch copied from TileMesh.setPosition()
+     */
+    override setPosition(): void;
+  }
+}

package/src/foundry/client/pixi/placeables/primary-canvas-objects/token-mesh.d.mts

@@ -0,0 +1,62 @@
+export {};
+
+type Color = number;
+
+declare global {
+  /**
+   * A SpriteMesh which visualizes a Token object in the PrimaryCanvasGroup.
+   */
+  class TokenMesh extends OccludableObjectMixin(SpriteMesh) {
+    /**
+     * Sorting values to deal with ties.
+     * @defaultValue `750`
+     */
+    static PRIMARY_SORT_ORDER: number;
+
+    static override get defaultData(): TokenMesh.Data;
+
+    override refresh(): void;
+
+    override setPosition(x: number, y: number): void;
+
+    override updateBounds(): void;
+
+    protected override _getTextureCoordinate(testX: number, testY: number): { x: number; y: number } | null;
+
+    /**
+     * Get the attributes for this TokenMesh which configure the display of this TokenMesh and are compatible
+     * with CanvasAnimation.
+     */
+    getDisplayAttributes(): TokenMeshDisplayAttributes;
+  }
+
+  namespace TokenMesh {
+    type Data = {
+      /**
+       * Is this TokenMesh rotation locked?
+       * @defaultValue `false`
+       */
+      lockRotation: boolean;
+    } & ReturnType<typeof OccludableObjectMixin<typeof SpriteMesh>>["defaultData"];
+  }
+
+  interface TokenMeshDisplayAttributes {
+    x: number;
+
+    y: number;
+
+    width: number;
+
+    height: number;
+
+    alpha: number;
+
+    rotation: number;
+
+    scaleX: number;
+
+    scaleY: number;
+
+    tint: Color;
+  }
+}

package/src/foundry/client/pixi/placeables/sound.d.mts

@@ -0,0 +1,133 @@
+import type { ConfiguredObjectClassOrDefault } from "../../config.d.mts";
+
+declare global {
+  namespace AmbientSound {
+    type ConfiguredClass = ConfiguredObjectClassOrDefault<typeof AmbientSound>;
+    type ConfiguredInstance = InstanceType<ConfiguredClass>;
+
+    interface RenderFlags extends PlaceableObject.RenderFlags {
+      refreshField: boolean;
+
+      refreshPosition: boolean;
+    }
+
+    interface SyncOptions {
+      /**
+       * A duration in milliseconds to fade volume transition
+       * @defaultValue `250`
+       */
+      fade: number;
+    }
+
+    interface UpdateSourceOptions {
+      /**
+       * Defer refreshing the SoundsLayer to manually call that refresh later.
+       * @defaultValue `false`
+       */
+      defer?: boolean | undefined;
+
+      /**
+       * Indicate that this SoundSource has been deleted.
+       * @defaultValue `false`
+       */
+      deleted?: boolean | undefined;
+    }
+  }
+
+  /**
+   * An AmbientSound is an implementation of PlaceableObject which represents a dynamic audio source within the Scene.
+   * @see {@link AmbientSoundDocument}
+   * @see {@link SoundsLayer}
+   */
+  class AmbientSound extends PlaceableObject<AmbientSoundDocument.ConfiguredInstance> {
+    constructor(document: AmbientSoundDocument.ConfiguredInstance);
+
+    /**
+     * The Sound which manages playback for this AmbientSound effect
+     */
+    sound: Sound | null;
+
+    /**
+     * A SoundSource object which manages the area of effect for this ambient sound
+     */
+    source: foundry.canvas.sources.PointSoundSource;
+
+    static override embeddedName: "AmbientSound";
+
+    static override RENDER_FLAGS: {
+      /** @defaultValue `{ propagate: ["refresh"] }` */
+      redraw: RenderFlag<Partial<AmbientSound.RenderFlags>>;
+
+      /** @defaultValue `{ propagate: ["refreshField"], alias: true }` */
+      refresh: RenderFlag<Partial<AmbientSound.RenderFlags>>;
+
+      /** @defaultValue `{ propagate: ["refreshPosition", "refreshState"] }` */
+      refreshField: RenderFlag<Partial<AmbientSound.RenderFlags>>;
+
+      /** @defaultValue `{}` */
+      refreshPosition: RenderFlag<Partial<AmbientSound.RenderFlags>>;
+
+      /** @defaultValue `{}` */
+      refreshState: RenderFlag<Partial<AmbientSound.RenderFlags>>;
+    };
+
+    /**
+     * Is this ambient sound is currently audible based on its hidden state and the darkness level of the Scene?
+     */
+    get isAudible(): boolean;
+
+    override get bounds(): Rectangle;
+
+    /**
+     * The named identified for the source object associated with this ambient sound
+     */
+    get sourceId(): string;
+
+    /**
+     * A convenience accessor for the sound radius in pixels
+     */
+    get radius(): number;
+
+    /**
+     * Toggle playback of the sound depending on whether or not it is audible
+     * @param isAudible - Is the sound audible?
+     * @param volume    - The target playback volume
+     * @param options   - Additional options which affect sound synchronization
+     */
+    sync(isAudible: boolean, volume: number, options?: Partial<AmbientSound.SyncOptions>): void;
+
+    override clear(): this;
+
+    protected override _draw(): Promise<void>;
+
+    protected override _destroy(options?: PIXI.IDestroyOptions | boolean): void;
+
+    protected _applyRenderFlags(flags: AmbientSound.RenderFlags): void;
+
+    /**
+     * Refresh the display of the ControlIcon for this AmbientSound source
+     */
+    refreshControl(): void;
+
+    /**
+     * Compute the field-of-vision for an object, determining its effective line-of-sight and field-of-vision polygons
+     * @param options - (default: `{}`)
+     */
+    updateSource(options?: AmbientSound.UpdateSourceOptions): void;
+
+    /**
+     * @privateRemarks _onCreate, _onUpdate, and _onDelete are all overridden but with no signature changes.
+     * For type simplicity they are left off. These methods historically have been the source of a large amount of computation from tsc.
+     */
+
+    protected override _canHUD(user: User.ConfiguredInstance, event?: any): boolean;
+
+    protected override _canConfigure(user: User.ConfiguredInstance, event?: any): boolean;
+
+    protected override _onClickRight(event: PIXI.FederatedEvent): void;
+
+    protected override _onDragLeftMove(event: PIXI.FederatedEvent): void;
+
+    protected override _onDragEnd(): void;
+  }
+}