@sandustry-modding/types 0.3.1 → 0.4.0

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

@@ -5,7 +5,7 @@ import type { terrains } from "../../shared/api/terrains";
  * `sandkit.api.excavation` — register custom excavation tool dig profiles.
  * Main thread only.
  *
- * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.excavation`
+ * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
  */
 export namespace excavation {
   /**
@@ -13,7 +13,36 @@ export namespace excavation {
    *
    * @param id - Unique profile id (1–128 chars: letters, numbers, `.`, `_`, `:`, `-`).
    * @param definition - Pattern, power, terrain rules, and profile options.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.excavation.registerProfile`
+   *
+   * @example
+   * ```ts
+   * const profileId = "example:voidGun";
+   * const duneType = api.terrains.getTypeById("dune");
+   * const sandType = api.elements.getTypeById("sand");
+   *
+   * api.excavation.registerProfile(profileId, {
+   *   power: 8,
+   *   terrainRules: [
+   *     {
+   *       cellType: duneType,
+   *       outputElementType: sandType,
+   *     },
+   *   ],
+   * });
+   *
+   * api.hooks.modify("excavation:prepare", (args) => {
+   *   if (
+   *     args.sourceKind !== "projectile"
+   *     || args.sourceId !== "implosionGun"
+   *   ) {
+   *     return;
+   *   }
+   *
+   *   args.profileId = profileId;
+   * });
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function registerProfile(id: string, definition: ExcavationProfileDefinitionV1): void;
 
@@ -47,7 +76,8 @@ export namespace excavation {
     cellType: terrains.TerrainRef;
     /**
      * @deprecated Use {@link cellType} instead.
-     * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias in `api.excavation.registerProfile` terrain rules
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     terrainType?: terrains.TerrainRef;
     /** Damage applied when this rule matches. */

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

@@ -3,13 +3,13 @@
  *
  * Available as `sandkit.api.factory`.
  *
- * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.factory`
+ * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
  */
 export namespace factory {
   /**
    * Return the current factory level.
    *
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.factory.getLevel`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getLevel(): number;
 
@@ -17,7 +17,8 @@ export namespace factory {
    * 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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getProcessCount(processId: FactoryProcessId): number;
 
@@ -25,7 +26,8 @@ export namespace factory {
    * 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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getProcessRate(processId: FactoryProcessId): number;
 

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

@@ -4,7 +4,7 @@ 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`
+ * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
  */
 export namespace fire {
   /**
@@ -12,7 +12,8 @@ export namespace fire {
    *
    * @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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function canBurnElementAtCell(...args: CellCoordinates): boolean;
 
@@ -21,13 +22,15 @@ export namespace fire {
    *
    * @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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#mutations-heading)
    */
   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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#mutations-heading)
    */
   export function burnElementAtCellWhenIdle(...args: CellCoordinates): void;
 }

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

@@ -3,14 +3,20 @@
  *
  * Available as `sandkit.api.game`.
  *
- * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.game`
+ * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
  */
 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`
+   *
+   * @example
+   * ```ts
+   * api.game.start({ skipIntro: true });
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function start(options?: GameStartOptions): void;
 

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

@@ -8,38 +8,53 @@ import type { terrains } from "./terrains";
  *
  * Main thread only.
  *
- * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid`
+ * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
  */
 export namespace grid {
   /**
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.getCellIdAtCell`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export import getCellIdAtCell = shared.api.grid.getCellIdAtCell;
   /**
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.isCellEmptyAtCell`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export import isCellEmptyAtCell = shared.api.grid.isCellEmptyAtCell;
   /**
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.isTerrainAtCell`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export import isTerrainAtCell = shared.api.grid.isTerrainAtCell;
   /**
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.reportActivityAtCell`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export import reportActivityAtCell = shared.api.grid.reportActivityAtCell;
   /**
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.excavateAtCell`
+   * @example
+   * ```ts
+   * api.grid.excavateAtCell(
+   *   cellX,
+   *   cellY,
+   *   { x: 0, y: -120 },
+   *   25,
+   * );
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export import excavateAtCell = shared.api.grid.excavateAtCell;
   /**
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.getDimensions`
+   * @example Main entry
+   * ```ts
+   * const { widthCells, heightCells } = api.grid.getDimensions();
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export import getDimensions = shared.api.grid.getDimensions;
-  /** @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.ExcavateOptions` */
+  /** @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading) */
   export import ExcavateOptions = shared.api.grid.ExcavateOptions;
-  /** @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.CellId` */
+  /** @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading) */
   export import CellId = shared.api.grid.CellId;
-  /** @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.grid.GridDimensions` */
+  /** @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading) */
   export import GridDimensions = shared.api.grid.GridDimensions;
 
   /**
@@ -47,8 +62,31 @@ export namespace grid {
    * 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`
+   *
+   * @example Deferred main-thread mutations
+   * ```ts
+   * api.grid.mutate((writer) => {
+   *   if (api.terrains.isTypeAtCell(cellX, cellY, "ice")) {
+   *     writer.elements.replaceAtCell(cellX, cellY, "water");
+   *   }
+   * });
+   * ```
+   *
+   * @example
+   * ```ts
+   * const waterType = api.elements.getTypeById("water");
+   *
+   * api.events.on("item:used", ({ itemId, cellX, cellY }) => {
+   *   if (itemId !== "laser") return;
+   *
+   *   api.grid.mutate((writer) => {
+   *     if (!api.terrains.isTypeAtCell(cellX, cellY, "ice")) return;
+   *     writer.elements.replaceAtCell(cellX, cellY, waterType);
+   *   });
+   * });
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#mutations-heading)
    */
   export function mutate(callback: (writer: GridMutationWriter) => void): void;
 
@@ -57,7 +95,8 @@ export namespace grid {
    *
    * @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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function revealFogAtCell(...args: CellCoordinates): void;
 
@@ -67,7 +106,8 @@ export namespace grid {
    * @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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function redrawAroundCell(...args: [...CellCoordinates, rangeCells: number]): void;
 
@@ -78,7 +118,8 @@ export namespace grid {
    * @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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function forEachCellInCircle(centerCellX: number, centerCellY: number, radiusCells: number, callback: (...args: CellCoordinates) => void): void;
 
@@ -90,13 +131,15 @@ export namespace grid {
    * @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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function forEachCellInRect(...args: [...CellCoordinates, widthCells: number, heightCells: number, callback: (...args: CellCoordinates) => void]): void;
 
@@ -117,7 +160,8 @@ export namespace grid {
      * @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`
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#mutations-heading)
      */
     createAtCell(...args: [...CellCoordinates, elementTypeOrId: elements.ElementRef, options?: elements.ElementCreateOptions]): void;
 
@@ -128,7 +172,8 @@ export namespace grid {
      * @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`
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#mutations-heading)
      */
     replaceAtCell(...args: [...CellCoordinates, elementTypeOrId: elements.ElementRef, options?: elements.ElementCreateOptions]): void;
 
@@ -138,7 +183,8 @@ export namespace grid {
      * @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`
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#mutations-heading)
      */
     removeAtCell(...args: [...CellCoordinates, options?: elements.ElementRemovalOptions]): void;
   }
@@ -152,7 +198,8 @@ export namespace grid {
      * @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`
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#mutations-heading)
      */
     createAtCell(...args: [...CellCoordinates, terrainTypeOrId: terrains.TerrainRef, options?: terrains.TerrainMutationOptions]): void;
 
@@ -163,7 +210,8 @@ export namespace grid {
      * @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`
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#mutations-heading)
      */
     replaceAtCell(...args: [...CellCoordinates, terrainTypeOrId: terrains.TerrainRef, options?: terrains.TerrainMutationOptions]): void;
 
@@ -173,7 +221,8 @@ export namespace 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 Official Sandkit API — Main entry `api.grid.mutate` writer `terrains.removeAtCell`
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#mutations-heading)
      */
     removeAtCell(...args: [...CellCoordinates, options?: terrains.TerrainMutationOptions]): void;
   }