@sandustry-modding/types 0.3.1 → 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;
 };