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

package/src/foundry/client/pixi/layers/placeables/walls.d.mts

@@ -0,0 +1,210 @@
+import type { ConstructorOf, InexactPartial } from "../../../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * The Walls canvas layer which provides a container for Wall objects within the rendered Scene.
+   */
+  class WallsLayer extends PlaceablesLayer<"Wall"> {
+    /**
+     * Synthetic Wall instances which represent the outer boundaries of the game canvas.
+     */
+    outerBounds: Wall[];
+
+    /**
+     * Synthetic Wall instances which represent the inner boundaries of the scene rectangle.
+     */
+    innerBounds: Wall[];
+
+    /**
+     * A graphics layer used to display chained Wall selection
+     * @defaultValue `null`
+     */
+    chain: PIXI.Graphics | null;
+
+    /**
+     * Track whether we are currently within a chained placement workflow
+     * @defaultValue `false`
+     */
+    protected _chain: boolean;
+
+    /**
+     * Track whether the layer is currently toggled to snap at exact grid precision
+     * @defaultValue `false`
+     */
+    protected _forceSnap: boolean;
+
+    /**
+     * Track the most recently created or updated wall data for use with the clone tool
+     * @defaultValue `null`
+     * @remarks This is intentional `public` because it is accessed from Wall
+     */
+    _cloneType: ReturnType<foundry.documents.BaseWall["toJSON"]> | null;
+
+    /**
+     * Reference the last interacted wall endpoint for the purposes of chaining
+     * @defaultValue
+     * ```
+     * {
+     *   point: null,
+     * }
+     * ```
+     */
+    protected last: {
+      point: PointArray | null;
+    };
+
+    /**
+     * @privateRemarks This is not overridden in foundry but reflects the real behavior.
+     */
+    static get instance(): Canvas["walls"];
+
+    /**
+     * @defaultValue
+     * ```js
+     * mergeObject(super.layerOptions, {
+     *  name: "walls"
+     *  controllableObjects: true,
+     *  sortActiveTop: true, // TODO this needs to be removed
+     *  zIndex: 40
+     * })
+     * ```
+     * @remarks The TODO is foundry internal
+     */
+    static override get layerOptions(): WallsLayer.LayerOptions;
+
+    /**
+     * @privateRemarks This is not overridden in foundry but reflects the real behavior.
+     */
+    override options: WallsLayer.LayerOptions;
+
+    static override documentName: "Wall";
+
+    override get hookName(): string;
+
+    /**
+     * An Array of Wall instances in the current Scene which act as Doors.
+     */
+    get doors(): Wall.ConfiguredInstance[];
+
+    /**
+     * Gate the precision of wall snapping to become less precise for small scale maps.
+     * @remarks Returns `1 | 4 | 8 | 16`
+     */
+    get gridPrecision(): number;
+
+    override _draw(options?: Record<string, unknown>): Promise<void>;
+
+    override _deactivate(): void;
+
+    /**
+     * Perform initialization steps for the WallsLayer whenever the composition of walls in the Scene is changed.
+     * Cache unique wall endpoints and identify interior walls using overhead roof tiles.
+     */
+    initialize(): void;
+
+    /**
+     * Initialization to identify all intersections between walls.
+     * These intersections are cached and used later when computing point source polygons.
+     */
+    identifyWallIntersections(): void;
+
+    /**
+     * Identify walls which are treated as "interior" because they are contained fully within a roof tile.
+     */
+    identifyInteriorWalls(): void;
+
+    /**
+     * Given a point and the coordinates of a wall, determine which endpoint is closer to the point
+     * @param point - The origin point of the new Wall placement
+     * @param wall  - The existing Wall object being chained to
+     * @returns The [x,y] coordinates of the starting endpoint
+     */
+    static getClosestEndpoint(point: Point, wall: Wall.ConfiguredInstance): PointArray;
+
+    override releaseAll(options?: PlaceableObject.ReleaseOptions): number;
+
+    override pasteObjects(
+      position: Point,
+      options?: Record<string, unknown>,
+    ): Promise<WallDocument.ConfiguredInstance[]>;
+
+    /**
+     * Pan the canvas view when the cursor position gets close to the edge of the frame
+     * @param event - The originating mouse movement event
+     * @param x     - The x-coordinate
+     * @param y     - The y-coordinate
+     */
+    protected _panCanvasEdge(event: MouseEvent, x: number, y: number): void | ReturnType<Canvas["animatePan"]>;
+
+    /**
+     * Get the wall endpoint coordinates for a given point.
+     * @param  point - The candidate wall endpoint.
+     * @returns The wall endpoint coordinates.
+     */
+    protected _getWallEndpointCoordinates(
+      point: Point,
+      options?: InexactPartial<{
+        /**
+         * Snap to the grid?
+         * @defaultValue `true`
+         */
+        snap: boolean;
+      }>,
+    ): PointArray;
+
+    /**
+     * The Scene Controls tools provide several different types of prototypical Walls to choose from
+     * This method helps to translate each tool into a default wall data configuration for that type
+     * @param tool - The active canvas tool
+     */
+    protected _getWallDataFromActiveTool(tool: string):
+      | {
+          light: foundry.CONST.WALL_SENSE_TYPES;
+          sight: foundry.CONST.WALL_SENSE_TYPES;
+          sound: foundry.CONST.WALL_SENSE_TYPES;
+          move: foundry.CONST.WALL_SENSE_TYPES;
+          door?: foundry.CONST.WALL_DOOR_TYPES;
+        }
+      | this["_cloneType"];
+
+    protected override _onDragLeftStart(event: PIXI.FederatedEvent): Promise<void>;
+
+    protected override _onDragLeftMove(event: PIXI.FederatedEvent): void;
+
+    protected override _onDragLeftDrop(event: PIXI.FederatedEvent): Promise<void>;
+
+    protected override _onDragLeftCancel(event: PointerEvent): void;
+
+    protected override _onClickRight(event: PIXI.FederatedEvent): void;
+
+    /**
+     * @deprecated since v10, will be removed in v12
+     * @remarks "WallsLayer#boundaries is deprecated in favor of WallsLayer#outerBounds and WallsLayer#innerBounds"
+     */
+    get boundaries(): Set<Wall>;
+
+    /**
+     * @deprecated since v11, will be removed in v13
+     * @remarks "WallsLayer#checkCollision is obsolete. Prefer calls to testCollision from CONFIG.Canvas.polygonBackends[type]"
+     */
+    checkCollision(ray: Ray, options: Parameters<(typeof PointSourcePolygon)["testCollision"]>[2]): boolean;
+
+    /**
+     * @deprecated since v11, will be removed in v13
+     * @remarks "The WallsLayer#highlightControlledSegments function is deprecated in favor of calling wall.renderFlags.set(\"refreshHighlight\") on individual Wall objects"
+     */
+    highlightControlledSegments(): void;
+  }
+
+  namespace WallsLayer {
+    interface LayerOptions extends PlaceablesLayer.LayerOptions<"Wall"> {
+      name: "walls";
+      controllableObjects: true;
+      objectClass: typeof Wall;
+      quadtree: true;
+      sheetClass: ConstructorOf<FormApplication>;
+      sortActiveTop: boolean;
+      zIndex: number;
+    }
+  }
+}

package/src/foundry/client/pixi/perception/clockwise-sweep.d.mts

@@ -0,0 +1,169 @@
+export {};
+
+declare global {
+  type VertexMap = Map<number, foundry.canvas.edges.PolygonVertex>;
+
+  type EdgeSet = Set<PolygonEdge>;
+
+  interface PolygonRay extends Ray {
+    result: foundry.canvas.edges.CollisionResult;
+  }
+
+  /**
+   * A PointSourcePolygon implementation that uses CCW (counter-clockwise) geometry orientation.
+   * Sweep around the origin, accumulating collision points based on the set of active walls.
+   * This algorithm was created with valuable contributions from https://github.com/caewok
+   */
+  class ClockwiseSweepPolygon extends PointSourcePolygon {
+    /**
+     * A mapping of vertices which define potential collision points
+     */
+    vertices: VertexMap;
+
+    /**
+     * The set of edges which define potential boundaries of the polygon
+     */
+    edges: EdgeSet;
+
+    /**
+     * A collection of rays which are fired at vertices
+     */
+    // @ts-expect-error Getter/setter routine is deprecated functionality as of v11, removed in v13
+    rays: PolygonRay[];
+
+    override initialize(origin: Point, config: PointSourcePolygonConfig): void;
+
+    clone(): this;
+
+    protected override _compute(): void;
+
+    /**
+     * Translate walls and other obstacles into edges which limit visibility
+     * @internal
+     */
+    protected _identifyEdges(): void;
+
+    /**
+     * Consolidate all vertices from identified edges and register them as part of the vertex mapping.
+     * @internal
+     */
+    protected _identifyVertices(): void;
+
+    /**
+     * Add additional vertices for intersections between edges.
+     * @param wallEdgeMap - A mapping of wall IDs to PolygonEdge instances
+     * @internal
+     */
+    protected _identifyIntersections(wallEdgeMap: Map<string, PolygonEdge>): void;
+
+    /**
+     * Execute the sweep over wall vertices
+     * @internal
+     */
+    protected _executeSweep(): void;
+
+    /**
+     * Update active edges at a given vertex
+     * Must delete first, in case the edge is in both sets.
+     * @param vertex      - The current vertex
+     * @param activeEdges - A set of currently active edges
+     * @internal
+     */
+    protected _updateActiveEdges(vertex: foundry.canvas.edges.PolygonVertex, activeEdges: EdgeSet): void;
+
+    /**
+     * Determine the initial set of active edges as those which intersect with the initial ray
+     * @returns A set of initially active edges
+     * @internal
+     */
+    protected _initializeActiveEdges(): EdgeSet;
+
+    /**
+     * Sort vertices clockwise from the initial ray (due west).
+     * @returns The array of sorted vertices
+     * @internal
+     */
+    protected _sortVertices(): foundry.canvas.edges.PolygonVertex[];
+
+    /**
+     * Test whether a target vertex is behind some closer active edge.
+     * If the vertex is to the left of the edge, is must be behind the edge relative to origin.
+     * If the vertex is collinear with the edge, it should be considered "behind" and ignored.
+     * We know edge.A is ccw to edge.B because of the logic in _identifyVertices.
+     * @param vertex      - The target vertex
+     * @param activeEdges - The set of active edges
+     * @returns Is the target vertex behind some closer edge?
+     * @internal
+     */
+    protected _isVertexBehindActiveEdges(
+      vertex: foundry.canvas.edges.PolygonVertex,
+      activeEdges: EdgeSet,
+    ): { isBehind: boolean; wasLimited: boolean };
+
+    /**
+     * Determine the result for the sweep at a given vertex
+     * @param vertex        - The target vertex
+     * @param activeEdges   - The set of active edges
+     * @param hasCollinear  - Are there collinear vertices behind the target vertex?
+     * @internal
+     */
+    protected _determineSweepResult(
+      vertex: foundry.canvas.edges.PolygonVertex,
+      activeEdges: EdgeSet,
+      hasCollinear: boolean,
+    ): void;
+
+    /**
+     * Switch to a new active edge.
+     * Moving from the origin, a collision that first blocks a side must be stored as a polygon point.
+     * Subsequent collisions blocking that side are ignored. Once both sides are blocked, we are done.
+     *
+     * Collisions that limit a side will block if that side was previously limited.
+     *
+     * If neither side is blocked and the ray internally collides with a non-limited edge, n skip without adding polygon
+     * endpoints. Sight is unaffected before this edge, and the internal collision can be ignored.
+     * @internal
+     *
+     * @param result      - The pending collision result
+     * @param activeEdges - The set of currently active edges
+     */
+    _switchEdge(result: foundry.canvas.edges.CollisionResult, activeEdges: EdgeSet): void;
+
+    /**
+     * Identify the collision points between an emitted Ray and a set of active edges.
+     * @param ray           - The candidate ray to test
+     * @param internalEdges - The set of edges to check for collisions against the ray
+     * @returns A sorted array of collision points
+     * @internal
+     */
+    protected _getInternalEdgeCollisions(ray: PolygonRay, internalEdges: EdgeSet): foundry.canvas.edges.PolygonVertex[];
+
+    /**
+     * @deprecated since v10, will be removed in v12
+     * @remarks ClockwiseSweepPolygon.getRayCollisions has been renamed to ClockwiseSweepPolygon.testCollision
+     */
+    static getRayCollisions(
+      ray: PolygonRay,
+      config: PointSourcePolygonConfig,
+    ): boolean | foundry.canvas.edges.PolygonVertex | foundry.canvas.edges.PolygonVertex[] | null;
+
+    /**
+     * Determine the set of collisions which occurs for a Ray.
+     * @param ray  - The Ray to test
+     * @param mode - The collision mode being tested
+     * @returns The collision test result
+     */
+    protected override _testCollision<Mode extends PointSourcePolygon.CollisionModes>(
+      ray: Ray,
+      mode: Mode,
+    ): PointSourcePolygon.TestCollision<Mode>;
+
+    override visualize(): PIXI.Graphics | undefined;
+
+    /**
+     * Visualize the polygon, displaying its computed area, rays, and collision points
+     * @internal
+     */
+    protected _visualizeCollision(ray: Ray, collisions: foundry.canvas.edges.PolygonVertex[]): void;
+  }
+}

package/src/foundry/client/pixi/perception/color-manager.d.mts

@@ -0,0 +1,86 @@
+export {};
+
+declare global {
+  /**
+   * A singleton class dedicated to manage the color spaces associated with the scene and the canvas.
+   */
+  class CanvasColorManager {
+    /**
+     * Colors exposed by the manager.
+     */
+    colors: {
+      darkness?: Color;
+      halfdark?: Color;
+      /** @defaultValue `0x909090` */
+      background?: Color;
+      dim?: Color;
+      bright?: Color;
+      ambientBrightest?: Color;
+      ambientDaylight?: Color;
+      ambientDarkness?: Color;
+      sceneBackground?: Color;
+      /** @defaultValue `0x000000` */
+      fogExplored?: Color;
+      /** @defaultValue `0x000000` */
+      fogUnexplored?: Color;
+    };
+
+    /**
+     * Weights used by the manager to compute colors.
+     */
+    weights: {
+      dark?: number;
+      halfdark?: number;
+      dim?: number;
+      bright?: number;
+    };
+
+    /**
+     * Fallback colors.
+     */
+    static #fallbackColors: {
+      darknessColor: 0x242448;
+      daylightColor: 0xeeeeee;
+      brightestColor: 0xffffff;
+      backgroundColor: 0x909090;
+      fogUnexplored: 0x000000;
+      fogExplored: 0x000000;
+    };
+
+    /**
+     * Returns the darkness penalty for the actual scene configuration.
+     */
+    get darknessPenalty(): number;
+
+    /**
+     * Get the darkness level of this scene.
+     */
+    get darknessLevel(): number;
+
+    /**
+     * Initialize color space pertaining to a specific scene.
+     */
+    initialize(colors?: {
+      /** The background canvas color */
+      backgroundColor?: Color | number | string;
+
+      /** The brightest ambient color */
+      brightestColor?: Color | number | string;
+
+      /** The color of darkness */
+      darknessColor?: Color | number | string;
+
+      /** A preview darkness level */
+      darknessLevel?: number;
+
+      /** The ambient daylight color */
+      daylightColor?: Color | number | string;
+
+      /** The color applied to explored areas */
+      fogExploredColor?: number;
+
+      /** The color applied to unexplored areas */
+      fogUnexploredColor?: number;
+    }): void;
+  }
+}

package/src/foundry/client/pixi/perception/detection-mode.d.mts

@@ -0,0 +1,196 @@
+import type { InexactPartial, ValueOf } from "../../../../types/utils.d.mts";
+import type { fields } from "../../../common/data/module.d.mts";
+import type { TokenDetectionMode } from "../../../common/documents/_types.d.mts";
+
+declare global {
+  namespace DetectionMode {
+    interface Schema extends DataSchema {
+      id: fields.StringField<{ blank: false }>;
+      label: fields.StringField<{ blank: false }>;
+      tokenConfig: fields.BooleanField<{ initial: true }>;
+      walls: fields.BooleanField<{ initial: true }>;
+      angle: fields.BooleanField<{ initial: true }>;
+      type: fields.NumberField<{
+        initial: typeof DetectionMode.DETECTION_TYPES.SIGHT;
+        choices: ValueOf<typeof DetectionMode.DETECTION_TYPES>[];
+      }>;
+    }
+  }
+
+  /**
+   * A Detection Mode which can be associated with any kind of sense/vision/perception.
+   * A token could have multiple detection modes.
+   */
+  class DetectionMode extends foundry.abstract.DataModel<DetectionMode.Schema> {
+    static override defineSchema(): DetectionMode.Schema;
+
+    /**
+     * Get the detection filter pertaining to this mode.
+     */
+    static getDetectionFilter(): PIXI.Filter | undefined;
+
+    /**
+     * An optional filter to apply on the target when it is detected with this mode.
+     */
+    static _detectionFilter: PIXI.Filter | undefined;
+
+    /**
+     * The type of the detection mode. If its sight based, sound based, etc.
+     * It is related to wall's WALL_RESTRICTION_TYPES
+     * @see CONST.WALL_RESTRICTION_TYPES
+     */
+    static DETECTION_TYPES: {
+      /** Sight, and anything depending on light perception */
+      SIGHT: 0;
+      /** What you can hear. Includes echolocation for bats per example */
+      SOUND: 1;
+      /** This is mostly a sense for touch and vibration, like tremorsense, movement detection, etc. */
+      MOVE: 2;
+      /** Can't fit in other types (smell, life sense, trans-dimensional sense, sense of humor...) */
+      OTHER: 3;
+    };
+
+    /**
+     * The identifier of the basic sight detection mode.
+     */
+    static BASIC_MODE_ID: "basicSight";
+
+    /**
+     * Test visibility of a target object or array of points for a specific vision source.
+     * @param visionSource  - The vision source being tested
+     * @param mode          - The detection mode configuration
+     * @param config        - The visibility test configuration
+     * @returns   Is the test target visible?
+     */
+    testVisibility(
+      visionSource: foundry.canvas.sources.PointVisionSource.Any,
+      mode: TokenDetectionMode,
+      { object, tests }: InexactPartial<CanvasVisibilityTestConfig>,
+    ): boolean;
+
+    /**
+     * Can this VisionSource theoretically detect a certain object based on its properties?
+     * This check should not consider the relative positions of either object, only their state.
+     * @param visionSource - The vision source being tested
+     * @param target       - The target object being tested
+     * @returns Can the target object theoretically be detected by this vision source?
+     */
+    protected _canDetect(visionSource: foundry.canvas.sources.PointVisionSource.Any, target: PlaceableObject): boolean;
+
+    /**
+     * Evaluate a single test point to confirm whether it is visible.
+     * Standard detection rules require that the test point be both within LOS and within range.
+     * @param visionSource - The vision source being tested
+     * @param mode         - The detection mode configuration
+     * @param target       - The target object being tested
+     * @param test         - The test case being evaluated
+     */
+    protected _testPoint(
+      visionSource: foundry.canvas.sources.PointVisionSource.Any,
+      mode: TokenDetectionMode,
+      target: PlaceableObject,
+      test: CanvasVisibilityTest,
+    ): boolean;
+
+    /**
+     * Test whether the line-of-sight requirement for detection is satisfied.
+     * Always true if the detection mode bypasses walls, otherwise the test point must be contained by the LOS polygon.
+     * The result of is cached for the vision source so that later checks for other detection modes do not repeat it.
+     * @param visionSource    - The vision source being tested
+     * @param mode            - The detection mode configuration
+     * @param target          - The target object being tested
+     * @param test            - The test case being evaluated
+     * @returns Is the LOS requirement satisfied for this test?
+     */
+    protected _testLOS(
+      visionSource: foundry.canvas.sources.PointVisionSource.Any,
+      mode: TokenDetectionMode,
+      target: PlaceableObject,
+      test: CanvasVisibilityTest,
+    ): boolean;
+
+    /**
+     * Test whether the target is within the vision angle.
+     * @param visionSource    - The vision source being tested
+     * @param mode            - The detection mode configuration
+     * @param target          - The target object being tested
+     * @param test            - The test case being evaluated
+     * @returns Is the point within the vision angle?
+     */
+    protected _testAngle(
+      visionSource: foundry.canvas.sources.PointVisionSource.Any,
+      mode: TokenDetectionMode,
+      target: PlaceableObject,
+      test: CanvasVisibilityTest,
+    ): boolean;
+
+    /**
+     * Verify that a target is in range of a source.
+     * @param visionSource    - The vision source being tested
+     * @param mode            - The detection mode configuration
+     * @param target          - The target object being tested
+     * @param test            - The test case being evaluated
+     * @returns Is the target within range?
+     */
+    protected _testRange(
+      visionSource: foundry.canvas.sources.PointVisionSource.Any,
+      mode: TokenDetectionMode,
+      target: PlaceableObject,
+      test: CanvasVisibilityTest,
+    ): boolean;
+  }
+
+  /**
+   * A special detection mode which models standard human vision.
+   * This mode is the default case which is tested first when evaluating visibility of objects.
+   * It is also a special case, in that it is the only detection mode which considers the area of distant light sources.
+   */
+  class DetectionModeBasicSight extends DetectionMode {
+    override _testPoint(
+      visionSource: foundry.canvas.sources.PointVisionSource.Any,
+      mode: TokenDetectionMode,
+      target: PlaceableObject,
+      test: CanvasVisibilityTest,
+    ): boolean;
+  }
+
+  /**
+   * Detection mode that see invisible creatures.
+   * This detection mode allows the source to:
+   * - See/Detect the invisible target as if visible.
+   * - The "See" version needs sight and is affected by blindness
+   */
+  class DetectionModeInvisibility extends DetectionMode {
+    static override getDetectionFilter(): PIXI.Filter | undefined;
+
+    protected override _canDetect(
+      visionSource: foundry.canvas.sources.PointVisionSource.Any,
+      target: PlaceableObject,
+    ): boolean;
+  }
+
+  /**
+   * Detection mode that see creatures in contact with the ground.
+   */
+  class DetectionModeTremor extends DetectionMode {
+    static override getDetectionFilter(): PIXI.Filter | undefined;
+
+    protected override _canDetect(
+      visionSource: foundry.canvas.sources.PointVisionSource.Any,
+      target: PlaceableObject,
+    ): boolean;
+  }
+
+  /**
+   * Detection mode that see ALL creatures (no blockers).
+   * If not constrained by walls, see everything within the range.
+   */
+  class DetectionModeAll extends DetectionMode {
+    static override getDetectionFilter(): PIXI.Filter | undefined;
+
+    protected override _canDetect(
+      visionSource: foundry.canvas.sources.PointVisionSource.Any,
+      target: PlaceableObject,
+    ): boolean;
+  }
+}