@sandustry-modding/types 0.3.0 → 0.4.0

package/src/worker/api/hooks.d.ts

@@ -13,7 +13,65 @@ export namespace hooks {
    * @param hookId - Registered hook identifier.
    * @param callback - Called with hook arguments and context; may cancel the hook.
    * @param options - Optional guard and priority.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Worker entry `api.hooks.intercept`
+   *
+   * @example cell:process
+   * ```ts
+   * api.hooks.intercept("cell:process", handleCell, {
+   *   guard: { elementType },
+   * });
+   * ```
+   *
+   * @example element:update
+   * ```ts
+   * api.hooks.intercept("element:update", handleUpdate, {
+   *   guard: { elementType },
+   * });
+   * ```
+   *
+   * @example element:move
+   * ```ts
+   * api.hooks.intercept("element:move", (args, context) => {
+   *   handleElementMove(args, context);
+   * });
+   * ```
+   *
+   * @example element:move:blocked
+   * ```ts
+   * api.hooks.intercept(
+   *   "element:move:blocked",
+   *   (args, context) => {
+   *     handleBlockedMovement(args, context);
+   *   },
+   *   { guard: { elementType } },
+   * );
+   * ```
+   *
+   * @example element:duration:expire
+   * ```ts
+   * api.hooks.intercept(
+   *   "element:duration:expire",
+   *   (args, context) => {
+   *     handleDurationExpiry(args, context);
+   *   },
+   *   { guard: { elementType } },
+   * );
+   * ```
+   *
+   * @example fire:element:burn
+   * ```ts
+   * api.hooks.intercept("fire:element:burn", (args, context) => {
+   *   handleElementBurn(args, context);
+   * });
+   * ```
+   *
+   * @example shaker:elementOn
+   * ```ts
+   * api.hooks.intercept("shaker:elementOn", (args, context) => {
+   *   handleShakerElement(args, context);
+   * });
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function intercept<K extends InterceptHookId>(
     hookId: K,
@@ -27,7 +85,15 @@ export namespace hooks {
    * @param hookId - Registered hook identifier.
    * @param callback - Called with hook arguments; may mutate hook payload.
    * @param options - Optional guard and priority.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Worker entry `api.hooks.modify`
+   *
+   * @example Worker entry
+   * ```ts
+   * api.hooks.modify("example:prepare", (args) => {
+   *   args.value *= 2;
+   * });
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function modify<K extends ModifyHookId>(
     hookId: K,

package/src/worker/api/lights.d.ts

@@ -9,7 +9,7 @@ export namespace lights {
   /**
    * Short-lived visual effect lights.
    *
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Worker entry `api.lights.temporary`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export namespace temporary {
     /** Options for {@link createAtWorld}. */
@@ -21,7 +21,8 @@ export namespace lights {
       lightId: number | null;
       /**
        * @deprecated Use {@link lightId} instead.
-       * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `light.lightId`
+       *
+       * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
        */
       index?: number | null;
     }
@@ -32,7 +33,16 @@ export namespace lights {
      * @param worldX - World x position in pixels.
      * @param worldY - World y position in pixels.
      * @param options - Brightness, duration, colour, and dedup settings.
-     * @see https://sandustry.com/sandkit.html Official Sandkit API — Worker entry `api.lights.temporary.createAtWorld`
+     *
+     * @example Worker entry
+     * ```ts
+     * const light = api.lights.temporary.createAtWorld(worldX, worldY, {
+     *   durationTicks: 15,
+     * });
+     * const lightId = light.lightId;
+     * ```
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     export function createAtWorld(
       worldX: number,

package/src/worker/api/shared.d.ts

@@ -23,7 +23,16 @@ export namespace shared {
      *
      * @param key - Buffer name shared across threads.
      * @param config - Expected array type and length for validation.
-     * @see https://sandustry.com/sandkit.html Official Sandkit API — Worker entry `api.shared.buffers.require`
+     *
+     * @example
+     * ```ts
+     * const counts = api.shared.buffers.require("counts", {
+     *   type: "uint32",
+     *   length: 4,
+     * });
+     * ```
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     export function require(key: string, config: { type: SharedArrayType; length: number; }): SharedArray;
 
@@ -31,7 +40,8 @@ export namespace shared {
      * Read an existing buffer without validating type or length.
      *
      * @param key - Buffer name shared across threads.
-     * @see https://sandustry.com/sandkit.html Official Sandkit API — Worker entry `api.shared.buffers.get`
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     export import get = sharedApi.api.shared.buffers.get;
   }

package/src/worker/sandkit-api.d.ts

@@ -34,7 +34,8 @@ export type WorkerSandkitApi = {
   worker: typeof import("./api/worker").worker;
   /**
    * @deprecated Use {@link grid} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.grid`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   world: typeof import("./api/grid").world;
 };

package/docs/Changelog.md

@@ -1,46 +0,0 @@
-# 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

@@ -1,62 +0,0 @@
-# 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
-```