@sandustry-modding/types 0.3.0 → 0.4.0

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

@@ -15,28 +15,28 @@ export namespace elements {
    * Numeric element type 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`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export type ElementType = ElementTypeEnum | TaggedNumber<"elementType">;
 
   /**
    * Mod or built-in element string id.
    *
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.elements`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export type ElementId = LooseString<never>;
 
   /**
    * Type handle or string id accepted by lookup helpers.
    *
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.elements`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export type ElementRef = ElementType | ElementId;
 
   /**
    * Physical behaviour category for an element.
    *
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.elements`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export enum MatterType {
     Solid = 1,
@@ -52,7 +52,7 @@ export namespace elements {
   /**
    * Mod-registered element definition snapshot.
    *
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.elements.register`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export type ElementDefinition = {
     id: string,
@@ -75,7 +75,7 @@ export namespace elements {
   /**
    * Options for {@link createAtCell}, replace, and related create helpers.
    *
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.elements.createAtCell`
+   * @see [Official docs](https://sandustry.com/sandkit.html#mutations-heading)
    */
   export interface ElementCreateOptions {
     /** Initial element data bag. */
@@ -85,12 +85,13 @@ export namespace elements {
     /**
      * Set both max and remaining duration in simulation ticks.
      *
-     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.elements.createAtCell`
+     * @see [Official docs](https://sandustry.com/sandkit.html#mutations-heading)
      */
     durationTicks?: number;
     /**
      * @deprecated Use {@link durationTicks} instead.
-     * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `options.durationTicks`
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     duration?: number;
     /** Override free-fall state on spawn. */
@@ -113,7 +114,7 @@ export namespace elements {
   /**
    * Options for element removal helpers.
    *
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.elements.removeAtCell`
+   * @see [Official docs](https://sandustry.com/sandkit.html#mutations-heading)
    */
   export interface ElementRemovalOptions {
     /** Skip collector accounting when removing the element. */
@@ -124,7 +125,8 @@ export namespace elements {
    * 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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getIdByType(elementType: ElementType): ElementId;
 
@@ -132,13 +134,15 @@ export namespace elements {
    * 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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getTypeFromId(elementId: ElementId): ElementType;
 
@@ -146,7 +150,8 @@ export namespace elements {
    * 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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getDefinitionByType(elementType: ElementType): ElementDefinition | undefined;
 
@@ -155,7 +160,8 @@ export namespace 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.getTypeAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getTypeAtCell(...args: CellCoordinates): ElementType | null;
 
@@ -164,7 +170,8 @@ export namespace 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.getResolvedTypeAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getResolvedTypeAtCell(...args: CellCoordinates): ElementType | null;
 
@@ -172,7 +179,8 @@ export namespace elements {
    * 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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getResolvedTypeFromCellId(cellId: CellId): ElementType | null;
 
@@ -181,7 +189,8 @@ export namespace 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.getInfoAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getInfoAtCell(...args: CellCoordinates): { elementType: ElementType; isParticle: boolean; cellId: CellId; elementIndex: number; } | null;
 
@@ -190,7 +199,8 @@ export namespace 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.getMatterTypeAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getMatterTypeAtCell(...args: CellCoordinates): MatterType | null;
 
@@ -200,7 +210,8 @@ export namespace elements {
    * @param cellX - Grid column of the target cell.
    * @param cellY - Grid row of the target cell.
    * @param elementTypeOrId - Numeric type or string id.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.elements.isTypeAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function isTypeAtCell(...args: [...CellCoordinates, elementTypeOrId: ElementRef]): boolean;
 
@@ -209,7 +220,8 @@ export namespace 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.isFreeFallingAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function isFreeFallingAtCell(...args: CellCoordinates): boolean;
 
@@ -218,7 +230,8 @@ export namespace 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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getVelocityAtCell(...args: CellCoordinates): { x: number; y: number; } | null;
 
@@ -228,7 +241,8 @@ export namespace elements {
    * @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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getDataFieldAtCell(...args: [...CellCoordinates, fieldNumber: 1 | 2 | 3 | 4]): number | null;
 }

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

@@ -16,7 +16,8 @@ export namespace grid {
    * @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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getCellIdAtCell(...args: CellCoordinates): CellId;
 
@@ -25,7 +26,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.isCellEmptyAtCell` / Worker entry `api.grid.isCellEmptyAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function isCellEmptyAtCell(...args: CellCoordinates): boolean;
 
@@ -34,7 +36,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.isTerrainAtCell` / Worker entry `api.grid.isTerrainAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function isTerrainAtCell(...args: CellCoordinates): boolean;
 
@@ -43,7 +46,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.reportActivityAtCell` / Worker entry `api.grid.reportActivityAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function reportActivityAtCell(...args: CellCoordinates): void;
 
@@ -55,14 +59,15 @@ export namespace grid {
    * @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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   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`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getDimensions(): GridDimensions;
 

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

@@ -10,13 +10,15 @@ 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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getPositionAtWorld(): Vector2;
 
   /**
    * @deprecated Use {@link getPositionAtWorld} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.player.getPositionAtWorld`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getWorldPosition(): Vector2;
 
@@ -26,7 +28,8 @@ export namespace player {
    * @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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function isCollidingWithCell(...args: CellCoordinates): boolean;
 
@@ -37,7 +40,8 @@ export namespace player {
    * @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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function isWithinRadiusOfCell(...args: [...CellCoordinates, radius: number]): boolean;
 }

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

@@ -14,7 +14,8 @@ export namespace shared {
      *
      * @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`
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     export function get(key: string): SharedArray | undefined;
   }

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

@@ -13,7 +13,15 @@ export namespace structures {
    *
    * @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`
+   *
+   * @example Worker entry
+   * ```ts
+   * api.structures.forEachOfType("exampleStructure", (structure) => {
+   *   processStructure(structure);
+   * });
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function forEachOfType(structureTypeOrId: StructureRef, callback: (structure: Structure) => void): void;
 
@@ -22,7 +30,8 @@ export namespace structures {
    *
    * @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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getAtCell(...args: CellCoordinates): Structure | null;
 
@@ -30,7 +39,8 @@ export namespace structures {
    * 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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getDefinitionByType(structureType: StructureRef): any;
 
@@ -38,13 +48,15 @@ export namespace structures {
    * 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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getTypeFromId(structureId: StructureId): StructureType;
 
@@ -53,7 +65,8 @@ export namespace structures {
    *
    * @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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function hasBuiltAtCell(...args: CellCoordinates): boolean;
 
@@ -62,7 +75,8 @@ export namespace structures {
    *
    * @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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function isType(structure: Structure | null, structureId: StructureId): boolean;
 
@@ -72,7 +86,8 @@ export namespace structures {
    * @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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function isTypeAtCell(...args: [...CellCoordinates, structureId: StructureId]): boolean;
 
@@ -81,7 +96,8 @@ export namespace structures {
    *
    * @param structure - Target structure instance.
    * @param index - Spritesheet frame index.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.structures.setSpritesheetIndex`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function setSpritesheetIndex(structure: Structure, index: number): void;
 
@@ -91,7 +107,8 @@ export namespace structures {
    * @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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function setSpritesheetIndexAtCell(...args: [...CellCoordinates, index: number]): void;
 
@@ -101,7 +118,8 @@ export namespace structures {
    * @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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function setSpritesheetIndexByValue(structure: Structure, value: number, thresholds: number[]): void;
 
@@ -112,7 +130,8 @@ export namespace structures {
    * @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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function setSpritesheetIndexByValueAtCell(...args: [...CellCoordinates, value: number, thresholds: number[]]): void;
 
@@ -121,7 +140,13 @@ export namespace structures {
    *
    * @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`
+   *
+   * @example Worker entry
+   * ```ts
+   * api.structures.update(structure, { propagateToWorkers: true });
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function update(structure: Structure, options?: { propagateToWorkers?: boolean; }): void;
 
@@ -131,13 +156,24 @@ export namespace structures {
    * @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`
+   *
+   * @example Worker entry
+   * ```ts
+   * api.structures.updateData(
+   *   structure,
+   *   { mode: "allow" },
+   *   { propagateToWorkers: true },
+   * );
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function setData(structure: Structure, partial: any, options?: { propagateToWorkers?: boolean; }): void;
 
@@ -148,13 +184,15 @@ export namespace structures {
      *
      * @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`
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     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`
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     export function isEnabledAt(...args: CellCoordinates): boolean;
   }