@sandustry-modding/types 0.1.0

package/sandkit/api/structures.d.ts

@@ -0,0 +1,320 @@
+/**
+ * Structure registration, queries, recipes, and idle mutations.
+ *
+ * Available as `sandkit.api.structures`.
+ *
+ * @module
+ */
+import { CellCoordinates, Vector2 } from "../../shared/player";
+import { shared } from "../../shared";
+// Aliased: `structures` declares a nested `processing` namespace that would
+// otherwise shadow this import.
+import { processing as processingApi } from "./processing";
+
+export namespace structures {
+
+  /** Call callback for each structure of the given type. */
+  export import forEachOfType = shared.api.structures.forEachOfType;
+  /** Return the structure at a cell, or null. */
+  export import getAtCell = shared.api.structures.getAtCell;
+  /** Return the definition for a structure type. */
+  export import getDefinitionByType = shared.api.structures.getDefinitionByType;
+  /** Resolve a string structure id to its type. */
+  export import getTypeFromId = shared.api.structures.getTypeFromId;
+  /** Return true when a built structure exists at the cell. */
+  export import hasBuiltAtCell = shared.api.structures.hasBuiltAtCell;
+  /** Return true when a structure matches a string id. */
+  export import isType = shared.api.structures.isType;
+  /** Return true when the cell structure matches a string id. */
+  export import isTypeAtCell = shared.api.structures.isTypeAtCell;
+  /** Set spritesheet index on a structure instance. */
+  export import setSpritesheetIndex = shared.api.structures.setSpritesheetIndex;
+  /** Set spritesheet index on the structure at a cell. */
+  export import setSpritesheetIndexAtCell = shared.api.structures.setSpritesheetIndexAtCell;
+  /** Map a value through thresholds to a spritesheet index on a structure. */
+  export import setSpritesheetIndexByValue = shared.api.structures.setSpritesheetIndexByValue;
+  /** Map a value through thresholds to a spritesheet index at a cell. */
+  export import setSpritesheetIndexByValueAtCell = shared.api.structures.setSpritesheetIndexByValueAtCell;
+  /** Push structure state updates to the game and workers. */
+  export import update = shared.api.structures.update;
+  /** Set partial data on a structure instance. */
+  export import setData = shared.api.structures.setData;
+  /** Structure instance in the world. */
+  export import Structure = shared.api.structures.Structure;
+  /** Structure type id or enum value. */
+  export import StructureType = shared.api.structures.StructureType;
+  /** Mod or built-in structure string id. */
+  export import StructureId = shared.api.structures.StructureId;
+  /** Type handle or string id accepted by lookup helpers. */
+  export import StructureRef = shared.api.structures.StructureRef;
+
+  /**
+   * Register a structure processor handler.
+   * @param structureId - Structure type or string id to attach the processor to.
+   * @param definition - Periodic processing interval and callback.
+   */
+  export function addProcessor(structureId: StructureRef, definition: StructureProcessorDefinitionV1): void;
+
+  /**
+   * Register a new structure definition.
+   * @param definition - Full structure definition.
+   * @param options - When `useRawShape` is true, keep the shape matrix as-is.
+   */
+  export function register(definition: SandkitStructureDefinition, options?: { useRawShape?: boolean; }): void;
+
+  /**
+   * Patch fields on an existing structure definition.
+   * @param structureTypeOrId - Structure type value or string id.
+   * @param partial - Fields to merge onto the definition.
+   * @param options - When `useRawShape` is true, keep the shape matrix as-is.
+   */
+  export function updateDefinition(structureTypeOrId: StructureRef, partial: Partial<SandkitStructureDefinition>, options?: { useRawShape?: boolean; }): void;
+
+  /**
+   * Add a rotated variant to a base structure type.
+   * @param baseStructureTypeOrId - Base structure type or id.
+   * @param variant - Variant id and supported rotation angles.
+   * @param options - Optional build-mode wiring for the variant.
+   */
+  export function addVariant(baseStructureTypeOrId: StructureRef, variant: { id: StructureRef; angles: number[]; }, options?: { addBuildMode?: unknown; }): void;
+
+  /**
+   * Register placement rules for a structure.
+   * @param definition - Hotbar placement field configuration.
+   */
+  export function registerPlacementConfig(definition: PlacementConfigDefinition): void;
+
+  /** Return structure types unlocked for building. */
+  export function getUnlockedTypes(): Set<StructureRef>;
+
+  /**
+   * Return true when the player blocks building at the cell.
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   */
+  export function isBlockedByPlayerAtCell(...args: CellCoordinates): boolean;
+
+  /**
+   * Return true when a launcher structure is at the cell.
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   */
+  export function isLauncherAtCell(...args: CellCoordinates): boolean;
+
+  /**
+   * Return true when a structure type is unlocked.
+   * @param structureType - Structure type value or string id.
+   */
+  export function isUnlockedByType(structureType: StructureRef): boolean;
+
+  /**
+   * Map a numeric value through thresholds to a spritesheet index.
+   * @param value - Numeric value to map.
+   * @param thresholds - Ascending threshold values.
+   * @returns Spritesheet frame index.
+   */
+  export function mapValueToSpritesheetIndex(value: number, thresholds: number[]): number;
+
+  /**
+   * Build a structure at a cell when simulation is idle.
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @param structureTypeOrId - Structure type or string id to build.
+   * @param options - Optional build overrides.
+   */
+  export function buildAtCellWhenIdle(...args: [...CellCoordinates, structureTypeOrId: StructureRef, options?: StructureBuildOptions]): void;
+
+  /**
+   * Remove a structure at a cell when simulation is idle.
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @param options - Optional removal flags.
+   */
+  export function removeAtCellWhenIdle(...args: [...CellCoordinates, options?: StructureRemovalOptions]): void;
+
+  /**
+   * Remove structures between two cells when simulation is idle.
+   * @param startCellX - Start cell column.
+   * @param startCellY - Start cell row.
+   * @param endCellX - End cell column.
+   * @param endCellY - End cell row.
+   * @param options - Optional bulk-removal flags.
+   */
+  export function removeBetweenCellsWhenIdle(startCellX: number, startCellY: number, endCellX: number, endCellY: number, options?: StructureBulkRemovalOptions): void;
+
+  /**
+   * Remove structures at many cells when simulation is idle.
+   * @param positions - Cell positions to clear.
+   * @param options - Optional bulk-removal flags.
+   */
+  export function removeAtCellsWhenIdle(positions: Vector2[], options?: StructureBulkRemovalOptions): void;
+
+  /** Structure recipe registration by machine kind. */
+  export namespace recipes {
+    /**
+     * Register a planter box recipe.
+     * @param id - Machine recipe slot id.
+     * @param definition - Grower recipe definition.
+     */
+    export function register(id: 'planterBox', definition: PlanterBoxRecipeDefinitionV1): void;
+
+    /**
+     * Register a shaker recipe.
+     * @param id - Machine recipe slot id.
+     * @param definition - Shaker recipe definition.
+     */
+    export function register(id: 'shaker', definition: ShakerRecipeDefinitionV1): void;
+
+    /**
+     * Register a kinetic press recipe.
+     * @param id - Machine recipe slot id.
+     * @param definition - Kinetic press recipe definition.
+     */
+    export function register(id: 'kineticPress', definition: KineticPressRecipeDefinitionV1): void;
+
+    /**
+     * Register a weighted refinery machine recipe.
+     * @param id - Refinery machine id.
+     * @param definition - Weighted input/output recipe.
+     */
+    export function register(id: 'condenser' | 'steamDryer' | 'synthesizer' | 'snowmaker' | 'smelter', definition: WeightedRefineryRecipeDefinitionV1): void;
+  }
+
+  /** Per-structure processing enablement and registration. */
+  export namespace processing {
+    /** Return true when processing is enabled at a cell. */
+    export import isEnabledAt = shared.api.structures.processing.isEnabledAt;
+
+    /**
+     * Register a custom processing definition by id.
+     * @param id - Unique processing registration id.
+     * @param definition - Structure type, interval, and callback.
+     */
+    export function register(id: StructureId, definition: StructureProcessingDefinitionV1): void;
+
+    /**
+     * Enable or disable processing at a cell.
+     * @param cellX - Grid column of the target cell.
+     * @param cellY - Grid row of the target cell.
+     * @param enabled - Desired processing enabled state.
+     * @returns True when the enabled state changed.
+     */
+    export function setEnabledAt(...args: [...CellCoordinates, enabled: boolean]): boolean;
+  }
+
+  /** Build mode entry for a structure definition. */
+  export interface StructureBuildMode {
+    type: string;
+    directions?: string[];
+  }
+
+  /** Rotated variant entry for a structure definition. */
+  export interface StructureVariant {
+    id: StructureRef;
+    angles: number[];
+  }
+
+  /** Render settings for a structure definition. */
+  export interface StructureRender {
+    imageName?: string;
+    size?: { width: number; height: number };
+    offset?: { x: number; y: number };
+  }
+
+  /** Full structure definition registered with the game. */
+  export interface SandkitStructureDefinition {
+    id: StructureId;
+    nameKey?: string;
+    descriptionKey?: string;
+    categoryKey?: string;
+    order?: number;
+    buildModes?: StructureBuildMode[];
+    shape?: number[][];
+    variants?: StructureVariant[];
+    render?: StructureRender;
+    defaultData?: Record<string, unknown>;
+    [key: string]: unknown;
+  }
+
+  /** Options passed to {@link buildAtCellWhenIdle}. */
+  export interface StructureBuildOptions {
+    [key: string]: unknown;
+  }
+
+  /** Options passed to {@link removeAtCellWhenIdle}. */
+  export interface StructureRemovalOptions {
+    /** Also remove underlying terrain cells in the footprint. */
+    removeCells?: boolean;
+    /** Skip visual teardown effects. */
+    skipVisuals?: boolean;
+  }
+
+  /** Options passed to bulk structure removal helpers. */
+  export interface StructureBulkRemovalOptions {
+    removeCells?: boolean;
+    skipVisuals?: boolean;
+    /** When set, only remove structures at these positions. */
+    preserveUnselectable?: boolean;
+    onlyPositions?: Vector2[];
+  }
+
+  /** Periodic structure processor attached with {@link addProcessor}. */
+  export interface StructureProcessorDefinitionV1 {
+    /** Tick interval in milliseconds. Must be > 0. */
+    intervalMs: number;
+    /** Synchronous callback invoked for each structure instance. */
+    process: (state: unknown, structure: Structure) => void;
+  }
+
+  /** Placement hotbar field definition. */
+  export type PlacementConfigField =
+    | PlacementConfigIntegerField
+    | PlacementConfigChoiceField;
+
+  /** Integer placement field with optional bounds. */
+  export interface PlacementConfigIntegerField {
+    type: "integer";
+    id: string;
+    labelKey: string;
+    min?: number;
+    max?: number;
+    default?: number;
+  }
+
+  /** Choice placement field with labeled options. */
+  export interface PlacementConfigChoiceField {
+    type: "choice";
+    id: string;
+    labelKey: string;
+    options: readonly {
+      value: string;
+      labelKey: string;
+    }[];
+  }
+
+  /** Placement rule definition for a structure type. */
+  export interface PlacementConfigDefinition {
+    structureId: StructureId;
+    fields: PlacementConfigField[];
+  }
+
+  /** Planter box recipe definition shape. */
+  export type PlanterBoxRecipeDefinitionV1 = processingApi.PlanterBoxRecipeDefinitionV1;
+  /** Shaker recipe definition shape. */
+  export type ShakerRecipeDefinitionV1 = processingApi.ShakerRecipeDefinitionV1;
+  /** Kinetic press recipe definition shape. */
+  export type KineticPressRecipeDefinitionV1 = processingApi.KineticPressRecipeDefinitionV1;
+
+  /** Weighted refinery recipe definition shape. */
+  export interface WeightedRefineryRecipeDefinitionV1 {
+    input: processingApi.WeightedRecipeOutput["elementType"];
+    outputs: processingApi.WeightedRecipeOutput[];
+  }
+
+  /** Custom structure processing definition shape. */
+  export interface StructureProcessingDefinitionV1 {
+    structureType: StructureRef;
+    intervalMs: number;
+    process: (state: unknown, structure: Structure) => void;
+  }
+}

package/sandkit/api/tech.d.ts

@@ -0,0 +1,66 @@
+import type { Tech as TechEnum } from "../enums/index";
+import type { LooseString, TaggedNumber } from "../../shared/nominal";
+
+/**
+ * Tech tree definitions, nodes, and lock state.
+ *
+ * Available as `sandkit.api.tech`.
+ *
+ * @module
+ */
+export namespace tech {
+  /**
+   * Return a tech definition by string id.
+   * @param techId - Tech entry identifier.
+   */
+  export function getDefinitionById(techId: TechGridId): TechDefinition | undefined;
+  /**
+   * Patch fields on an existing tech definition.
+   * @param techId - Tech entry identifier.
+   * @param updates - Fields to merge into the definition.
+   */
+  export function updateDefinition(techId: TechGridId, updates: Partial<TechDefinition>): void;
+  /**
+   * Add a new tech definition by id.
+   * @param techId - Tech entry identifier.
+   * @param definition - Full tech definition to register.
+   */
+  export function addDefinition(techId: TechGridId, definition: TechDefinition): void;
+  /**
+   * Register a tech node on the grid with parent and position options.
+   * @param techId - Tech grid node id.
+   * @param definition - Tech definition for the node.
+   * @param options - Parent node id and optional preferred grid position.
+   */
+  export function registerNode(techId: TechGridId, definition: TechDefinition, options: { parentId: TechGridId; preferredPosition?: TechGridPosition; }): TechGridPosition;
+  /**
+   * Return true when a tech entry is locked.
+   * @param techId - Tech entry id (string or numeric enum).
+   */
+  export function isLockedById(techId: TechGridId): boolean;
+  /**
+   * Set locked state for a tech entry by id.
+   * @param techId - Tech entry id (string or numeric enum).
+   * @param locked - When true, the tech cannot be purchased.
+   */
+  export function setLockedById(techId: TechGridId, locked: boolean): void;
+
+  /**
+   * Tech grid node id.
+   * Built-in {@link TechEnum} values autocomplete; custom string ids and tagged handles are allowed.
+   */
+  export type TechGridId = TechEnum | LooseString<never> | TaggedNumber<"tech">;
+  /** Tech definition shape. */
+  export interface TechDefinition {
+    /** Display name translation key. */
+    nameKey?: string;
+    /** Description translation key. */
+    descriptionKey?: string;
+    [key: string]: unknown;
+  }
+  /** Position on the tech grid. */
+  export interface TechGridPosition {
+    x: number;
+    y: number;
+  }
+}

package/sandkit/api/terrains.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Terrain registration, queries, and idle cell mutations.
+ *
+ * Available as `sandkit.api.terrains`.
+ *
+ * @module
+ */
+import { CellCoordinates } from '../../shared/player';
+import { shared } from '../../shared';
+import type { elements } from './elements';
+
+export namespace terrains {
+
+  /** Resolve a terrain string id to its cell type number. */
+  export import getTypeFromId = shared.api.terrains.getTypeFromId;
+  /** Return terrain cell type at a cell, or null. */
+  export import getTypeAtCell = shared.api.terrains.getTypeAtCell;
+  /** Return terrain data at a cell, or null. */
+  export import getDataAtCell = shared.api.terrains.getDataAtCell;
+  /** Return true when any terrain exists at the cell. */
+  export import isAtCell = shared.api.terrains.isAtCell;
+  /** Return true when terrain at the cell matches a string id. */
+  export import isTypeAtCell = shared.api.terrains.isTypeAtCell;
+  /** Return true when a cell id represents terrain. */
+  export import isCellIdTerrain = shared.api.terrains.isCellIdTerrain;
+  /** Apply damage to terrain at a cell. */
+  export import damageAtCell = shared.api.terrains.damageAtCell;
+  /** Create terrain at a cell immediately. */
+  export import createAtCell = shared.api.terrains.createAtCell;
+  /** Replace terrain at a cell immediately. */
+  export import replaceAtCell = shared.api.terrains.replaceAtCell;
+  /** Remove terrain at a cell immediately. */
+  export import removeAtCell = shared.api.terrains.removeAtCell;
+  /** Options for terrain create, replace, and remove calls. */
+  export import TerrainMutationOptions = shared.api.terrains.TerrainMutationOptions;
+  /** Numeric terrain cell type handle. */
+  export import TerrainType = shared.api.terrains.TerrainType;
+  /** Mod or built-in terrain string id. */
+  export import TerrainId = shared.api.terrains.TerrainId;
+  /** Type handle or string id accepted by mutation helpers. */
+  export import TerrainRef = shared.api.terrains.TerrainRef;
+
+  /**
+   * Register a new terrain definition.
+   * @param definition - Terrain definition to register.
+   * @returns Object with the assigned `cellType`.
+   */
+  export function register(definition: TerrainDefinition): { cellType: TerrainType; };
+
+  /**
+   * Patch fields on an existing terrain definition.
+   * @param cellTypeOrId - Numeric cell type or terrain string id.
+   * @param partial - Fields to merge onto the definition.
+   */
+  export function updateDefinition(cellTypeOrId: TerrainRef, partial: Partial<TerrainDefinition>): void;
+
+  /**
+   * Create terrain at a cell when simulation is idle.
+   * @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 createAtCellWhenIdle(...args: [...CellCoordinates, terrainTypeOrId: TerrainRef, options?: TerrainMutationOptions]): void;
+
+  /**
+   * Replace terrain at a cell when simulation is idle.
+   * @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 replaceAtCellWhenIdle(...args: [...CellCoordinates, terrainTypeOrId: TerrainRef, options?: TerrainMutationOptions]): void;
+
+  /**
+   * Remove terrain at a cell when simulation is idle.
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @param options - Optional mutation flags.
+   */
+  export function removeAtCellWhenIdle(...args: [...CellCoordinates, options?: TerrainMutationOptions]): void;
+
+  /**
+   * Set terrain hit points at a cell when simulation is idle.
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @param hp - New hit point value.
+   */
+  export function setHpAtCellWhenIdle(...args: [...CellCoordinates, hp: number]): void;
+
+  /**
+   * Set terrain hit points at a cell immediately.
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @param hp - New hit point value.
+   * @returns True when hp changed or the terrain was removed.
+   */
+  export function setHpAtCell(...args: [...CellCoordinates, hp: number]): boolean;
+
+  /** Terrain definition shape for {@link register} and {@link updateDefinition}. */
+  export interface TerrainDefinition {
+    /** Unique mod-scoped terrain id. */
+    id: string;
+    /** i18n key for the terrain display name. */
+    nameKey?: string;
+    /** Default terrain hit points. */
+    hp?: number;
+    /** Material id used for rendering. Must be > obstacle breakpoint and < 150. */
+    materialId?: number;
+    /** UI/meta color as 0xRRGGBB. */
+    metaColor?: number;
+    /** Base terrain color as HSL components. */
+    colorHSL?: [number, number, number];
+    /** Tool item ids required to excavate this terrain. */
+    excavationRequirements?: readonly string[];
+    /** Tooltip interactions shown for this terrain. */
+    interactions?: readonly elements.Interaction[];
+    /** Default element drop when the terrain is destroyed. */
+    output?: {
+      elementType: elements.ElementType;
+      chance: number;
+    };
+    [key: string]: unknown;
+  }
+}

package/sandkit/api/time.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Game time in milliseconds and tick counter.
+ *
+ * Available as `sandkit.api.time`.
+ *
+ * @module
+ */
+export namespace time {
+  /** Return elapsed game time in milliseconds. */
+  export function getTimeMs(): number;
+  /** Return the current simulation tick number. */
+  export function getTick(): number;
+}

package/sandkit/api/tools.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Tool-specific API helpers.
+ *
+ * Available as `sandkit.api.tools`.
+ *
+ * @module
+ */
+export namespace tools {
+  /** Grabber tool size and state. */
+  export namespace grabber {
+    /**
+     * Set grabber radius size.
+     * @param size - Grab radius in cells.
+     */
+    export function setSize(size: number): void;
+
+    /**
+     * Return current grabber radius size.
+     * @returns Grab radius in cells.
+     */
+    export function getSize(): number;
+
+    /**
+     * Return true when grabber tool is active.
+     * @returns True when the grabber is the active tool.
+     */
+    export function isActive(): boolean;
+
+    /**
+     * Return true when grabber holds elements.
+     * @returns True when the grabber buffer is not empty.
+     */
+    export function isLoaded(): boolean;
+  }
+}

package/sandkit/api/triggers.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Interval-based main-thread trigger registration.
+ *
+ * Available as `sandkit.api.triggers`.
+ *
+ * @module
+ */
+export namespace triggers {
+  /**
+   * Register a repeating trigger with interval and callback.
+   * @param triggerId - Unique trigger identifier.
+   * @param definition - Interval in ticks and callback to invoke.
+   */
+  export function register(triggerId: string, definition: MainTriggerDefinition): void;
+
+  /** Main-thread trigger definition shape. */
+  export interface MainTriggerDefinition {
+    /** Interval between callbacks in simulation ticks. */
+    interval: number;
+    /** Called each time the trigger fires. */
+    callback: () => void;
+    [key: string]: unknown;
+  }
+}