@sandustry-modding/types 0.1.0 → 0.3.0

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

@@ -0,0 +1,147 @@
+/**
+ * Terrain registration, queries, and deferred cell mutations.
+ *
+ * Available as `sandkit.api.terrains`.
+ *
+ * @module
+ */
+import { CellCoordinates } from '../../shared/player';
+import { shared } from '../../shared';
+import type { elements } from './elements';
+
+export namespace terrains {
+
+  /** Return the mod string id for a numeric terrain type. */
+  export import getIdByType = shared.api.terrains.getIdByType;
+  /** Resolve a terrain string id to its cell type number. */
+  export import getTypeById = shared.api.terrains.getTypeById;
+  /**
+   * @deprecated Use {@link getTypeById} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.terrains.getTypeById`
+   */
+  export import getTypeFromId = shared.api.terrains.getTypeFromId;
+  /** Look up the definition for a terrain type. */
+  export import getDefinitionByType = shared.api.terrains.getDefinitionByType;
+  /** Return terrain cell type at a cell, or null. */
+  export import getTypeAtCell = shared.api.terrains.getTypeAtCell;
+  /** Return terrain data at a cell, or null. */
+  export import getDataAtCell = shared.api.terrains.getDataAtCell;
+  /** Return true when any terrain exists at the cell. */
+  export import isAtCell = shared.api.terrains.isAtCell;
+  /** Return true when terrain at the cell matches a string id. */
+  export import isTypeAtCell = shared.api.terrains.isTypeAtCell;
+  /** Return true when a cell id represents terrain. */
+  export import isCellIdTerrain = shared.api.terrains.isCellIdTerrain;
+  /** Apply damage to terrain at a cell. */
+  export import damageAtCell = shared.api.terrains.damageAtCell;
+  /** Options for terrain create, replace, and remove calls. */
+  export import TerrainMutationOptions = shared.api.terrains.TerrainMutationOptions;
+  /** Numeric terrain cell type handle. */
+  export import TerrainType = shared.api.terrains.TerrainType;
+  /** Mod or built-in terrain string id. */
+  export import TerrainId = shared.api.terrains.TerrainId;
+  /** Type handle or string id accepted by mutation helpers. */
+  export import TerrainRef = shared.api.terrains.TerrainRef;
+  /** Terrain cell data returned by {@link getDataAtCell}. */
+  export import TerrainDataAtCell = shared.api.terrains.TerrainDataAtCell;
+
+  /**
+   * Terrain definition shape with typed element interactions.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.terrains.register`
+   */
+  export interface TerrainDefinition extends Omit<shared.api.terrains.TerrainDefinition, "interactions"> {
+    /** Tooltip interactions shown for this terrain. */
+    interactions?: readonly elements.Interaction[];
+  }
+
+  /**
+   * Register a new terrain definition.
+   *
+   * @param definition - Terrain definition to register.
+   * @returns Object with the assigned `cellType`.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.terrains.register`
+   */
+  export function register(definition: TerrainDefinition): { cellType: TerrainType; };
+
+  /**
+   * Patch fields on an existing terrain definition.
+   *
+   * @param cellTypeOrId - Numeric cell type or terrain string id.
+   * @param partial - Fields to merge onto the definition.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.terrains.updateDefinition`
+   */
+  export function updateDefinition(cellTypeOrId: TerrainRef, partial: Partial<TerrainDefinition>): void;
+
+  /**
+   * Create terrain at a cell. Main-entry writes are deferred; reads see the old grid.
+   *
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @param terrainTypeOrId - Numeric cell type or terrain string id.
+   * @param options - Optional mutation flags.
+   * @see https://sandustry.com/sandkit.html#mutations-heading Official Sandkit API — Main entry `api.terrains.createAtCell`
+   */
+  export function createAtCell(...args: [...CellCoordinates, terrainTypeOrId: TerrainRef, options?: TerrainMutationOptions]): void;
+
+  /**
+   * @deprecated Use {@link createAtCell} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.terrains.createAtCell`
+   */
+  export function createAtCellWhenIdle(...args: [...CellCoordinates, terrainTypeOrId: TerrainRef, options?: TerrainMutationOptions]): void;
+
+  /**
+   * Replace terrain at a cell. Main-entry writes are deferred; reads see the old grid.
+   *
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @param terrainTypeOrId - Numeric cell type or terrain string id.
+   * @param options - Optional mutation flags.
+   * @see https://sandustry.com/sandkit.html#mutations-heading Official Sandkit API — Main entry `api.terrains.replaceAtCell`
+   */
+  export function replaceAtCell(...args: [...CellCoordinates, terrainTypeOrId: TerrainRef, options?: TerrainMutationOptions]): void;
+
+  /**
+   * @deprecated Use {@link replaceAtCell} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.terrains.replaceAtCell`
+   */
+  export function replaceAtCellWhenIdle(...args: [...CellCoordinates, terrainTypeOrId: TerrainRef, options?: TerrainMutationOptions]): void;
+
+  /**
+   * Remove terrain at a cell. Main-entry writes are deferred; reads see the old grid.
+   *
+   * @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#mutations-heading Official Sandkit API — Main entry `api.terrains.removeAtCell`
+   */
+  export function removeAtCell(...args: [...CellCoordinates, options?: TerrainMutationOptions]): void;
+
+  /**
+   * @deprecated Use {@link removeAtCell} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.terrains.removeAtCell`
+   */
+  export function removeAtCellWhenIdle(...args: [...CellCoordinates, options?: TerrainMutationOptions]): void;
+
+  /**
+   * Set terrain hit points at a cell. Main-entry writes are deferred; reads see the old grid.
+   *
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @param hitPoints - New hit point value.
+   * @see https://sandustry.com/sandkit.html#mutations-heading Official Sandkit API — Main entry `api.terrains.setHitPointsAtCell`
+   */
+  export function setHitPointsAtCell(...args: [...CellCoordinates, hitPoints: number]): void;
+
+  /**
+   * @deprecated Use {@link setHitPointsAtCell} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.terrains.setHitPointsAtCell`
+   */
+  export function setHpAtCell(...args: [...CellCoordinates, hitPoints: number]): boolean;
+
+  /**
+   * @deprecated Use {@link setHitPointsAtCell} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.terrains.setHitPointsAtCell`
+   */
+  export function setHpAtCellWhenIdle(...args: [...CellCoordinates, hitPoints: number]): void;
+}

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

@@ -35,6 +35,15 @@ export namespace upgrades {
    * @param upgradeId - Upgrade id within the item.
    */
   export function getAvailableLevelById(itemId: string, upgradeId: string): number;
+  /**
+   * Set the purchased level for an upgrade.
+   *
+   * @param itemId - Parent item id.
+   * @param upgradeId - Upgrade id within the item.
+   * @param level - Level to set.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.upgrades.setLevelById`
+   */
+  export function setLevelById(itemId: string, upgradeId: string, level: number): void;
 
   /** Upgrade definition registered for an item. */
   export interface UpgradeDefinition {

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

@@ -10,26 +10,43 @@ import type { Vector2 } from "../../shared/player";
 export namespace utils {
   /**
    * Return distance between two points.
+   *
    * @param pointA - First point.
    * @param pointB - Second point.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.utils.getDistance`
    */
   export function getDistance(pointA: Vector2, pointB: Vector2): number;
+
   /**
    * Return normalized direction from point A to point B.
+   *
    * @param pointA - Origin point.
    * @param pointB - Target point.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.utils.getDirection`
    */
   export function getDirection(pointA: Vector2, pointB: Vector2): Vector2;
+
   /**
    * Return angle in radians from point A to point B.
+   *
    * @param pointA - Origin point.
    * @param pointB - Target point.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.utils.getAngle`
    */
   export function getAngle(pointA: Vector2, pointB: Vector2): number;
+
   /**
    * Return grid cells along a line between two points.
-   * @param pointA - Line start in cell or world coordinates.
-   * @param pointB - Line end in cell or world coordinates.
+   *
+   * @param pointA - Line start in cell coordinates.
+   * @param pointB - Line end in cell coordinates.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.utils.getCoordinatesBetweenCells`
+   */
+  export function getCoordinatesBetweenCells(pointA: Vector2, pointB: Vector2): Vector2[];
+
+  /**
+   * @deprecated Use {@link getCoordinatesBetweenCells} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.utils.getCoordinatesBetweenCells`
    */
   export function getCoordinatesBetweenPoints(pointA: Vector2, pointB: Vector2): Vector2[];
 }

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

@@ -0,0 +1,105 @@
+/**
+ * World cell queries, excavation, fog, redraw, and pickups.
+ *
+ * @deprecated Use {@link grid} and {@link pickups} instead.
+ *
+ * Available as `sandkit.api.world`.
+ *
+ * @module
+ */
+import { CellCoordinates } from "../../shared/player";
+import { grid } from "./grid";
+import { pickups as pickupsNs } from "./pickups";
+
+/**
+ * @deprecated Use {@link grid} instead.
+ * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid`
+ */
+export namespace world {
+  /**
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.getCellIdAtCell`
+   */
+  export import getCellIdAtCell = grid.getCellIdAtCell;
+  /**
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.isCellEmptyAtCell`
+   */
+  export import isCellEmptyAtCell = grid.isCellEmptyAtCell;
+  /**
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.isTerrainAtCell`
+   */
+  export import isTerrainAtCell = grid.isTerrainAtCell;
+  /**
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.reportActivityAtCell`
+   */
+  export import reportActivityAtCell = grid.reportActivityAtCell;
+  /**
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.excavateAtCell`
+   */
+  export import excavateAtCell = grid.excavateAtCell;
+  /**
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.getDimensions`
+   */
+  export import getDimensions = grid.getDimensions;
+  /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.ExcavateOptions` */
+  export import ExcavateOptions = grid.ExcavateOptions;
+  /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.CellId` */
+  export import CellId = grid.CellId;
+  /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.GridDimensions` */
+  export import GridDimensions = grid.GridDimensions;
+
+  /**
+   * 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 — deprecated alias of `api.grid.revealFogAtCell`
+   */
+  export import revealFogAtCell = grid.revealFogAtCell;
+
+  /**
+   * @deprecated Use {@link grid.mutate} instead.
+   * @see https://sandustry.com/sandkit.html#mutations-heading
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.mutate`
+   */
+  export function runWhenSimulationIdle(callback: () => void): void;
+
+  /**
+   * @deprecated Use {@link grid.redrawAroundCell} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.redrawAroundCell`
+   */
+  export function redrawAroundCellWhenIdle(...args: [...CellCoordinates, range: number]): void;
+
+  /**
+   * @deprecated Use {@link pickups} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups`
+   */
+  export namespace pickups {
+    /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.spawnAtWorld` */
+    export import spawnAtWorld = pickupsNs.spawnAtWorld;
+    /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.remove` */
+    export import destroy = pickupsNs.destroy;
+    /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.pickUp` */
+    export import pickUp = pickupsNs.pickUp;
+    /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.getAll` */
+    export import getAll = pickupsNs.getAll;
+    /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.getById` */
+    export import getById = pickupsNs.getById;
+    /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.remove` */
+    export import remove = pickupsNs.remove;
+  }
+
+  /**
+   * @deprecated Use {@link pickups.PickupType} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.PickupType`
+   */
+  export import WorldItemType = pickupsNs.WorldItemType;
+
+  /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.PickupType` */
+  export import PickupType = pickupsNs.PickupType;
+
+  /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.WorldItemLight` */
+  export import WorldItemLight = pickupsNs.WorldItemLight;
+
+  /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.WorldItem` */
+  export import WorldItem = pickupsNs.WorldItem;
+}

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

@@ -410,6 +410,16 @@ export enum TechStatus {
 }
 
 /** Pickups and interactable world items. */
+export enum PickupType {
+  Artifact = 1,
+  GlyphKey = 2,
+  Stratacore = 3,
+  Orb = 4,
+}
+
+/**
+ * @deprecated Use {@link PickupType} instead.
+ */
 export enum WorldItemType {
   Artifact = 1,
   GlyphKey = 2,
@@ -440,5 +450,9 @@ export type SandkitEnums = {
   StructureType: typeof StructureType;
   Tech: typeof Tech;
   TechStatus: typeof TechStatus;
+  PickupType: typeof PickupType;
+  /**
+   * @deprecated Use {@link PickupType} instead.
+   */
   WorldItemType: typeof WorldItemType;
 };

package/{shared → src/shared}/api/elements.d.ts

@@ -6,23 +6,38 @@ import type { CellId, LooseString, TaggedNumber } from "../nominal";
  * Shared `sandkit.api.elements` base — element reads and definitions.
  *
  * Workers add direct mutation helpers on top of this shape. Main thread adds
- * idle-scheduled mutations and registration APIs.
+ * deferred grid mutations and registration APIs.
  *
  * @internal Base namespace reused by main and worker declarations.
  */
 export namespace elements {
   /**
    * Numeric element type handle.
-   * Built-in {@link ElementTypeEnum} values autocomplete; `getTypeFromId` returns a tagged handle.
+   * Built-in {@link ElementTypeEnum} values autocomplete; {@link getTypeById} returns a tagged handle.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.elements`
    */
   export type ElementType = ElementTypeEnum | TaggedNumber<"elementType">;
 
-  /** Mod or built-in element string id. */
+  /**
+   * Mod or built-in element string id.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.elements`
+   */
   export type ElementId = LooseString<never>;
-  /** Type handle or string id accepted by lookup helpers. */
+
+  /**
+   * Type handle or string id accepted by lookup helpers.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.elements`
+   */
   export type ElementRef = ElementType | ElementId;
 
-  /** Physical behaviour category for an element. */
+  /**
+   * Physical behaviour category for an element.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.elements`
+   */
   export enum MatterType {
     Solid = 1,
     Liquid = 2,
@@ -34,7 +49,11 @@ export namespace elements {
     Powder = 8,
   }
 
-  /** Mod-registered element definition snapshot. */
+  /**
+   * Mod-registered element definition snapshot.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.elements.register`
+   */
   export type ElementDefinition = {
     id: string,
     nameKey: string,
@@ -53,13 +72,26 @@ export namespace elements {
     getExtraProps?: () => { data: Record<PropertyKey, any> }
   };
 
-  /** Options for {@link createAtCell}, replace, and idle create helpers. */
+  /**
+   * Options for {@link createAtCell}, replace, and related create helpers.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.elements.createAtCell`
+   */
   export interface ElementCreateOptions {
     /** Initial element data bag. */
     data?: Record<string, unknown>;
     /** Override element density. */
     density?: number;
-    /** Set both max and remaining duration. */
+    /**
+     * Set both max and remaining duration in simulation ticks.
+     *
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.elements.createAtCell`
+     */
+    durationTicks?: number;
+    /**
+     * @deprecated Use {@link durationTicks} instead.
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `options.durationTicks`
+     */
     duration?: number;
     /** Override free-fall state on spawn. */
     isFreeFalling?: boolean;
@@ -78,85 +110,125 @@ export namespace elements {
     skipCollectorCheck?: boolean;
   }
 
-  /** Options for element removal helpers. */
+  /**
+   * Options for element removal helpers.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.elements.removeAtCell`
+   */
   export interface ElementRemovalOptions {
     /** Skip collector accounting when removing the element. */
     skipCollectorCheck?: boolean;
   }
 
+  /**
+   * Return the mod string id for a numeric element type.
+   *
+   * @param elementType - Numeric element type.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.elements.getIdByType`
+   */
+  export function getIdByType(elementType: ElementType): ElementId;
+
   /**
    * Resolve a mod element string id to a type handle.
+   *
    * @param elementId - Mod-registered element id.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.elements.getTypeById`
+   */
+  export function getTypeById(elementId: ElementId): ElementType;
+
+  /**
+   * @deprecated Use {@link getTypeById} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.elements.getTypeById`
    */
   export function getTypeFromId(elementId: ElementId): ElementType;
 
   /**
    * Look up the definition for a type handle.
+   *
    * @param elementType - Numeric element type.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.elements.getDefinitionByType`
    */
   export function getDefinitionByType(elementType: ElementType): ElementDefinition | undefined;
 
   /**
    * Return the raw element type at a cell (may differ from resolved type).
+   *
    * @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.elements.getTypeAtCell`
    */
   export function getTypeAtCell(...args: CellCoordinates): ElementType | null;
 
   /**
    * Return the resolved element type after overlays and particles.
+   *
    * @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.elements.getResolvedTypeAtCell`
    */
   export function getResolvedTypeAtCell(...args: CellCoordinates): ElementType | null;
 
   /**
    * Return the resolved element type from a packed cell id.
+   *
    * @param cellId - Packed cell id from {@link world.getCellIdAtCell}.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.elements.getResolvedTypeFromCellId`
    */
   export function getResolvedTypeFromCellId(cellId: CellId): ElementType | null;
 
   /**
    * Return element index, particle flag, and ids 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.elements.getInfoAtCell`
    */
   export function getInfoAtCell(...args: CellCoordinates): { elementType: ElementType; isParticle: boolean; cellId: CellId; elementIndex: number; } | null;
 
   /**
    * Return the matter category at a cell, or null when empty.
+   *
    * @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.elements.getMatterTypeAtCell`
    */
   export function getMatterTypeAtCell(...args: CellCoordinates): MatterType | null;
 
   /**
-   * Return true when the cell holds the given element type.
+   * Return true when the cell holds the given element type or id.
+   *
    * @param cellX - Grid column of the target cell.
    * @param cellY - Grid row of the target cell.
-   * @param elementType - Element type to compare.
+   * @param elementTypeOrId - Numeric type or string id.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.elements.isTypeAtCell`
    */
-  export function isTypeAtCell(...args: [...CellCoordinates, elementType: ElementType]): boolean;
+  export function isTypeAtCell(...args: [...CellCoordinates, elementTypeOrId: ElementRef]): boolean;
 
   /**
    * Return true when the element at the cell is falling.
+   *
    * @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.elements.isFreeFallingAtCell`
    */
   export function isFreeFallingAtCell(...args: CellCoordinates): boolean;
 
   /**
    * Return per-cell velocity for moving elements.
+   *
    * @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.elements.getVelocityAtCell`
    */
   export function getVelocityAtCell(...args: CellCoordinates): { x: number; y: number; } | null;
 
   /**
    * Read element data field 1–4 at a cell.
+   *
    * @param cellX - Grid column of the target cell.
    * @param cellY - Grid row of the target cell.
    * @param fieldNumber - Data field index (1–4).
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.elements.getDataFieldAtCell`
    */
   export function getDataFieldAtCell(...args: [...CellCoordinates, fieldNumber: 1 | 2 | 3 | 4]): number | null;
 }

package/{shared/api/world.d.ts → src/shared/api/grid.d.ts}

@@ -2,55 +2,81 @@ import type { CellCoordinates, Vector2 } from "../../shared/player";
 import type { CellId as PackedCellId } from "../nominal";
 
 /**
- * Shared `sandkit.api.world` base — cell and terrain queries plus excavation.
+ * Shared `sandkit.api.grid` base — cell queries, excavation, and dimensions.
  *
- * Main thread adds idle scheduling and fog helpers on top of this shape.
+ * Main thread adds deferred mutations, fog, redraw, and iteration helpers on
+ * top of this shape.
  *
  * @internal Base namespace reused by main and worker declarations.
  */
-export namespace world {
+export namespace grid {
   /**
    * Return the packed cell id at grid coordinates.
+   *
    * @param cellX - Grid column of the target cell.
    * @param cellY - Grid row of the target cell.
    * @returns Packed cell id for the cell.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.getCellIdAtCell` / Worker entry `api.grid.getCellIdAtCell`
    */
   export function getCellIdAtCell(...args: CellCoordinates): CellId;
 
   /**
    * Return true when the cell has no element or terrain content.
+   *
    * @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.isCellEmptyAtCell` / Worker entry `api.grid.isCellEmptyAtCell`
    */
   export function isCellEmptyAtCell(...args: CellCoordinates): boolean;
 
   /**
    * Return true when the cell holds terrain (not an element).
+   *
    * @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.isTerrainAtCell` / Worker entry `api.grid.isTerrainAtCell`
    */
   export function isTerrainAtCell(...args: CellCoordinates): boolean;
 
   /**
    * Mark the cell active for simulation this tick.
+   *
    * @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.reportActivityAtCell` / Worker entry `api.grid.reportActivityAtCell`
    */
   export function reportActivityAtCell(...args: CellCoordinates): void;
 
   /**
    * Apply excavation damage and eject velocity at a cell.
+   *
    * @param cellX - Grid column of the target cell.
    * @param cellY - Grid row of the target cell.
    * @param outVelocity - Ejection velocity written into this vector.
    * @param damage - Damage applied to terrain in the pattern.
    * @param options - Optional excavation source flags.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.excavateAtCell` / Worker entry `api.grid.excavateAtCell`
    */
   export function excavateAtCell(...args: [...CellCoordinates, outVelocity: Vector2, damage: number, options?: ExcavateOptions]): void;
 
+  /**
+   * Return the world grid size in cells.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.getDimensions` / Worker entry `api.grid.getDimensions`
+   */
+  export function getDimensions(): GridDimensions;
+
   /** Packed cell id from {@link getCellIdAtCell}. */
   export type CellId = PackedCellId;
 
+  /** World grid width and height in cells. */
+  export interface GridDimensions {
+    /** Grid width in cells. */
+    widthCells: number;
+    /** Grid height in cells. */
+    heightCells: number;
+  }
+
   /** Flags that control how {@link excavateAtCell} resolves damage and drops. */
   export interface ExcavateOptions {
     /** Treat the dig as gun fire for terrain resistance checks. */