@sandustry-modding/types 0.1.0

package/shared/index.d.ts

@@ -0,0 +1,25 @@
+import { ui as uiNs } from "./api/ui";
+import { player as playerNs } from "./api/player";
+import { world as worldNs } from "./api/world";
+import { terrains as terrainsNs } from "./api/terrains";
+import { structures as structuresNs } from "./api/structures";
+import { elements as elementsNs } from "./api/elements";
+import { maps as mapsNs } from "./api/maps";
+import { effects as effectsNs } from "./api/effects";
+import { shared as sharedBuffersNs } from "./api/shared";
+
+/** Shared main/worker API namespaces grouped under `shared.api`. */
+export namespace shared {
+  export namespace api {
+    export import ui = uiNs;
+    export import player = playerNs;
+    export import world = worldNs;
+    export import terrains = terrainsNs;
+    export import structures = structuresNs;
+    export import elements = elementsNs;
+    export import maps = mapsNs;
+    export import effects = effectsNs;
+    /** Cross-thread shared memory buffers. */
+    export import shared = sharedBuffersNs;
+  }
+}

package/shared/jsonvalue.d.ts

@@ -0,0 +1,30 @@
+/**
+ * JSON-serializable value shapes for mod payloads and storage.
+ *
+ * Used by APIs such as `sandkit.api.gameConfig` and mod storage helpers when
+ * values must round-trip through JSON.
+ *
+ * @internal Base types reused by API declarations. Not a runtime namespace.
+ */
+
+/**
+ * JSON object with string keys and {@link JsonValueV1} values.
+ *
+ * Use for open-ended config bags and serialized mod data.
+ */
+export interface JsonObjectV1 {
+  [key: string]: JsonValueV1
+}
+
+/**
+ * JSON value: primitive, object, array, or null.
+ *
+ * Does not include `undefined` — omit keys instead.
+ */
+export type JsonValueV1 =
+  | string
+  | number
+  | boolean
+  | JsonObjectV1
+  | JsonValueV1[]
+  | null;

package/shared/nominal.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Nominal helpers for Sandkit types.
+ *
+ * `LooseString` / `LooseNumber` keep autocomplete for known literals while
+ * still accepting any string or number (the `string & {}` / `number & {}` trick).
+ *
+ * `TaggedNumber` marks handles so an element type is not a cell id.
+ *
+ * @internal Not a runtime `sandkit` namespace.
+ */
+
+/**
+ * Known string literals plus any other string.
+ * `T | string` collapses to `string` and drops autocomplete.
+ */
+export type LooseString<T extends string> = T | (string & {});
+
+/**
+ * Known numeric literals plus any other number.
+ * `T | number` collapses to `number` and drops autocomplete.
+ */
+export type LooseNumber<T extends number> = T | (number & {});
+
+/**
+ * Number handle that does not mix with a different tag.
+ * Plain `number` is not assignable; numeric literals and enum members are.
+ */
+export type TaggedNumber<Tag extends string> = number & { readonly __tag?: Tag };
+
+/** Packed simulation cell id from `world.getCellIdAtCell`. */
+export type CellId = TaggedNumber<"cellId">;

package/shared/player.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Shared player and coordinate domain shapes.
+ *
+ * @internal Base types reused by main and worker API declarations. Not a
+ * runtime `sandkit` namespace.
+ */
+import { AssetRef } from "./asset";
+
+/**
+ * Grid cell position as `[cellX, cellY]`.
+ *
+ * Cell coordinates match `sandkit.api.*AtCell` helpers: column first, then row.
+ */
+export type CellCoordinates = [cellX: number, cellY: number]
+
+/**
+ * 2D vector in world or cell space.
+ *
+ * World positions use pixels. Cell helpers may return pixel or cell units
+ * depending on the API.
+ */
+export type Vector2 = {
+  /** Horizontal component. */
+  x: number;
+  /** Vertical component. */
+  y: number;
+};
+
+/**
+ * Live player state snapshot (read-only shape for mods).
+ *
+ * Reflects `sandkit.engine.state` / store player fields exposed to mods.
+ */
+export interface Player {
+  /** Player hitbox left edge in world pixels. */
+  x: number;
+  /** Player hitbox top edge in world pixels. */
+  y: number;
+  /** Player hitbox width in world pixels. */
+  width: number;
+  /** Player hitbox height in world pixels. */
+  height: number;
+  /** Current movement velocity in pixels per second. */
+  velocity: Vector2
+  /** Movement threshold accumulator used by physics. */
+  threshold: Vector2;
+  /**
+   * Spawn flag. Live physics does not update this field.
+   * Use `sandkit.api.player.isOnGround()` (solid cells 1px below the hitbox).
+   */
+  onGround: boolean;
+  /** Temporary speed-cap bonuses applied on each axis. */
+  speedCapOverdrive: {
+    x: {
+      dir: null;
+      active: boolean;
+      bonus: number;
+      releaseTime: number;
+      releaseBonus: number;
+    };
+    y: {
+      dir: null;
+      active: boolean;
+      bonus: number;
+      releaseTime: number;
+      releaseBonus: number;
+    };
+  };
+  /** Items currently held in the player inventory. */
+  inventory: InventoryItem[];
+  /** Structure type ids the player has unlocked for building. */
+  buildings: number[];
+  /** Tech tree nodes and their unlock metadata. */
+  tech: {
+    [key: string | number]: {
+      x: number,
+      y: number,
+      descriptionKey: string;
+      descriptionParams?: {
+        [key: string]: number;
+      };
+      cost: number;
+      branch: string;
+      nameKey?: string;
+      icon?: {
+        spriteName: string;
+      };
+      unlocks: {
+        structures?: string[];
+        items?: string[];
+        map?: boolean;
+      };
+      currencyType?: string;
+      isElectricity?: boolean;
+      electricityNodeStyle?: boolean;
+      requires?: (string | number)[];
+      isAlien?: boolean;
+      radiusUnlockPx?: number;
+      locked?: boolean;
+      threshold?: number;
+    };
+  };
+  /** Tech ids explicitly locked for this save. */
+  lockedTechs: { [key: string]: boolean },
+  /** Active world action, or null when idle. */
+  action: null;
+  /** Hotbar slots, active indices, and item sprites. */
+  hotbar: {
+    activeSlotIndex: number;
+    hotbarIndex: number;
+    bars: AssetRef[][];
+  };
+  /** True when the grappling hook is equipped or active. */
+  grapplingHook: boolean;
+  /** Cooldown timestamps for movement particles and slowdown. */
+  cooldowns: {
+    boostParticle: {
+      time: number;
+      last: number;
+    };
+    hoverParticle: {
+      time: number;
+      last: number;
+    };
+    slowdown: {
+      last: number;
+    };
+  };
+  /** True when hover movement mode is active. */
+  isHovering: boolean;
+  /** Per-weapon runtime metadata. */
+  weaponsMeta: {
+    rocketLauncher: {
+      ammo: {
+        current: number;
+        reload: {
+          last: number;
+        };
+        reloading: boolean;
+      };
+    };
+  };
+}
+
+/** One hotbar or inventory item entry. */
+export interface InventoryItem {
+  id: number,
+  itemType: number,
+  abilities: {
+    type: number,
+    levelRequirement?: number,
+    attributes: {
+      [key: string]: {
+        opts?: {
+          speed?: number,
+          angle?: number
+        },
+        type: number,
+        attributes?: {
+          blastRadius?: number
+        },
+      },
+    },
+    cooldown: {
+      time: number,
+      last: number
+    }
+  }[],
+  nameKey: string,
+  descriptionKey: string,
+  categoryKey: "excavation" | "utility" | "drones",
+  sprite?: AssetRef,
+}

package/worker/api/elements.d.ts

@@ -0,0 +1,60 @@
+import type { CellCoordinates } from "../../shared/player";
+import { shared } from "../../shared";
+
+/**
+ * Worker-thread `sandkit.api.elements` — shared reads plus direct mutations.
+ *
+ * Main thread uses `*WhenIdle` helpers instead of `createAtCell` /
+ * `replaceAtCell` / `removeAtCell`. Built on {@link elements} base shapes.
+ *
+ * @internal Worker extension; not interchangeable with main-thread
+ * `sandkit.api.elements`.
+ */
+export namespace elements {
+  /** Numeric id for a registered element type. */
+  export import ElementType = shared.api.elements.ElementType;
+  /** Mod or built-in element string id. */
+  export import ElementId = shared.api.elements.ElementId;
+  /** Type handle or string id accepted by lookup helpers. */
+  export import ElementRef = shared.api.elements.ElementRef;
+  /** Matter category for element physics behavior. */
+  export import MatterType = shared.api.elements.MatterType;
+  /** Full definition used to register a custom element. */
+  export import ElementDefinition = shared.api.elements.ElementDefinition;
+  /** Options for {@link createAtCell}. */
+  export import ElementCreateOptions = shared.api.elements.ElementCreateOptions;
+  /** Resolves a string element id to its numeric type. */
+  export import getTypeFromId = shared.api.elements.getTypeFromId;
+  /** Returns the definition for an element type. */
+  export import getDefinitionByType = shared.api.elements.getDefinitionByType;
+  /** Returns the element type at a cell, or null. */
+  export import getTypeAtCell = shared.api.elements.getTypeAtCell;
+  /** Returns the resolved element type at a cell, or null. */
+  export import getResolvedTypeAtCell = shared.api.elements.getResolvedTypeAtCell;
+  /** Returns the resolved element type from a cell id, or null. */
+  export import getResolvedTypeFromCellId = shared.api.elements.getResolvedTypeFromCellId;
+  /** Returns element info at a cell, or null. */
+  export import getInfoAtCell = shared.api.elements.getInfoAtCell;
+  /** Returns the matter type at a cell, or null. */
+  export import getMatterTypeAtCell = shared.api.elements.getMatterTypeAtCell;
+  /** Returns true when the cell contains the given element type. */
+  export import isTypeAtCell = shared.api.elements.isTypeAtCell;
+  /** Returns true when the element at the cell is free-falling. */
+  export import isFreeFallingAtCell = shared.api.elements.isFreeFallingAtCell;
+  /** Returns particle velocity at a cell, or null. */
+  export import getVelocityAtCell = shared.api.elements.getVelocityAtCell;
+  /** Returns a data field value at a cell, or null. */
+  export import getDataFieldAtCell = shared.api.elements.getDataFieldAtCell;
+
+  /**
+   * Create an element at a cell immediately on this worker.
+   * Main thread: use `createAtCellWhenIdle`.
+   * @param cellX - Grid column of the target cell.
+   * @param cellY - Grid row of the target cell.
+   * @param elementType - Element type to place.
+   * @param options - Optional spawn overrides.
+   */
+  export function createAtCell(
+    ...args: [...CellCoordinates, elementType: ElementType, options?: ElementCreateOptions]
+  ): void;
+}

package/worker/api/main.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Worker thread only.
+ *
+ * `sandkit.api.main` — send events to the main thread.
+ *
+ * @internal Base shape reused by {@link WorkerSandkitApi}. Main thread has a
+ * larger `sandkit.api` surface; do not assume parity.
+ */
+export namespace main {
+  /**
+   * Emit a custom event on the main thread.
+   * @param eventId - Registered event name.
+   * @param payload - Serializable payload passed to main-thread listeners.
+   */
+  export function emitEvent<Payload = any>(eventId: string, payload: Payload): void;
+}

package/worker/api/shared.d.ts

@@ -0,0 +1,38 @@
+// Aliased: this module declares its own `shared` namespace below.
+import { shared as sharedApi } from "../../shared";
+
+/**
+ * Worker thread only.
+ *
+ * `sandkit.api.shared` — shared memory buffers for workers.
+ *
+ * Workers **require** buffers created on the main thread. Main thread only
+ * **gets** existing buffers. See {@link shared} for the shared base declarations.
+ *
+ * @internal Worker extension of {@link shared}; not interchangeable with
+ * main-thread `sandkit.api.shared`.
+ */
+export namespace shared {
+  /** Named shared memory buffers for worker threads. */
+  export namespace buffers {
+    /**
+     * Attach to a named shared buffer on this worker.
+     *
+     * The buffer must already exist on the main thread with the same
+     * {@link SharedArrayType} and length as `config`.
+     *
+     * @param key - Buffer name shared across threads.
+     * @param config - Expected array type and length for validation.
+     */
+    export function require(key: string, config: { type: SharedArrayType; length: number; }): SharedArray;
+    /**
+     * Read an existing buffer without validating type or length.
+     * @param key - Buffer name shared across threads.
+     */
+    export import get = sharedApi.api.shared.buffers.get
+  }
+  /** Typed array backing store for a shared buffer. */
+  export import SharedArray = sharedApi.api.shared.SharedArray
+  /** Discriminator for the underlying typed array kind. */
+  export import SharedArrayType = sharedApi.api.shared.SharedArrayType
+}

package/worker/api/worker.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Worker thread only.
+ *
+ * `sandkit.api.worker` — identity of the current simulation worker.
+ *
+ * @internal Base shape reused by {@link WorkerSandkitApi}. Not the same as
+ * main-thread APIs.
+ */
+export namespace worker {
+  /**
+   * Return the zero-based index of this worker in the worker pool.
+   * @returns Worker index (`0` … `getCount() - 1`).
+   */
+  export function getIndex(): number;
+  /**
+   * Return the total number of simulation workers.
+   * @returns Worker count for the active simulation.
+   */
+  export function getCount(): number;
+}

package/worker/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Worker-thread `sandkit.api` namespaces.
+ *
+ * Prefer these declarations in `worker.js`. Type `sandkit.api` as
+ * {@link WorkerSandkitApi}. Do not assume main-thread methods exist here.
+ * See {@link sandkit.api} for the main-thread public API.
+ *
+ * @module worker
+ */
+export * from "./api/main"
+export * from "./api/shared"
+export * from "./api/worker"
+export * from "./api/elements"
+
+// Shared files
+export * from "../sandkit/api/collector"
+export * from "../sandkit/api/fire"
+export * from "../sandkit/api/hooks"
+export * from "../shared/api/maps"
+export * from "../sandkit/api/patterns"
+export * from "../shared/api/player"
+export * from "../sandkit/api/random"
+export * from "../shared/api/structures"
+export * from "../shared/api/terrains"
+export * from "../shared/api/ui"
+export * from "../sandkit/api/utils"
+export * from "../shared/api/world"
+
+export type { WorkerSandkitApi } from "./sandkit-api"

package/worker/sandkit-api.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Composed worker-thread `sandkit.api` object.
+ *
+ * Namespace members are documented under {@link worker}. Use this type in
+ * `worker.js` / `worker.ts`:
+ *
+ * ```ts
+ * const api = sandkit.api as unknown as WorkerSandkitApi;
+ * ```
+ *
+ * Main and worker surfaces overlap but are not interchangeable. Do not use
+ * {@link sandkit.SandkitApi} on worker threads.
+ */
+export type WorkerSandkitApi = {
+  collector: typeof import("../sandkit/api/collector").collector;
+  elements: typeof import("./api/elements").elements;
+  fire: typeof import("../sandkit/api/fire").fire;
+  hooks: typeof import("../sandkit/api/hooks").hooks;
+  main: typeof import("./api/main").main;
+  maps: typeof import("../shared/api/maps").maps;
+  patterns: typeof import("../sandkit/api/patterns").patterns;
+  player: typeof import("../shared/api/player").player;
+  random: typeof import("../sandkit/api/random").random;
+  shared: typeof import("./api/shared").shared;
+  structures: typeof import("../shared/api/structures").structures;
+  terrains: typeof import("../shared/api/terrains").terrains;
+  ui: typeof import("../shared/api/ui").ui;
+  utils: typeof import("../sandkit/api/utils").utils;
+  worker: typeof import("./api/worker").worker;
+  world: typeof import("../shared/api/world").world;
+};