@sandustry-modding/types 0.1.0

package/shared/api/elements.d.ts

@@ -0,0 +1,162 @@
+import type { ElementType as ElementTypeEnum } from "../../sandkit/enums/index";
+import type { CellCoordinates, Vector2 } from "../../shared/player";
+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.
+ *
+ * @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.
+   */
+  export type ElementType = ElementTypeEnum | TaggedNumber<"elementType">;
+
+  /** Mod or built-in element string id. */
+  export type ElementId = LooseString<never>;
+  /** Type handle or string id accepted by lookup helpers. */
+  export type ElementRef = ElementType | ElementId;
+
+  /** Physical behaviour category for an element. */
+  export enum MatterType {
+    Solid = 1,
+    Liquid = 2,
+    Particle = 3,
+    Gas = 4,
+    Static = 5,
+    Slushy = 6,
+    Wisp = 7,
+    Powder = 8,
+  }
+
+  /** Mod-registered element definition snapshot. */
+  export type ElementDefinition = {
+    id: string,
+    nameKey: string,
+    defaultDataFields?: { [key: string]: number },
+    colors: {
+      variantFromDataField1?: {
+        rangeMin?: number,
+        rangeMax?: number,
+        invert?: boolean,
+        useGradient?: boolean,
+      },
+      variants: [number, number, number][],
+    },
+    density: number,
+    matterType: MatterType,
+    getExtraProps?: () => { data: Record<PropertyKey, any> }
+  };
+
+  /** Options for {@link createAtCell}, replace, and idle create helpers. */
+  export interface ElementCreateOptions {
+    /** Initial element data bag. */
+    data?: Record<string, unknown>;
+    /** Override element density. */
+    density?: number;
+    /** Set both max and remaining duration. */
+    duration?: number;
+    /** Override free-fall state on spawn. */
+    isFreeFalling?: boolean;
+    /** Override default data fields 1–4. */
+    dataFields?: {
+      field1?: number;
+      field2?: number;
+      field3?: number;
+      field4?: number;
+    };
+    /** Spawn as a particle with the given velocity. */
+    particle?: {
+      velocity: Vector2;
+    };
+    /** Skip collector accounting when placing the element. */
+    skipCollectorCheck?: boolean;
+  }
+
+  /** Options for element removal helpers. */
+  export interface ElementRemovalOptions {
+    /** Skip collector accounting when removing the element. */
+    skipCollectorCheck?: boolean;
+  }
+
+  /**
+   * Resolve a mod element string id to a type handle.
+   * @param elementId - Mod-registered element id.
+   */
+  export function getTypeFromId(elementId: ElementId): ElementType;
+
+  /**
+   * Look up the definition for a type handle.
+   * @param elementType - Numeric element type.
+   */
+  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.
+   */
+  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.
+   */
+  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}.
+   */
+  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.
+   */
+  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.
+   */
+  export function getMatterTypeAtCell(...args: CellCoordinates): MatterType | null;
+
+  /**
+   * Return true when the cell holds the given element type.
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @param elementType - Element type to compare.
+   */
+  export function isTypeAtCell(...args: [...CellCoordinates, elementType: ElementType]): 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.
+   */
+  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.
+   */
+  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).
+   */
+  export function getDataFieldAtCell(...args: [...CellCoordinates, fieldNumber: 1 | 2 | 3 | 4]): number | null;
+}

package/shared/api/maps.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared `sandkit.api.maps` base — active custom map metadata.
+ *
+ * @internal Base namespace reused by main and worker declarations.
+ */
+export namespace maps {
+  /**
+   * Return the currently loaded custom map definition.
+   * @returns Active map metadata, or `null` outside custom maps.
+   */
+  export function getActive(): Readonly<ActiveMapV1> | null;
+
+  /**
+   * Active custom map record (version 1 schema).
+   *
+   * Shape varies by map. Known fields are optional; additional keys may exist.
+   */
+  export interface ActiveMapV1 {
+    id?: string;
+    deployment?: unknown;
+    spawn?: unknown;
+    topBounds?: {
+      soft?: number;
+      hard?: number;
+    };
+    parallax?: unknown;
+    depthLight?: unknown;
+    [key: string]: unknown;
+  }
+}

package/shared/api/player.d.ts

@@ -0,0 +1,31 @@
+import type { CellCoordinates, Vector2 } from "../../shared/player";
+
+/**
+ * Shared `sandkit.api.player` base — player position and collision queries.
+ *
+ * @internal Base namespace reused by main and worker declarations.
+ */
+export namespace player {
+  /**
+   * Return the player center position in world pixels.
+   * @returns World position as `{ x, y }` in pixels.
+   */
+  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.
+   */
+  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.
+   */
+  export function isWithinRadiusOfCell(...args: [...CellCoordinates, radius: number]): boolean;
+}

package/shared/api/shared.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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`.
+ *
+ * @internal Base namespace reused by main and worker declarations.
+ */
+export namespace shared {
+  /** Named shared memory buffers (`create` / `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.
+     */
+    export function get(key: string): SharedArray | undefined;
+  }
+
+  /**
+   * Typed array backing a shared buffer.
+   *
+   * Use {@link SharedArrayType} when creating or requiring a buffer. The runtime
+   * returns the matching `*Array` constructor for the configured type.
+   */
+  export type SharedArray =
+    | Uint8Array
+    | Uint16Array
+    | Uint32Array
+    | Int8Array
+    | Int16Array
+    | Int32Array
+    | Float32Array
+    | Float64Array;
+
+  /** Discriminator for the underlying typed array kind. */
+  export type SharedArrayType =
+    | "uint8"
+    | "uint16"
+    | "uint32"
+    | "int8"
+    | "int16"
+    | "int32"
+    | "float32"
+    | "float64";
+}

package/shared/api/structures.d.ts

@@ -0,0 +1,138 @@
+import type { CellCoordinates } from "../../shared/player";
+import type { LooseString, TaggedNumber } from "../nominal";
+import type { StructureType as StructureTypeEnum } from "../../sandkit/enums/index";
+
+/**
+ * Shared `sandkit.api.structures` base — structure lookup and mutation.
+ *
+ * @internal Base namespace reused by main and worker declarations.
+ */
+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.
+   */
+  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.
+   */
+  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.
+   */
+  export function getDefinitionByType(structureType: StructureRef): any;
+
+  /**
+   * Map a structure string id to its runtime type value.
+   * @param structureId - Structure string id.
+   */
+  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.
+   */
+  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.
+   */
+  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.
+   */
+  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.
+   */
+  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.
+   */
+  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.
+   */
+  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.
+   */
+  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.
+   */
+  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.
+   */
+  export function setData(structure: Structure, partial: any, options?: { propagateToWorkers?: boolean; }): void;
+
+  /** Structure processing enablement checks. */
+  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.
+     */
+    export function isEnabledAt(...args: CellCoordinates): boolean;
+  }
+
+  /** Per-structure custom data bag. */
+  export interface StructureData {
+    elementId?: string | null;
+    elementType?: TaggedNumber<"elementType"> | null;
+    [key: string]: unknown;
+  }
+
+  /** Live structure instance in the world grid. */
+  export interface Structure {
+    x: number;
+    y: number;
+    trapped?: boolean;
+    data?: StructureData;
+    [key: string]: unknown;
+  }
+
+  /** Numeric structure type handle. Built-in enum values autocomplete. */
+  export type StructureType = StructureTypeEnum | TaggedNumber<"structureType">;
+  /** Mod or built-in structure string id. */
+  export type StructureId = LooseString<never>;
+  /** Type handle or string id accepted by lookup helpers. */
+  export type StructureRef = StructureType | StructureId;
+}

package/shared/api/terrains.d.ts

@@ -0,0 +1,100 @@
+import type { CellCoordinates } from "../../shared/player";
+import type { CellId, LooseString, TaggedNumber } from "../nominal";
+import type { CellType as CellTypeEnum } from "../../sandkit/enums/index";
+
+/**
+ * Shared `sandkit.api.terrains` base — terrain type lookup and cell mutation.
+ *
+ * @internal Base namespace reused by main and worker declarations.
+ */
+export namespace terrains {
+  /**
+   * Resolve a terrain string id to a numeric cell type.
+   * @param terrainId - Mod-registered or built-in terrain id.
+   * @returns Numeric terrain cell type.
+   */
+  export function getTypeFromId(terrainId: TerrainId): TerrainType;
+
+  /**
+   * 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.
+   */
+  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 hp, or null when the cell is not terrain.
+   */
+  export function getDataAtCell(...args: CellCoordinates): { cellType: TerrainType; hp: number | null; } | 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.
+   */
+  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.
+   */
+  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}.
+   */
+  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.
+   */
+  export function damageAtCell(...args: [...CellCoordinates, damage: number]): void;
+
+  /**
+   * Place terrain at an empty cell.
+   * @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.
+   */
+  export function createAtCell(...args: [...CellCoordinates, terrainTypeOrId: TerrainRef, options?: TerrainMutationOptions]): void;
+
+  /**
+   * Replace existing terrain at a cell.
+   * @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.
+   */
+  export function replaceAtCell(...args: [...CellCoordinates, terrainTypeOrId: TerrainRef, options?: TerrainMutationOptions]): void;
+
+  /**
+   * Remove terrain from a cell.
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @param options - Optional mutation flags.
+   */
+  export function removeAtCell(...args: [...CellCoordinates, options?: TerrainMutationOptions]): void;
+
+  /** Options for terrain create, replace, or remove calls. */
+  export interface TerrainMutationOptions {
+    /** Skip shadow updates around the changed cell. */
+    skipShadow?: boolean;
+  }
+
+  /** Numeric terrain / {@link CellTypeEnum} handle. */
+  export type TerrainType = CellTypeEnum | TaggedNumber<"terrainType">;
+  /** Mod or built-in terrain string id. */
+  export type TerrainId = LooseString<never>;
+  /** Type handle or string id accepted by mutation helpers. */
+  export type TerrainRef = TerrainType | TerrainId;
+}

package/shared/api/ui.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared `sandkit.api.ui` base — lightweight UI helpers available on workers.
+ *
+ * Main thread adds richer UI APIs on top of this shape.
+ *
+ * @internal Base namespace reused by main and worker declarations.
+ */
+export namespace ui {
+  /**
+   * Show a short on-screen toast message.
+   * @param message - Plain text, translation key, or translatable value.
+   * @param options - Cooldown, style, and auto-dismiss options.
+   */
+  export function toast(message: LocalizedText, options?: ToastOptions): void;
+
+  /** Plain text, translation key object, or i18n translatable value. */
+  export type LocalizedText =
+    | string
+    | I18nTextKey
+    | I18nTranslatable;
+
+  /** Translation key with optional parameter substitution. */
+  export interface I18nTextKey {
+    /** Namespaced translation key (for example `ui|save|save`). */
+    key: string;
+    /** Values merged into the translated string. */
+    params?: Record<string, string | number>;
+  }
+
+  /** Value returned by `sandkit.api.i18n.translatable`. */
+  export interface I18nTranslatable {
+    __translatable: true;
+    key: string;
+    fallback: string;
+  }
+
+  /** Cooldown, style, and auto-dismiss options for {@link toast}. */
+  export interface ToastOptions {
+    /** Minimum ms before the same toast can show again. */
+    cooldown?: number;
+    /**
+     * Dedupe key paired with {@link ToastOptions.cooldown}.
+     * Defaults to the message string or `message.key`.
+     */
+    cooldownKey?: string;
+    /**
+     * Auto-dismiss delay in ms. Default `5000`.
+     * Set `false` to keep the toast until another toast replaces it.
+     */
+    duration?: number | false;
+    /** Visual style applied to the toast body. */
+    variant?: "danger" | "hint" | "hole" | (string & {});
+  }
+}

package/shared/api/world.d.ts

@@ -0,0 +1,71 @@
+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.
+ *
+ * Main thread adds idle scheduling and fog helpers on top of this shape.
+ *
+ * @internal Base namespace reused by main and worker declarations.
+ */
+export namespace world {
+  /**
+   * 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.
+   */
+  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.
+   */
+  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.
+   */
+  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.
+   */
+  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.
+   */
+  export function excavateAtCell(...args: [...CellCoordinates, outVelocity: Vector2, damage: number, options?: ExcavateOptions]): void;
+
+  /** Packed cell id from {@link getCellIdAtCell}. */
+  export type CellId = PackedCellId;
+
+  /** Flags that control how {@link excavateAtCell} resolves damage and drops. */
+  export interface ExcavateOptions {
+    /** Treat the dig as gun fire for terrain resistance checks. */
+    fromGun?: boolean;
+    /** Treat the dig as rocket or dynamite explosion damage. */
+    fromRocketExplosion?: boolean;
+    /** Treat the dig as drill damage. */
+    fromDrill?: boolean;
+    /** Use {@link outVelocity} literally instead of deriving ejection speed. */
+    useLiteralOutVelocity?: boolean;
+    /** Allow removing terrain marked non-destructible. */
+    destroyNonDestructible?: boolean;
+    /** Force-remove all matched cells regardless of normal rules. */
+    forceRemoveAll?: boolean;
+    /** Extra drill-tier damage when {@link fromDrill} is true. Clamped to 0–1000. */
+    drillTierDamage?: number;
+  }
+}

package/shared/asset.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared asset reference shape.
+ *
+ * @internal Base type reused by domain shapes such as {@link Player}. Not a
+ * runtime `sandkit` namespace.
+ */
+
+/** Reference to a loaded sprite or texture asset. */
+export interface AssetRef {
+  /** Runtime asset id. */
+  id: number
+  /** Asset category discriminator used by the renderer. */
+  type: number
+}

package/shared/engine.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared engine API stub types.
+ *
+ * Used where `sandkit.engine.api` namespaces overlap the public mod API but are
+ * not fully typed in declarations.
+ *
+ * @internal
+ */
+
+/** Stub for an unresolved engine method. @internal */
+export type EngineFn = (...args: unknown[]) => unknown;
+
+/**
+ * Loose bag for namespaces that overlap `sandkit.api` (different names / state-first).
+ * @internal
+ */
+export type EngineOverlapNs = Record<string, EngineFn | Record<string, unknown> | unknown>;