@sandustry-modding/types 0.3.1 → 0.4.0

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

@@ -13,7 +13,32 @@ export namespace lights {
      * @param worldX - World X coordinate in pixels.
      * @param worldY - World Y coordinate in pixels.
      * @param options - Brightness, duration, color, and dedup options.
-     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.lights.temporary.createAtWorld`
+     *
+     * @example Main entry
+     * ```ts
+     * const light = api.lights.temporary.createAtWorld(worldX, worldY, {
+     *   brightness: 1,
+     *   durationMs: 250,
+     *   size: 80,
+     * });
+     * const lightId = light.lightId;
+     * ```
+     *
+     * @example options.durationTicks
+     * ```ts
+     * api.lights.temporary.createAtWorld(worldX, worldY, {
+     *   durationTicks: 15,
+     * });
+     * ```
+     *
+     * @example options.durationMs
+     * ```ts
+     * api.lights.temporary.createAtWorld(worldX, worldY, {
+     *   durationMs: 250,
+     * });
+     * ```
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     export function createAtWorld(worldX: number, worldY: number, options?: TemporaryLightOptions): TemporaryLightHandle;
 
@@ -21,14 +46,23 @@ export namespace lights {
      * Remove a temporary light by its id.
      *
      * @param lightId - Light id returned from {@link createAtWorld}.
-     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.lights.temporary.removeById`
+     *
+     * @example
+     * ```ts
+     * if (light.lightId !== null) {
+     *   api.lights.temporary.removeById(light.lightId);
+     * }
+     * ```
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     export function removeById(lightId: number): void;
   }
 
   /**
    * @deprecated Use {@link temporary} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.lights.temporary`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export import vfx = temporary;
 
@@ -40,7 +74,17 @@ export namespace lights {
      * @param worldX - World X coordinate in pixels.
      * @param worldY - World Y coordinate in pixels.
      * @param options - Brightness, size, color, and persistence options.
-     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.lights.persistent.createAtWorld`
+     *
+     * @example
+     * ```ts
+     * const light = api.lights.persistent.createAtWorld(
+     *   worldX,
+     *   worldY,
+     *   { brightness: 1, size: 80 },
+     * );
+     * ```
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     export function createAtWorld(worldX: number, worldY: number, options?: PersistentLightOptions): PersistentLightHandle;
 
@@ -49,7 +93,8 @@ export namespace lights {
      *
      * @param worldX - World X coordinate in pixels.
      * @param worldY - World Y coordinate in pixels.
-     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.lights.persistent.removeAtWorld`
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     export function removeAtWorld(worldX: number, worldY: number): void;
 
@@ -59,14 +104,15 @@ export namespace lights {
      * @param worldX - World X coordinate in pixels.
      * @param worldY - World Y coordinate in pixels.
      * @param durationMs - Fade duration in milliseconds.
-     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.lights.persistent.fadeAtWorld`
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     export function fadeAtWorld(worldX: number, worldY: number, durationMs?: number): void;
 
     /**
      * Mark persistent lights dirty so they are saved on the next flush.
      *
-     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.lights.persistent.markDirty`
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     export function markDirty(): void;
   }
@@ -77,7 +123,8 @@ export namespace lights {
     lightId: number | null;
     /**
      * @deprecated Use {@link lightId} instead.
-     * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias on `api.lights.temporary.createAtWorld` return value
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     index: number | null;
   }

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

@@ -25,7 +25,16 @@ export namespace maps {
   /**
    * Return artifact marker locations for the active map.
    *
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.maps.getArtifactLocations`
+   * @example
+   * ```ts
+   * api.events.on("game:ready", () => {
+   *   api.maps.getArtifactLocations().forEach(({ cellX, cellY, name }) => {
+   *     addMarker(cellX, cellY, name);
+   *   });
+   * });
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getArtifactLocations(): readonly ArtifactLocation[];
 

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

@@ -24,6 +24,28 @@ export namespace patterns {
    * @param outVelocity - Ejection velocity written into this vector.
    * @param power - Dig strength applied to matched cells.
    * @param options - Optional excavation source flags.
+   *
+   * @example Main entry
+   * ```ts
+   * api.patterns.excavateAtCell(
+   *   cellX,
+   *   cellY,
+   *   api.patterns.createCircle(5),
+   *   { x: 0, y: -120 },
+   *   2,
+   * );
+   * ```
+   *
+   * @example Worker entry
+   * ```ts
+   * api.patterns.excavateAtCell(
+   *   cellX,
+   *   cellY,
+   *   pattern,
+   *   { x: 0, y: -1 },
+   *   10,
+   * );
+   * ```
    */
   export function excavateAtCell(...args: [...CellCoordinates, pattern: number[][], outVelocity: Vector2, power: number, options?: PatternExcavateOptions]): void;
 

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

@@ -5,7 +5,7 @@ import type { PickupType as PickupTypeEnum } from "../enums/index";
  *
  * Available as `sandkit.api.pickups`.
  *
- * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.pickups`
+ * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
  */
 export namespace pickups {
   /** Official pickup type discriminator. */
@@ -13,7 +13,8 @@ export namespace pickups {
 
   /**
    * @deprecated Use {@link PickupType} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.PickupType`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export type WorldItemType = PickupType;
 
@@ -45,7 +46,8 @@ export namespace pickups {
    * @param data - Optional per-item data bag copied onto the instance.
    * @param light - Optional point light spawned with the pickup.
    * @returns The spawned pickup instance.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.pickups.spawnAtWorld`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function spawnAtWorld(type: PickupType, worldX: number, worldY: number, data?: Record<string, unknown>, light?: WorldItemLight): WorldItem;
 
@@ -53,13 +55,15 @@ export namespace pickups {
    * Remove a pickup instance from the world.
    *
    * @param pickup - Pickup returned from spawn or lookup helpers.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.pickups.remove`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function remove(pickup: WorldItem): void;
 
   /**
    * @deprecated Use {@link remove} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.pickups.remove`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function destroy(pickup: WorldItem): void;
 
@@ -68,14 +72,15 @@ export namespace pickups {
    *
    * @param pickup - Pickup to collect.
    * @returns True when the item was collected.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.pickups.pickUp`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function pickUp(pickup: WorldItem): boolean;
 
   /**
    * Return all active pickups.
    *
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.pickups.getAll`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getAll(): WorldItem[];
 
@@ -83,7 +88,8 @@ export namespace pickups {
    * Return a pickup by numeric id.
    *
    * @param pickupId - Runtime pickup id.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.pickups.getById`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getById(pickupId: number): WorldItem | undefined;
 }

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

@@ -5,7 +5,7 @@ import type { CellCoordinates } from "../../shared/player";
  *
  * Available as `sandkit.api.pipes`.
  *
- * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.pipes`
+ * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
  */
 export namespace pipes {
   /**
@@ -13,7 +13,8 @@ export namespace pipes {
    *
    * @param cellX - Grid column of the target cell.
    * @param cellY - Grid row of the target cell.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.pipes.isAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function isAtCell(...args: CellCoordinates): boolean;
 
@@ -22,7 +23,8 @@ export namespace pipes {
    *
    * @param cellX - Grid column of the target cell.
    * @param cellY - Grid row of the target cell.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.pipes.isEnabledAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function isEnabledAtCell(...args: CellCoordinates): boolean;
 
@@ -31,7 +33,8 @@ export namespace pipes {
    *
    * @param cellX - Grid column of the target cell.
    * @param cellY - Grid row of the target cell.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.pipes.getConnectedVentsAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getConnectedVentsAtCell(...args: CellCoordinates): readonly PipeVentCell[];
 
@@ -41,7 +44,8 @@ export namespace pipes {
    * @param cellX - Grid column of the target cell.
    * @param cellY - Grid row of the target cell.
    * @param enabled - Desired enabled state.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.pipes.setEnabledAtCell`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function setEnabledAtCell(...args: [...CellCoordinates, enabled: boolean]): void;
 

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

@@ -18,7 +18,8 @@ export namespace player {
 
   /**
    * @deprecated Use {@link getPositionAtWorld} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.player.getPositionAtWorld`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export import getWorldPosition = shared.api.player.getWorldPosition;
 
@@ -27,13 +28,15 @@ export namespace player {
    *
    * @param worldX - World x position in pixels.
    * @param worldY - World y position in pixels.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.setPositionAtWorld`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function setPositionAtWorld(worldX: number, worldY: number): void;
 
   /**
    * @deprecated Use {@link setPositionAtWorld} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.player.setPositionAtWorld`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function setWorldPosition(worldX: number, worldY: number): void;
 
@@ -42,7 +45,8 @@ export namespace player {
    *
    * @param velocityX - Horizontal velocity in pixels per second.
    * @param velocityY - Vertical velocity in pixels per second.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.setVelocity`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function setVelocity(velocityX: number, velocityY: number): void;
 
@@ -51,7 +55,8 @@ export namespace player {
    *
    * @param multiplier - Speed scale factor (`1` is default walk). `0` freezes movement.
    * Vanilla Sprint Boost (Shift burst + meter) only runs when this value is exactly `1`.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.setMovementSpeedMultiplier`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function setMovementSpeedMultiplier(multiplier: number): void;
 
@@ -60,7 +65,8 @@ export namespace player {
    *
    * @param mode - `"normal"` for default physics, or `"hover"` for hover flight.
    * @returns True when the mode changes.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.setMovementMode`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function setMovementMode(mode: 'normal' | 'hover'): boolean;
 
@@ -70,14 +76,15 @@ export namespace player {
    * on the store snapshot — that flag is not updated during play.
    *
    * @returns True when the player touches solid ground.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.isOnGround`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function isOnGround(): boolean;
 
   /**
    * Move the player down until ground is found.
    *
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.teleportToGround`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function teleportToGround(): void;
 
@@ -87,13 +94,15 @@ export namespace player {
    * @param worldX - World x position in pixels to test.
    * @param worldY - World y position in pixels to test.
    * @returns True when the player hitbox fits at the position.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.isPositionClearAtWorld`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function isPositionClearAtWorld(worldX: number, worldY: number): boolean;
 
   /**
    * @deprecated Use {@link isPositionClearAtWorld} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.player.isPositionClearAtWorld`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function isWorldPositionClear(worldX: number, worldY: number): boolean;
 
@@ -103,13 +112,15 @@ export namespace player {
      * Add an item to inventory by item id.
      *
      * @param itemId - Registered item id string.
-     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.inventory.addById`
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     export function addById(itemId: string): void;
 
     /**
      * @deprecated Use {@link addById} instead.
-     * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.player.inventory.addById`
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     export function addFromId(itemId: string): void;
   }
@@ -120,13 +131,15 @@ export namespace player {
      * Unlock a structure type for building.
      *
      * @param structureId - Registered structure id string.
-     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.buildings.unlockById`
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     export function unlockById(structureId: string): void;
 
     /**
      * @deprecated Use {@link unlockById} instead.
-     * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.player.buildings.unlockById`
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     export function unlockByType(structureId: string): void;
 
@@ -134,7 +147,8 @@ export namespace player {
      * Remove a structure unlock from the player.
      *
      * @param structureId - Registered structure id string.
-     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.player.buildings.removeById`
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     export function removeById(structureId: string): void;
   }

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

@@ -10,6 +10,14 @@ export namespace progression {
   /**
    * Mark a progression step complete. Return true when completion succeeds.
    * @param request - Progression id and optional metadata for the step.
+   *
+   * @example
+   * ```ts
+   * const completed = api.progression.complete({
+   *   domain: "objective",
+   *   id: "all",
+   * });
+   * ```
    */
   export function complete(request: ProgressionCompletionRequestV1): boolean;
 

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

@@ -11,6 +11,17 @@ export namespace reactions {
   /**
    * Register a contact reaction between elements.
    * @param definition - Contact recipe inputs, outputs, and orientation.
+   *
+   * @example
+   * ```ts
+   * api.reactions.registerContact({
+   *   inputA: "water",
+   *   inputB: "examplePowder",
+   *   outputA: "steam",
+   *   outputB: null,
+   *   orientation: "any",
+   * });
+   * ```
    */
   export function registerContact(definition: ContactRecipeDefinitionV1): void;
 

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

@@ -19,16 +19,39 @@ export namespace rendering {
    *
    * @param worldX - World x position in pixels.
    * @param worldY - World y position in pixels.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.rendering.getDrawPositionAtWorld`
+   *
+   * @example
+   * ```ts
+   * api.events.on("frame:render", () => {
+   *   const drawPos = api.rendering.getDrawPositionAtWorld(worldX, worldY);
+   *   drawMarker(drawPos.x, drawPos.y);
+   * });
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getDrawPositionAtWorld(worldX: number, worldY: number): Vector2;
-  /** Return cell size and snap grid metrics. */
+  /**
+   * Return cell size and snap grid metrics.
+   *
+   * @example
+   * ```ts
+   * const { cellSize, snapGridCellSize } = api.rendering.getGridMetrics();
+   * ```
+   */
   export function getGridMetrics(): { cellSize: number; snapGridCellSize: number; };
   /** Return overlay viewport width and height in pixels. */
   export function getOverlayViewportSize(): { width: number; height: number; };
   /**
    * Run a callback with the overlay canvas context.
    * @param callback - Receives the overlay 2D context; return value is passed through.
+   *
+   * @example
+   * ```ts
+   * api.rendering.withOverlayContext((context) => {
+   *   context.fillRect(0, 0, 16, 16);
+   * });
+   * ```
    */
   export function withOverlayContext<T>(callback: (context: CanvasRenderingContext2D) => T): T;
 }

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

@@ -18,6 +18,11 @@ export namespace resources {
    * Update stored energy by amount with optional UI deferral.
    * @param amount - Energy delta (positive or negative).
    * @param options - When `deferUi` is true, skip immediate UI refresh.
+   *
+   * @example Official `api.resources.adjustEnergy` (typed deprecated alias: updateEnergy)
+   * ```ts
+   * api.resources.adjustEnergy(100, { deferUi: true });
+   * ```
    */
   export function updateEnergy(amount: number, options?: { deferUi?: boolean; }): void;
 }

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

@@ -9,6 +9,13 @@ export namespace schedule {
   /**
    * Run a callback on the next game tick.
    * @param callback - Function invoked once on the next tick.
+   *
+   * @example
+   * ```ts
+   * api.schedule.nextTick(() => {
+   *   runDeferredWork();
+   * });
+   * ```
    */
   export function nextTick(callback: () => void): void;
 }

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

@@ -18,6 +18,13 @@ export namespace settings {
   /**
    * Subscribe to settings changes. Return an unsubscribe function.
    * @param callback - Called with the full settings map after a change.
+   *
+   * @example
+   * ```ts
+   * const unsubscribe = api.settings.onChange((values) => {
+   *   applySettings(values);
+   * });
+   * ```
    */
   export function onChange(callback: (values: Readonly<Record<string, ConfigValueV1>>) => void): () => void;
 

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

@@ -16,20 +16,30 @@ export namespace shared {
      *
      * @param key - Buffer name shared across threads.
      * @param config - Typed array kind and element count.
-     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.shared.buffers.ensure`
+     *
+     * @example
+     * ```ts
+     * const counts = api.shared.buffers.ensure("counts", {
+     *   type: "uint32",
+     *   length: 4,
+     * });
+     * ```
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     export function ensure(key: string, config: { type: SharedArrayType; length: number; }): SharedArray;
 
     /**
      * @deprecated Use {@link ensure} instead.
-     * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.shared.buffers.ensure`
+     *
+     * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
      */
     export function create(key: string, config: { type: SharedArrayType; length: number; }): SharedArray;
 
     /**
      * Look up a named shared buffer without creating it.
      *
-     * @see https://sandustry.com/sandkit.html Official Sandkit API — Main 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/sandkit/api/signals.d.ts

@@ -4,6 +4,28 @@
  * Available as `sandkit.api.signals`.
  *
  * @module
+ *
+ * @example api.signals.interactables.register
+ * ```ts
+ * api.signals.interactables.register("exampleLever", (structure) => {
+ *   structure.data.on = !structure.data.on;
+ *   api.structures.update(structure);
+ * });
+ * ```
+ *
+ * @example api.signals.registerSenderType
+ * ```ts
+ * api.signals.registerSenderType("exampleSensor", (structure) => {
+ *   return structure.data.charge >= structure.data.threshold;
+ * });
+ * ```
+ *
+ * @example api.signals.setOutputAtCell
+ * ```ts
+ * api.structures.forEachOfType("exampleSensor", (structure) => {
+ *   api.signals.setOutputAtCell(structure.x, structure.y, structure.data.active);
+ * });
+ * ```
  */
 export namespace signals {
   /** Signal target registration for structure types. */
@@ -12,6 +34,13 @@ export namespace signals {
      * Register a handler when a signal targets a structure type.
      * @param structureTypeOrId - Structure type id or enum value.
      * @param apply - Called when a signal reaches a matching structure.
+     *
+     * @example
+     * ```ts
+     * api.signals.targets.register("exampleMachine", (structure, payload) => {
+     *   api.structures.processing.setEnabledAtCell(structure.x, structure.y, payload.combined);
+     * });
+     * ```
      */
     export function register(structureTypeOrId: string | StructureType, apply: (structure: Structure, payload: SignalTargetPayloadV1) => void): void;
   }