@sandustry-modding/types 0.1.0

package/sandkit/api/raycast.d.ts

@@ -0,0 +1,19 @@
+/**
+ * World raycast queries from a start point and angle.
+ *
+ * Available as `sandkit.api.raycast`.
+ *
+ * @module
+ */
+import type { Vector2 } from "../../shared/player";
+
+export namespace raycast {
+  /**
+   * Cast a ray from world position. Return hit point and distance, or null.
+   * @param startWorldX - Ray origin world X in pixels.
+   * @param startWorldY - Ray origin world Y in pixels.
+   * @param angle - Ray direction in radians.
+   * @param maxDistance - Maximum ray length in pixels.
+   */
+  export function castFromWorld(startWorldX: number, startWorldY: number, angle: number, maxDistance: number): Vector2 & { distance: number; } | null;
+}

package/sandkit/api/reactions.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Element contact reaction recipe registration.
+ *
+ * Available as `sandkit.api.reactions`.
+ *
+ * @module
+ */
+import type { elements } from "./elements";
+
+export namespace reactions {
+  /**
+   * Register a contact reaction between elements.
+   * @param definition - Contact recipe inputs, outputs, and orientation.
+   */
+  export function registerContact(definition: ContactRecipeDefinitionV1): void;
+
+  /** Contact reaction recipe definition. */
+  export interface ContactRecipeDefinitionV1 {
+    /** First reacting element type. */
+    inputA: elements.ElementType;
+    /** Second reacting element type. */
+    inputB: elements.ElementType;
+    /** Element type produced from input A, or null for no output. */
+    outputA: elements.ElementType | null;
+    /** Element type produced from input B, or null for no output. */
+    outputB: elements.ElementType | null;
+    /** Contact layout requirement. Default `"any"`. */
+    orientation?: "any" | "stacked";
+  }
+}

package/sandkit/api/rendering.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Screen-space drawing helpers and overlay canvas access.
+ *
+ * Available as `sandkit.api.rendering`.
+ *
+ * @module
+ */
+import type { CellCoordinates, Vector2 } from "../../shared/player";
+
+export namespace rendering {
+  /**
+   * Return screen draw position for a grid cell.
+   * @param cellX - Grid cell X coordinate.
+   * @param cellY - Grid cell Y coordinate.
+   */
+  export function getDrawPositionAtCell(...args: CellCoordinates): Vector2;
+  /** Return cell size and snap grid metrics. */
+  export function getGridMetrics(): { cellSize: number; snapGridCellSize: number; };
+  /** Return overlay viewport width and height in pixels. */
+  export function getOverlayViewportSize(): { width: number; height: number; };
+  /**
+   * Run a callback with the overlay canvas context.
+   * @param callback - Receives the overlay 2D context; return value is passed through.
+   */
+  export function withOverlayContext<T>(callback: (context: CanvasRenderingContext2D) => T): T;
+}

package/sandkit/api/resources.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Fluxite collection and energy updates.
+ *
+ * Available as `sandkit.api.resources`.
+ *
+ * @module
+ */
+import { CellCoordinates } from "../../shared/player";
+
+export namespace resources {
+  /**
+   * Collect fluxite at the given cell.
+   * @param cellX - Grid cell X coordinate.
+   * @param cellY - Grid cell Y coordinate.
+   */
+  export function collectFluxiteAtCell(...args: CellCoordinates): void;
+  /**
+   * Update stored energy by amount with optional UI deferral.
+   * @param amount - Energy delta (positive or negative).
+   * @param options - When `deferUi` is true, skip immediate UI refresh.
+   */
+  export function updateEnergy(amount: number, options?: { deferUi?: boolean; }): void;
+}

package/sandkit/api/sandkit-api.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Composed main-thread `sandkit.api` object type.
+ *
+ * Each property matches a namespace under `sandkit.api.*`.
+ * Namespace members are documented in their module files.
+ * Use this type when typing the host `sandkit.api` value as a whole.
+ */
+export type SandkitApi = {
+  /** Player action and custom action data. */
+  action: typeof import("./action").action;
+  /** Mod asset URLs and provider selection. */
+  assets: typeof import("./assets").assets;
+  /** Build authorization checks. */
+  authorization: typeof import("./authorization").authorization;
+  /** Building mode and placement. */
+  building: typeof import("./building").building;
+  /** Camera position and bounds. */
+  camera: typeof import("./camera").camera;
+  /** Collector machine helpers. */
+  collector: typeof import("./collector").collector;
+  /** Shared game constants. */
+  constants: typeof import("./constants").constants;
+  /** Cooldown timers. */
+  cooldown: typeof import("./cooldown").cooldown;
+  /** Discovery tracking. */
+  discoveries: typeof import("./discoveries").discoveries;
+  /** Visual and gameplay effects. */
+  effects: typeof import("./effects").effects;
+  /** Element types and cell mutations. */
+  elements: typeof import("./elements").elements;
+  /** Energy network helpers. */
+  energy: typeof import("./energy").energy;
+  /** Game event subscription. */
+  events: typeof import("./events").events;
+  /** Excavation helpers. */
+  excavation: typeof import("./excavation").excavation;
+  /** Fire and burning helpers. */
+  fire: typeof import("./fire").fire;
+  /** Game configuration values. */
+  gameConfig: typeof import("./gameconfig").gameConfig;
+  /** Grid metrics and cell helpers. */
+  grid: typeof import("./grid").grid;
+  /** Intercept and modify hooks. */
+  hooks: typeof import("./hooks").hooks;
+  /** Localization strings. */
+  i18n: typeof import("./i18n").i18n;
+  /** Input state and bindings. */
+  input: typeof import("./input").input;
+  /** Item definitions and inventory. */
+  items: typeof import("./items").items;
+  /** Dynamic light sources. */
+  lights: typeof import("./lights").lights;
+  /** Map selection and session start. */
+  maps: typeof import("./maps").maps;
+  /** Mod asset provider lookup. */
+  mods: typeof import("./mods").mods;
+  /** Excavation pattern helpers. */
+  patterns: typeof import("./patterns").patterns;
+  /** Player position, movement, and inventory. */
+  player: typeof import("./player").player;
+  /** Processing recipe registration. */
+  processing: typeof import("./processing").processing;
+  /** Story progression completion. */
+  progression: typeof import("./progression").progression;
+  /** Projectile spawn and lifecycle. */
+  projectiles: typeof import("./projectiles").projectiles;
+  /** Game random number helpers. */
+  random: typeof import("./random").random;
+  /** World raycast queries. */
+  raycast: typeof import("./raycast").raycast;
+  /** Element contact reactions. */
+  reactions: typeof import("./reactions").reactions;
+  /** Screen drawing and overlay canvas. */
+  rendering: typeof import("./rendering").rendering;
+  /** Fluxite and energy resources. */
+  resources: typeof import("./resources").resources;
+  /** Active game scene. */
+  scene: typeof import("./scene").scene;
+  /** Next-tick callback scheduling. */
+  schedule: typeof import("./schedule").schedule;
+  /** Game settings read and change events. */
+  settings: typeof import("./settings").settings;
+  /** Cross-thread shared buffers. */
+  shared: typeof import("./shared").shared;
+  /** Signal target registration. */
+  signals: typeof import("./signals").signals;
+  /** Sound playback and stop controls. */
+  sound: typeof import("./sound").sound;
+  /** Sprite load and transforms. */
+  sprites: typeof import("./sprites").sprites;
+  /** Per-mod and local storage. */
+  storage: typeof import("./storage").storage;
+  /** Conveyor and launcher behaviors. */
+  structureBehaviors: typeof import("./structureBehaviors").structureBehaviors;
+  /** Structure registration and queries. */
+  structures: typeof import("./structures").structures;
+  /** Tech tree definitions and locks. */
+  tech: typeof import("./tech").tech;
+  /** Terrain registration and mutations. */
+  terrains: typeof import("./terrains").terrains;
+  /** Game time and tick counter. */
+  time: typeof import("./time").time;
+  /** Tool-specific helpers. */
+  tools: typeof import("./tools").tools;
+  /** Interval trigger registration. */
+  triggers: typeof import("./triggers").triggers;
+  /** UI overlays, dialogs, and navigation. */
+  ui: typeof import("./ui").ui;
+  /** Upgrade categories and levels. */
+  upgrades: typeof import("./upgrades").upgrades;
+  /** Vector math helpers. */
+  utils: typeof import("./utils").utils;
+  /** Worker post-update control. */
+  workers: typeof import("./workers").workers;
+  /** World cells, fog, redraw, and pickups. */
+  world: typeof import("./world").world;
+};

package/sandkit/api/scene.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Active game scene and scene enum.
+ *
+ * Available as `sandkit.api.scene`.
+ *
+ * @module
+ */
+import { Scene as SceneEnum } from "../enums";
+
+export namespace scene {
+  /** Scene enum values. */
+  export import Scene = SceneEnum;
+  /** Return the active scene. */
+  export function getActive(): SceneEnum;
+}

package/sandkit/api/schedule.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Deferred callback scheduling on the next tick.
+ *
+ * Available as `sandkit.api.schedule`.
+ *
+ * @module
+ */
+export namespace schedule {
+  /**
+   * Run a callback on the next game tick.
+   * @param callback - Function invoked once on the next tick.
+   */
+  export function nextTick(callback: () => void): void;
+}

package/sandkit/api/settings.d.ts

@@ -0,0 +1,29 @@
+import type { LooseString } from "../../shared/nominal";
+
+/**
+ * Game settings read and change notifications.
+ *
+ * Available as `sandkit.api.settings`.
+ *
+ * @module
+ */
+export namespace settings {
+  /**
+   * Return a settings field value by id.
+   * @param fieldId - Settings field identifier.
+   */
+  export function get(fieldId: FieldId): ConfigValueV1 | undefined;
+  /** Return all settings as a read-only map. */
+  export function getAll(): Readonly<Record<string, ConfigValueV1>>;
+  /**
+   * Subscribe to settings changes. Return an unsubscribe function.
+   * @param callback - Called with the full settings map after a change.
+   */
+  export function onChange(callback: (values: Readonly<Record<string, ConfigValueV1>>) => void): () => void;
+
+  /** Settings field id. Any string is allowed. */
+  export type FieldId = LooseString<never>;
+
+  /** Settings field value shape. */
+  export type ConfigValueV1 = string | number | boolean | null;
+}

package/sandkit/api/shared.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Cross-thread shared memory buffers.
+ *
+ * Available as `sandkit.api.shared`.
+ *
+ * @module
+ */
+// Aliased: this module declares its own `shared` namespace below.
+import { shared as sharedApi } from "../../shared";
+
+export namespace shared {
+  /** Shared buffer create and lookup. */
+  export namespace buffers {
+    /**
+     * Create a named shared buffer with type and length.
+     * @param key - Buffer name shared across threads.
+     * @param config - Typed array kind and element count.
+     */
+    export function create(key: string, config: { type: SharedArrayType; length: number; }): SharedArray;
+    /** Look up a named shared buffer without creating it. */
+    export import get = sharedApi.api.shared.buffers.get
+  }
+  /** Opaque shared array backing store. */
+  export import SharedArray = sharedApi.api.shared.SharedArray
+  /** Discriminator for the underlying typed array kind. */
+  export import SharedArrayType = sharedApi.api.shared.SharedArrayType
+}

package/sandkit/api/signals.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Signal target registration for structures.
+ *
+ * Available as `sandkit.api.signals`.
+ *
+ * @module
+ */
+export namespace signals {
+  /** Signal target registration for structure types. */
+  export namespace targets {
+    /**
+     * Register a handler when a signal targets a structure type.
+     * @param structureTypeOrId - Structure type id or enum value.
+     * @param apply - Called when a signal reaches a matching structure.
+     */
+    export function register(structureTypeOrId: string | StructureType, apply: (structure: Structure, payload: SignalTargetPayloadV1) => void): void;
+  }
+
+  /** Structure type id or enum value. */
+  export type StructureType = unknown
+  /** Structure instance in the world. */
+  export type Structure = unknown
+  /** Payload delivered to a signal target handler. */
+  export type SignalTargetPayloadV1 = unknown
+}

package/sandkit/api/sound.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Sound playback, layers, and stop controls.
+ *
+ * Available as `sandkit.api.sound`.
+ *
+ * @module
+ */
+export namespace sound {
+  /**
+   * Play a sound by id with optional options.
+   * @param soundId - Registered sound identifier.
+   * @param options - Volume, position, playback rate, and rate-limit options.
+   */
+  export function play(soundId: string, options?: SoundOptions): SoundHandle;
+  /**
+   * Play a sound on the active sound channel.
+   * @param soundId - Registered sound identifier.
+   * @param options - Volume, position, playback rate, and rate-limit options.
+   */
+  export function playActive(soundId: string, options?: SoundOptions): SoundHandle;
+  /**
+   * Play multiple sound layers with shared options.
+   * @param layers - Layer definitions (sound id, volume, delay, and per-layer options).
+   * @param options - Shared position, volume, and rate-limit options for all layers.
+   */
+  export function playLayers(layers: SoundLayer[], options?: SoundLayersOptions): SoundHandle[];
+  /**
+   * Build distance-based volume options for a world position.
+   * @param worldX - World X coordinate in pixels.
+   * @param worldY - World Y coordinate in pixels.
+   * @param baseVolume - Base volume before distance attenuation.
+   */
+  export function calculateDistanceOptionsAtWorld(worldX: number, worldY: number, baseVolume?: number): SoundOptions;
+  /**
+   * Stop a sound by id.
+   * @param soundId - Registered sound identifier to stop.
+   */
+  export function stopById(soundId: string): void;
+  /** Stop the active sound channel. */
+  export function stopActive(): void;
+  /** Stop all playing sounds. */
+  export function stopAll(): void;
+
+  /** Handle returned from a play call. */
+  export interface SoundHandle {
+    /** Stop this sound instance. */
+    stop(): void;
+  }
+
+  /** One layer in a layered sound. */
+  export interface SoundLayer {
+    /** Sound id for this layer. */
+    soundId: string;
+    /** Layer volume multiplier. */
+    volume?: number;
+    /** Delay in milliseconds before this layer plays. */
+    delay?: number;
+    /** Playback rate for this layer. */
+    playbackRate?: number;
+    [key: string]: unknown;
+  }
+
+  /** Options passed to sound play helpers. */
+  export interface SoundOptions {
+    /** Volume multiplier (0–1 typical). */
+    volume?: number;
+    /** Playback rate multiplier. */
+    playbackRate?: number;
+    /** World position for distance attenuation. */
+    position?: { x: number; y: number };
+    /** When true, loop until stopped. */
+    loop?: boolean;
+    /** Key used with rateLimitMs to dedupe rapid replays. */
+    rateLimitKey?: string;
+    /** Minimum ms between plays with the same rateLimitKey. */
+    rateLimitMs?: number;
+    [key: string]: unknown;
+  }
+
+  /** Shared options for {@link playLayers}. */
+  export interface SoundLayersOptions {
+    /** World position applied to all layers. */
+    position?: { x: number; y: number };
+    /** Volume multiplier applied to all layers. */
+    volume?: number;
+    /** Key used with rateLimitMs to dedupe rapid replays. */
+    rateLimitKey?: string;
+    /** Minimum ms between plays with the same rateLimitKey. */
+    rateLimitMs?: number;
+  }
+}

package/sandkit/api/sprites.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Sprite load, lookup, and player mod sprite transforms.
+ *
+ * Available as `sandkit.api.sprites`.
+ *
+ * @module
+ */
+export namespace sprites {
+  /**
+   * Load a sprite from a URL path.
+   * @param spriteId - Id used with {@link getById}.
+   * @param path - URL or asset path to load.
+   * @param options - Optional tint and load options.
+   */
+  export function load(spriteId: string, path: string, options?: SpriteLoadOptions): Promise<void>;
+  /**
+   * Load a sprite from the calling mod folder.
+   * @param spriteId - Id used with {@link getById}.
+   * @param relativePath - Path relative to the mod folder.
+   * @param options - Optional tint and load options.
+   */
+  export function loadFromMod(spriteId: string, relativePath: string, options?: SpriteLoadOptions): Promise<void>;
+  /**
+   * Return a loaded sprite by id.
+   * @param spriteId - Sprite id from {@link load} or {@link loadFromMod}.
+   */
+  export function getById(spriteId: string): LoadedSprite | undefined;
+  /** Hide all player mod-attached sprites. */
+  export function hideAllPlayerModSprites(): void;
+  /**
+   * Rotate all player mod-attached sprites by angle.
+   * @param angle - Rotation in radians.
+   */
+  export function rotatePlayerModSprites(angle: number): void;
+
+  /** Loaded sprite handle (runtime texture or display object). */
+  export type LoadedSprite = unknown
+
+  /** Options for {@link load} and {@link loadFromMod}. */
+  export interface SpriteLoadOptions {
+    /** Packed RGB tint applied after load. */
+    tint?: number;
+    [key: string]: unknown;
+  }
+}

package/sandkit/api/storage.d.ts

@@ -0,0 +1,55 @@
+import { JsonObjectV1, JsonValueV1 } from "../../shared/jsonvalue";
+
+/**
+ * Per-mod persistent storage and local session storage.
+ *
+ * Available as `sandkit.api.storage`.
+ *
+ * @module
+ */
+export namespace storage {
+  /**
+   * Ensure storage exists for a mod id.
+   * @param modId - Mod identifier (typically `modinfo.id`).
+   */
+  export function ensure(modId: string): JsonObjectV1;
+  /**
+   * Read a value from mod storage by key.
+   * @param modId - Mod identifier.
+   * @param key - Storage key.
+   */
+  export function get(modId: string, key: string): JsonValueV1 | undefined;
+  /**
+   * Write a value to mod storage by key.
+   * @param modId - Mod identifier.
+   * @param key - Storage key.
+   * @param value - JSON-serializable value.
+   */
+  export function set(modId: string, key: string, value: JsonValueV1): void;
+  /**
+   * Remove a key from mod storage.
+   * @param modId - Mod identifier.
+   * @param key - Storage key.
+   */
+  export function remove(modId: string, key: string): void;
+
+  /** Local session storage without mod id scope. */
+  export namespace local {
+    /**
+     * Read a local storage value by key.
+     * @param key - Storage key.
+     */
+    export function get(key: string): JsonValueV1 | undefined;
+    /**
+     * Write a local storage value by key.
+     * @param key - Storage key.
+     * @param value - JSON-serializable value.
+     */
+    export function set(key: string, value: JsonValueV1): void;
+    /**
+     * Remove a local storage key.
+     * @param key - Storage key.
+     */
+    export function remove(key: string): void;
+  }
+}

package/sandkit/api/structureBehaviors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Structure behavior registration for conveyors and launchers.
+ *
+ * Available as `sandkit.api.structureBehaviors`.
+ *
+ * @module
+ */
+import type { Vector2 } from "../../shared/player";
+
+export namespace structureBehaviors {
+  /**
+   * Register conveyor behavior for a structure type.
+   * @param structureId - Structure type id string.
+   * @param options - Transport offset, velocity, distance, and run direction.
+   */
+  export function registerConveyorType(structureId: string, options?: { transportOffset?: Vector2; velocity?: Vector2; maxTransportDistance?: number; transportHeight?: number; runWith?: 'left' | 'right'; skipQueued?: boolean; }): void;
+  /**
+   * Register launcher behavior for up, left, and right launcher types.
+   * @param definition - Launcher type ids, velocities, and optional shared buffer key.
+   */
+  export function registerLauncherType(definition: { upType: string; leftType: string; rightType: string; velocity: [number, number]; softDropVelocity: number; runTickSharedBufferKey?: string; }): void;
+}