@sandustry-modding/types 0.1.0 → 0.3.1

package/sandkit/api/shared.d.ts

@@ -1,27 +0,0 @@
-/**
- * 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/terrains.d.ts

@@ -1,125 +0,0 @@
-/**
- * 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/world.d.ts

@@ -1,107 +0,0 @@
-/**
- * World cell queries, excavation, fog, redraw, and pickups.
- *
- * Available as `sandkit.api.world`.
- *
- * @module
- */
-import { CellCoordinates } from "../../shared/player";
-import { shared } from "../../shared";
-import type { WorldItemType as WorldItemTypeEnum } from "../enums/index";
-
-export namespace world {
-
-  /** Return cell id at a grid cell. */
-  export import getCellIdAtCell = shared.api.world.getCellIdAtCell;
-  /** Return true when the cell is empty. */
-  export import isCellEmptyAtCell = shared.api.world.isCellEmptyAtCell;
-  /** Return true when the cell holds terrain. */
-  export import isTerrainAtCell = shared.api.world.isTerrainAtCell;
-  /** Mark a cell as active for simulation this tick. */
-  export import reportActivityAtCell = shared.api.world.reportActivityAtCell;
-  /** Excavate at a cell with output velocity and damage. */
-  export import excavateAtCell = shared.api.world.excavateAtCell;
-  /** Options for {@link excavateAtCell}. */
-  export import ExcavateOptions = shared.api.world.ExcavateOptions;
-  /** Packed cell id from {@link getCellIdAtCell}. */
-  export import CellId = shared.api.world.CellId;
-
-  /**
-   * Run a callback when simulation is idle.
-   * @param callback - Function invoked on the main thread when workers are idle.
-   */
-  export function runWhenSimulationIdle(callback: () => void): void;
-
-  /**
-   * Reveal fog of war at a cell.
-   * @param cellX - Grid column of the target cell.
-   * @param cellY - Grid row of the target cell.
-   */
-  export function revealFogAtCell(...args: CellCoordinates): void;
-
-  /**
-   * Request redraw around a cell when simulation is idle.
-   * @param cellX - Grid column of the target cell.
-   * @param cellY - Grid row of the target cell.
-   * @param range - Radius in cells to redraw.
-   */
-  export function redrawAroundCellWhenIdle(...args: [...CellCoordinates, range: number]): void;
-
-  /** World item spawn, pickup, and lookup. */
-  export namespace pickups {
-    /**
-     * Spawn a world pickup at world position.
-     * @param type - Pickup type discriminator.
-     * @param worldX - World x position in pixels.
-     * @param worldY - World y position in pixels.
-     * @param data - Optional per-item data bag copied onto the instance.
-     * @param light - Optional point light spawned with the pickup.
-     * @returns The spawned world item instance.
-     */
-    export function spawnAtWorld(type: WorldItemType, worldX: number, worldY: number, data?: Record<string, unknown>, light?: WorldItemLight): WorldItem;
-
-    /**
-     * Destroy a world pickup instance.
-     * @param worldItem - World item returned from spawn or lookup helpers.
-     */
-    export function destroy(worldItem: WorldItem): void;
-
-    /**
-     * Pick up a world item into inventory.
-     * @param worldItem - World item to pick up.
-     * @returns True when the item was collected.
-     */
-    export function pickUp(worldItem: WorldItem): boolean;
-
-    /** Return all active world pickups. */
-    export function getAll(): WorldItem[];
-
-    /**
-     * Return a world pickup by numeric id.
-     * @param worldItemId - Runtime world item id.
-     */
-    export function getById(worldItemId: number): WorldItem | undefined;
-  }
-
-  /** World pickup type discriminator. */
-  export type WorldItemType = WorldItemTypeEnum;
-
-  /** Optional point light attached when spawning a pickup. */
-  export interface WorldItemLight {
-    /** Light brightness multiplier. Default 1. */
-    brightness?: number;
-    /** Light radius in world pixels. Default 100. */
-    size?: number;
-    /** RGB or RGBA color components in 0–1 range. */
-    color?: [number, number, number] | [number, number, number, number];
-  }
-
-  /** Active world pickup instance. */
-  export interface WorldItem {
-    id: number;
-    x: number;
-    y: number;
-    type: WorldItemType;
-    data: Record<string, unknown>;
-  }
-}

package/shared/api/terrains.d.ts

@@ -1,100 +0,0 @@
-import type { CellCoordinates } from "../../shared/player";
-import type { CellId, LooseString, TaggedNumber } from "../nominal";
-import type { CellType as CellTypeEnum } from "../../sandkit/enums/index";
-
-/**
- * Shared `sandkit.api.terrains` base — terrain type lookup and cell mutation.
- *
- * @internal Base namespace reused by main and worker declarations.
- */
-export namespace terrains {
-  /**
-   * Resolve a terrain string id to a numeric cell type.
-   * @param terrainId - Mod-registered or built-in terrain id.
-   * @returns Numeric terrain cell type.
-   */
-  export function getTypeFromId(terrainId: TerrainId): TerrainType;
-
-  /**
-   * Return the terrain cell type at a cell, or null when none.
-   * @param cellX - Grid column of the target cell.
-   * @param cellY - Grid row of the target cell.
-   */
-  export function getTypeAtCell(...args: CellCoordinates): TerrainType | null;
-
-  /**
-   * Return terrain cell type and hit points at a cell.
-   * @param cellX - Grid column of the target cell.
-   * @param cellY - Grid row of the target cell.
-   * @returns Cell type and hp, or null when the cell is not terrain.
-   */
-  export function getDataAtCell(...args: CellCoordinates): { cellType: TerrainType; hp: number | null; } | null;
-
-  /**
-   * Return true when any terrain occupies the cell.
-   * @param cellX - Grid column of the target cell.
-   * @param cellY - Grid row of the target cell.
-   */
-  export function isAtCell(...args: CellCoordinates): boolean;
-
-  /**
-   * Return true when the cell terrain matches the given id.
-   * @param cellX - Grid column of the target cell.
-   * @param cellY - Grid row of the target cell.
-   * @param terrainId - Terrain string id to compare.
-   */
-  export function isTypeAtCell(...args: [...CellCoordinates, terrainId: TerrainId]): boolean;
-
-  /**
-   * Return true when a packed cell id refers to terrain.
-   * @param cellId - Packed cell id from {@link world.getCellIdAtCell}.
-   */
-  export function isCellIdTerrain(cellId: CellId): boolean;
-
-  /**
-   * Apply damage to terrain at a cell.
-   * @param cellX - Grid column of the target cell.
-   * @param cellY - Grid row of the target cell.
-   * @param damage - Damage amount to apply.
-   */
-  export function damageAtCell(...args: [...CellCoordinates, damage: number]): void;
-
-  /**
-   * Place terrain at an empty cell.
-   * @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 createAtCell(...args: [...CellCoordinates, terrainTypeOrId: TerrainRef, options?: TerrainMutationOptions]): void;
-
-  /**
-   * Replace existing terrain at a cell.
-   * @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 replaceAtCell(...args: [...CellCoordinates, terrainTypeOrId: TerrainRef, options?: TerrainMutationOptions]): void;
-
-  /**
-   * Remove terrain from a cell.
-   * @param cellX - Grid column of the target cell.
-   * @param cellY - Grid row of the target cell.
-   * @param options - Optional mutation flags.
-   */
-  export function removeAtCell(...args: [...CellCoordinates, options?: TerrainMutationOptions]): void;
-
-  /** Options for terrain create, replace, or remove calls. */
-  export interface TerrainMutationOptions {
-    /** Skip shadow updates around the changed cell. */
-    skipShadow?: boolean;
-  }
-
-  /** Numeric terrain / {@link CellTypeEnum} handle. */
-  export type TerrainType = CellTypeEnum | TaggedNumber<"terrainType">;
-  /** Mod or built-in terrain string id. */
-  export type TerrainId = LooseString<never>;
-  /** Type handle or string id accepted by mutation helpers. */
-  export type TerrainRef = TerrainType | TerrainId;
-}

package/worker/api/elements.d.ts

@@ -1,60 +0,0 @@
-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;
-}