@sandustry-modding/types 0.1.0 → 0.3.0

package/{sandkit → src/sandkit}/api/i18n.d.ts

@@ -7,81 +7,157 @@ import type { LooseString } from "../../shared/nominal";
 export namespace i18n {
   /**
    * Translates a key with optional parameter substitution.
+   *
    * @param key - Translation key.
    * @param params - Placeholder values for the key template.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.t`
    */
   export function t(key: string, params?: Record<string, string | number>): string;
+
   /**
    * Registers translation strings for a locale.
+   *
    * @param locale - Locale code (e.g. `en`).
    * @param translations - Map of keys to translated strings.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.register`
    */
   export function register(locale: Locale, translations: Record<string, string>): void;
-  /** Returns the active locale code. */
+
+  /**
+   * Returns the active locale code.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.getLocale`
+   */
   export function getLocale(): Locale;
+
   /**
    * Returns true when a translation exists for the key.
+   *
    * @param key - Translation key.
    * @param locale - Optional locale; defaults to the active locale.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.hasTranslation`
    */
   export function hasTranslation(key: string, locale?: Locale): boolean;
+
   /**
    * Sets the active locale.
+   *
    * @param locale - Locale code to activate.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.setLocale`
    */
   export function setLocale(locale: Locale): Promise<void>;
-  /** Returns metadata for all known languages. */
+
+  /**
+   * Returns metadata for all known languages.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.getLanguages`
+   */
   export function getLanguages(): { code: Locale; nativeName: string; englishName: string; enabled: boolean; }[];
-  /** Returns locale codes that have registered translations. */
+
+  /**
+   * Returns locale codes that have registered translations.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.getAvailableLocales`
+   */
   export function getAvailableLocales(): Locale[];
+
   /**
    * Formats a number for the active locale.
+   *
    * @param value - Number to format.
    * @param options - Intl-style number format options.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.formatNumber`
    */
   export function formatNumber(value: number, options?: I18nNumberFormatOptions): string;
+
   /**
    * Joins key parts into a single translation key.
+   *
    * @param parts - Key segments joined with `.`.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.joinKey`
+   */
+  export function joinKey(...parts: string[]): string;
+
+  /**
+   * @deprecated Use {@link joinKey} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.i18n.joinKey`
    */
   export function key(...parts: string[]): string;
+
   /**
    * Returns the display name from a definition with nameKey or name.
+   *
    * @param definition - Object with `nameKey` or `name`.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.getName`
    */
   export function getName(definition: { nameKey?: string; name?: string; }): string;
+
   /**
    * Returns the description from a definition with descriptionKey or description.
+   *
    * @param definition - Object with `descriptionKey` or `description`.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.getDescription`
    */
   export function getDescription(definition: { descriptionKey?: string; description?: string; }): string;
+
   /**
    * Creates a translatable string object with a fallback.
+   *
    * @param key - Translation key.
    * @param fallback - Text used when no translation is registered.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.createTranslatable`
+   */
+  export function createTranslatable(key: string, fallback: string): { __translatable: true; key: string; fallback: string; };
+
+  /**
+   * @deprecated Use {@link createTranslatable} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.i18n.createTranslatable`
    */
   export function translatable(key: string, fallback: string): { __translatable: true; key: string; fallback: string; };
+
   /**
    * Sets a global string or lazy resolver used in translations.
+   *
    * @param key - Global helper key.
    * @param value - Static string or function that returns the current value.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.setGlobal`
    */
   export function setGlobal(key: string, value: string | (() => string)): void;
+
   /**
    * Returns a global translation helper value.
+   *
    * @param key - Global helper key.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.getGlobal`
    */
   export function getGlobal(key: string): string | undefined;
+
   /**
    * Removes a global translation helper value.
+   *
    * @param key - Global helper key.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.removeGlobal`
+   */
+  export function removeGlobal(key: string): void;
+
+  /**
+   * @deprecated Use {@link removeGlobal} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.i18n.removeGlobal`
    */
   export function clearGlobal(key: string): void;
-  /** Returns all global translation helper values. */
+
+  /**
+   * Returns all global translation helper values.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.getGlobals`
+   */
   export function getGlobals(): Record<string, string>;
+
   /**
    * Formats a key code for display in UI.
+   *
    * @param keyCode - Keyboard key code or binding name.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.formatKeyForDisplay`
    */
   export function formatKeyForDisplay(keyCode: string): string;
 

package/{sandkit → src/sandkit}/api/index.d.ts

@@ -11,6 +11,7 @@ export * from "./action"
 export * from "./assets"
 export * from "./authorization"
 export * from "./building"
+export * from "./blueprints"
 export * from "./camera"
 export * from "./collector"
 export * from "./constants"
@@ -18,10 +19,13 @@ export * from "./cooldown"
 export * from "./discoveries"
 export * from "./effects"
 export * from "./elements"
+export * from "./entities"
 export * from "./energy"
 export * from "./events"
 export * from "./excavation"
 export * from "./fire"
+export * from "./factory"
+export * from "./game"
 export * from "./gameconfig"
 export * from "./grid"
 export * from "./hooks"
@@ -32,6 +36,8 @@ export * from "./lights"
 export * from "./maps"
 export * from "./mods"
 export * from "./patterns"
+export * from "./pipes"
+export * from "./pickups"
 export * from "./player"
 export * from "./processing"
 export * from "./progression"

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

@@ -0,0 +1,101 @@
+import type { shared } from "../../shared";
+
+/**
+ * `sandkit.api.lights` — temporary lights and persistent world lights.
+ * Main thread only.
+ */
+export namespace lights {
+  /** Short-lived visual effect lights. */
+  export namespace temporary {
+    /**
+     * Create a temporary light at world coordinates.
+     *
+     * @param worldX - World X coordinate in pixels.
+     * @param worldY - World Y coordinate in pixels.
+     * @param options - Brightness, duration, color, and dedup options.
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.lights.temporary.createAtWorld`
+     */
+    export function createAtWorld(worldX: number, worldY: number, options?: TemporaryLightOptions): TemporaryLightHandle;
+
+    /**
+     * Remove a temporary light by its id.
+     *
+     * @param lightId - Light id returned from {@link createAtWorld}.
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.lights.temporary.removeById`
+     */
+    export function removeById(lightId: number): void;
+  }
+
+  /**
+   * @deprecated Use {@link temporary} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.lights.temporary`
+   */
+  export import vfx = temporary;
+
+  /** Lights that persist in the world save. */
+  export namespace persistent {
+    /**
+     * Create a persistent light at world coordinates.
+     *
+     * @param worldX - World X coordinate in pixels.
+     * @param worldY - World Y coordinate in pixels.
+     * @param options - Brightness, size, color, and persistence options.
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.lights.persistent.createAtWorld`
+     */
+    export function createAtWorld(worldX: number, worldY: number, options?: PersistentLightOptions): PersistentLightHandle;
+
+    /**
+     * Remove the persistent light at world coordinates.
+     *
+     * @param worldX - World X coordinate in pixels.
+     * @param worldY - World Y coordinate in pixels.
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.lights.persistent.removeAtWorld`
+     */
+    export function removeAtWorld(worldX: number, worldY: number): void;
+
+    /**
+     * Fade out the persistent light at world coordinates over durationMs.
+     *
+     * @param worldX - World X coordinate in pixels.
+     * @param worldY - World Y coordinate in pixels.
+     * @param durationMs - Fade duration in milliseconds.
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.lights.persistent.fadeAtWorld`
+     */
+    export function fadeAtWorld(worldX: number, worldY: number, durationMs?: number): void;
+
+    /**
+     * Mark persistent lights dirty so they are saved on the next flush.
+     *
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.lights.persistent.markDirty`
+     */
+    export function markDirty(): void;
+  }
+
+  /** Handle returned from {@link temporary.createAtWorld}. */
+  export interface TemporaryLightHandle {
+    /** Assigned temporary light id, or null when creation failed. */
+    lightId: number | null;
+    /**
+     * @deprecated Use {@link lightId} instead.
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias on `api.lights.temporary.createAtWorld` return value
+     */
+    index: number | null;
+  }
+
+  /** Options for temporary lights. */
+  export type TemporaryLightOptions = shared.api.effects.TemporaryLightOptions;
+
+  /** Options for persistent world lights. */
+  export interface PersistentLightOptions {
+    /** Light brightness multiplier. */
+    brightness?: number;
+    /** Light radius in pixels. */
+    size?: number;
+    /** RGBA color components. */
+    color?: [number, number, number, number];
+    [key: string]: unknown;
+  }
+
+  /** Handle returned from {@link persistent.createAtWorld}. */
+  export type PersistentLightHandle = unknown;
+}

package/{sandkit → src/sandkit}/api/maps.d.ts

@@ -22,6 +22,21 @@ export namespace maps {
    */
   export function start(mapId: string): boolean;
 
+  /**
+   * Return artifact marker locations for the active map.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.maps.getArtifactLocations`
+   */
+  export function getArtifactLocations(): readonly ArtifactLocation[];
+
+  /** Artifact location entry from {@link getArtifactLocations}. */
+  export interface ArtifactLocation {
+    cellX: number;
+    cellY: number;
+    name: string;
+    [key: string]: unknown;
+  }
+
   /** Available map entry shape. */
   export interface AvailableMapV1 {
     /** Map identifier passed to {@link start}. */

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

@@ -0,0 +1,89 @@
+import type { PickupType as PickupTypeEnum } from "../enums/index";
+
+/**
+ * World pickups — spawn, collect, and query pickup instances.
+ *
+ * Available as `sandkit.api.pickups`.
+ *
+ * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.pickups`
+ */
+export namespace pickups {
+  /** Official pickup type discriminator. */
+  export type PickupType = PickupTypeEnum;
+
+  /**
+   * @deprecated Use {@link PickupType} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.PickupType`
+   */
+  export type WorldItemType = PickupType;
+
+  /** Optional point light attached when spawning a pickup. */
+  export interface WorldItemLight {
+    /** Light brightness multiplier. Default 1. */
+    brightness?: number;
+    /** Light radius in world pixels. Default 100. */
+    size?: number;
+    /** RGB or RGBA color components in 0–1 range. */
+    color?: [number, number, number] | [number, number, number, number];
+  }
+
+  /** Active world pickup instance. */
+  export interface WorldItem {
+    id: number;
+    x: number;
+    y: number;
+    type: PickupType;
+    data: Record<string, unknown>;
+  }
+
+  /**
+   * Spawn a pickup at world position.
+   *
+   * @param type - Pickup type discriminator.
+   * @param worldX - World x position in pixels.
+   * @param worldY - World y position in pixels.
+   * @param data - Optional per-item data bag copied onto the instance.
+   * @param light - Optional point light spawned with the pickup.
+   * @returns The spawned pickup instance.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.pickups.spawnAtWorld`
+   */
+  export function spawnAtWorld(type: PickupType, worldX: number, worldY: number, data?: Record<string, unknown>, light?: WorldItemLight): WorldItem;
+
+  /**
+   * Remove a pickup instance from the world.
+   *
+   * @param pickup - Pickup returned from spawn or lookup helpers.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.pickups.remove`
+   */
+  export function remove(pickup: WorldItem): void;
+
+  /**
+   * @deprecated Use {@link remove} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.remove`
+   */
+  export function destroy(pickup: WorldItem): void;
+
+  /**
+   * Pick up a world item into inventory.
+   *
+   * @param pickup - Pickup to collect.
+   * @returns True when the item was collected.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.pickups.pickUp`
+   */
+  export function pickUp(pickup: WorldItem): boolean;
+
+  /**
+   * Return all active pickups.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.pickups.getAll`
+   */
+  export function getAll(): WorldItem[];
+
+  /**
+   * Return a pickup by numeric id.
+   *
+   * @param pickupId - Runtime pickup id.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.pickups.getById`
+   */
+  export function getById(pickupId: number): WorldItem | undefined;
+}

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

@@ -0,0 +1,54 @@
+import type { CellCoordinates } from "../../shared/player";
+
+/**
+ * Pipe network queries and enablement at grid cells.
+ *
+ * Available as `sandkit.api.pipes`.
+ *
+ * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.pipes`
+ */
+export namespace pipes {
+  /**
+   * Return true when a pipe occupies the 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.pipes.isAtCell`
+   */
+  export function isAtCell(...args: CellCoordinates): boolean;
+
+  /**
+   * Return true when pipe flow is enabled at the 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.pipes.isEnabledAtCell`
+   */
+  export function isEnabledAtCell(...args: CellCoordinates): boolean;
+
+  /**
+   * Return connected liquid vent cell positions for the pipe 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.pipes.getConnectedVentsAtCell`
+   */
+  export function getConnectedVentsAtCell(...args: CellCoordinates): readonly PipeVentCell[];
+
+  /**
+   * Enable or disable pipe flow at a cell.
+   *
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @param enabled - Desired enabled state.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.pipes.setEnabledAtCell`
+   */
+  export function setEnabledAtCell(...args: [...CellCoordinates, enabled: boolean]): void;
+
+  /** Connected vent cell position. */
+  export interface PipeVentCell {
+    cellX: number;
+    cellY: number;
+    [key: string]: unknown;
+  }
+}

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

@@ -0,0 +1,141 @@
+/**
+ * Player position, movement, inventory, and building unlocks.
+ *
+ * Available as `sandkit.api.player`.
+ *
+ * @module
+ */
+import { shared } from "../../shared";
+
+export namespace player {
+
+  /** Return the player world position. */
+  export import getPositionAtWorld = shared.api.player.getPositionAtWorld;
+  /** Return true when the player overlaps the given cell. */
+  export import isCollidingWithCell = shared.api.player.isCollidingWithCell;
+  /** Return true when the player is within radius of the given cell. */
+  export import isWithinRadiusOfCell = shared.api.player.isWithinRadiusOfCell;
+
+  /**
+   * @deprecated Use {@link getPositionAtWorld} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.player.getPositionAtWorld`
+   */
+  export import getWorldPosition = shared.api.player.getWorldPosition;
+
+  /**
+   * Set the player world position.
+   *
+   * @param worldX - World x position in pixels.
+   * @param worldY - World y position in pixels.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.setPositionAtWorld`
+   */
+  export function setPositionAtWorld(worldX: number, worldY: number): void;
+
+  /**
+   * @deprecated Use {@link setPositionAtWorld} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.player.setPositionAtWorld`
+   */
+  export function setWorldPosition(worldX: number, worldY: number): void;
+
+  /**
+   * Set the player velocity.
+   *
+   * @param velocityX - Horizontal velocity in pixels per second.
+   * @param velocityY - Vertical velocity in pixels per second.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.setVelocity`
+   */
+  export function setVelocity(velocityX: number, velocityY: number): void;
+
+  /**
+   * Set the movement speed multiplier.
+   *
+   * @param multiplier - Speed scale factor (`1` is default walk). `0` freezes movement.
+   * Vanilla Sprint Boost (Shift burst + meter) only runs when this value is exactly `1`.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.setMovementSpeedMultiplier`
+   */
+  export function setMovementSpeedMultiplier(multiplier: number): void;
+
+  /**
+   * Set movement mode to normal or hover.
+   *
+   * @param mode - `"normal"` for default physics, or `"hover"` for hover flight.
+   * @returns True when the mode changes.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.setMovementMode`
+   */
+  export function setMovementMode(mode: 'normal' | 'hover'): boolean;
+
+  /**
+   * Return true when the player is on ground.
+   * Tests solid cells 1 pixel below the hitbox. Do not use `player.onGround`
+   * on the store snapshot — that flag is not updated during play.
+   *
+   * @returns True when the player touches solid ground.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.isOnGround`
+   */
+  export function isOnGround(): boolean;
+
+  /**
+   * Move the player down until ground is found.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.teleportToGround`
+   */
+  export function teleportToGround(): void;
+
+  /**
+   * Return true when the world position has no collision.
+   *
+   * @param worldX - World x position in pixels to test.
+   * @param worldY - World y position in pixels to test.
+   * @returns True when the player hitbox fits at the position.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.isPositionClearAtWorld`
+   */
+  export function isPositionClearAtWorld(worldX: number, worldY: number): boolean;
+
+  /**
+   * @deprecated Use {@link isPositionClearAtWorld} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.player.isPositionClearAtWorld`
+   */
+  export function isWorldPositionClear(worldX: number, worldY: number): boolean;
+
+  /** Player inventory helpers. */
+  export namespace inventory {
+    /**
+     * Add an item to inventory by item id.
+     *
+     * @param itemId - Registered item id string.
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.inventory.addById`
+     */
+    export function addById(itemId: string): void;
+
+    /**
+     * @deprecated Use {@link addById} instead.
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.player.inventory.addById`
+     */
+    export function addFromId(itemId: string): void;
+  }
+
+  /** Player building unlock helpers. */
+  export namespace buildings {
+    /**
+     * Unlock a structure type for building.
+     *
+     * @param structureId - Registered structure id string.
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.buildings.unlockById`
+     */
+    export function unlockById(structureId: string): void;
+
+    /**
+     * @deprecated Use {@link unlockById} instead.
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.player.buildings.unlockById`
+     */
+    export function unlockByType(structureId: string): void;
+
+    /**
+     * Remove a structure unlock from the player.
+     *
+     * @param structureId - Registered structure id string.
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.buildings.removeById`
+     */
+    export function removeById(structureId: string): void;
+  }
+}

package/{sandkit → src/sandkit}/api/rendering.d.ts

@@ -14,6 +14,14 @@ export namespace rendering {
    * @param cellY - Grid cell Y coordinate.
    */
   export function getDrawPositionAtCell(...args: CellCoordinates): Vector2;
+  /**
+   * Return screen draw position for a world-space point.
+   *
+   * @param worldX - World x position in pixels.
+   * @param worldY - World y position in pixels.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.rendering.getDrawPositionAtWorld`
+   */
+  export function getDrawPositionAtWorld(worldX: number, worldY: number): Vector2;
   /** Return cell size and snap grid metrics. */
   export function getGridMetrics(): { cellSize: number; snapGridCellSize: number; };
   /** Return overlay viewport width and height in pixels. */

package/{sandkit → src/sandkit}/api/sandkit-api.d.ts

@@ -14,6 +14,8 @@ export type SandkitApi = {
   authorization: typeof import("./authorization").authorization;
   /** Building mode and placement. */
   building: typeof import("./building").building;
+  /** Structure blueprint serialize and localize helpers. */
+  blueprints: typeof import("./blueprints").blueprints;
   /** Camera position and bounds. */
   camera: typeof import("./camera").camera;
   /** Collector machine helpers. */
@@ -28,6 +30,8 @@ export type SandkitApi = {
   effects: typeof import("./effects").effects;
   /** Element types and cell mutations. */
   elements: typeof import("./elements").elements;
+  /** Entity spawn, capture, and lifecycle. */
+  entities: typeof import("./entities").entities;
   /** Energy network helpers. */
   energy: typeof import("./energy").energy;
   /** Game event subscription. */
@@ -36,9 +40,16 @@ export type SandkitApi = {
   excavation: typeof import("./excavation").excavation;
   /** Fire and burning helpers. */
   fire: typeof import("./fire").fire;
+  /** Factory progression level and process counters. */
+  factory: typeof import("./factory").factory;
+  /** Game session start helpers. */
+  game: typeof import("./game").game;
   /** Game configuration values. */
   gameConfig: typeof import("./gameconfig").gameConfig;
-  /** Grid metrics and cell helpers. */
+  /**
+   * Cell queries, deferred mutations, fog, and redraw.
+   * Official name for the former `api.world` surface.
+   */
   grid: typeof import("./grid").grid;
   /** Intercept and modify hooks. */
   hooks: typeof import("./hooks").hooks;
@@ -56,6 +67,10 @@ export type SandkitApi = {
   mods: typeof import("./mods").mods;
   /** Excavation pattern helpers. */
   patterns: typeof import("./patterns").patterns;
+  /** Pipe network queries and enablement. */
+  pipes: typeof import("./pipes").pipes;
+  /** World pickup spawn, collect, and lookup. */
+  pickups: typeof import("./pickups").pickups;
   /** Player position, movement, and inventory. */
   player: typeof import("./player").player;
   /** Processing recipe registration. */
@@ -112,6 +127,8 @@ export type SandkitApi = {
   utils: typeof import("./utils").utils;
   /** Worker post-update control. */
   workers: typeof import("./workers").workers;
-  /** World cells, fog, redraw, and pickups. */
+  /**
+   * @deprecated Use {@link grid} for cell APIs and {@link pickups} for world items.
+   */
   world: typeof import("./world").world;
 };