@sandustry-modding/types 0.1.0

package/sandkit/engine/api/queue.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `sandkit.engine.api.queue` — deferred tick queue with handlers.
+ *
+ * **Internal API.** Prefer {@link sandkit.api} when a public method exists.
+ * Methods use loose stubs; signatures may take game state as the first argument.
+ * Engine methods pass game state as the first argument (args[0]); remaining entries are method-specific.
+ *
+ * @internal
+ */
+export namespace queue {
+  /**
+   * Enqueue work to run on a future tick.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function enqueue(...args: unknown[]): unknown;
+  /**
+   * Enqueue work to run after a tick delay.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function enqueueInTicks(...args: unknown[]): unknown;
+  /**
+   * Enqueue work that skips the current tick.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function enqueueSkipTick(...args: unknown[]): unknown;
+  /**
+   * Process pending queue items for the current tick.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function process(...args: unknown[]): unknown;
+  /**
+   * Register a handler for a queue item type.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function registerHandler(...args: unknown[]): unknown;
+  /**
+   * Remove queued items by key.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function removeByKey(...args: unknown[]): unknown;
+}

package/sandkit/engine/api/shadows.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `sandkit.engine.api.shadows` — shadow map refresh for regions.
+ *
+ * **Internal API.** Prefer {@link sandkit.api} when a public method exists.
+ * Methods use loose stubs; signatures may take game state as the first argument.
+ * Engine methods pass game state as the first argument (args[0]); remaining entries are method-specific.
+ *
+ * @internal
+ */
+export namespace shadows {
+  /**
+   * Refresh shadows for the whole visible area.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function refresh(...args: unknown[]): unknown;
+  /**
+   * Refresh shadows within a circular radius.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function refreshRadius(...args: unknown[]): unknown;
+  /**
+   * Refresh shadows within a rectangle.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function refreshRect(...args: unknown[]): unknown;
+}

package/sandkit/engine/api/strataform.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `sandkit.engine.api.strataform` — strataform event triggers and type registration.
+ *
+ * **Internal API.** Prefer {@link sandkit.api} when a public method exists.
+ * Methods use loose stubs; signatures may take game state as the first argument.
+ * Engine methods pass game state as the first argument (args[0]); remaining entries are method-specific.
+ *
+ * @internal
+ */
+export namespace strataform {
+  /**
+   * Return the default strataform configuration.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function getDefaultConfig(...args: unknown[]): unknown;
+  /**
+   * Return all registered strataform types.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function getRegisteredTypes(...args: unknown[]): unknown;
+  /**
+   * Register a custom strataform type.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function registerType(...args: unknown[]): unknown;
+  /**
+   * Trigger a strataform event at a location.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function trigger(...args: unknown[]): unknown;
+  /**
+   * Trigger a strataform event by type id.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function triggerByType(...args: unknown[]): unknown;
+}

package/sandkit/engine/api/swarmConsole.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `sandkit.engine.api.swarmConsole` — swarm convergence console state.
+ *
+ * **Internal API.** Prefer {@link sandkit.api} when a public method exists.
+ * Methods use loose stubs; signatures may take game state as the first argument.
+ * Engine methods pass game state as the first argument (args[0]); remaining entries are method-specific.
+ *
+ * @internal
+ */
+export namespace swarmConsole {
+  /**
+   * Decrease the convergence buffer by one step.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function decrementConvergenceBuffer(...args: unknown[]): unknown;
+  /**
+   * Return total crystal mined for swarm consoles.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function getCrystalMined(...args: unknown[]): unknown;
+  /**
+   * Return the disk radius in cells for a console.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function getDiskRadiusCells(...args: unknown[]): unknown;
+  /**
+   * Return the entity type used by swarm consoles.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function getEntityType(...args: unknown[]): unknown;
+  /**
+   * Return the nearest convergence point.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function getNearestConvergence(...args: unknown[]): unknown;
+  /**
+   * Return the pending convergence target.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function getPendingConvergence(...args: unknown[]): unknown;
+  /**
+   * Return all placed swarm console structures.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function getPlacedConsoles(...args: unknown[]): unknown;
+  /**
+   * Return the console effect radius in pixels.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function getRadiusPx(...args: unknown[]): unknown;
+  /**
+   * Return whether swarm spawn is currently jammed.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function isSpawnJammed(...args: unknown[]): unknown;
+  /**
+   * Register the entity type for swarm consoles.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function registerEntityType(...args: unknown[]): unknown;
+  /**
+   * Reset convergence buffers on all consoles.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function resetAllConvergenceBuffers(...args: unknown[]): unknown;
+  /**
+   * Set whether swarm spawn is jammed.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function setSpawnJammed(...args: unknown[]): unknown;
+}

package/sandkit/engine/api/sweeperDrone.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `sandkit.engine.api.sweeperDrone` — sweeper drone selection control.
+ *
+ * **Internal API.** Prefer {@link sandkit.api} when a public method exists.
+ * Methods use loose stubs; signatures may take game state as the first argument.
+ * Engine methods pass game state as the first argument (args[0]); remaining entries are method-specific.
+ *
+ * @internal
+ */
+export namespace sweeperDrone {
+  /**
+   * Cancel the active sweeper drone selection.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function cancelSelection(...args: unknown[]): unknown;
+}

package/sandkit/engine/api/teleportZones.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `sandkit.engine.api.teleportZones` — player teleport zone management.
+ *
+ * **Internal API.** Prefer {@link sandkit.api} when a public method exists.
+ * Methods use loose stubs; signatures may take game state as the first argument.
+ * Engine methods pass game state as the first argument (args[0]); remaining entries are method-specific.
+ *
+ * @internal
+ */
+export namespace teleportZones {
+  /**
+   * Add a teleport zone to the world.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function add(...args: unknown[]): unknown;
+  /**
+   * Return all teleport zones.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function getAll(...args: unknown[]): unknown;
+  /**
+   * Return the teleport zone at one grid cell.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function getAtCell(...args: unknown[]): unknown;
+  /**
+   * Return one teleport zone by id.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function getById(...args: unknown[]): unknown;
+  /**
+   * Remove a teleport zone.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function remove(...args: unknown[]): unknown;
+  /**
+   * Spawn default particles at a teleport zone.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function spawnDefaultParticles(...args: unknown[]): unknown;
+  /**
+   * Teleport the player to a zone or position.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function teleportPlayerTo(...args: unknown[]): unknown;
+}

package/sandkit/engine/api/tutorialBuild.d.ts

@@ -0,0 +1,66 @@
+/**
+ * `sandkit.engine.api.tutorialBuild` — tutorial build-step constraints and targets.
+ *
+ * **Internal API.** Prefer {@link sandkit.api} when a public method exists.
+ * Methods use loose stubs; signatures may take game state as the first argument.
+ * Engine methods pass game state as the first argument (args[0]); remaining entries are method-specific.
+ *
+ * @internal
+ */
+export namespace tutorialBuild {
+  /**
+   * Return whether all active tutorial targets are built.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function areAllTargetsBuilt(...args: unknown[]): unknown;
+  /**
+   * Return whether all targets in a structure family are built.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function areFamilyTargetsBuilt(...args: unknown[]): unknown;
+  /**
+   * Return whether placement is allowed at the active target.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function canPlaceAtActiveTarget(...args: unknown[]): unknown;
+  /**
+   * Return foundation move destination cells for the tutorial step.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function getFoundationMoveDests(...args: unknown[]): unknown;
+  /**
+   * Return foundation move source cells for the tutorial step.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function getFoundationMoveSources(...args: unknown[]): unknown;
+  /**
+   * Return build targets for the current tutorial step.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function getTargets(...args: unknown[]): unknown;
+  /**
+   * Return whether a tutorial build definition exists.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function hasDefinition(...args: unknown[]): unknown;
+  /**
+   * Return whether the current step restricts building.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function isStepConstrained(...args: unknown[]): unknown;
+  /**
+   * Return whether a foundation move matches tutorial rules.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function matchesFoundationMove(...args: unknown[]): unknown;
+  /**
+   * Return whether a foundation remove matches tutorial rules.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function matchesFoundationRemove(...args: unknown[]): unknown;
+  /**
+   * Return whether the active target should be protected at a cell.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function shouldProtectActiveTargetAt(...args: unknown[]): unknown;
+}

package/sandkit/engine/api/usageTracker.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `sandkit.engine.api.usageTracker` — tool and structure usage statistics.
+ *
+ * **Internal API.** Prefer {@link sandkit.api} when a public method exists.
+ * Methods use loose stubs; signatures may take game state as the first argument.
+ * Engine methods pass game state as the first argument (args[0]); remaining entries are method-specific.
+ *
+ * @internal
+ */
+export namespace usageTracker {
+  /**
+   * Clear recorded usage statistics.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function clear(...args: unknown[]): unknown;
+  /**
+   * Return the most recently used item or structure.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function getLatest(...args: unknown[]): unknown;
+  /**
+   * Return the most frequently used item or structure.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function getMostUsed(...args: unknown[]): unknown;
+}

package/sandkit/engine/api/wall.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `sandkit.engine.api.wall` — wall tile palette and cell data.
+ *
+ * **Internal API.** Prefer {@link sandkit.api} when a public method exists.
+ * Methods use loose stubs; signatures may take game state as the first argument.
+ * Engine methods pass game state as the first argument (args[0]); remaining entries are method-specific.
+ *
+ * @internal
+ */
+export namespace wall {
+  /**
+   * Return wall palette data for rendering.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function getPaletteData(...args: unknown[]): unknown;
+  /**
+   * Return wall tile data at one cell.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function getWallDataAt(...args: unknown[]): unknown;
+  /**
+   * Return the byte size of wall tile data.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function getWallDataSize(...args: unknown[]): unknown;
+  /**
+   * Set wall tile data at one cell.
+   * @param args - Game state first, then method-specific arguments.
+   */
+  export function setWallDataAt(...args: unknown[]): unknown;
+}

package/sandkit/engine/api/workerLocal.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `sandkit.engine.api.workerLocal` — per-worker ephemeral key-value storage.
+ *
+ * **Internal API.** Prefer {@link sandkit.api} when a public method exists.
+ * Available on worker threads only. Values do not persist across workers.
+ *
+ * @internal
+ */
+export namespace workerLocal {
+  /**
+   * Remove all keys from worker-local storage.
+   * @param args - Worker-local context first on workers; otherwise game state first, then method-specific arguments.
+   */
+  export function clear(...args: unknown[]): unknown;
+  /**
+   * Return a value by key, or undefined when missing.
+   * @param args - Worker-local context first on workers; otherwise game state first, then method-specific arguments.
+   */
+  export function get(...args: unknown[]): unknown;
+  /**
+   * Return a value by key, initializing it when missing.
+   * @param args - Worker-local context first on workers; otherwise game state first, then method-specific arguments.
+   */
+  export function getOrInit(...args: unknown[]): unknown;
+  /**
+   * Store a value by key.
+   * @param args - Worker-local context first on workers; otherwise game state first, then method-specific arguments.
+   */
+  export function set(...args: unknown[]): unknown;
+}

package/sandkit/engine/index.d.ts

@@ -0,0 +1,135 @@
+/**
+ * `sandkit.engine` — state-first engine APIs and Retro Console.
+ *
+ * Runtime paths: `sandkit.engine.api.<name>` and `sandkit.engine.state`
+ * (same object as `sandkit.state`). Available on both the main thread
+ * (`main.js`) and worker thread (`worker.js`). The public `sandkit.api`
+ * surface still differs by runtime.
+ *
+ * **Internal API.** Prefer {@link sandkit.api} when a public method exists.
+ * These declarations are best-effort stubs. There is no guarantee they are
+ * complete or correct.
+ *
+ * @module engine
+ * @internal
+ */
+import type { RetroConsoleApi } from "./retro-console";
+import type { EngineFn, EngineOverlapNs } from "../../shared/engine";
+import type { SandkitState } from "./state";
+
+export * from "./retro-console";
+export * from "./api";
+export * from "./state";
+
+/**
+ * Composed `sandkit.engine.api` shape.
+ *
+ * Overlap namespaces mirror {@link sandkit.api} with state-first signatures.
+ * Engine-only namespaces are declared under `api/`.
+ *
+ * @internal
+ */
+export type SandkitEngineApi = {
+  // --- Overlap with sandkit.api (prefer the public API) ---
+  action: EngineOverlapNs;
+  authorization: EngineOverlapNs;
+  building: EngineOverlapNs;
+  camera: EngineOverlapNs;
+  collector: EngineOverlapNs;
+  constants: EngineOverlapNs;
+  cooldown: EngineOverlapNs;
+  discoveries: EngineOverlapNs;
+  effects: EngineOverlapNs;
+  elements: EngineOverlapNs;
+  energy: EngineOverlapNs;
+  events: EngineOverlapNs;
+  excavation: EngineOverlapNs;
+  fire: EngineOverlapNs;
+  grid: EngineOverlapNs;
+  hooks: EngineOverlapNs;
+  i18n: EngineOverlapNs;
+  input: EngineOverlapNs;
+  items: EngineOverlapNs;
+  lights: EngineOverlapNs;
+  maps: EngineOverlapNs;
+  patterns: EngineOverlapNs;
+  player: EngineOverlapNs;
+  processing: EngineOverlapNs;
+  progression: EngineOverlapNs;
+  projectiles: EngineOverlapNs;
+  random: EngineOverlapNs;
+  raycast: EngineOverlapNs;
+  reactions: EngineOverlapNs;
+  rendering: EngineOverlapNs;
+  resources: EngineOverlapNs;
+  scene: EngineOverlapNs;
+  schedule: EngineOverlapNs;
+  signals: EngineOverlapNs;
+  sound: EngineOverlapNs;
+  sprites: EngineOverlapNs;
+  storage: EngineOverlapNs;
+  structures: EngineOverlapNs;
+  tech: EngineOverlapNs;
+  terrains: EngineOverlapNs;
+  tools: EngineOverlapNs;
+  triggers: EngineOverlapNs;
+  ui: EngineOverlapNs;
+  upgrades: EngineOverlapNs;
+  utils: EngineOverlapNs;
+  workers: EngineOverlapNs;
+  world: EngineOverlapNs;
+
+  // --- Engine-only ---
+  augments: typeof import("./api/augments").augments;
+  auralite: typeof import("./api/auralite").auralite;
+  blueprints: typeof import("./api/blueprints").blueprints;
+  clipboard: typeof import("./api/clipboard").clipboard;
+  colorPicker: typeof import("./api/colorPicker").colorPicker;
+  coloringTool: typeof import("./api/coloringTool").coloringTool;
+  conveyors: typeof import("./api/conveyors").conveyors;
+  debug: typeof import("./api/debug").debug;
+  drones: typeof import("./api/drones").drones;
+  entities: typeof import("./api/entities").entities;
+  extensions: typeof import("./api/extensions").extensions;
+  factory: typeof import("./api/factory").factory;
+  foliage: typeof import("./api/foliage").foliage;
+  foundationColorPicker: typeof import("./api/foundationColorPicker").foundationColorPicker;
+  game: typeof import("./api/game").game;
+  heatTransfer: typeof import("./api/heatTransfer").heatTransfer;
+  launchers: typeof import("./api/launchers").launchers;
+  lightColorPicker: typeof import("./api/lightColorPicker").lightColorPicker;
+  matters: typeof import("./api/matters").matters;
+  misc: typeof import("./api/misc").misc;
+  portals: typeof import("./api/portals").portals;
+  prefabData: typeof import("./api/prefabData").prefabData;
+  prefabDecor: typeof import("./api/prefabDecor").prefabDecor;
+  prefabulator: typeof import("./api/prefabulator").prefabulator;
+  prismaline: typeof import("./api/prismaline").prismaline;
+  prismite: typeof import("./api/prismite").prismite;
+  queue: typeof import("./api/queue").queue;
+  shadows: typeof import("./api/shadows").shadows;
+  strataform: typeof import("./api/strataform").strataform;
+  swarmConsole: typeof import("./api/swarmConsole").swarmConsole;
+  sweeperDrone: typeof import("./api/sweeperDrone").sweeperDrone;
+  teleportZones: typeof import("./api/teleportZones").teleportZones;
+  tutorialBuild: typeof import("./api/tutorialBuild").tutorialBuild;
+  usageTracker: typeof import("./api/usageTracker").usageTracker;
+  wall: typeof import("./api/wall").wall;
+  workerLocal: typeof import("./api/workerLocal").workerLocal;
+  config: EngineFn;
+  extend: EngineFn;
+  retroConsole: RetroConsoleApi;
+};
+
+/**
+ * Host `sandkit.engine` object (main and worker).
+ *
+ * **Internal API.** Prefer {@link sandkit.api} when a public method exists.
+ * At runtime `sandkit.engine.state === sandkit.state`.
+ *
+ * @internal
+ */
+export interface SandkitEngine {
+  api: SandkitEngineApi;
+  state: SandkitState;
+}

package/sandkit/engine/retro-console.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `sandkit.engine.api.retroConsole` — in-world Retro Console game types.
+ *
+ * **Internal API.** Prefer {@link sandkit.api} when a public method exists.
+ * Register games through {@link RetroConsoleApi.registerGame}.
+ *
+ * @internal
+ */
+
+/** Pixel value for the Retro Console framebuffer. @internal */
+export type RetroConsolePixel = boolean | number;
+
+/** Low-resolution display buffer for a Retro Console game. @internal */
+export interface RetroConsoleDisplay {
+  width: number;
+  height: number;
+  /** Clear the framebuffer. Optional fill value defaults to off. */
+  clearScreen(value?: RetroConsolePixel): void;
+  /** Set one pixel in the framebuffer. */
+  drawPixel(x: number, y: number, value: RetroConsolePixel): void;
+}
+
+/** Directional input from the Retro Console controls. @internal */
+export interface RetroConsoleInput {
+  x: number;
+  y: number;
+}
+
+/** Display size options for a registered Retro Console game. @internal */
+export interface RetroConsoleGameOptions {
+  width: number;
+  height: number;
+}
+
+/** Retro Console game definition passed to {@link RetroConsoleApi.registerGame}. @internal */
+export interface RetroConsoleGame<TState = unknown> {
+  id: string;
+  name: string;
+  options?: RetroConsoleGameOptions;
+  /** Create initial game state and draw the first frame. */
+  init(display: RetroConsoleDisplay): TState;
+  /** Advance one frame and return updated game state. */
+  update(display: RetroConsoleDisplay, state: TState): TState;
+  /** Handle player input when provided. */
+  handleInput?(display: RetroConsoleDisplay, state: TState, input: RetroConsoleInput): TState;
+}
+
+/** `sandkit.engine.api.retroConsole` registration API. @internal */
+export interface RetroConsoleApi {
+  /** Register a Retro Console mini-game. */
+  registerGame<TState>(game: RetroConsoleGame<TState>): void;
+}

package/sandkit/engine/state.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `sandkit.engine.state` — live game state object.
+ *
+ * Same object as `sandkit.state` at runtime. **Internal API.** Prefer
+ * {@link sandkit.api} when a public method exists. Shapes below are stubs;
+ * refine fields as they are confirmed.
+ *
+ * @internal
+ */
+
+/** Live game state exposed on `sandkit.engine.state`. @internal */
+export type SandkitState = {
+  environment: {
+    context: number;
+    multithreading: unknown;
+    readonly [key: string]: unknown;
+  };
+  sandkit: {
+    events: unknown;
+    gameReady: boolean;
+    graphics: unknown;
+    hooks: unknown;
+    keyBindings: unknown;
+    mods: unknown;
+    registeredLauncherTypes: unknown;
+    readonly [key: string]: unknown;
+  };
+  session: unknown;
+  shared: unknown;
+  store: unknown;
+};