@sandustry-modding/types 0.1.0 → 0.3.0

package/README.md

@@ -2,21 +2,23 @@
 
 TypeScript declarations and Docsify API docs for the live Sandustry `sandkit` object. Package name: `@sandustry-modding/types`.
 
+Originally a fork of [flamableassassin/sandustry-modding-types](https://github.com/flamableassassin/sandustry-modding-types/).
+
 Folder layout mirrors runtime shape so you can jump from code to the matching `.d.ts` path.
 
 ## Runtime map
 
 | Path | Runtime object |
 | --- | --- |
-| `sandkit/api/` | `sandkit.api` (main thread) |
-| `sandkit/engine/api/` | `sandkit.engine.api` |
-| `sandkit/engine/state.d.ts` | `sandkit.engine.state` / `sandkit.state` |
-| `sandkit/enums/` | `sandkit.enums` |
-| `sandkit/react.d.ts` | `sandkit.react` |
-| `sandkit/index.d.ts` | Composed `Sandkit` root type |
-| `global.d.ts` | Ambient `sandkit` free variable and type aliases |
-| `worker/` | Worker-thread `sandkit.api` (see `WorkerSandkitApi`) |
-| `shared/` | Internal base shapes reused by main and worker declarations |
+| `src/sandkit/api/` | `sandkit.api` (main thread) |
+| `src/sandkit/engine/api/` | `sandkit.engine.api` |
+| `src/sandkit/engine/state.d.ts` | `sandkit.engine.state` / `sandkit.state` |
+| `src/sandkit/enums/` | `sandkit.enums` |
+| `src/sandkit/react.d.ts` | `sandkit.react` |
+| `src/sandkit/index.d.ts` | Composed `Sandkit` root type |
+| `src/global.d.ts` | Ambient `sandkit` free variable and type aliases |
+| `src/worker/` | Worker-thread `sandkit.api` (see `WorkerSandkitApi`) |
+| `src/shared/` | Internal base shapes reused by main and worker declarations |
 
 ## Runtime shape vs `export namespace`
 
@@ -35,7 +37,9 @@ Declaration files use `export namespace` because it is the usual `.d.ts` pattern
 npm install @sandustry-modding/types
 ```
 
-In `tsconfig.json`, include the package types (or reference them from an ambient file):
+### Project config (preferred)
+
+Add the package to `compilerOptions.types` in `tsconfig.json` or `jsconfig.json`:
 
 ```json
 {
@@ -45,6 +49,26 @@ In `tsconfig.json`, include the package types (or reference them from an ambient
 }
 ```
 
+If you already list other packages in `types` (for example `"react"` or `"node"`), keep those entries and add `"@sandustry-modding/types"` to the same array. A non-empty `types` list replaces TypeScript’s default auto-inclusion of all `@types/*` packages.
+
+`jsconfig.json` uses the same shape for JavaScript mods.
+
+### Per-file reference
+
+You can also pull the ambient types into one file:
+
+```ts
+/// <reference types="@sandustry-modding/types" />
+```
+
+That triple-slash directive works in `.ts` and `.js` (including checked JS with `checkJs`). Put it at the top of `main.js` / `worker.js`, or in a small ambient `.d.ts` included by your project.
+
+Deep declaration modules are also available, for example:
+
+```ts
+import type { RetroConsoleGame } from "@sandustry-modding/types/sandkit/engine";
+```
+
 ## Usage
 
 - **Main mod (`main.js`):** use the ambient free name `sandkit`. Type aliases such as `SandkitApi` are global; do not import a value binding.
@@ -53,7 +77,7 @@ In `tsconfig.json`, include the package types (or reference them from an ambient
 
 ## Maintaining types
 
-Edit `.d.ts` files here. Regenerate the Docsify API reference after JSDoc changes.
+Edit `.d.ts` files under `src/`. Regenerate the Docsify API reference after JSDoc changes.
 
 ## Docs site
 
@@ -63,4 +87,4 @@ Regenerate the Docsify API reference from these declarations:
 npm run docs:api
 ```
 
-Output lands in `docs/api/`. `npm run docs` runs that step, then serves the docs site.
+Output lands in `docs/api/`. The namespace index is `docs/modules.md` and the combined page is `docs/full.md`. `npm run docs` runs that step, then serves the docs site.

package/docs/Changelog.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2026-08-27
+
+### Changed
+
+- Move declaration sources into `src/` (`src/sandkit`, `src/worker`, `src/shared`, `src/global.d.ts`). Package subpaths such as `@sandustry-modding/types/sandkit/engine` stay the same
+- Show local names for API member headings in the Docsify reference (full runtime path stays under each heading)
+
+## [0.2.0] - 2026-08-27
+
+### Added
+
+- Official Sandkit API coverage from [sandustry.com/sandkit.html](https://sandustry.com/sandkit.html): `api.entities`, `api.pipes`, `api.factory`, `api.game`, `api.blueprints`, `api.pickups`, `api.grid.mutate`, and related worker surfaces
+- JSDoc `@see` links back to the official Sandkit page on documented members
+
+### Changed
+
+- Canonical mutation names match official docs (`createAtCell`, `grid.mutate`, `getTypeById`, and similar). Old names stay as `@deprecated` aliases (`*WhenIdle`, `api.world`, `getTypeFromId`, and similar)
+
+## [0.1.1] - 2026-08-27
+
+### Changed
+
+- Export subpaths (`./*`) so mods can import declaration modules such as `@sandustry-modding/types/sandkit/engine`
+
+## [0.1.0] - 2026-08-27
+
+### Added
+
+- Initial public release of `@sandustry-modding/types`
+- TypeScript declarations for main-thread `sandkit` (`sandkit/api`, `sandkit/engine`, `sandkit/enums`, `sandkit/react`)
+- Worker-thread declarations under `worker/` (`WorkerSandkitApi`)
+- Shared base shapes under `shared/` for main and worker reuse
+- Ambient `sandkit` free variable and type aliases via `global.d.ts`
+- Docsify API reference generated from the declarations
+
+[0.3.0]: https://github.com/sandustry-modding/SandustryTypes/releases/tag/v0.3.0
+[0.2.0]: https://github.com/sandustry-modding/SandustryTypes/releases/tag/v0.2.0
+[0.1.1]: https://github.com/sandustry-modding/SandustryTypes/releases/tag/v0.1.1
+[0.1.0]: https://github.com/sandustry-modding/SandustryTypes/releases/tag/v0.1.0

package/docs/README.md

@@ -0,0 +1,62 @@
+# Sandkit API
+
+> [!WARNING]
+> **Unofficial** community docs. Not affiliated with Lantto Games, Hooded Horse, or the [official Sandustry wiki](https://wiki.hoodedhorse.com/Sandustry/Sandustry_Official_Wiki). See the [official Sandkit docs](https://sandustry.com/sandkit.html).
+
+Community TypeScript reference for the live Sandustry `sandkit` host API. Package: [`@sandustry-modding/types`](https://www.npmjs.com/package/@sandustry-modding/types).
+
+## Start here
+
+| Go to | When you need |
+| --- | --- |
+| [Namespaces](modules.md) | Browse namespaces by group |
+| [Full API reference](full.md) | All namespaces on one page |
+| [Main thread](api/sandkit.api.md) | `main.js` APIs (`sandkit.api`) |
+| [Worker thread](api/sandkit.api.worker.md) | `worker.js` APIs (subset + direct mutations) |
+| [Engine](api/sandkit.engine.md) | Escape hatch (`sandkit.engine`) |
+| [Enums](api/sandkit.enums.md) | Runtime enum values |
+| [React](api/sandkit.react.md) | HUD JSX helpers |
+
+## Install types
+
+```bash
+npm install @sandustry-modding/types
+```
+
+### Project config (preferred)
+
+In `tsconfig.json` or `jsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@sandustry-modding/types"]
+  }
+}
+```
+
+If `types` already lists other packages (for example `"react"` or `"node"`), add `"@sandustry-modding/types"` to that array. A non-empty `types` list replaces auto-inclusion of all `@types/*` packages.
+
+### Per-file reference
+
+```ts
+/// <reference types="@sandustry-modding/types" />
+```
+
+Works in `.ts` and `.js` (including checked JS). Put it at the top of a source file, or in an ambient `.d.ts` included by the project.
+
+Use the ambient `sandkit` free name in `main.js`. In `worker.js`, type the API as `WorkerSandkitApi` — worker and main surfaces overlap but are not interchangeable.
+
+## Also useful
+
+- [Official Sandkit docs](https://sandustry.com/sandkit.html)
+- [Sandustry Mod Template](https://sandustry-modding.github.io/SandustryModTemplate/#/)
+- [Official Sandustry wiki](https://wiki.hoodedhorse.com/Sandustry/Sandustry_Official_Wiki)
+
+## Regenerate
+
+From the package repo root:
+
+```bash
+npm run docs:api
+```

package/package.json

@@ -1,31 +1,32 @@
 {
   "name": "@sandustry-modding/types",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "TypeScript declarations and API docs for the Sandustry Sandkit host API",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/sandustry-modding/SandustryTypes.git"
   },
-  "homepage": "https://github.com/sandustry-modding/SandustryTypes#readme",
+  "homepage": "https://sandustry-modding.github.io/SandustryTypes/",
   "bugs": {
     "url": "https://github.com/sandustry-modding/SandustryTypes/issues"
   },
-  "types": "./global.d.ts",
+  "types": "./src/global.d.ts",
   "exports": {
     ".": {
-      "types": "./global.d.ts"
+      "types": "./src/global.d.ts"
+    },
+    "./package.json": "./package.json",
+    "./*": {
+      "types": "./src/*"
     }
   },
   "files": [
-    "global.d.ts",
-    "sandkit/**/*.d.ts",
-    "shared/**/*.d.ts",
-    "worker/**/*.d.ts",
+    "src/**/*.d.ts",
     "CHANGELOG.md",
+    "docs/Changelog.md",
     "LICENSE",
-    "README.md",
-    "ATTRIBUTION.md"
+    "README.md"
   ],
   "scripts": {
     "docs": "npm run docs:api && npm run docs:serve",

package/src/sandkit/api/blueprints.d.ts

@@ -0,0 +1,33 @@
+import type { structures } from "../../shared/api/structures";
+
+/**
+ * Structure blueprint serialize and localize helpers.
+ *
+ * Available as `sandkit.api.blueprints`.
+ *
+ * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.blueprints`
+ */
+export namespace blueprints {
+  /**
+   * Serialize live structure instances into blueprint records.
+   *
+   * @param structures - Structure instances to encode.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.blueprints.serializeStructures`
+   */
+  export function serializeStructures(structures: readonly structures.Structure[]): BlueprintStructure[];
+
+  /**
+   * Localize blueprint structure records for placement.
+   *
+   * @param structures - Blueprint structure records to localize.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.blueprints.localizeStructures`
+   */
+  export function localizeStructures(structures: readonly BlueprintStructure[]): BlueprintStructure[];
+
+  /** Serialized structure entry used in blueprints. */
+  export interface BlueprintStructure {
+    x: number;
+    y: number;
+    [key: string]: unknown;
+  }
+}

package/src/sandkit/api/effects.d.ts

@@ -0,0 +1,127 @@
+import { shared } from "../../shared";
+
+/**
+ * `sandkit.api.effects` — visual effects, particles, and lasers at world positions.
+ * Main thread only. Temporary lights live under {@link lights.temporary}.
+ */
+export namespace effects {
+  /** Options for generic screen effects. */
+  export import EffectOptions = shared.api.effects.EffectOptions;
+  /** Options for temporary lights. */
+  export import TemporaryLightOptions = shared.api.effects.TemporaryLightOptions;
+  /** Options for particle effects. */
+  export import ParticleEffectOptions = shared.api.effects.ParticleEffectOptions;
+
+  /**
+   * Creates a named screen effect at world coordinates.
+   *
+   * @param effectId - Registered effect id (for example `heatWave`).
+   * @param worldX - World X coordinate in pixels.
+   * @param worldY - World Y coordinate in pixels.
+   * @param options - Duration, radius, and intensity settings.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.effects.createAtWorld`
+   */
+  export function createAtWorld(
+    effectId: string,
+    worldX: number,
+    worldY: number,
+    options?: EffectOptions,
+  ): void;
+
+  /**
+   * @deprecated Use {@link createAtWorld} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.effects.createAtWorld`
+   */
+  export function createEffectAtWorld(
+    effectId: string,
+    worldX: number,
+    worldY: number,
+    options?: EffectOptions,
+  ): void;
+
+  /**
+   * Spawns particles at world coordinates.
+   *
+   * @param worldX - World X coordinate in pixels.
+   * @param worldY - World Y coordinate in pixels.
+   * @param options - Count, velocity, colour, and lifetime settings.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.effects.createParticlesAtWorld`
+   */
+  export import createParticlesAtWorld = shared.api.effects.createParticlesAtWorld;
+
+  /**
+   * @deprecated Use {@link lights.temporary.createAtWorld} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.lights.temporary.createAtWorld`
+   */
+  export function createLightAtWorld(
+    worldX: number,
+    worldY: number,
+    options?: TemporaryLightOptions,
+  ): { lightId: number | null; index?: number | null; };
+
+  /**
+   * Creates a distortion wave effect at world coordinates.
+   *
+   * @param worldX - World X coordinate in pixels.
+   * @param worldY - World Y coordinate in pixels.
+   * @param options - Style, duration, radius, intensity, and color.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.effects.createDistortionWaveAtWorld`
+   */
+  export function createDistortionWaveAtWorld(worldX: number, worldY: number, options?: DistortionEffectOptions): void;
+
+  /**
+   * Creates a laser beam between two world points. Returns a handle to destroy it.
+   *
+   * @param startWorldX - Beam start world X in pixels.
+   * @param startWorldY - Beam start world Y in pixels.
+   * @param endWorldX - Beam end world X in pixels.
+   * @param endWorldY - Beam end world Y in pixels.
+   * @param options - Width, brightness, color, and glow options.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.effects.createLaserAtWorld`
+   */
+  export function createLaserAtWorld(
+    startWorldX: number,
+    startWorldY: number,
+    endWorldX: number,
+    endWorldY: number,
+    options?: LaserEffectOptions,
+  ): LaserEffectHandle;
+
+  /**
+   * @deprecated Use {@link lights.temporary.removeById} instead.
+   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.lights.temporary.removeById`
+   */
+  export function removeLightById(lightId: number): void;
+
+  /** Options for laser beam effects. */
+  export interface LaserEffectOptions {
+    /** Beam width in pixels. */
+    width?: number;
+    /** Beam brightness multiplier. */
+    brightness?: number;
+    /** Beam color as a packed integer. */
+    color?: number;
+    /** When true, draws a glow around the beam. */
+    glow?: boolean;
+  }
+
+  /** Handle returned by createLaserAtWorld. */
+  export interface LaserEffectHandle {
+    /** Removes the laser from the scene. */
+    destroy(): void;
+  }
+
+  /** Options for distortion wave effects. */
+  export interface DistortionEffectOptions {
+    /** Distortion style: implode or explode. */
+    style?: "implode" | "explode";
+    /** Effect duration in seconds. */
+    duration?: number;
+    /** Maximum radius of the wave. */
+    maxRadius?: number;
+    /** Visual intensity of the distortion. */
+    intensity?: number;
+    /** RGBA color components for the effect. */
+    color?: [number, number, number, number];
+  }
+}