@sandustry-modding/types 0.1.0 → 0.3.1

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

@@ -8,24 +8,36 @@ import type { CellCoordinates, Vector2 } from "../../shared/player";
 export namespace player {
   /**
    * Return the player center position in world pixels.
+   *
    * @returns World position as `{ x, y }` in pixels.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.getPositionAtWorld`
+   */
+  export function getPositionAtWorld(): Vector2;
+
+  /**
+   * @deprecated Use {@link getPositionAtWorld} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.player.getPositionAtWorld`
    */
   export function getWorldPosition(): Vector2;
 
   /**
    * Return true when the player hitbox overlaps the cell.
+   *
    * @param cellX - Grid column of the cell.
    * @param cellY - Grid row of the cell.
    * @returns True when the player overlaps the cell.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.isCollidingWithCell`
    */
   export function isCollidingWithCell(...args: CellCoordinates): boolean;
 
   /**
    * Return true when the player is within `radius` cells of the point.
+   *
    * @param cellX - Grid column of the reference cell.
    * @param cellY - Grid row of the reference cell.
    * @param radius - Maximum distance in cells (inclusive).
    * @returns True when the player is inside the radius.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.isWithinRadiusOfCell`
    */
   export function isWithinRadiusOfCell(...args: [...CellCoordinates, radius: number]): boolean;
 }

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

@@ -1,18 +1,20 @@
 /**
  * Shared `sandkit.api.shared` base — cross-thread shared memory buffers.
  *
- * Main thread uses {@link shared.buffers.get} and `create`. Workers extend this
- * with `require` in worker `sandkit.api.shared`.
+ * Main thread uses {@link shared.buffers.get} and {@link shared.buffers.ensure}.
+ * Workers extend this with `require` in worker `sandkit.api.shared`.
  *
  * @internal Base namespace reused by main and worker declarations.
  */
 export namespace shared {
-  /** Named shared memory buffers (`create` / `get` on main; `require` on workers). */
+  /** Named shared memory buffers (`ensure` / `get` on main; `require` on workers). */
   export namespace buffers {
     /**
      * Look up a named shared buffer without creating it.
+     *
      * @param key - Buffer name shared across threads.
      * @returns The typed array, or `undefined` when the buffer does not exist.
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.shared.buffers.get`
      */
     export function get(key: string): SharedArray | undefined;
   }

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

@@ -10,96 +10,134 @@ import type { StructureType as StructureTypeEnum } from "../../sandkit/enums/ind
 export namespace structures {
   /**
    * Invoke a callback for every structure of the given type.
+   *
    * @param structureTypeOrId - Structure type value or string id.
    * @param callback - Called once per matching structure instance.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.structures.forEachOfType`
    */
   export function forEachOfType(structureTypeOrId: StructureRef, callback: (structure: Structure) => void): void;
 
   /**
    * Return the structure at a cell, or null when none.
+   *
    * @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.structures.getAtCell`
    */
   export function getAtCell(...args: CellCoordinates): Structure | null;
 
   /**
    * Return the mod-registered or built-in definition for a structure type.
+   *
    * @param structureType - Structure type value or string id.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.structures.getDefinitionByType`
    */
   export function getDefinitionByType(structureType: StructureRef): any;
 
   /**
    * Map a structure string id to its runtime type value.
+   *
    * @param structureId - Structure string id.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.structures.getTypeById`
+   */
+  export function getTypeById(structureId: StructureId): StructureType;
+
+  /**
+   * @deprecated Use {@link getTypeById} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.structures.getTypeById`
    */
   export function getTypeFromId(structureId: StructureId): StructureType;
 
   /**
    * Return true when a completed structure 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.structures.hasBuiltAtCell`
    */
   export function hasBuiltAtCell(...args: CellCoordinates): boolean;
 
   /**
    * Return true when the structure matches the given id.
+   *
    * @param structure - Structure instance, or null.
    * @param structureId - Structure string id to compare.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.structures.isType`
    */
   export function isType(structure: Structure | null, structureId: StructureId): boolean;
 
   /**
    * Return true when the cell structure matches the given id.
+   *
    * @param cellX - Grid column of the target cell.
    * @param cellY - Grid row of the target cell.
    * @param structureId - Structure string id to compare.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.structures.isTypeAtCell`
    */
   export function isTypeAtCell(...args: [...CellCoordinates, structureId: StructureId]): boolean;
 
   /**
    * Set the spritesheet frame index on a structure instance.
+   *
    * @param structure - Target structure instance.
    * @param index - Spritesheet frame index.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.structures.setSpritesheetIndex`
    */
   export function setSpritesheetIndex(structure: Structure, index: number): void;
 
   /**
    * Set spritesheet frame index for the structure at a cell.
+   *
    * @param cellX - Grid column of the target cell.
    * @param cellY - Grid row of the target cell.
    * @param index - Spritesheet frame index.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.structures.setSpritesheetIndexAtCell`
    */
   export function setSpritesheetIndexAtCell(...args: [...CellCoordinates, index: number]): void;
 
   /**
    * Pick spritesheet index from a value and threshold table on a structure.
+   *
    * @param structure - Target structure instance.
    * @param value - Numeric value mapped through thresholds.
    * @param thresholds - Ascending threshold values.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.structures.setSpritesheetIndexByValue`
    */
   export function setSpritesheetIndexByValue(structure: Structure, value: number, thresholds: number[]): void;
 
   /**
    * Same as {@link setSpritesheetIndexByValue} for the structure at a cell.
+   *
    * @param cellX - Grid column of the target cell.
    * @param cellY - Grid row of the target cell.
    * @param value - Numeric value mapped through thresholds.
    * @param thresholds - Ascending threshold values.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.structures.setSpritesheetIndexByValueAtCell`
    */
   export function setSpritesheetIndexByValueAtCell(...args: [...CellCoordinates, value: number, thresholds: number[]]): void;
 
   /**
    * Push structure field changes to simulation.
+   *
    * @param structure - Structure instance to update.
    * @param options - When `propagateToWorkers` is true, sync to worker threads.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.structures.update`
    */
   export function update(structure: Structure, options?: { propagateToWorkers?: boolean; }): void;
 
   /**
    * Merge partial data onto a structure.
+   *
    * @param structure - Structure instance to update.
    * @param partial - Fields to merge onto `structure.data`.
    * @param options - When `propagateToWorkers` is true, sync to worker threads.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.structures.updateData`
+   */
+  export function updateData(structure: Structure, partial: any, options?: { propagateToWorkers?: boolean; }): void;
+
+  /**
+   * @deprecated Use {@link updateData} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.structures.updateData`
    */
   export function setData(structure: Structure, partial: any, options?: { propagateToWorkers?: boolean; }): void;
 
@@ -107,8 +145,16 @@ export namespace structures {
   export namespace processing {
     /**
      * Return true when processing 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 — Worker entry `api.structures.processing.isEnabledAtCell`
+     */
+    export function isEnabledAtCell(...args: CellCoordinates): boolean;
+
+    /**
+     * @deprecated Use {@link isEnabledAtCell} instead.
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.structures.processing.isEnabledAtCell`
      */
     export function isEnabledAt(...args: CellCoordinates): boolean;
   }

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

@@ -0,0 +1,231 @@
+import type { CellCoordinates } from "../../shared/player";
+import type { CellId, LooseString, TaggedNumber } from "../nominal";
+import type { CellType as CellTypeEnum } from "../../sandkit/enums/index";
+import type { elements } from "./elements";
+
+/**
+ * Shared `sandkit.api.terrains` base — terrain type lookup and cell mutation.
+ *
+ * Worker-entry mutations are immediate. Main thread defers matching helpers in
+ * `sandkit.api.terrains`.
+ *
+ * @internal Base namespace reused by main and worker declarations.
+ */
+export namespace terrains {
+  /**
+   * Terrain definition shape for {@link register} and {@link getDefinitionByType}.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.terrains.register`
+   */
+  export interface TerrainDefinition {
+    /** Unique mod-scoped terrain id. */
+    id: string;
+    /** i18n key for the terrain display name. */
+    nameKey?: string;
+    /** Default terrain hit points. */
+    hp?: number;
+    /** Material id used for rendering. Must be > obstacle breakpoint and < 150. */
+    materialId?: number;
+    /** UI/meta color as 0xRRGGBB. */
+    metaColor?: number;
+    /** Base terrain color as HSL components. */
+    colorHSL?: [number, number, number];
+    /** Tool item ids required to excavate this terrain. */
+    excavationRequirements?: readonly string[];
+    /** Tooltip interactions shown for this terrain. */
+    interactions?: readonly { kind: string; [key: string]: unknown }[];
+    /** Default element drop when the terrain is destroyed. */
+    output?: {
+      elementType: elements.ElementType;
+      chance: number;
+    };
+    [key: string]: unknown;
+  }
+
+  /**
+   * Terrain cell data returned by {@link getDataAtCell}.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.terrains.getDataAtCell`
+   */
+  export interface TerrainDataAtCell {
+    /** Numeric terrain cell type. */
+    cellType: TerrainType;
+    /**
+     * Current hit points, or null when the terrain has no hp.
+     *
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.terrains.getDataAtCell`
+     */
+    hitPoints: number | null;
+    /**
+     * @deprecated Use {@link hitPoints} instead.
+     * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `result.hitPoints`
+     */
+    hp?: number | null;
+  }
+
+  /**
+   * Return the mod string id for a numeric terrain type.
+   *
+   * @param terrainType - Numeric terrain cell type.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.terrains.getIdByType`
+   */
+  export function getIdByType(terrainType: TerrainType): TerrainId;
+
+  /**
+   * Resolve a terrain string id to a numeric cell type.
+   *
+   * @param terrainId - Mod-registered or built-in terrain id.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.terrains.getTypeById`
+   */
+  export function getTypeById(terrainId: TerrainId): TerrainType;
+
+  /**
+   * @deprecated Use {@link getTypeById} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.terrains.getTypeById`
+   */
+  export function getTypeFromId(terrainId: TerrainId): TerrainType;
+
+  /**
+   * Look up the definition for a terrain type.
+   *
+   * @param terrainType - Numeric terrain cell type.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.terrains.getDefinitionByType`
+   */
+  export function getDefinitionByType(terrainType: TerrainType): TerrainDefinition | undefined;
+
+  /**
+   * Return the terrain cell type at a cell, or null when none.
+   *
+   * @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.terrains.getTypeAtCell`
+   */
+  export function getTypeAtCell(...args: CellCoordinates): TerrainType | null;
+
+  /**
+   * Return terrain cell type and hit points at a cell.
+   *
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @returns Cell type and hit points, or null when the cell is not terrain.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.terrains.getDataAtCell`
+   */
+  export function getDataAtCell(...args: CellCoordinates): TerrainDataAtCell | null;
+
+  /**
+   * Return true when any terrain 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.terrains.isAtCell`
+   */
+  export function isAtCell(...args: CellCoordinates): boolean;
+
+  /**
+   * Return true when the cell terrain matches the given id.
+   *
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @param terrainId - Terrain string id to compare.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.terrains.isTypeAtCell`
+   */
+  export function isTypeAtCell(...args: [...CellCoordinates, terrainId: TerrainId]): boolean;
+
+  /**
+   * Return true when a packed cell id refers to terrain.
+   *
+   * @param cellId - Packed cell id from {@link world.getCellIdAtCell}.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.terrains.isCellIdTerrain`
+   */
+  export function isCellIdTerrain(cellId: CellId): boolean;
+
+  /**
+   * Apply damage to terrain at a cell.
+   *
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @param damage - Damage amount to apply.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.terrains.damageAtCell`
+   */
+  export function damageAtCell(...args: [...CellCoordinates, damage: number]): void;
+
+  /**
+   * Place terrain at an empty cell. Worker-entry writes are immediate.
+   *
+   * @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 — Worker entry `api.terrains.createAtCell`
+   */
+  export function createAtCell(...args: [...CellCoordinates, terrainTypeOrId: TerrainRef, options?: TerrainMutationOptions]): void;
+
+  /**
+   * Replace existing terrain at a cell. Worker-entry writes are immediate.
+   *
+   * @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 — Worker entry `api.terrains.replaceAtCell`
+   */
+  export function replaceAtCell(...args: [...CellCoordinates, terrainTypeOrId: TerrainRef, options?: TerrainMutationOptions]): void;
+
+  /**
+   * Remove terrain from a cell. Worker-entry writes are immediate.
+   *
+   * @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 — Worker entry `api.terrains.removeAtCell`
+   */
+  export function removeAtCell(...args: [...CellCoordinates, options?: TerrainMutationOptions]): void;
+
+  /**
+   * Set terrain hit points at a cell. Worker-entry writes are immediate.
+   *
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @param hitPoints - New hit point value.
+   * @returns True when hit points changed or the terrain was removed.
+   * @see https://sandustry.com/sandkit.html#mutations-heading Official Sandkit API — Worker entry `api.terrains.setHitPointsAtCell`
+   */
+  export function setHitPointsAtCell(...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 setHpAtCell(...args: [...CellCoordinates, hitPoints: number]): boolean;
+
+  /**
+   * Options for terrain create, replace, or remove calls.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.terrains.createAtCell`
+   */
+  export interface TerrainMutationOptions {
+    /** Skip shadow updates around the changed cell. */
+    skipShadow?: boolean;
+  }
+
+  /**
+   * Numeric terrain / {@link CellTypeEnum} handle.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.terrains`
+   */
+  export type TerrainType = CellTypeEnum | TaggedNumber<"terrainType">;
+
+  /**
+   * Mod or built-in terrain string id.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.terrains`
+   */
+  export type TerrainId = LooseString<never>;
+
+  /**
+   * Type handle or string id accepted by mutation helpers.
+   *
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.terrains`
+   */
+  export type TerrainRef = TerrainType | TerrainId;
+}

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

@@ -0,0 +1,43 @@
+import { grid as gridNs } from "./grid";
+
+/**
+ * Shared `sandkit.api.world` base — deprecated alias of {@link grid}.
+ *
+ * Cell queries, excavation, and dimensions are re-exported from {@link grid} so
+ * existing `shared.api.world` imports keep working.
+ *
+ * @deprecated Use {@link grid} instead.
+ * @internal Base namespace reused by main and worker declarations.
+ */
+export namespace world {
+  /**
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.getCellIdAtCell`
+   */
+  export import getCellIdAtCell = gridNs.getCellIdAtCell;
+  /**
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.isCellEmptyAtCell`
+   */
+  export import isCellEmptyAtCell = gridNs.isCellEmptyAtCell;
+  /**
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.isTerrainAtCell`
+   */
+  export import isTerrainAtCell = gridNs.isTerrainAtCell;
+  /**
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.reportActivityAtCell`
+   */
+  export import reportActivityAtCell = gridNs.reportActivityAtCell;
+  /**
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.excavateAtCell`
+   */
+  export import excavateAtCell = gridNs.excavateAtCell;
+  /**
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.getDimensions`
+   */
+  export import getDimensions = gridNs.getDimensions;
+  /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.ExcavateOptions` */
+  export import ExcavateOptions = gridNs.ExcavateOptions;
+  /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.CellId` */
+  export import CellId = gridNs.CellId;
+  /** @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid.GridDimensions` */
+  export import GridDimensions = gridNs.GridDimensions;
+}

package/{shared → src/shared}/index.d.ts

@@ -1,5 +1,6 @@
 import { ui as uiNs } from "./api/ui";
 import { player as playerNs } from "./api/player";
+import { grid as gridNs } from "./api/grid";
 import { world as worldNs } from "./api/world";
 import { terrains as terrainsNs } from "./api/terrains";
 import { structures as structuresNs } from "./api/structures";
@@ -13,6 +14,7 @@ export namespace shared {
   export namespace api {
     export import ui = uiNs;
     export import player = playerNs;
+    export import grid = gridNs;
     export import world = worldNs;
     export import terrains = terrainsNs;
     export import structures = structuresNs;

package/src/worker/api/effects.d.ts

@@ -0,0 +1,52 @@
+import { shared } from "../../shared";
+
+/**
+ * Worker-thread `sandkit.api.effects` — world-space visual effects on workers.
+ *
+ * Temporary lights live under {@link lights.temporary}, not here.
+ *
+ * @internal Worker-only surface; main thread exposes additional effect helpers.
+ */
+export namespace effects {
+  /** Options for generic screen effects. */
+  export import EffectOptions = shared.api.effects.EffectOptions;
+  /** Options for particle effects. */
+  export import ParticleEffectOptions = shared.api.effects.ParticleEffectOptions;
+
+  /**
+   * Spawn a named screen-space or world effect.
+   *
+   * @param effectId - Registered effect id.
+   * @param worldX - World x position in pixels.
+   * @param worldY - World y position in pixels.
+   * @param options - Duration, radius, and intensity settings.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Worker entry `api.effects.createAtWorld`
+   */
+  export function createAtWorld(
+    effectId: string,
+    worldX: number,
+    worldY: number,
+    options?: EffectOptions,
+  ): void;
+
+  /**
+   * @deprecated Use {@link createAtWorld} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.effects.createAtWorld`
+   */
+  export function createEffectAtWorld(
+    effectId: string,
+    worldX: number,
+    worldY: number,
+    options?: EffectOptions,
+  ): void;
+
+  /**
+   * Emit particles at world coordinates.
+   *
+   * @param worldX - World x position in pixels.
+   * @param worldY - World y position in pixels.
+   * @param options - Count, velocity, colour, and lifetime settings.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Worker entry `api.effects.createParticlesAtWorld`
+   */
+  export import createParticlesAtWorld = shared.api.effects.createParticlesAtWorld;
+}