@sandustry-modding/types 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-08-27
+
+### Added
+
+- Initial public release of `@sandustry-modding/types`
+- TypeScript declarations for main-thread `sandkit` (`sandkit/api`, `sandkit/engine`, `sandkit/enums`, `sandkit/react`)
+- Worker-thread declarations under `worker/` (`WorkerSandkitApi`)
+- Shared base shapes under `shared/` for main and worker reuse
+- Ambient `sandkit` free variable and type aliases via `global.d.ts`
+- Docsify API reference generated from the declarations
+
+[0.1.0]: https://github.com/sandustry-modding/SandustryTypes/releases/tag/v0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# SandustryTypes
+
+TypeScript declarations and Docsify API docs for the live Sandustry `sandkit` object. Package name: `@sandustry-modding/types`.
+
+Folder layout mirrors runtime shape so you can jump from code to the matching `.d.ts` path.
+
+## Runtime map
+
+| Path | Runtime object |
+| --- | --- |
+| `sandkit/api/` | `sandkit.api` (main thread) |
+| `sandkit/engine/api/` | `sandkit.engine.api` |
+| `sandkit/engine/state.d.ts` | `sandkit.engine.state` / `sandkit.state` |
+| `sandkit/enums/` | `sandkit.enums` |
+| `sandkit/react.d.ts` | `sandkit.react` |
+| `sandkit/index.d.ts` | Composed `Sandkit` root type |
+| `global.d.ts` | Ambient `sandkit` free variable and type aliases |
+| `worker/` | Worker-thread `sandkit.api` (see `WorkerSandkitApi`) |
+| `shared/` | Internal base shapes reused by main and worker declarations |
+
+## Runtime shape vs `export namespace`
+
+At runtime, every API bag is a **plain object** with function properties — not a TypeScript `namespace`. MCP checks on a live game session show:
+
+- `sandkit.api`, `sandkit.api.ui`, `sandkit.api.ui.overlays`, and `sandkit.engine.api.game` are all `typeof "object"` with `Object.prototype`
+- Nested keys hold functions or further plain objects
+
+Declaration files use `export namespace` because it is the usual `.d.ts` pattern for nested object APIs. It matches how you call the API (`sandkit.api.ui.update`) and supports `export import` when main and worker share base shapes under `shared/`.
+
+`interface` or `type` object literals would also work for runtime shape, but they do not support the `export import` re-export style used across main, worker, and shared modules.
+
+## Install
+
+```bash
+npm install @sandustry-modding/types
+```
+
+In `tsconfig.json`, include the package types (or reference them from an ambient file):
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@sandustry-modding/types"]
+  }
+}
+```
+
+## Usage
+
+- **Main mod (`main.js`):** use the ambient free name `sandkit`. Type aliases such as `SandkitApi` are global; do not import a value binding.
+- **Worker mod (`worker.js`):** type `sandkit.api` as `WorkerSandkitApi`. Worker and main APIs overlap but are not interchangeable.
+- **Shared folder:** not a runtime namespace. It holds domain shapes and API bases that main and worker modules extend.
+
+## Maintaining types
+
+Edit `.d.ts` files here. Regenerate the Docsify API reference after JSDoc changes.
+
+## Docs site
+
+Regenerate the Docsify API reference from these declarations:
+
+```bash
+npm run docs:api
+```
+
+Output lands in `docs/api/`. `npm run docs` runs that step, then serves the docs site.

package/global.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Ambient host bindings for mod `main.js`.
+ *
+ * The game evaluates the bundle with `new Function("__sandkit", body)` and
+ * binds `const sandkit = __sandkit` before the IIFE. Use the free name
+ * `sandkit` in mod and modkit code — do not import a value binding.
+ *
+ * Type names below are also ambient so mods can annotate without imports.
+ * Prefer `typeof sandkit` / `typeof sandkit.api` when that reads clearer.
+ */
+declare global {
+  /**
+   * Host-injected free variable in the sandkit loader scope (not `globalThis`).
+   * Use this name in mod `main.js` and modkit code. Do not import a value binding.
+   */
+  const sandkit: import("./sandkit").Sandkit;
+
+  /** Full shape of the ambient `sandkit` object. */
+  type Sandkit = import("./sandkit").Sandkit;
+  /** Main-thread `sandkit.api` composed type. Not the worker API. */
+  type SandkitApi = import("./sandkit").SandkitApi;
+  /** `sandkit.engine` internals bag (state-first APIs). */
+  type SandkitEngine = import("./sandkit").SandkitEngine;
+  /** Composed `sandkit.engine.api` namespaces. */
+  type SandkitEngineApi = import("./sandkit").SandkitEngineApi;
+  /** Game state at `sandkit.state` / `sandkit.engine.state`. */
+  type SandkitState = import("./sandkit").SandkitState;
+  /** Runtime enum bags at `sandkit.enums`. */
+  type SandkitEnums = import("./sandkit").SandkitEnums;
+  /** Host React package at `sandkit.react`. */
+  type SandkitReact = import("./sandkit").SandkitReact;
+  /** Retro Console API surface on supported engine namespaces. */
+  type RetroConsoleApi = import("./sandkit").RetroConsoleApi;
+  /** Worker-thread `sandkit.api` shape — use in `worker.ts`. */
+  type WorkerSandkitApi = import("./worker/sandkit-api").WorkerSandkitApi;
+}
+
+export {};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@sandustry-modding/types",
+  "version": "0.1.0",
+  "description": "TypeScript declarations and API docs for the Sandustry Sandkit host API",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sandustry-modding/SandustryTypes.git"
+  },
+  "homepage": "https://github.com/sandustry-modding/SandustryTypes#readme",
+  "bugs": {
+    "url": "https://github.com/sandustry-modding/SandustryTypes/issues"
+  },
+  "types": "./global.d.ts",
+  "exports": {
+    ".": {
+      "types": "./global.d.ts"
+    }
+  },
+  "files": [
+    "global.d.ts",
+    "sandkit/**/*.d.ts",
+    "shared/**/*.d.ts",
+    "worker/**/*.d.ts",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "ATTRIBUTION.md"
+  ],
+  "scripts": {
+    "docs": "npm run docs:api && npm run docs:serve",
+    "docs:api": "node scripts/generate-api-docs.mjs",
+    "docs:serve": "npx --yes docsify-cli serve docs",
+    "test": "node --test scripts/api-search.test.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.1",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/sandkit/api/action.d.ts

@@ -0,0 +1,28 @@
+import { AssetRef } from "../../shared/asset";
+
+/**
+ * `sandkit.api.action` — active hotbar action and custom handler data.
+ * Main thread only.
+ */
+export declare namespace action {
+  /** Hotbar action asset reference. */
+  export type Action = AssetRef;
+
+  /**
+   * Return the action slot the player is using.
+   * @returns Active hotbar action reference.
+   */
+  export function getActive(): Action;
+
+  /**
+   * Return the action slot selected in the hotbar.
+   * @returns Selected hotbar action reference.
+   */
+  export function getSelected(): Action;
+
+  /**
+   * Store custom data on the active action handler.
+   * @param data - Serializable payload attached to the active action.
+   */
+  export function setCustomData<Input>(data: Input): void;
+}

package/sandkit/api/assets.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `sandkit.api.assets` — mod asset URLs and asset provider selection.
+ * Main thread only.
+ */
+export namespace assets {
+  /** Describes a mod or pack that supplies assets for a kind. */
+  export type AssetProviderV1 = {
+    id: `${string}:${string}:${string}`,
+    kind: string,
+    localId?: string,
+    modId?: number,
+    modName: string,
+  };
+  /**
+   * Resolves a path under the mod folder to a loadable URL.
+   * @param relativePath - Path relative to the calling mod folder.
+   */
+  export function getUrl(relativePath: string): string;
+  /**
+   * Returns the selected provider for an asset kind, or null.
+   * @param kind - Asset kind identifier.
+   */
+  export function getSelectedProvider(kind: string): AssetProviderV1 | null;
+  /**
+   * Selects a provider for an asset kind. Returns true on success.
+   * @param kind - Asset kind identifier.
+   * @param providerId - Provider id from {@link getSelectedProvider}, or null to clear.
+   */
+  export function selectProvider(kind: string, providerId: string | null): boolean;
+}

package/sandkit/api/authorization.d.ts

@@ -0,0 +1,54 @@
+import { CellCoordinates, Player } from "../../shared/player";
+
+/**
+ * `sandkit.api.authorization` — player permission checks for build, grab, and tools.
+ * Main thread only.
+ */
+export namespace authorization {
+  /**
+   * Return true when the player may place a structure at the cell.
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @returns True when building is allowed in the authorization zone.
+   */
+  export function canBuildAtCell(...args: CellCoordinates): boolean;
+
+  /**
+   * Return true when the player may grab at the cell.
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @returns True when grabbing is allowed in the authorization zone.
+   */
+  export function canGrabAtCell(...args: CellCoordinates): boolean;
+
+  /**
+   * Return true when the player may use a tool.
+   * @param player - Player state snapshot.
+   * @param isFlamethrower - When true, apply flamethrower-specific rules.
+   * @returns True when tool use is allowed for the player.
+   */
+  export function canUseTool(player: Player, isFlamethrower?: boolean): boolean;
+
+  /**
+   * Return true when the player may use a tool at the cell.
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @param isFlamethrower - When true, apply flamethrower-specific rules.
+   * @returns True when tool use is allowed at the cell.
+   */
+  export function canUseToolAtCell(...args: [...CellCoordinates, isFlamethrower?: boolean]): boolean;
+
+  /**
+   * Return the authorization zone id at the cell.
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @returns Numeric zone id for the cell.
+   */
+  export function getZoneIdAtCell(...args: CellCoordinates): number;
+
+  /**
+   * Return the authorization zone id for the player.
+   * @returns Numeric zone id for the player's current position.
+   */
+  export function getPlayerZoneId(): number;
+}

package/sandkit/api/building.d.ts

@@ -0,0 +1,92 @@
+import { CellCoordinates, Vector2 } from "../../shared/player";
+import { shared } from "../../shared";
+
+/**
+ * `sandkit.api.building` — structure placement and built-in structure types.
+ * Main thread only.
+ */
+export namespace building {
+  /** Built-in structure type ids used during placement. */
+  export enum StructureType {
+    /** Left-facing conveyor belt. */
+    ConveyorLeft = 1,
+    /** Right-facing conveyor belt. */
+    ConveyorRight = 2,
+    /** Left-facing shaker. */
+    ShakerLeft = 3,
+    /** Right-facing shaker. */
+    ShakerRight = 4,
+    /** Up-facing launcher. */
+    LauncherUp = 5,
+    /** Left-facing launcher. */
+    LauncherLeft = 6,
+    /** Right-facing launcher. */
+    LauncherRight = 7,
+    /** Left-facing splitter. */
+    SplitterLeft = 8,
+    /** Right-facing splitter. */
+    SplitterRight = 9,
+    /** Dropper structure. */
+    Dropper = 10,
+    /** Foundation block. */
+    Foundation = 11,
+    /** Angled foundation facing left. */
+    FoundationAngledLeft = 12,
+    /** Left triangle foundation (deprecated id). */
+    FoundationTriangleLeftDel = 13,
+    /** Angled foundation facing right. */
+    FoundationAngledRight = 14,
+    /** Right triangle foundation (deprecated id). */
+    FoundationTriangleRightDel = 15,
+    /** Collector structure. */
+    Collector = 16,
+    /** Left-facing filter. */
+    FilterLeft = 17,
+    /** Right-facing filter. */
+    FilterRight = 18,
+    /** Sliding foundation block. */
+    SlidingFoundation = 19,
+    /** Velocity soaker structure. */
+    VelocitySoaker = 20,
+    /** Grower structure. */
+    Grower = 21,
+    /** Sound box structure. */
+    SoundBox = 22,
+    /** Pipe segment. */
+    Pipe = 23,
+    /** Pump structure. */
+    Pump = 24,
+    /** Liquid vent structure. */
+    LiquidVent = 25,
+    /** Light structure. */
+    Light = 26,
+    /** Gloom emitter structure. */
+    GloomEmitter = 27,
+  }
+
+  /**
+   * Return the snapped world position for placement at the cell.
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @returns Snapped world position in pixels.
+   */
+  export function getSnappedPositionAtCell(...args: CellCoordinates): Vector2;
+
+  /**
+   * Return true when placement is blocked at the cell.
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @returns True when a structure cannot be placed at the cell.
+   */
+  export function isBlockedAtCell(...args: CellCoordinates): boolean;
+
+  /** Cancel the current structure placement preview. */
+  export function cancelPlacement(): void;
+
+  /**
+   * Select a structure for placement by type or id.
+   * @param structureTypeOrId - Built-in {@link StructureType} value or registered structure id.
+   * @returns Resolved selection, or null when the type or id is invalid.
+   */
+  export function selectStructure(structureTypeOrId: StructureType | shared.api.structures.StructureRef): shared.api.structures.StructureRef | null;
+}

package/sandkit/api/camera.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `sandkit.api.camera` — camera focus and follow control.
+ * Main thread only.
+ */
+export namespace camera {
+  /** Snap the camera to the player position. */
+  export function snapToPlayer(): void;
+
+  /**
+   * Move camera focus to world coordinates.
+   * @param worldX - World x position in pixels.
+   * @param worldY - World y position in pixels.
+   * @returns True when focus was applied.
+   */
+  export function setFocusAtWorld(worldX: number, worldY: number): boolean;
+
+  /**
+   * Release scripted focus and return control to the player.
+   * @param options - Optional transition duration in milliseconds.
+   * @returns True when focus was released.
+   */
+  export function releaseFocus(options?: { durationMs?: number; }): boolean;
+}

package/sandkit/api/collector.d.ts

@@ -0,0 +1,36 @@
+import { CellCoordinates } from "../../shared/player";
+import type { CellId } from "../../shared/nominal";
+import { shared } from "../../shared";
+
+/**
+ * `sandkit.api.collector` — collector structure value and pickup handling.
+ * Main thread only.
+ */
+export namespace collector {
+  /**
+   * Returns the collector value for a cell id.
+   * @param cellId - Packed cell identifier.
+   */
+  export function getValueFromCellId(cellId: CellId): number;
+  /**
+   * Returns the collector value for an element type.
+   * @param elementType - Numeric element type id.
+   */
+  export function getValueByType(elementType: shared.api.elements.ElementType): number;
+  /**
+   * Returns true when the cell id can be collected.
+   * @param cellId - Packed cell identifier.
+   */
+  export function isCellIdCollectable(cellId: CellId): boolean;
+  /**
+   * Returns true when the cell id can be collected for sprite display.
+   * @param cellId - Packed cell identifier.
+   */
+  export function isCellIdCollectableForSprite(cellId: CellId): boolean;
+  /**
+   * Notifies collector logic that a pickup happened at the cell.
+   * @param cellX - Grid cell X coordinate.
+   * @param cellY - Grid cell Y coordinate.
+   */
+  export function notifyPickupAtCell(...args: CellCoordinates): void;
+}

package/sandkit/api/constants.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Physics skip modes used with element skip-physics fields.
+ *
+ * `sandkit.api.constants` — shared numeric constants for mod API use.
+ * Main thread only.
+ *
+ * @module
+ */
+export namespace constants {
+  /**
+   * Skip-physics modes for element physics fields.
+   */
+  export const physics: Readonly<{
+    /** Run physics every tick. */
+    normal: 0;
+    /** Skip some physics updates. */
+    skip: 1;
+    /** Skip more aggressively than `skip`. */
+    aggressiveSkip: 2;
+  }>;
+}

package/sandkit/api/cooldown.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `sandkit.api.cooldown` — reusable cooldown timers for abilities and items.
+ * Main thread only.
+ */
+export namespace cooldown {
+  /**
+   * Starts the cooldown when ready and returns true; otherwise returns false.
+   * @param cooldown - Cooldown state object to check and update.
+   * @param overrideTime - Optional timestamp (ms) instead of current game time.
+   */
+  export function check(cooldown: Cooldown, overrideTime?: number): boolean;
+  /**
+   * Returns true when the cooldown has elapsed.
+   * @param cooldown - Cooldown state object to check.
+   * @param overrideTime - Optional timestamp (ms) instead of current game time.
+   */
+  export function isReady(cooldown: Cooldown, overrideTime?: number): boolean;
+
+  /** Cooldown state object passed to {@link check} and {@link isReady}. */
+  export interface Cooldown {
+    /** Timestamp when the cooldown was last triggered (game time). */
+    last: number;
+    /** Cooldown duration in milliseconds. */
+    time: number;
+  }
+}

package/sandkit/api/discoveries.d.ts

@@ -0,0 +1,18 @@
+import { shared } from "../../shared";
+
+/**
+ * `sandkit.api.discoveries` — unlock element and terrain entries in the discovery log.
+ * Main thread only.
+ */
+export namespace discoveries {
+  /**
+   * Marks an element type as discovered for the player.
+   * @param elementType - Numeric element type id.
+   */
+  export function addElementByType(elementType: shared.api.elements.ElementType): void;
+  /**
+   * Marks a terrain type as discovered for the player.
+   * @param terrainType - Numeric terrain type id.
+   */
+  export function addTerrainByType(terrainType: shared.api.terrains.TerrainType): void;
+}

package/sandkit/api/effects.d.ts

@@ -0,0 +1,76 @@
+import { shared } from "../../shared";
+
+/**
+ * `sandkit.api.effects` — visual effects, particles, lights, and lasers at world positions.
+ * Main thread only.
+ */
+declare namespace effects {
+  // Shared functions
+  /** Creates a short-lived light at world coordinates. */
+  export import createLightAtWorld = shared.api.effects.createLightAtWorld
+  /** Spawns particles at world coordinates. */
+  export import createParticlesAtWorld = shared.api.effects.createParticlesAtWorld
+  /** Creates a named screen effect at world coordinates. */
+  export import createEffectAtWorld = shared.api.effects.createEffectAtWorld
+  // Shared types
+  /** Options for generic screen effects. */
+  export import EffectOptions = shared.api.effects.EffectOptions
+  /** Options for temporary lights. */
+  export import TemporaryLightOptions = shared.api.effects.TemporaryLightOptions
+  /** Options for particle effects. */
+  export import ParticleEffectOptions = shared.api.effects.ParticleEffectOptions
+
+  /**
+   * Creates a distortion wave effect at world coordinates.
+   * @param worldX - World X coordinate in pixels.
+   * @param worldY - World Y coordinate in pixels.
+   * @param options - Style, duration, radius, intensity, and color.
+   */
+  export function createDistortionWaveAtWorld(worldX: number, worldY: number, options?: DistortionEffectOptions): void;
+  /**
+   * Creates a laser beam between two world points. Returns a handle to destroy it.
+   * @param startWorldX - Beam start world X in pixels.
+   * @param startWorldY - Beam start world Y in pixels.
+   * @param endWorldX - Beam end world X in pixels.
+   * @param endWorldY - Beam end world Y in pixels.
+   * @param options - Width, brightness, color, and glow options.
+   */
+  export function createLaserAtWorld(startWorldX: number, startWorldY: number, endWorldX: number, endWorldY: number, options?: LaserEffectOptions): LaserEffectHandle;
+  /**
+   * Removes a temporary light by its id.
+   * @param lightId - Light index from {@link createLightAtWorld}.
+   */
+  export function removeLightById(lightId: number): void;
+
+  /** Options for laser beam effects. */
+  export interface LaserEffectOptions {
+    /** Beam width in pixels. */
+    width?: number;
+    /** Beam brightness multiplier. */
+    brightness?: number;
+    /** Beam color as a packed integer. */
+    color?: number;
+    /** When true, draws a glow around the beam. */
+    glow?: boolean;
+  }
+
+  /** Handle returned by createLaserAtWorld. */
+  export interface LaserEffectHandle {
+    /** Removes the laser from the scene. */
+    destroy(): void;
+  }
+
+  /** Options for distortion wave effects. */
+  export interface DistortionEffectOptions {
+    /** Distortion style: implode or explode. */
+    style?: 'implode' | 'explode';
+    /** Effect duration in seconds. */
+    duration?: number;
+    /** Maximum radius of the wave. */
+    maxRadius?: number;
+    /** Visual intensity of the distortion. */
+    intensity?: number;
+    /** RGBA color components for the effect. */
+    color?: [number, number, number, number];
+  }
+}