screeps-clockwork 0.12.0 → 0.13.1

package/dist/src/index.d.ts

@@ -1,6 +1,8 @@
 import 'fastestsmallesttextencoderdecoder-encodeinto/EncoderDecoderTogether.min.js';
 import { ClockworkCostMatrix, DirectionOrder } from './wasm/screeps_clockwork';
+import { type PortalPair } from './utils/packedArrays';
 export { ClockworkCostMatrix, DirectionOrder };
+export type { PortalPair };
 export * from './wrappers/astarDistanceMap';
 export * from './wrappers/bfsDistanceMap';
 export * from './wrappers/dijkstraDistanceMap';
@@ -13,12 +15,47 @@ export * from './wrappers/multiroomMonoFlowField';
 export * from './wrappers/path';
 export type { ClockworkDistanceMap } from './wrappers/distanceMap';
 export type { ClockworkMultiroomDistanceMap } from './wrappers/multiroomDistanceMap';
+export interface ClockworkInitializeOptions {
+    verbose?: boolean;
+    portals?: readonly PortalPair[];
+    portalDistanceCacheRoomLimit?: number;
+}
+export interface PortalIndexDebugInfo {
+    cachedDistanceMaps: number;
+    maxCachedDistanceMaps: number;
+    cachedPortals: number;
+    portalRoomSummaries: number;
+    totalSizeBytes: number;
+    totalSize: string;
+}
 /**
- * The `initialize` function should be called in your main loop before
- * using any other screeps-clockwork functions. Depending on available
- * CPU, it may not load the WASM module completely in the first tick,
- * but it will pick back up where it left off if the script times out.
+ * The `initialize` function initializes the WASM module and applies global
+ * setup options. Call it in your main loop before using any other
+ * screeps-clockwork functions. Depending on available CPU, it may not load the
+ * WASM module completely in the first tick, but it will pick back up where it
+ * left off if the script times out.
  *
- * @param verbose - If true, will log the state of the WASM module as it loads.
+ * It is safe to call this function repeatedly, but setup options such as
+ * portals and portal cache sizing are applied only once, after WASM
+ * initialization has completed. Use `setPortals` when you intentionally need
+ * to reconfigure portals later.
+ *
+ * @param options - Pass `true` or `{ verbose: true }` to log WASM loading;
+ * provide portals and cache sizing to apply them once after WASM initialization.
+ */
+export declare function initialize(options?: boolean | ClockworkInitializeOptions): void;
+/**
+ * Configure the portal pairs used by portal-aware pathfinding functions.
+ * Each pair is installed bidirectionally.
+ */
+export declare function setPortals(portals: readonly PortalPair[]): void;
+/**
+ * Remove all configured portal pairs while preserving the initialize-time cache limit.
+ */
+export declare function clearPortals(): void;
+/**
+ * Return debug counters for the configured portal index and its nearest-portal cache.
+ * `totalSize` is an approximate in-memory size formatted for logs; `totalSizeBytes`
+ * preserves the raw byte estimate.
  */
-export declare function initialize(verbose?: boolean): void;
+export declare function debugPortalIndex(): PortalIndexDebugInfo;

package/dist/src/utils/packedArrays.d.ts

@@ -1,6 +1,9 @@
-export interface PackedDestination {
+interface PackedDestination {
     pos: RoomPosition;
     range: number;
 }
+export type PortalPair = readonly [RoomPosition, RoomPosition];
 export declare function packPositions(positions: RoomPosition[]): Uint32Array;
 export declare function packDestinations(destinations: PackedDestination[] | undefined): Uint32Array | undefined;
+export declare function packPortalPairs(portals: readonly PortalPair[]): Uint32Array;
+export {};

package/dist/src/wasm/screeps_clockwork.d.ts

@@ -1,3 +1,8 @@
+export function clear_portals(): void;
+/**
+ * @returns {any}
+ */
+export function debug_portal_index(): any;
 /**
  * Exports the global range calculation between two positions.
  * @param {number} packed_pos_1
@@ -24,6 +29,17 @@ export function get_terrain_cost_matrix(room_name: number, plain_cost?: number |
  * @returns {SearchResult}
  */
 export function js_astar_multiroom_distance_map(start_packed: Uint32Array, get_cost_matrix: Function, max_rooms: number, max_ops: number, max_path_cost: number, any_of_destinations?: Uint32Array | null, all_of_destinations?: Uint32Array | null): SearchResult;
+/**
+ * @param {Uint32Array} start_packed
+ * @param {Function} get_cost_matrix
+ * @param {number} max_rooms
+ * @param {number} max_ops
+ * @param {number} max_path_cost
+ * @param {Uint32Array | null} [any_of_destinations]
+ * @param {Uint32Array | null} [all_of_destinations]
+ * @returns {SearchResult}
+ */
+export function js_astar_portal_multiroom_distance_map(start_packed: Uint32Array, get_cost_matrix: Function, max_rooms: number, max_ops: number, max_path_cost: number, any_of_destinations?: Uint32Array | null, all_of_destinations?: Uint32Array | null): SearchResult;
 /**
  * WASM wrapper for the BFS multiroom distance map function.
  *
@@ -49,6 +65,17 @@ export function js_astar_multiroom_distance_map(start_packed: Uint32Array, get_c
  * @returns {SearchResult}
  */
 export function js_bfs_multiroom_distance_map(start_packed: Uint32Array, get_cost_matrix: Function, max_ops: number, max_rooms: number, max_path_cost: number, any_of_destinations?: Uint32Array | null, all_of_destinations?: Uint32Array | null): SearchResult;
+/**
+ * @param {Uint32Array} start_packed
+ * @param {Function} get_cost_matrix
+ * @param {number} max_ops
+ * @param {number} max_rooms
+ * @param {number} max_path_cost
+ * @param {Uint32Array | null} [any_of_destinations]
+ * @param {Uint32Array | null} [all_of_destinations]
+ * @returns {SearchResult}
+ */
+export function js_bfs_portal_multiroom_distance_map(start_packed: Uint32Array, get_cost_matrix: Function, max_ops: number, max_rooms: number, max_path_cost: number, any_of_destinations?: Uint32Array | null, all_of_destinations?: Uint32Array | null): SearchResult;
 /**
  * @param {Uint32Array} start_packed
  * @param {Function} get_cost_matrix
@@ -60,6 +87,17 @@ export function js_bfs_multiroom_distance_map(start_packed: Uint32Array, get_cos
  * @returns {SearchResult}
  */
 export function js_dijkstra_multiroom_distance_map(start_packed: Uint32Array, get_cost_matrix: Function, max_ops: number, max_rooms: number, max_path_cost: number, any_of_destinations?: Uint32Array | null, all_of_destinations?: Uint32Array | null): SearchResult;
+/**
+ * @param {Uint32Array} start_packed
+ * @param {Function} get_cost_matrix
+ * @param {number} max_ops
+ * @param {number} max_rooms
+ * @param {number} max_path_cost
+ * @param {Uint32Array | null} [any_of_destinations]
+ * @param {Uint32Array | null} [all_of_destinations]
+ * @returns {SearchResult}
+ */
+export function js_dijkstra_portal_multiroom_distance_map(start_packed: Uint32Array, get_cost_matrix: Function, max_ops: number, max_rooms: number, max_path_cost: number, any_of_destinations?: Uint32Array | null, all_of_destinations?: Uint32Array | null): SearchResult;
 /**
  * @param {number} start
  * @param {MultiroomDistanceMap} distance_map
@@ -67,18 +105,37 @@ export function js_dijkstra_multiroom_distance_map(start_packed: Uint32Array, ge
  * @returns {Path}
  */
 export function js_path_to_multiroom_distance_map_origin(start: number, distance_map: MultiroomDistanceMap, direction_order: DirectionOrder): Path;
+/**
+ * @param {number} start
+ * @param {MultiroomDistanceMap} distance_map
+ * @param {DirectionOrder} direction_order
+ * @returns {Path}
+ */
+export function js_path_to_multiroom_distance_map_origin_with_portals(start: number, distance_map: MultiroomDistanceMap, direction_order: DirectionOrder): Path;
 /**
  * @param {number} start
  * @param {MultiroomFlowField} flow_field
  * @returns {Path}
  */
 export function js_path_to_multiroom_flow_field_origin(start: number, flow_field: MultiroomFlowField): Path;
+/**
+ * @param {number} start
+ * @param {MultiroomFlowField} flow_field
+ * @returns {Path}
+ */
+export function js_path_to_multiroom_flow_field_origin_with_portals(start: number, flow_field: MultiroomFlowField): Path;
 /**
  * @param {number} start
  * @param {MultiroomMonoFlowField} flow_field
  * @returns {Path}
  */
 export function js_path_to_multiroom_mono_flow_field_origin(start: number, flow_field: MultiroomMonoFlowField): Path;
+/**
+ * @param {number} start
+ * @param {MultiroomMonoFlowField} flow_field
+ * @returns {Path}
+ */
+export function js_path_to_multiroom_mono_flow_field_origin_with_portals(start: number, flow_field: MultiroomMonoFlowField): Path;
 /**
  * Creates a flow field for the given distance map.
  * @param {MultiroomDistanceMap} distance_map
@@ -93,6 +150,26 @@ export function multiroomFlowField(distance_map: MultiroomDistanceMap, direction
  * @returns {MultiroomMonoFlowField}
  */
 export function multiroomMonoFlowField(distance_map: MultiroomDistanceMap, direction_order: DirectionOrder): MultiroomMonoFlowField;
+/**
+ * @param {MultiroomDistanceMap} distance_map
+ * @param {DirectionOrder} direction_order
+ * @returns {MultiroomFlowField}
+ */
+export function multiroomPortalFlowField(distance_map: MultiroomDistanceMap, direction_order: DirectionOrder): MultiroomFlowField;
+/**
+ * @param {MultiroomDistanceMap} distance_map
+ * @param {DirectionOrder} direction_order
+ * @returns {MultiroomMonoFlowField}
+ */
+export function multiroomPortalMonoFlowField(distance_map: MultiroomDistanceMap, direction_order: DirectionOrder): MultiroomMonoFlowField;
+/**
+ * @param {number} room_limit
+ */
+export function set_portal_distance_cache_room_limit(room_limit: number): void;
+/**
+ * @param {Uint32Array} packed_pairs
+ */
+export function set_portals(packed_pairs: Uint32Array): void;
 /**
  * @returns {string}
  */

package/dist/src/wrappers/astarDistanceMap.d.ts

@@ -33,3 +33,39 @@ export declare function astarMultiroomDistanceMap(start: RoomPosition[], { costM
     foundTargets: RoomPosition[];
     ops: number;
 };
+/**
+ * Create a portal-aware distance map for the given start positions, using A* to
+ * optimize the search toward the given destinations.
+ *
+ * Portals configured with `initialize({ portals })` or `setPortals` are treated
+ * like exits: stepping onto a portal entrance lands on its paired exit.
+ *
+ * This calculates a distance map across multiple rooms, with a few configurable limits:
+ * - `maxOps`: The maximum number of pathfinding operations to perform.
+ * - `maxRooms`: The maximum number of rooms to explore.
+ * - `maxPathCost`: Don't explore tiles with a greater path cost than this.
+ *
+ * At least one of these limits or destination lists must be set.
+ *
+ * @param start - The starting positions.
+ * @param options - The options for the distance map.
+ * @returns A multi-room distance map.
+ */
+export declare function astarPortalMultiroomDistanceMap(start: RoomPosition[], { costMatrixCallback, maxRooms, maxOps, maxPathCost, anyOfDestinations, allOfDestinations }: {
+    costMatrixCallback: (room: string) => ClockworkCostMatrix | undefined;
+    maxRooms?: number;
+    maxOps?: number;
+    maxPathCost?: number;
+    anyOfDestinations?: {
+        pos: RoomPosition;
+        range: number;
+    }[];
+    allOfDestinations?: {
+        pos: RoomPosition;
+        range: number;
+    }[];
+}): {
+    distanceMap: import("./multiroomDistanceMap").ClockworkMultiroomDistanceMap;
+    foundTargets: RoomPosition[];
+    ops: number;
+};

package/dist/src/wrappers/bfsDistanceMap.d.ts

@@ -33,3 +33,40 @@ export declare function bfsMultiroomDistanceMap(start: RoomPosition[], { costMat
     foundTargets: RoomPosition[];
     ops: number;
 };
+/**
+ * Create a portal-aware distance map for the given start positions, using a breadth-first search.
+ * This does not factor in terrain costs (treating anything less than 255 in the cost
+ * matrix as passable), so it's faster but less useful than Dijkstra's algorithm.
+ *
+ * Portals configured with `initialize({ portals })` or `setPortals` are treated
+ * like exits: stepping onto a portal entrance lands on its paired exit.
+ *
+ * This calculates a distance map across multiple rooms, with a few configurable limits:
+ * - `maxOps`: The maximum number of pathfinding operations to perform.
+ * - `maxRooms`: The maximum number of rooms to explore.
+ * - `maxPathCost`: Don't explore tiles with a greater path cost than this.
+ *
+ * At least one of these limits or destination lists must be set.
+ *
+ * @param start - The starting positions.
+ * @param options - The options for the distance map.
+ * @returns A multi-room distance map.
+ */
+export declare function bfsPortalMultiroomDistanceMap(start: RoomPosition[], { costMatrixCallback, maxOps, maxRooms, maxPathCost, anyOfDestinations, allOfDestinations }: {
+    costMatrixCallback: (room: string) => ClockworkCostMatrix | undefined;
+    maxOps?: number;
+    maxRooms?: number;
+    maxPathCost?: number;
+    anyOfDestinations?: {
+        pos: RoomPosition;
+        range: number;
+    }[];
+    allOfDestinations?: {
+        pos: RoomPosition;
+        range: number;
+    }[];
+}): {
+    distanceMap: import("./multiroomDistanceMap").ClockworkMultiroomDistanceMap;
+    foundTargets: RoomPosition[];
+    ops: number;
+};

package/dist/src/wrappers/dijkstraDistanceMap.d.ts

@@ -32,3 +32,39 @@ export declare function dijkstraMultiroomDistanceMap(start: RoomPosition[], { co
     foundTargets: RoomPosition[];
     ops: number;
 };
+/**
+ * Create a portal-aware distance map for the given start positions, using Dijkstra's
+ * algorithm to factor in terrain costs (0-255, where 255 is impassable).
+ *
+ * Portals configured with `initialize({ portals })` or `setPortals` are treated
+ * like exits: stepping onto a portal entrance lands on its paired exit.
+ *
+ * This calculates a distance map across multiple rooms, with a few configurable limits:
+ * - `maxOps`: The maximum number of pathfinding operations to perform.
+ * - `maxRooms`: The maximum number of rooms to explore.
+ * - `maxPathCost`: Don't explore tiles with a greater path cost than this.
+ *
+ * At least one of these limits or destination lists must be set.
+ *
+ * @param start - The starting positions.
+ * @param options - The options for the distance map.
+ * @returns A multi-room distance map.
+ */
+export declare function dijkstraPortalMultiroomDistanceMap(start: RoomPosition[], { costMatrixCallback, maxOps, maxRooms, maxPathCost, anyOfDestinations, allOfDestinations }: {
+    costMatrixCallback: (room: string) => ClockworkCostMatrix | undefined;
+    maxOps?: number;
+    maxRooms?: number;
+    maxPathCost?: number;
+    anyOfDestinations?: {
+        pos: RoomPosition;
+        range: number;
+    }[];
+    allOfDestinations?: {
+        pos: RoomPosition;
+        range: number;
+    }[];
+}): {
+    distanceMap: import("./multiroomDistanceMap").ClockworkMultiroomDistanceMap;
+    foundTargets: RoomPosition[];
+    ops: number;
+};

package/dist/src/wrappers/multiroomDistanceMap.d.ts

@@ -38,14 +38,29 @@ export declare class ClockworkMultiroomDistanceMap {
      * Pass `DirectionOrder.DiagonalFirst` to prefer diagonal steps when multiple neighbors are equally close.
      */
     pathToOrigin(start: RoomPosition, options?: DirectionOrderOptions): ClockworkPath;
+    /**
+     * Portal-aware path to the origin from a given position.
+     * Pass `DirectionOrder.DiagonalFirst` to prefer diagonal steps when multiple neighbors are equally close.
+     */
+    pathToOriginWithPortals(start: RoomPosition, options?: DirectionOrderOptions): ClockworkPath;
     /**
      * Flow field for this distance map.
      * Pass `DirectionOrder.DiagonalFirst` to prefer diagonal directions when multiple neighbors are equally close.
      */
     toFlowField(options?: DirectionOrderOptions): ClockworkMultiroomFlowField;
+    /**
+     * Portal-aware flow field for this distance map.
+     * Pass `DirectionOrder.DiagonalFirst` to prefer diagonal directions when multiple neighbors are equally close.
+     */
+    toFlowFieldWithPortals(options?: DirectionOrderOptions): ClockworkMultiroomFlowField;
     /**
      * Mono-directional flow field for this distance map.
      * Pass `DirectionOrder.DiagonalFirst` to prefer diagonal directions when multiple neighbors are equally close.
      */
     toMonoFlowField(options?: DirectionOrderOptions): ClockworkMultiroomMonoFlowField;
+    /**
+     * Portal-aware monodirectional flow field for this distance map.
+     * Pass `DirectionOrder.DiagonalFirst` to prefer diagonal directions when multiple neighbors are equally close.
+     */
+    toMonoFlowFieldWithPortals(options?: DirectionOrderOptions): ClockworkMultiroomMonoFlowField;
 }

package/dist/src/wrappers/multiroomFlowField.d.ts

@@ -43,4 +43,8 @@ export declare class ClockworkMultiroomFlowField {
      * Find a path from a given position to the origin of the flow field.
      */
     pathToOrigin(start: RoomPosition): ClockworkPath;
+    /**
+     * Find a portal-aware path from a given position to the origin of the flow field.
+     */
+    pathToOriginWithPortals(start: RoomPosition): ClockworkPath;
 }

package/dist/src/wrappers/multiroomMonoFlowField.d.ts

@@ -31,4 +31,8 @@ export declare class ClockworkMultiroomMonoFlowField {
      * Find a path from a given position to the origin of the flow field.
      */
     pathToOrigin(start: RoomPosition): ClockworkPath;
+    /**
+     * Find a portal-aware path from a given position to the origin of the flow field.
+     */
+    pathToOriginWithPortals(start: RoomPosition): ClockworkPath;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screeps-clockwork",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "A WASM movement library for Screeps",
   "main": "dist/index.js",
   "types": "dist/src/index.d.ts",
@@ -21,15 +21,15 @@
     "typecheck:ts:test": "tsc -p tsconfig.test.json --noEmit",
     "typecheck:rust": "cargo check --target wasm32-unknown-unknown --all-features",
     "check:wasm-types": "run-s check:wasm-types:present check:wasm-types:src check:wasm-types:bench",
-    "check:wasm-types:present": "test -f src/wasm/screeps_clockwork.d.ts && test -f src/wasm/screeps_clockwork_bg.wasm.d.ts && test -f benches/wasm/pkg/screeps_clockwork.d.ts && test -f benches/wasm/pkg/screeps_clockwork_bg.wasm.d.ts",
-    "check:wasm-types:src": "npm run build:lib && git diff --exit-code -- src/wasm/screeps_clockwork.d.ts src/wasm/screeps_clockwork_bg.wasm.d.ts",
-    "check:wasm-types:bench": "npm run bench:wasm:build && git diff --exit-code -- benches/wasm/pkg/screeps_clockwork.d.ts benches/wasm/pkg/screeps_clockwork_bg.wasm.d.ts",
+    "check:wasm-types:present": "test -f src/wasm/screeps_clockwork.d.ts && test -f benches/wasm/pkg/screeps_clockwork.d.ts",
+    "check:wasm-types:src": "npm run build:lib && git diff --exit-code -- src/wasm/screeps_clockwork.d.ts",
+    "check:wasm-types:bench": "npm run bench:wasm:build && git diff --exit-code -- benches/wasm/pkg/screeps_clockwork.d.ts",
     "build": "run-s build:lib build:src",
-    "build:lib": "wasm-pack build --target web --out-dir src/wasm --config build.rustflags=[\\'-Ctarget-feature=-reference-types\\',\\'-Ctarget-feature=-multivalue\\',\\'-Ctarget-feature=-sign-ext\\'] -Z build-std=std,panic_abort && printf '*\\n!*.d.ts\\n' > src/wasm/.gitignore",
+    "build:lib": "wasm-pack build --target web --out-dir src/wasm --config build.rustflags=[\\'-Ctarget-feature=-reference-types\\',\\'-Ctarget-feature=-multivalue\\',\\'-Ctarget-feature=-sign-ext\\'] -Z build-std=std,panic_abort && printf '*\\n!screeps_clockwork.d.ts\\n' > src/wasm/.gitignore",
     "build:src": "rollup -c",
     "build:docs": "typedoc",
     "bench:rust": "cargo bench --features bench --bench distance_map",
-    "bench:wasm:build": "wasm-pack build --target nodejs --out-dir benches/wasm/pkg --config \"build.rustflags=['-Ctarget-feature=-reference-types','-Ctarget-feature=-multivalue','-Ctarget-feature=-sign-ext']\" -Z build-std=std,panic_abort && printf '*\\n!*.d.ts\\n' > benches/wasm/pkg/.gitignore && cp benches/wasm/pkg/screeps_clockwork.js benches/wasm/pkg/screeps_clockwork.cjs",
+    "bench:wasm:build": "wasm-pack build --target nodejs --out-dir benches/wasm/pkg --config \"build.rustflags=['-Ctarget-feature=-reference-types','-Ctarget-feature=-multivalue','-Ctarget-feature=-sign-ext']\" -Z build-std=std,panic_abort && printf '*\\n!screeps_clockwork.d.ts\\n' > benches/wasm/pkg/.gitignore && cp benches/wasm/pkg/screeps_clockwork.js benches/wasm/pkg/screeps_clockwork.cjs",
     "bench:wasm:run": "node --no-liftoff --no-wasm-lazy-compilation --wasm-wrapper-tiering-budget=0 ./node_modules/vitest/vitest.mjs bench benches/wasm",
     "bench:wasm": "run-s bench:wasm:build bench:wasm:run",
     "bench:wasm:save": "run-s bench:wasm:build bench:wasm:save:run",