@sandustry-modding/types 0.1.0 → 0.3.1

package/CHANGELOG.md

@@ -5,6 +5,42 @@ 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.1] - 2026-08-27
+
+### Fixed
+
+- Deep package imports such as `@sandustry-modding/types/sandkit/engine` (Node `exports` `*` matches one path segment; map file and `index.d.ts` targets under `src/`)
+- Ship root `CHANGELOG.md` and `LICENSE` in the npm tarball
+- Document ambient setup with `/// <reference types="@sandustry-modding/types" />` (do not list this package under `compilerOptions.types`)
+
+### Added
+
+- `npm run validate` gate: declaration typecheck, unit tests, and packed-tarball consumer probes
+
+## [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
@@ -16,4 +52,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Ambient `sandkit` free variable and type aliases via `global.d.ts`
 - Docsify API reference generated from the declarations
 
+[0.3.1]: https://github.com/sandustry-modding/SandustryTypes/releases/tag/v0.3.1
+[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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sandustry-modding
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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,14 +37,22 @@ 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):
+### Ambient types (preferred)
+
+Pull the host `sandkit` ambient into your project with a triple-slash reference. Put it at the top of `main.js` / `worker.js`, or in a small ambient `.d.ts` that your `tsconfig` / `jsconfig` includes:
+
+```ts
+/// <reference types="@sandustry-modding/types" />
+```
+
+That works in `.ts` and `.js` (including checked JS with `checkJs`).
+
+Do **not** list `@sandustry-modding/types` under `compilerOptions.types`. That list only loads packages from `node_modules/@types` (for example `"react"` or `"node"`).
+
+Deep declaration modules are also available, for example:
 
-```json
-{
-  "compilerOptions": {
-    "types": ["@sandustry-modding/types"]
-  }
-}
+```ts
+import type { RetroConsoleGame } from "@sandustry-modding/types/sandkit/engine";
 ```
 
 ## Usage
@@ -53,7 +63,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 +73,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/package.json

@@ -1,38 +1,89 @@
 {
   "name": "@sandustry-modding/types",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "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",
+    "./sandkit": {
+      "types": "./src/sandkit/index.d.ts"
+    },
+    "./sandkit/*": {
+      "types": [
+        "./src/sandkit/*.d.ts",
+        "./src/sandkit/*/index.d.ts"
+      ]
+    },
+    "./sandkit/*/*": {
+      "types": [
+        "./src/sandkit/*/*.d.ts",
+        "./src/sandkit/*/*/index.d.ts"
+      ]
+    },
+    "./sandkit/*/*/*": {
+      "types": [
+        "./src/sandkit/*/*/*.d.ts",
+        "./src/sandkit/*/*/*/index.d.ts"
+      ]
+    },
+    "./shared": {
+      "types": "./src/shared/index.d.ts"
+    },
+    "./shared/*": {
+      "types": [
+        "./src/shared/*.d.ts",
+        "./src/shared/*/index.d.ts"
+      ]
+    },
+    "./shared/*/*": {
+      "types": [
+        "./src/shared/*/*.d.ts",
+        "./src/shared/*/*/index.d.ts"
+      ]
+    },
+    "./worker": {
+      "types": "./src/worker/index.d.ts"
+    },
+    "./worker/*": {
+      "types": [
+        "./src/worker/*.d.ts",
+        "./src/worker/*/index.d.ts"
+      ]
+    },
+    "./worker/*/*": {
+      "types": [
+        "./src/worker/*/*.d.ts",
+        "./src/worker/*/*/index.d.ts"
+      ]
     }
   },
   "files": [
-    "global.d.ts",
-    "sandkit/**/*.d.ts",
-    "shared/**/*.d.ts",
-    "worker/**/*.d.ts",
+    "src/**/*.d.ts",
     "CHANGELOG.md",
     "LICENSE",
-    "README.md",
-    "ATTRIBUTION.md"
+    "README.md"
   ],
   "scripts": {
     "docs": "npm run docs:api && npm run docs:serve",
     "docs:api": "node scripts/generate-api-docs.mjs",
     "docs:serve": "npx --yes docsify-cli serve docs",
     "test": "node --test scripts/api-search.test.js",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "verify-package": "node scripts/verify-package.mjs",
+    "validate": "npm run typecheck && npm test && npm run verify-package",
+    "prepack": "npm run validate"
   },
   "devDependencies": {
     "@types/react": "^18.3.1",

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];
+  }
+}