@sandustry-modding/types 0.1.0 → 0.3.0

package/src/sandkit/api/factory.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Factory progression level and process counters.
+ *
+ * Available as `sandkit.api.factory`.
+ *
+ * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.factory`
+ */
+export namespace factory {
+  /**
+   * Return the current factory level.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.factory.getLevel`
+   */
+  export function getLevel(): number;
+
+  /**
+   * Return completed count for a factory process.
+   *
+   * @param processId - Built-in factory process id.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.factory.getProcessCount`
+   */
+  export function getProcessCount(processId: FactoryProcessId): number;
+
+  /**
+   * Return completion rate for a factory process.
+   *
+   * @param processId - Built-in factory process id.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.factory.getProcessRate`
+   */
+  export function getProcessRate(processId: FactoryProcessId): number;
+
+  /** Built-in factory process identifiers. */
+  export type FactoryProcessId =
+    | "shakeWetSand"
+    | "pressBurntResidue"
+    | "growFlowers"
+    | "condenseFlorin";
+}

package/src/sandkit/api/fire.d.ts

@@ -0,0 +1,33 @@
+import { CellCoordinates } from "../../shared/player";
+
+/**
+ * `sandkit.api.fire` — ignite and burn elements at grid cells.
+ * Main thread only.
+ *
+ * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.fire`
+ */
+export namespace fire {
+  /**
+   * Returns true when the element at the cell can burn.
+   *
+   * @param cellX - Grid cell X coordinate.
+   * @param cellY - Grid cell Y coordinate.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.fire.canBurnElementAtCell`
+   */
+  export function canBurnElementAtCell(...args: CellCoordinates): boolean;
+
+  /**
+   * Burn the element at the cell. Main-entry writes are deferred; reads see the old grid.
+   *
+   * @param cellX - Grid cell X coordinate.
+   * @param cellY - Grid cell Y coordinate.
+   * @see https://sandustry.com/sandkit.html#mutations-heading Official Sandkit API — Main entry `api.fire.burnElementAtCell`
+   */
+  export function burnElementAtCell(...args: CellCoordinates): void;
+
+  /**
+   * @deprecated Use {@link burnElementAtCell} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.fire.burnElementAtCell`
+   */
+  export function burnElementAtCellWhenIdle(...args: CellCoordinates): void;
+}

package/src/sandkit/api/game.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Game session start helpers.
+ *
+ * Available as `sandkit.api.game`.
+ *
+ * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.game`
+ */
+export namespace game {
+  /**
+   * Start or restart the game session.
+   *
+   * @param options - Optional session start flags.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.game.start`
+   */
+  export function start(options?: GameStartOptions): void;
+
+  /** Options for {@link start}. */
+  export interface GameStartOptions {
+    /** When true, skip the intro sequence. */
+    skipIntro?: boolean;
+  }
+}

package/src/sandkit/api/grid.d.ts

@@ -0,0 +1,180 @@
+import { CellCoordinates } from "../../shared/player";
+import { shared } from "../../shared";
+import type { elements } from "./elements";
+import type { terrains } from "./terrains";
+
+/**
+ * `sandkit.api.grid` — grid cell queries, deferred mutations, and iteration.
+ *
+ * Main thread only.
+ *
+ * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid`
+ */
+export namespace grid {
+  /**
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.getCellIdAtCell`
+   */
+  export import getCellIdAtCell = shared.api.grid.getCellIdAtCell;
+  /**
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.isCellEmptyAtCell`
+   */
+  export import isCellEmptyAtCell = shared.api.grid.isCellEmptyAtCell;
+  /**
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.isTerrainAtCell`
+   */
+  export import isTerrainAtCell = shared.api.grid.isTerrainAtCell;
+  /**
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.reportActivityAtCell`
+   */
+  export import reportActivityAtCell = shared.api.grid.reportActivityAtCell;
+  /**
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.excavateAtCell`
+   */
+  export import excavateAtCell = shared.api.grid.excavateAtCell;
+  /**
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.getDimensions`
+   */
+  export import getDimensions = shared.api.grid.getDimensions;
+  /** @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.ExcavateOptions` */
+  export import ExcavateOptions = shared.api.grid.ExcavateOptions;
+  /** @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.CellId` */
+  export import CellId = shared.api.grid.CellId;
+  /** @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.GridDimensions` */
+  export import GridDimensions = shared.api.grid.GridDimensions;
+
+  /**
+   * Run deferred grid mutations on the main thread. Reads see the old grid until
+   * mutations apply.
+   *
+   * @param callback - Receives a writer for element and terrain cell mutations.
+   * @see https://sandustry.com/sandkit.html#mutations-heading
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.mutate`
+   */
+  export function mutate(callback: (writer: GridMutationWriter) => void): void;
+
+  /**
+   * Reveal fog of war at a cell.
+   *
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.revealFogAtCell`
+   */
+  export function revealFogAtCell(...args: CellCoordinates): void;
+
+  /**
+   * Request redraw around a cell.
+   *
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @param rangeCells - Radius in cells to redraw.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.redrawAroundCell`
+   */
+  export function redrawAroundCell(...args: [...CellCoordinates, rangeCells: number]): void;
+
+  /**
+   * Calls the callback for each cell inside a circle.
+   *
+   * @param centerCellX - Circle center cell column.
+   * @param centerCellY - Circle center cell row.
+   * @param radiusCells - Circle radius in cells.
+   * @param callback - Invoked for each cell with `(cellX, cellY)`.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.forEachCellInCircle`
+   */
+  export function forEachCellInCircle(centerCellX: number, centerCellY: number, radiusCells: number, callback: (...args: CellCoordinates) => void): void;
+
+  /**
+   * Calls the callback for each cell in a rectangle.
+   *
+   * @param cellX - Origin cell column (top-left).
+   * @param cellY - Origin cell row (top-left).
+   * @param widthCells - Rectangle width in cells.
+   * @param heightCells - Rectangle height in cells.
+   * @param callback - Invoked for each cell with `(cellX, cellY)`.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.forEachCellInRectangle`
+   */
+  export function forEachCellInRectangle(...args: [...CellCoordinates, widthCells: number, heightCells: number, callback: (...args: CellCoordinates) => void]): void;
+
+  /**
+   * @deprecated Use {@link forEachCellInRectangle} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.forEachCellInRectangle`
+   */
+  export function forEachCellInRect(...args: [...CellCoordinates, widthCells: number, heightCells: number, callback: (...args: CellCoordinates) => void]): void;
+
+  /** Deferred element and terrain mutations passed to {@link mutate}. */
+  export interface GridMutationWriter {
+    /** Element cell mutations inside a {@link mutate} callback. */
+    elements: GridMutationWriterElements;
+    /** Terrain cell mutations inside a {@link mutate} callback. */
+    terrains: GridMutationWriterTerrains;
+  }
+
+  /** Element writers available on {@link GridMutationWriter.elements}. */
+  export interface GridMutationWriterElements {
+    /**
+     * Create an element at a cell inside a {@link mutate} callback.
+     *
+     * @param cellX - Grid column of the target cell.
+     * @param cellY - Grid row of the target cell.
+     * @param elementTypeOrId - Numeric element type or string id.
+     * @param options - Optional create flags.
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.mutate` writer `elements.createAtCell`
+     */
+    createAtCell(...args: [...CellCoordinates, elementTypeOrId: elements.ElementRef, options?: elements.ElementCreateOptions]): void;
+
+    /**
+     * Replace the element at a cell inside a {@link mutate} callback.
+     *
+     * @param cellX - Grid column of the target cell.
+     * @param cellY - Grid row of the target cell.
+     * @param elementTypeOrId - Numeric element type or string id.
+     * @param options - Optional create flags.
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.mutate` writer `elements.replaceAtCell`
+     */
+    replaceAtCell(...args: [...CellCoordinates, elementTypeOrId: elements.ElementRef, options?: elements.ElementCreateOptions]): void;
+
+    /**
+     * Remove the element at a cell inside a {@link mutate} callback.
+     *
+     * @param cellX - Grid column of the target cell.
+     * @param cellY - Grid row of the target cell.
+     * @param options - Optional removal flags.
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.mutate` writer `elements.removeAtCell`
+     */
+    removeAtCell(...args: [...CellCoordinates, options?: elements.ElementRemovalOptions]): void;
+  }
+
+  /** Terrain writers available on {@link GridMutationWriter.terrains}. */
+  export interface GridMutationWriterTerrains {
+    /**
+     * Create terrain at a cell inside a {@link mutate} callback.
+     *
+     * @param cellX - Grid column of the target cell.
+     * @param cellY - Grid row of the target cell.
+     * @param terrainTypeOrId - Numeric terrain type or string id.
+     * @param options - Optional mutation flags.
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.mutate` writer `terrains.createAtCell`
+     */
+    createAtCell(...args: [...CellCoordinates, terrainTypeOrId: terrains.TerrainRef, options?: terrains.TerrainMutationOptions]): void;
+
+    /**
+     * Replace terrain at a cell inside a {@link mutate} callback.
+     *
+     * @param cellX - Grid column of the target cell.
+     * @param cellY - Grid row of the target cell.
+     * @param terrainTypeOrId - Numeric terrain type or string id.
+     * @param options - Optional mutation flags.
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.mutate` writer `terrains.replaceAtCell`
+     */
+    replaceAtCell(...args: [...CellCoordinates, terrainTypeOrId: terrains.TerrainRef, options?: terrains.TerrainMutationOptions]): void;
+
+    /**
+     * Remove terrain at a cell inside a {@link mutate} callback.
+     *
+     * @param cellX - Grid column of the target cell.
+     * @param cellY - Grid row of the target cell.
+     * @param options - Optional mutation flags.
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.mutate` writer `terrains.removeAtCell`
+     */
+    removeAtCell(...args: [...CellCoordinates, options?: terrains.TerrainMutationOptions]): void;
+  }
+}

package/src/sandkit/api/hooks.d.ts

@@ -0,0 +1,357 @@
+import type { LooseString } from "../../shared/nominal";
+
+/**
+ * `sandkit.api.hooks` — intercept and modify internal game hook points.
+ * Main thread only.
+ */
+export namespace hooks {
+  /**
+   * Registers an intercept hook. Returns an unsubscribe function.
+   *
+   * @param hookId - Registered hook identifier.
+   * @param callback - Called with hook arguments and context; may cancel the hook.
+   * @param options - Optional priority and filter options.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.hooks.intercept`
+   */
+  export function intercept<K extends InterceptHookId>(
+    hookId: K,
+    callback: (args: InterceptHookArgs<K>, context: HookContext) => void,
+    options?: InterceptHookOptions<K>,
+  ): () => void;
+
+  /**
+   * Registers a modifier hook. Returns an unsubscribe function.
+   *
+   * @param hookId - Registered hook identifier.
+   * @param callback - Called with hook arguments; may mutate hook payload.
+   * @param options - Optional priority and filter options.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.hooks.modify`
+   */
+  export function modify<K extends ModifyHookId>(
+    hookId: K,
+    callback: (args: ModifyHookArgs<K>) => void,
+    options?: ModifyHookOptions,
+  ): () => void;
+
+  /** Context passed to intercept hook callbacks. */
+  export interface HookContext {
+    /** When called, the intercepted action is skipped. */
+    cancel(): void;
+    /** True after {@link cancel} was called on this context. */
+    cancelled: boolean;
+  }
+
+  /** Options shared by intercept and modify hooks. */
+  export interface HookOptions {
+    /** Run this hook before others with lower priority. */
+    priority?: number;
+    [key: string]: unknown;
+  }
+
+  /** Options for {@link intercept}. */
+  export type InterceptHookOptions<K extends InterceptHookId> = HookOptions &
+    (K extends "item:use"
+      ? { itemIds?: string[]; priority?: number }
+      : K extends "entity:update"
+        ? { entityTypes?: string[]; priority?: number }
+        : K extends "building:place"
+          ? { structureTypes?: string[]; priority?: number }
+          : K extends "projectile:fire:overStructure" | "projectile:hit"
+            ? { projectileTypes?: string[]; priority?: number }
+            : Record<string, unknown>);
+
+  /** Options for {@link modify}. */
+  export type ModifyHookOptions = HookOptions &
+    (
+      | { weaponIds?: string[]; priority?: number }
+      | { projectileTypes?: string[]; priority?: number }
+      | { triggerIds?: string[]; priority?: number }
+      | { resourceIds?: string[]; priority?: number }
+      | Record<string, unknown>
+    );
+
+  /** Known main-thread intercept hook ids plus custom strings. */
+  export type InterceptHookId = LooseString<
+    | "item:use"
+    | "teleport:effect:create"
+    | "teleport:effect"
+    | "action:start"
+    | "action:intercept"
+    | "input:keyDown"
+    | "input:keydown"
+    | "input:keyUp"
+    | "input:keyup"
+    | "placePoints:suppress"
+    | "placePoints:isSuppressed"
+    | "placePoints:directionalArrows:suppress"
+    | "placePoints:directionalArrows:isSuppressed"
+    | "entity:update"
+    | "building:place"
+    | "building:clearShape"
+    | "input:scroll"
+    | "input:boostDown"
+    | "input:boost-down"
+    | "input:descendDown"
+    | "input:descend-down"
+    | "input:escape"
+    | "interactable:suppressHover"
+    | "fire:element:ignite"
+    | "projectile:fire:overStructure"
+    | "projectile:hit"
+    | "player:position:commit"
+    | "progression:purchase"
+  >;
+
+  /** Known main-thread modify hook ids plus custom strings. */
+  export type ModifyHookId = LooseString<
+    | "excavation:prepare"
+    | "locator:scan:prepare"
+    | "vacuum:prepare"
+    | "vacuum:element:prepare"
+    | "player:movement:prepare"
+    | "player:movement"
+    | "building:placementLimit:prepare"
+    | "building:placementLimit"
+    | "building:placement-limit"
+    | "fluxEmanator:processing:prepare"
+    | "fluxEmanator:processing"
+    | "flux-emanator:processing"
+    | "render:pipes:prepare"
+    | "render:pipes"
+    | "structures:moved:prepare"
+    | "structures:removed:prepare"
+    | "weapon:reload:prepare"
+    | "projectile:travel:prepare"
+    | "projectile:impact:prepare"
+    | "player:collision:prepare"
+    | "trigger:schedule:prepare"
+    | "progression:cost:prepare"
+    | "resource:collection:prepare"
+    | "resource:delivery:prepare"
+    | "resource:balance:prepare"
+    | "gold:removal:prepare"
+    | "gold:removal:settle"
+  >;
+
+  /** Intercept hook argument shapes keyed by hook id. */
+  export interface InterceptHookMap {
+    "item:use": {
+      itemId: string;
+      useId: string;
+      kind: "instant" | "sustained" | "chargeThenFire";
+      baseline: Readonly<Record<string, unknown>>;
+      prepared: Record<string, unknown>;
+    };
+    "teleport:effect:create": Record<string, unknown>;
+    /** @deprecated Use `"teleport:effect:create"` instead. */
+    "teleport:effect": InterceptHookMap["teleport:effect:create"];
+    "action:start": { action?: { id?: string; } & Record<string, unknown>; } & Record<string, unknown>;
+    /** @deprecated Use `"action:start"` instead. */
+    "action:intercept": InterceptHookMap["action:start"];
+    "input:keyDown": { key?: string; code?: string; event?: Event; };
+    /** @deprecated Use `"input:keyDown"` instead. */
+    "input:keydown": InterceptHookMap["input:keyDown"];
+    "input:keyUp": { key?: string; code?: string; event?: Event; };
+    /** @deprecated Use `"input:keyUp"` instead. */
+    "input:keyup": InterceptHookMap["input:keyUp"];
+    "placePoints:suppress": { type?: string; } & Record<string, unknown>;
+    /** @deprecated Use `"placePoints:suppress"` instead. */
+    "placePoints:isSuppressed": InterceptHookMap["placePoints:suppress"];
+    "placePoints:directionalArrows:suppress": { type?: string; } & Record<string, unknown>;
+    /** @deprecated Use `"placePoints:directionalArrows:suppress"` instead. */
+    "placePoints:directionalArrows:isSuppressed": InterceptHookMap["placePoints:directionalArrows:suppress"];
+    "entity:update": {
+      entityTypeId: string;
+      entity: Record<string, unknown>;
+      deltaTimeSeconds: number;
+      phase: "normal" | "capturing" | "launching";
+      isVisible: boolean;
+      playerWorldX: number;
+      playerWorldY: number;
+      worldMinX: number;
+      worldMinY: number;
+      worldMaxX: number;
+      worldMaxY: number;
+      cellSize: number;
+      timeSeconds: number;
+    };
+    "building:place": {
+      structureId: string;
+      x: number;
+      y: number;
+      data?: Record<string, unknown>;
+    };
+    "building:clearShape": { structure: Record<string, unknown>; };
+    "input:scroll": { deltaY: number; } & Record<string, unknown>;
+    "input:boostDown": Record<string, unknown>;
+    /** @deprecated Use `"input:boostDown"` instead. */
+    "input:boost-down": InterceptHookMap["input:boostDown"];
+    "input:descendDown": Record<string, unknown>;
+    /** @deprecated Use `"input:descendDown"` instead. */
+    "input:descend-down": InterceptHookMap["input:descendDown"];
+    "input:escape": Record<string, unknown>;
+    "interactable:suppressHover": { type?: string; structure?: Record<string, unknown>; } & Record<string, unknown>;
+    "fire:element:ignite": { x: number; y: number; elementType: number; };
+    "projectile:fire:overStructure": { projectile: Record<string, unknown>; x: number; y: number; };
+    "projectile:hit": { projectile: Record<string, unknown>; travelResult: Record<string, unknown>; };
+    "player:position:commit": {
+      previousWorldX: number;
+      previousWorldY: number;
+      proposedWorldX: number;
+      proposedWorldY: number;
+      velocityX: number;
+      velocityY: number;
+    };
+    "progression:purchase": {
+      domain: "tech" | "upgrade";
+      id: string;
+      itemId?: string;
+      costs: Record<string, unknown>;
+    };
+  }
+
+  /** Modify hook argument shapes keyed by hook id. */
+  export interface ModifierHookMap {
+    "excavation:prepare": {
+      sourceId: string;
+      sourceKind: "tool" | "projectile" | "structure" | "drone";
+      originCellX: number;
+      originCellY: number;
+      consumedVoid: boolean;
+      profileId: string;
+      patternDiameterCells: number;
+      drillTierDamage: number;
+    };
+    "locator:scan:prepare": {
+      originWorldX: number;
+      originWorldY: number;
+      hasTarget: boolean;
+      targetCellX: number;
+      targetCellY: number;
+      outerTint: [number, number, number];
+      innerTint: [number, number, number];
+      noTargetToast: string;
+      noTargetToastKey: string;
+      triangulationLensOverride: true | false | null;
+    };
+    "vacuum:prepare": {
+      nozzleCellX: number;
+      nozzleCellY: number;
+      targetCellX: number;
+      targetCellY: number;
+      pattern: number[][];
+    };
+    "vacuum:element:prepare": {
+      elementType: number;
+      matterType: number;
+      isTransportable: boolean;
+      collectable: boolean;
+      visibleInPicker: boolean;
+    };
+    "player:movement:prepare": Record<string, unknown>;
+    /** @deprecated Use `"player:movement:prepare"` instead. */
+    "player:movement": ModifierHookMap["player:movement:prepare"];
+    "building:placementLimit:prepare": { maxCount: number | null; } & Record<string, unknown>;
+    /** @deprecated Use `"building:placementLimit:prepare"` instead. */
+    "building:placementLimit": ModifierHookMap["building:placementLimit:prepare"];
+    /** @deprecated Use `"building:placementLimit:prepare"` instead. */
+    "building:placement-limit": ModifierHookMap["building:placementLimit:prepare"];
+    "fluxEmanator:processing:prepare": { speedMultiplier: number; } & Record<string, unknown>;
+    /** @deprecated Use `"fluxEmanator:processing:prepare"` instead. */
+    "fluxEmanator:processing": ModifierHookMap["fluxEmanator:processing:prepare"];
+    /** @deprecated Use `"fluxEmanator:processing:prepare"` instead. */
+    "flux-emanator:processing": ModifierHookMap["fluxEmanator:processing:prepare"];
+    "render:pipes:prepare": { layer?: string; } & Record<string, unknown>;
+    /** @deprecated Use `"render:pipes:prepare"` instead. */
+    "render:pipes": ModifierHookMap["render:pipes:prepare"];
+    "structures:moved:prepare": {
+      moved: unknown[];
+      failedToPlace: unknown[];
+    };
+    "structures:removed:prepare": {
+      removed: unknown[];
+      structures?: unknown[];
+      byMove: boolean;
+    };
+    "weapon:reload:prepare": {
+      weaponId: string;
+      reloadMs: number;
+      maxAmmo: number;
+    };
+    "projectile:travel:prepare": {
+      projectileType: string;
+      firstCollisionStep: number;
+      maxCollisionSteps: number;
+      collidesWithTerrain: boolean;
+      collidesWithStructures: boolean;
+    };
+    "projectile:impact:prepare": {
+      projectileType: string;
+      impactKind: string;
+      profileId: string;
+      power: number;
+      centerPower: number;
+      radiusCells: number;
+      /** @deprecated Use {@link radiusCells} instead. */
+      radius?: number;
+    };
+    "player:collision:prepare": {
+      phaseThroughTerrain: boolean;
+      phaseThroughStructures: boolean;
+      maxStepCells: number;
+    };
+    "trigger:schedule:prepare": {
+      triggerId: string;
+      intervalMs: number;
+      sequentialRuns: number;
+    };
+    "progression:cost:prepare": {
+      domain: "tech" | "upgrade";
+      id: string;
+      itemId?: string;
+      currencyId: string;
+      amount: number;
+    };
+    "resource:collection:prepare": {
+      resourceId: string;
+      sourceKind: string;
+      cellX: number;
+      cellY: number;
+      amount: number;
+      feedback: "default" | "silent";
+    };
+    "resource:delivery:prepare": {
+      resourceId: string;
+      sourceKind: string;
+      sourceId: string;
+      sourceCellX: number;
+      sourceCellY: number;
+      targetCellX: number;
+      targetCellY: number;
+      mode: "world" | "collection";
+      amount: number;
+      feedback: "default" | "silent";
+    };
+    "resource:balance:prepare": {
+      resourceId: string;
+      balance: number;
+    };
+    "gold:removal:prepare": {
+      requestedAmount: number;
+      shortfall: number;
+    };
+    "gold:removal:settle": {
+      requestedAmount: number;
+      physicalRemoved: number;
+      shortfall: number;
+    };
+  }
+
+  /** Intercept hook args for a given hook id. */
+  export type InterceptHookArgs<K extends InterceptHookId> =
+    K extends keyof InterceptHookMap ? InterceptHookMap[K] : unknown;
+
+  /** Modify hook args for a given hook id. */
+  export type ModifyHookArgs<K extends ModifyHookId> =
+    K extends keyof ModifierHookMap ? ModifierHookMap[K] : unknown;
+}