@sandustry-modding/types 0.1.0

package/sandkit/api/index.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Main-thread `sandkit.api` barrel.
+ *
+ * Re-exports all namespaces available as `sandkit.api.*` on the main thread.
+ * Prefer these methods over {@link sandkit.engine} when both exist.
+ *
+ * @module
+ */
+
+export * from "./action"
+export * from "./assets"
+export * from "./authorization"
+export * from "./building"
+export * from "./camera"
+export * from "./collector"
+export * from "./constants"
+export * from "./cooldown"
+export * from "./discoveries"
+export * from "./effects"
+export * from "./elements"
+export * from "./energy"
+export * from "./events"
+export * from "./excavation"
+export * from "./fire"
+export * from "./gameconfig"
+export * from "./grid"
+export * from "./hooks"
+export * from "./i18n"
+export * from "./input"
+export * from "./items"
+export * from "./lights"
+export * from "./maps"
+export * from "./mods"
+export * from "./patterns"
+export * from "./player"
+export * from "./processing"
+export * from "./progression"
+export * from "./projectiles"
+export * from "./random"
+export * from "./raycast"
+export * from "./reactions"
+export * from "./rendering"
+export * from "./resources"
+export * from "./scene"
+export * from "./schedule"
+export * from "./settings"
+export * from "./shared"
+export * from "./signals"
+export * from "./sound"
+export * from "./sprites"
+export * from "./storage"
+export * from "./structureBehaviors"
+export * from "./structures"
+export * from "./tech"
+export * from "./terrains"
+export * from "./time"
+export * from "./tools"
+export * from "./triggers"
+export * from "./ui"
+export * from "./upgrades"
+export * from "./utils"
+export * from "./workers"
+export * from "./world"
+
+/** Composed type of the main-thread `sandkit.api` object. */
+export type { SandkitApi } from "./sandkit-api"

package/sandkit/api/input.d.ts

@@ -0,0 +1,119 @@
+import type { KeyBinding as KeyBindingEnum } from "../enums/index";
+import type { LooseString } from "../../shared/nominal";
+
+/**
+ * `sandkit.api.input` — key bindings, mouse position, and modifier keys.
+ * Main thread only.
+ */
+export namespace input {
+  /**
+   * Register a key binding and return its binding id.
+   * @param bindingId - Unique id for the binding (also used in settings).
+   * @param defaultKeys - Default key codes (for example `"Control+KeyC"`).
+   * @param definition - Display metadata and press/release handlers.
+   * @returns The registered binding id.
+   */
+  export function registerBinding(bindingId: BindingId, defaultKeys: KeyCode[], definition: InputBindingDefinition): BindingId;
+
+  /**
+   * Return the mouse position in cell coordinates.
+   * @returns Cell `{ x, y }` under the cursor.
+   */
+  export function getMouseCellPosition(): { x: number; y: number; };
+
+  /**
+   * Return the keys currently bound to a binding id.
+   * @param bindingId - Registered binding id.
+   * @returns Key strings from settings (for example `"KeyA"` or `"Shift"`).
+   * Session `input.keys` is keyed by `KeyboardEvent.code`. Modifier aliases
+   * (`Shift`, `Alt`, `Control`, `Meta`) expand to `ShiftLeft` / `ShiftRight` and the same for the other modifiers.
+   */
+  export function getBoundKeys(bindingId: BindingId): KeyCode[];
+
+  /**
+   * Return a display label for the bound key.
+   * @param bindingId - Registered binding id.
+   * @param defaultLabel - Fallback label when no key is bound.
+   * @returns Human-readable key label for UI.
+   */
+  export function getDisplayKey(bindingId: BindingId, defaultLabel?: string): string;
+
+  /**
+   * Fire the binding down handler as if the key was pressed.
+   * @param bindingId - Registered binding id.
+   */
+  export function triggerBinding(bindingId: BindingId): void;
+
+  /**
+   * Fire the binding down handler without a matching release.
+   * @param bindingId - Registered binding id.
+   */
+  export function pressBinding(bindingId: BindingId): void;
+
+  /**
+   * Fire the binding up handler.
+   * @param bindingId - Registered binding id.
+   */
+  export function releaseBinding(bindingId: BindingId): void;
+
+  /** Clear internal mouse button state. */
+  export function resetMouseState(): void;
+
+  /**
+   * Return true when Ctrl is held.
+   * @returns True when the Ctrl modifier is down.
+   */
+  export function isCtrlHeld(): boolean;
+
+  /**
+   * Return true when Alt is held.
+   * @returns True when the Alt modifier is down.
+   */
+  export function isAltHeld(): boolean;
+
+  /**
+   * Binding id. Vanilla {@link KeyBindingEnum} names autocomplete; custom ids are allowed.
+   */
+  export type BindingId = LooseString<`${KeyBindingEnum}`>;
+
+  /**
+   * KeyboardEvent.code, a modifier alias (`Shift`), or a chord (`Control+KeyC`).
+   */
+  export type KeyCode = LooseString<
+    | "Shift"
+    | "Alt"
+    | "Control"
+    | "Meta"
+    | "ShiftLeft"
+    | "ShiftRight"
+    | "AltLeft"
+    | "AltRight"
+    | "ControlLeft"
+    | "ControlRight"
+    | "MetaLeft"
+    | "MetaRight"
+  >;
+
+  /** Handlers invoked when a binding is pressed or released. */
+  export interface InputBindingHandlers {
+    /** Called when the binding is pressed. */
+    down?: () => void;
+    /** Called when the binding is released. */
+    up?: () => void;
+  }
+
+  /** Definition for a registered input binding. */
+  export interface InputBindingDefinition {
+    /** Display name shown in settings. */
+    displayName: string;
+    /** i18n key for the display name (overrides displayName when set). */
+    displayNameKey?: string;
+    /** Settings category for grouping. */
+    category: string;
+    /** Press and release handlers. */
+    handlers: InputBindingHandlers;
+
+    // Temporary until we're sure we have the full definition.
+    [key: string]: unknown;
+  }
+}

package/sandkit/api/items.d.ts

@@ -0,0 +1,60 @@
+import type { ItemId as ItemIdEnum, ItemType as ItemTypeEnum } from "../enums/index";
+import type { LooseString, TaggedNumber } from "../../shared/nominal";
+
+/**
+ * `sandkit.api.items` — register custom inventory items and query active items.
+ * Main thread only.
+ */
+export namespace items {
+  /** Definition for a mod-registered inventory item. */
+  export interface ItemDefinition<State = unknown, Action = unknown> {
+    /** Handles item use actions. */
+    handleAction?: (state: State, action: Action) => unknown;
+    /** Called after the item is rendered each frame. */
+    afterRender?: (state: State) => void;
+    [key: string]: unknown;
+  }
+
+  /**
+   * Registers a new item definition.
+   * @param definition - Item id, handlers, and display metadata.
+   */
+  export function register(definition: ItemDefinition): void;
+  /**
+   * Updates fields on an existing item definition.
+   * @param itemId - Registered item id.
+   * @param partial - Fields to merge into the definition.
+   */
+  export function updateDefinition(itemId: ItemId, partial: Partial<ItemDefinition>): void;
+  /**
+   * Returns the item definition for an id, or undefined.
+   * @param itemId - Registered item id.
+   */
+  export function getDefinitionById(itemId: ItemId): ItemDefinition | undefined;
+  /**
+   * Creates a runtime item instance from an id.
+   * @param itemId - Registered item id.
+   */
+  export function createFromId(itemId: ItemId): ModItem;
+  /** Returns the item definition for the active hotbar slot. */
+  export function getActive(): ItemDefinition | undefined;
+  /**
+   * Returns true when the given item is the active hotbar item.
+   * @param itemId - Item id or numeric type to compare.
+   * @param itemType - Optional item type discriminator.
+   */
+  export function isActiveById(itemId: ItemId, itemType?: ItemType): boolean;
+
+  /**
+   * Inventory item id.
+   * Built-in {@link ItemIdEnum} values autocomplete; custom string ids are allowed.
+   */
+  export type ItemId = ItemIdEnum | LooseString<never>;
+  /**
+   * Item category handle.
+   * Built-in {@link ItemTypeEnum} values autocomplete.
+   */
+  export type ItemType = ItemTypeEnum | TaggedNumber<"itemType">;
+  /** Runtime item instance (not yet typed in declarations). */
+  export type ModItem = unknown;
+}

package/sandkit/api/lights.d.ts

@@ -0,0 +1,66 @@
+import type { shared } from "../../shared";
+
+/**
+ * `sandkit.api.lights` — temporary VFX lights and persistent world lights.
+ * Main thread only.
+ */
+export namespace lights {
+  /** Short-lived visual effect lights. */
+  export namespace vfx {
+    /**
+     * Creates a temporary light at world coordinates.
+     * @param worldX - World X coordinate in pixels.
+     * @param worldY - World Y coordinate in pixels.
+     * @param options - Brightness, duration, color, and dedup options.
+     */
+    export function createAtWorld(worldX: number, worldY: number, options?: TemporaryLightOptions): { index: number | null; };
+    /**
+     * Removes a temporary light by its id.
+     * @param lightId - Light index returned from {@link createAtWorld}.
+     */
+    export function removeById(lightId: number): void;
+  }
+
+  /** Lights that persist in the world save. */
+  export namespace persistent {
+    /**
+     * Creates a persistent light at world coordinates.
+     * @param worldX - World X coordinate in pixels.
+     * @param worldY - World Y coordinate in pixels.
+     * @param options - Brightness, size, color, and persistence options.
+     */
+    export function createAtWorld(worldX: number, worldY: number, options?: PersistentLightOptions): PersistentLightHandle;
+    /**
+     * Removes the persistent light at world coordinates.
+     * @param worldX - World X coordinate in pixels.
+     * @param worldY - World Y coordinate in pixels.
+     */
+    export function removeAtWorld(worldX: number, worldY: number): void;
+    /**
+     * Fades out the persistent light at world coordinates over durationMs.
+     * @param worldX - World X coordinate in pixels.
+     * @param worldY - World Y coordinate in pixels.
+     * @param durationMs - Fade duration in milliseconds.
+     */
+    export function fadeAtWorld(worldX: number, worldY: number, durationMs?: number): void;
+    /** Marks persistent lights dirty so they are saved on the next flush. */
+    export function markDirty(): void;
+  }
+
+  /** Options for temporary VFX lights. */
+  export type TemporaryLightOptions = shared.api.effects.TemporaryLightOptions;
+
+  /** Options for persistent world lights. */
+  export interface PersistentLightOptions {
+    /** Light brightness multiplier. */
+    brightness?: number;
+    /** Light radius in pixels. */
+    size?: number;
+    /** RGBA color components. */
+    color?: [number, number, number, number];
+    [key: string]: unknown;
+  }
+
+  /** Handle returned from {@link persistent.createAtWorld}. */
+  export type PersistentLightHandle = unknown
+}

package/sandkit/api/maps.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Map selection and session start.
+ *
+ * Available as `sandkit.api.maps`.
+ *
+ * @module
+ */
+import { shared } from "../../shared";
+
+export namespace maps {
+  // Shared
+  /** Return the active map for this session. */
+  export import getActive = shared.api.maps.getActive
+  /** Active map data shape. */
+  export import ActiveMapV1 = shared.api.maps.ActiveMapV1
+
+  /** Return maps the player can start. */
+  export function getAvailable(): readonly Readonly<AvailableMapV1>[];
+  /**
+   * Start a map by id. Return true when start succeeds.
+   * @param mapId - Custom map identifier.
+   */
+  export function start(mapId: string): boolean;
+
+  /** Available map entry shape. */
+  export interface AvailableMapV1 {
+    /** Map identifier passed to {@link start}. */
+    id: string;
+    /** Display name or translation key. */
+    name?: string;
+    [key: string]: unknown;
+  }
+}

package/sandkit/api/mods.d.ts

@@ -0,0 +1,18 @@
+import type { assets } from "./assets";
+
+/**
+ * Mod asset provider lookup.
+ *
+ * Available as `sandkit.api.mods`.
+ *
+ * @module
+ */
+export namespace mods {
+  /**
+   * Return asset providers registered for a kind string.
+   * @param kind - Asset kind identifier (e.g. texture pack category).
+   */
+  export function getProviders(kind: string): readonly AssetProviderV1[];
+  /** Asset provider entry shape. */
+  export type AssetProviderV1 = assets.AssetProviderV1
+}

package/sandkit/api/patterns.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Excavation patterns and cell-pattern helpers.
+ *
+ * Available as `sandkit.api.patterns`.
+ *
+ * @module
+ */
+import type { CellCoordinates, Vector2 } from "../../shared/player";
+import type { shared } from "../../shared";
+
+export namespace patterns {
+  /**
+   * Build a circular excavation pattern matrix for the given size.
+   * @param size - Pattern width and height in cells.
+   * @returns Square matrix with `1` inside the circle and `0` outside.
+   */
+  export function createCircle(size: number): number[][];
+
+  /**
+   * Excavate at a cell using a pattern matrix and output velocity.
+   * @param cellX - Anchor cell column for the pattern.
+   * @param cellY - Anchor cell row for the pattern.
+   * @param pattern - Excavation pattern matrix.
+   * @param outVelocity - Ejection velocity written into this vector.
+   * @param power - Dig strength applied to matched cells.
+   * @param options - Optional excavation source flags.
+   */
+  export function excavateAtCell(...args: [...CellCoordinates, pattern: number[][], outVelocity: Vector2, power: number, options?: PatternExcavateOptions]): void;
+
+  /** Options for pattern-based excavation. Same shape as {@link shared.api.world.ExcavateOptions}. */
+  export type PatternExcavateOptions = shared.api.world.ExcavateOptions;
+}

package/sandkit/api/player.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Player position, movement, inventory, and building unlocks.
+ *
+ * Available as `sandkit.api.player`.
+ *
+ * @module
+ */
+import { shared } from "../../shared";
+
+export namespace player {
+
+  // Shared
+  /** Return the player world position. */
+  export import getWorldPosition = shared.api.player.getWorldPosition
+  /** Return true when the player overlaps the given cell. */
+  export import isCollidingWithCell = shared.api.player.isCollidingWithCell
+  /** Return true when the player is within radius of the given cell. */
+  export import isWithinRadiusOfCell = shared.api.player.isWithinRadiusOfCell
+
+  /**
+   * Set the player world position.
+   * @param worldX - World x position in pixels.
+   * @param worldY - World y position in pixels.
+   */
+  export function setWorldPosition(worldX: number, worldY: number): void;
+
+  /**
+   * Set the player velocity.
+   * @param velocityX - Horizontal velocity in pixels per second.
+   * @param velocityY - Vertical velocity in pixels per second.
+   */
+  export function setVelocity(velocityX: number, velocityY: number): void;
+
+  /**
+   * Set the movement speed multiplier.
+   * @param multiplier - Speed scale factor (`1` is default walk). `0` freezes movement.
+   * Vanilla Sprint Boost (Shift burst + meter) only runs when this value is exactly `1`.
+   */
+  export function setMovementSpeedMultiplier(multiplier: number): void;
+
+  /**
+   * Set movement mode to normal or hover.
+   * @param mode - `"normal"` for default physics, or `"hover"` for hover flight.
+   * @returns True when the mode changes.
+   */
+  export function setMovementMode(mode: 'normal' | 'hover'): boolean;
+
+  /**
+   * Return true when the player is on ground.
+   * Tests solid cells 1 pixel below the hitbox. Do not use `player.onGround`
+   * on the store snapshot — that flag is not updated during play.
+   * @returns True when the player touches solid ground.
+   */
+  export function isOnGround(): boolean;
+
+  /** Move the player down until ground is found. */
+  export function teleportToGround(): void;
+
+  /**
+   * Return true when the world position has no collision.
+   * @param worldX - World x position in pixels to test.
+   * @param worldY - World y position in pixels to test.
+   * @returns True when the player hitbox fits at the position.
+   */
+  export function isWorldPositionClear(worldX: number, worldY: number): boolean;
+
+  /** Player inventory helpers. */
+  export namespace inventory {
+    /**
+     * Add an item to inventory by item id.
+     * @param itemId - Registered item id string.
+     */
+    export function addFromId(itemId: string): void;
+  }
+
+  /** Player building unlock helpers. */
+  export namespace buildings {
+    /**
+     * Unlock a structure type for building.
+     * @param structureId - Registered structure id string.
+     */
+    export function unlockByType(structureId: string): void;
+  }
+}

package/sandkit/api/processing.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Register processing recipes for grower, shaker, and kinetic press structures.
+ *
+ * Available as `sandkit.api.processing`.
+ *
+ * @module
+ */
+import type { elements } from "./elements";
+
+export namespace processing {
+  /**
+   * Register a planter box grower recipe.
+   * @param definition - Grower input/output recipe.
+   */
+  export function registerGrower(definition: PlanterBoxRecipeDefinitionV1): void;
+
+  /**
+   * Register a shaker recipe.
+   * @param definition - Shaker input and weighted outputs.
+   */
+  export function registerShaker(definition: ShakerRecipeDefinitionV1): void;
+
+  /**
+   * Register a kinetic press recipe.
+   * @param definition - Press input, velocity threshold, and outputs.
+   */
+  export function registerKineticPress(definition: KineticPressRecipeDefinitionV1): void;
+
+  /** Weighted element output entry shared by machine recipes. */
+  export interface WeightedRecipeOutput {
+    /** Output element type (1–255). */
+    elementType: elements.ElementType;
+    /** Output probability from 0 to 1. */
+    chance: number;
+  }
+
+  /** Planter box grower recipe definition. */
+  export interface PlanterBoxRecipeDefinitionV1 {
+    /** Input element type placed on the grower. */
+    input: elements.ElementType;
+    /** Output element type produced by the grower. */
+    output: elements.ElementType;
+    /** Success chance from 0 to 1. Default 1. */
+    chance?: number;
+  }
+
+  /** Shaker recipe definition. */
+  export interface ShakerRecipeDefinitionV1 {
+    /** Input element type dropped on the shaker. */
+    input: elements.ElementType;
+    /** Weighted outputs ejected upward. */
+    outputsAbove: WeightedRecipeOutput[];
+    /** Weighted outputs ejected downward. */
+    outputsBelow: WeightedRecipeOutput[];
+  }
+
+  /** Kinetic press recipe definition. */
+  export interface KineticPressRecipeDefinitionV1 {
+    /** Input element type processed by the press. */
+    input: elements.ElementType;
+    /** Minimum downward velocity required to trigger the press. */
+    minimumDownwardVelocity: number;
+    /** Weighted outputs produced by the press. */
+    outputs: WeightedRecipeOutput[];
+  }
+}

package/sandkit/api/progression.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Story and quest progression completion.
+ *
+ * Available as `sandkit.api.progression`.
+ *
+ * @module
+ */
+
+export namespace progression {
+  /**
+   * Mark a progression step complete. Return true when completion succeeds.
+   * @param request - Progression id and optional metadata for the step.
+   */
+  export function complete(request: ProgressionCompletionRequestV1): boolean;
+
+  /** Progression completion request shape. */
+  export interface ProgressionCompletionRequestV1 {
+    /** Progression step or quest identifier. */
+    id: string;
+    [key: string]: unknown;
+  }
+}

package/sandkit/api/projectiles.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Projectile definitions, spawning, and lifecycle.
+ *
+ * Available as `sandkit.api.projectiles`.
+ *
+ * @module
+ */
+export namespace projectiles {
+  /**
+   * Register a projectile definition.
+   * @param definition - Projectile id, sprite, and runtime options factory.
+   */
+  export function register(definition: ProjectileDefinition): void;
+
+  /**
+   * Return a projectile definition by string id.
+   * @param projectileId - Registered projectile id.
+   */
+  export function getDefinitionById(projectileId: string): ProjectileDefinition | undefined;
+
+  /**
+   * Build a spawn blueprint from a projectile string id.
+   * @param projectileId - Registered projectile id.
+   * @returns Blueprint passed to {@link spawnAtWorld}.
+   */
+  export function createBlueprintFromId(projectileId: string): ProjectileBlueprint;
+
+  /** Return all active projectiles. */
+  export function getAll(): Projectile[];
+
+  /**
+   * Return a projectile by numeric id.
+   * @param projectileId - Runtime projectile id.
+   */
+  export function getById(projectileId: number): Projectile | undefined;
+
+  /**
+   * Remove a projectile from the world.
+   * @param projectile - Projectile instance to remove.
+   */
+  export function remove(projectile: Projectile): void;
+
+  /**
+   * Spawn a projectile at world position with angle and blueprint.
+   * @param worldX - Spawn x position in world pixels.
+   * @param worldY - Spawn y position in world pixels.
+   * @param angle - Launch angle in radians.
+   * @param blueprint - Blueprint from {@link createBlueprintFromId}.
+   * @returns The spawned projectile instance.
+   */
+  export function spawnAtWorld(worldX: number, worldY: number, angle: number, blueprint: ProjectileBlueprint): Projectile;
+
+  /** Mod-registered projectile definition. */
+  export interface ProjectileDefinition {
+    id: string;
+    sprite: {
+      id: string;
+      tint?: number;
+    };
+    /** Returns spawn-time physics and visual options. */
+    getOptions: () => Record<string, unknown>;
+    /** Optional per-projectile mutable data factory. */
+    getModData?: (state: unknown, projectile: Projectile) => Record<string, unknown>;
+    [key: string]: unknown;
+  }
+
+  /** Blueprint used to spawn a projectile. */
+  export interface ProjectileBlueprint {
+    opts: Record<string, unknown>;
+    type: unknown;
+  }
+
+  /** Active projectile instance. */
+  export interface Projectile {
+    id: number;
+    x: number;
+    y: number;
+    [key: string]: unknown;
+  }
+}

package/sandkit/api/random.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Deterministic game random number helpers.
+ *
+ * Available as `sandkit.api.random`.
+ *
+ * @module
+ */
+export namespace random {
+  /**
+   * Return a random integer in the inclusive range.
+   * @param min - Minimum value (inclusive).
+   * @param max - Maximum value (inclusive).
+   */
+  export function int(min: number, max: number): number;
+  /**
+   * Return a random float in the inclusive range.
+   * @param min - Minimum value (inclusive).
+   * @param max - Maximum value (inclusive).
+   */
+  export function float(min: number, max: number): number;
+}