@sandustry-modding/types 0.3.1 → 0.4.0

package/src/configs/patches.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Sandkit bundle patch schema (`patches.json`).
+ *
+ * Not a runtime `sandkit` object. Use these types when authoring or validating
+ * compiled-bundle patches. Patches break across game updates; prefer
+ * `sandkit.api` when possible.
+ *
+ * @module
+ *
+ * @see [Official docs](https://sandustry.com/sandkit.html#patches-heading)
+ */
+
+/**
+ * Known compiled bundle paths the loader can patch.
+ *
+ * | Value | Role |
+ * | --- | --- |
+ * | `js/bundle.js` | Main renderer |
+ * | `js/manager-worker.js` | Manager worker |
+ * | `js/simulation-worker.js` | Simulation workers |
+ * | `js/utility-worker.js` | Utility worker |
+ *
+ * @see [Official docs](https://sandustry.com/sandkit.html#patches-heading)
+ */
+export type PatchTargetFile =
+  | "js/bundle.js"
+  | "js/simulation-worker.js"
+  | "js/manager-worker.js"
+  | "js/utility-worker.js"
+  | (string & {});
+
+/**
+ * Supported patch operations.
+ *
+ * | Value | Behaviour |
+ * | --- | --- |
+ * | `replace` | Replace the matched text with {@link BundlePatch.code} / {@link BundlePatch.replace} |
+ * | `remove` | Delete the matched text |
+ * | `insertBefore` | Insert {@link BundlePatch.code} before the match |
+ * | `insertAfter` | Insert {@link BundlePatch.code} after the match |
+ * | `wrap` | Surround the match with {@link BundlePatch.before} and {@link BundlePatch.after} |
+ *
+ * @see [Official docs](https://sandustry.com/sandkit.html#patches-heading)
+ */
+export type PatchOperation =
+  | "replace"
+  | "remove"
+  | "insertBefore"
+  | "insertAfter"
+  | "wrap";
+
+/**
+ * Regex finder when the target is not a plain {@link BundlePatch.find} string.
+ *
+ * @see [Official docs](https://sandustry.com/sandkit.html#patches-heading)
+ */
+export interface BundlePatchRegex {
+  /**
+   * JavaScript regex pattern source (without surrounding `/` delimiters).
+   * Capture groups may be referenced from {@link BundlePatch.code} as `$1`, `$2`, …
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#patches-heading)
+   */
+  pattern: string;
+  /**
+   * Optional regex flags (for example `"g"` or `"m"`).
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#patches-heading)
+   */
+  flags?: string;
+}
+
+/**
+ * One entry in `patches.json`.
+ *
+ * The file is an array of these objects. Prefer `expectedMatches` so a missed
+ * or duplicated match fails loudly. When several patches must succeed together
+ * (for example main + worker), set the same {@link atomicGroup} on each.
+ *
+ * @example patches.json example
+ * ```ts
+ * [
+ *   {
+ *     "file": "js/bundle.js",
+ *     "find": "const message = 'Hello';",
+ *     "operation": "replace",
+ *     "code": "const message = 'Hello from my mod';",
+ *     "expectedMatches": 1
+ *   },
+ *   {
+ *     "file": "js/simulation-worker.js",
+ *     "regex": {
+ *       "pattern": "const ([a-z]+) = false;"
+ *     },
+ *     "operation": "replace",
+ *     "code": "const $1 = true;",
+ *     "expectedMatches": 1
+ *   },
+ *   {
+ *     "file": "js/bundle.js",
+ *     "find": "doThing();",
+ *     "operation": "wrap",
+ *     "before": "if (enabled) { ",
+ *     "after": " }",
+ *     "expectedMatches": 1
+ *   }
+ * ]
+ * ```
+ *
+ * @see [Official docs](https://sandustry.com/sandkit.html#patches-heading)
+ */
+export interface BundlePatch {
+  /**
+   * Compiled bundle to modify.
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#patches-heading)
+   */
+  file: PatchTargetFile;
+  /**
+   * Exact source substring to locate in the bundle.
+   * Mutually exclusive with {@link regex} in typical patches.
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#patches-heading)
+   */
+  find?: string;
+  /**
+   * Replacement or inserted source text.
+   * Official examples use `code`; some loaders also accept {@link replace}.
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#patches-heading)
+   */
+  code?: string;
+  /**
+   * Alias of {@link code} used by some patch loaders and workshop mods.
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#patches-heading)
+   */
+  replace?: string;
+  /**
+   * How to apply the match. Defaults to replace-style behaviour when omitted
+   * in common workshop patches.
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#patches-heading)
+   */
+  operation?: PatchOperation;
+  /**
+   * How many times `find` / `regex` must match.
+   * Use a number (often `1`) so the load fails on miss or over-match.
+   * Some loaders accept `"any"`.
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#patches-heading)
+   */
+  expectedMatches?: number | "any";
+  /**
+   * Regex-based locator instead of a literal {@link find} string.
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#patches-heading)
+   */
+  regex?: BundlePatchRegex;
+  /**
+   * Text inserted before the match when {@link operation} is `"wrap"`.
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#patches-heading)
+   */
+  before?: string;
+  /**
+   * Text inserted after the match when {@link operation} is `"wrap"`.
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#patches-heading)
+   */
+  after?: string;
+  /**
+   * Optional stable id for logging and tooling.
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#patches-heading)
+   */
+  id?: string;
+  /**
+   * Group id shared by patches that must all succeed or all fail together.
+   * Use the same string on paired main (`js/bundle.js`) and worker
+   * (`js/simulation-worker.js`) patches.
+   */
+  atomicGroup?: string;
+  /**
+   * Human-readable note for maintainers. Not required by the official schema.
+   */
+  description?: string;
+}
+
+/**
+ * Root shape of `patches.json`: an ordered list of {@link BundlePatch} entries.
+ *
+ * @see [Official docs](https://sandustry.com/sandkit.html#patches-heading)
+ */
+export type BundlePatchesFile = BundlePatch[];

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

@@ -23,6 +23,11 @@ export declare namespace action {
   /**
    * Store custom data on the active action handler.
    * @param data - Serializable payload attached to the active action.
+   *
+   * @example
+   * ```ts
+   * api.action.setCustomData({ mode: "example" });
+   * ```
    */
   export function setCustomData<Input>(data: Input): void;
 }

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

@@ -5,14 +5,15 @@ import type { structures } from "../../shared/api/structures";
  *
  * Available as `sandkit.api.blueprints`.
  *
- * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.blueprints`
+ * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
  */
 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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function serializeStructures(structures: readonly structures.Structure[]): BlueprintStructure[];
 
@@ -20,7 +21,8 @@ export namespace blueprints {
    * 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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function localizeStructures(structures: readonly BlueprintStructure[]): BlueprintStructure[];
 

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

@@ -18,6 +18,11 @@ export namespace camera {
    * Release scripted focus and return control to the player.
    * @param options - Optional transition duration in milliseconds.
    * @returns True when focus was released.
+   *
+   * @example
+   * ```ts
+   * const released = api.camera.releaseFocus({ durationMs: 250 });
+   * ```
    */
   export function releaseFocus(options?: { durationMs?: number; }): boolean;
 }

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

@@ -19,7 +19,8 @@ export namespace effects {
    * @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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function createAtWorld(
     effectId: string,
@@ -30,7 +31,8 @@ export namespace effects {
 
   /**
    * @deprecated Use {@link createAtWorld} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.effects.createAtWorld`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function createEffectAtWorld(
     effectId: string,
@@ -45,13 +47,22 @@ export namespace effects {
    * @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`
+   *
+   * @example Main entry
+   * ```ts
+   * api.effects.createParticlesAtWorld(worldX, worldY, {
+   *   count: 12,
+   * });
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function createLightAtWorld(
     worldX: number,
@@ -65,7 +76,15 @@ export namespace effects {
    * @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`
+   *
+   * @example
+   * ```ts
+   * api.effects.createDistortionWaveAtWorld(worldX, worldY, {
+   *   style: "implode",
+   * });
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function createDistortionWaveAtWorld(worldX: number, worldY: number, options?: DistortionEffectOptions): void;
 
@@ -77,7 +96,8 @@ export namespace effects {
    * @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`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function createLaserAtWorld(
     startWorldX: number,
@@ -89,7 +109,8 @@ export namespace effects {
 
   /**
    * @deprecated Use {@link lights.temporary.removeById} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.lights.temporary.removeById`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function removeLightById(lightId: number): void;