@sandustry-modding/types 0.3.0 → 0.4.0

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

@@ -11,7 +11,169 @@ export namespace hooks {
    * @param hookId - Registered hook identifier.
    * @param callback - Called with hook arguments and context; may cancel the hook.
    * @param options - Optional priority and filter options.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.hooks.intercept`
+   *
+   * @example item:use
+   * ```ts
+   * const unsubscribe = api.hooks.intercept(
+   *   "item:use",
+   *   (args, context) => {
+   *     args.prepared.energyCost = Number(args.baseline.energyCost) * 2;
+   *
+   *     if (args.prepared.energyCost > 1000) {
+   *       context.cancel();
+   *     }
+   *   },
+   *   { itemIds: ["laser"], priority: 0 },
+   * );
+   * ```
+   *
+   * @example teleport:effect:create
+   * ```ts
+   * api.hooks.intercept("teleport:effect:create", (args, context) => {
+   *   context.cancel();
+   * });
+   * ```
+   *
+   * @example action:start
+   * ```ts
+   * api.hooks.intercept("action:start", (args, context) => {
+   *   if (args.action?.id === "example") context.cancel();
+   * });
+   * ```
+   *
+   * @example input:keyDown
+   * ```ts
+   * api.hooks.intercept("input:keyDown", (args, context) => {
+   *   if (args.code === "KeyK") context.cancel();
+   * });
+   * ```
+   *
+   * @example input:keyUp
+   * ```ts
+   * api.hooks.intercept("input:keyUp", (args, context) => {
+   *   if (args.code === "KeyK") context.cancel();
+   * });
+   * ```
+   *
+   * @example placePoints:suppress
+   * ```ts
+   * api.hooks.intercept("placePoints:suppress", (args, context) => {
+   *   if (args.type === "exampleStructure") context.cancel();
+   * });
+   * ```
+   *
+   * @example placePoints:directionalArrows:suppress
+   * ```ts
+   * api.hooks.intercept(
+   *   "placePoints:directionalArrows:suppress",
+   *   (args, context) => {
+   *     if (args.type === "exampleStructure") context.cancel();
+   *   },
+   * );
+   * ```
+   *
+   * @example entity:update
+   * ```ts
+   * const unsubscribe = api.hooks.intercept(
+   *   "entity:update",
+   *   (args) => {
+   *     if (args.phase !== "normal") return;
+   *     args.entity.targetX = args.playerWorldX;
+   *     args.entity.targetY = args.playerWorldY;
+   *   },
+   *   { entityTypes: ["lumling"], priority: 0 },
+   * );
+   * ```
+   *
+   * @example building:place
+   * ```ts
+   * api.hooks.intercept("building:place", (args, context) => {
+   *   if (args.structureId === "exampleStructure") context.cancel();
+   * });
+   * ```
+   *
+   * @example building:clearShape
+   * ```ts
+   * api.hooks.intercept("building:clearShape", (args, context) => {
+   *   if (args.structure.data?.protected) context.cancel();
+   * });
+   * ```
+   *
+   * @example input:scroll
+   * ```ts
+   * api.hooks.intercept("input:scroll", (args, context) => {
+   *   if (args.deltaY !== 0) context.cancel();
+   * });
+   * ```
+   *
+   * @example input:boostDown
+   * ```ts
+   * api.hooks.intercept("input:boostDown", (args, context) => {
+   *   context.cancel();
+   * });
+   * ```
+   *
+   * @example input:descendDown
+   * ```ts
+   * api.hooks.intercept("input:descendDown", (args, context) => {
+   *   context.cancel();
+   * });
+   * ```
+   *
+   * @example input:escape
+   * ```ts
+   * api.hooks.intercept("input:escape", (args, context) => {
+   *   context.cancel();
+   * });
+   * ```
+   *
+   * @example interactable:suppressHover
+   * ```ts
+   * api.hooks.intercept("interactable:suppressHover", (args, context) => {
+   *   if (args.type === "exampleStructure") context.cancel();
+   * });
+   * ```
+   *
+   * @example fire:element:ignite
+   * ```ts
+   * api.hooks.intercept("fire:element:ignite", (args, context) => {
+   *   if (args.elementType === exampleElementType) context.cancel();
+   * });
+   * ```
+   *
+   * @example projectile:fire:overStructure
+   * ```ts
+   * api.hooks.intercept(
+   *   "projectile:fire:overStructure",
+   *   (args, context) => {
+   *     if (args.projectile.type === "exampleProjectile") context.cancel();
+   *   },
+   * );
+   * ```
+   *
+   * @example projectile:hit
+   * ```ts
+   * api.hooks.intercept("projectile:hit", (args, context) => {
+   *   if (args.projectile.type === "exampleProjectile") context.cancel();
+   * });
+   * ```
+   *
+   * @example player:position:commit
+   * ```ts
+   * api.hooks.intercept("player:position:commit", (args) => {
+   *   args.velocityX *= 0.5;
+   *   args.velocityY *= 0.5;
+   * });
+   * ```
+   *
+   * @example progression:purchase
+   * ```ts
+   * api.hooks.intercept("progression:purchase", (args, context) => {
+   *   if (args.id === "exampleTech") context.cancel();
+   * });
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function intercept<K extends InterceptHookId>(
     hookId: K,
@@ -25,7 +187,205 @@ export namespace hooks {
    * @param hookId - Registered hook identifier.
    * @param callback - Called with hook arguments; may mutate hook payload.
    * @param options - Optional priority and filter options.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.hooks.modify`
+   *
+   * @example excavation:prepare
+   * ```ts
+   * const unsubscribe = api.hooks.modify(
+   *   "excavation:prepare",
+   *   (args) => {
+   *     if (args.sourceId !== "implosionGun") return;
+   *
+   *     args.profileId = "example:voidGun";
+   *     args.patternDiameterCells = 21;
+   *     args.drillTierDamage = 8;
+   *   },
+   *   { priority: 0 },
+   * );
+   * ```
+   *
+   * @example locator:scan:prepare
+   * ```ts
+   * const unsubscribe = api.hooks.modify(
+   *   "locator:scan:prepare",
+   *   (args) => {
+   *     const target = findNearestTarget(args.originWorldX, args.originWorldY);
+   *     args.hasTarget = target !== null;
+   *
+   *     if (!target) {
+   *       args.noTargetToast = "No example target was found.";
+   *       args.noTargetToastKey = "mods|example|noTarget";
+   *       return;
+   *     }
+   *
+   *     args.targetCellX = target.cellX;
+   *     args.targetCellY = target.cellY;
+   *     args.outerTint[0] = 103;
+   *     args.outerTint[1] = 232;
+   *     args.outerTint[2] = 249;
+   *     args.triangulationLensOverride = true;
+   *   },
+   *   { priority: 0 },
+   * );
+   * ```
+   *
+   * @example vacuum:prepare
+   * ```ts
+   * const vacuumPattern = [
+   *   [0, 1, 0],
+   *   [1, 1, 1],
+   *   [0, 1, 0],
+   * ];
+   *
+   * const unsubscribe = api.hooks.modify(
+   *   "vacuum:prepare",
+   *   (args) => {
+   *     const target = api.input.getMousePositionAtCell();
+   *     args.targetCellX = target.x;
+   *     args.targetCellY = target.y;
+   *     args.pattern = vacuumPattern;
+   *   },
+   *   { priority: 0 },
+   * );
+   * ```
+   *
+   * @example vacuum:element:prepare
+   * ```ts
+   * const unsubscribe = api.hooks.modify(
+   *   "vacuum:element:prepare",
+   *   (args) => {
+   *     if (args.matterType !== sandkit.enums.MatterType.Liquid) return;
+   *
+   *     args.collectable = true;
+   *     args.visibleInPicker = true;
+   *   },
+   *   { priority: 0 },
+   * );
+   * ```
+   *
+   * @example player:movement:prepare
+   * ```ts
+   * api.hooks.modify("player:movement:prepare", (args) => {
+   *   args.horizontalMaxSpeed *= 1.25;
+   * });
+   * ```
+   *
+   * @example building:placementLimit:prepare
+   * ```ts
+   * api.hooks.modify("building:placementLimit:prepare", (args) => {
+   *   args.maxCount = args.maxCount === null ? 10 : args.maxCount + 10;
+   * });
+   * ```
+   *
+   * @example fluxEmanator:processing:prepare
+   * ```ts
+   * api.hooks.modify("fluxEmanator:processing:prepare", (args) => {
+   *   args.speedMultiplier *= 2;
+   * });
+   * ```
+   *
+   * @example render:pipes:prepare
+   * ```ts
+   * api.hooks.modify("render:pipes:prepare", (args) => {
+   *   args.layer = "foreground";
+   * });
+   * ```
+   *
+   * @example structures:moved:prepare
+   * ```ts
+   * api.hooks.modify("structures:moved:prepare", (args) => {
+   *   prepareMovedStructures(args.moved, args.failedToPlace);
+   * });
+   * ```
+   *
+   * @example structures:removed:prepare
+   * ```ts
+   * api.hooks.modify("structures:removed:prepare", (args) => {
+   *   prepareRemovedStructures(args.removed, args.byMove);
+   * });
+   * ```
+   *
+   * @example weapon:reload:prepare
+   * ```ts
+   * api.hooks.modify("weapon:reload:prepare", (args) => {
+   *   args.reloadMs *= 0.8;
+   * }, { weaponIds: ["exampleWeapon"] });
+   * ```
+   *
+   * @example projectile:travel:prepare
+   * ```ts
+   * api.hooks.modify("projectile:travel:prepare", (args) => {
+   *   args.collidesWithStructures = false;
+   * }, { projectileTypes: ["exampleProjectile"] });
+   * ```
+   *
+   * @example projectile:impact:prepare
+   * ```ts
+   * api.hooks.modify("projectile:impact:prepare", (args) => {
+   *   args.radiusCells = 8;
+   * }, { projectileTypes: ["exampleProjectile"] });
+   * ```
+   *
+   * @example player:collision:prepare
+   * ```ts
+   * api.hooks.modify("player:collision:prepare", (args) => {
+   *   args.maxStepCells = 4;
+   * });
+   * ```
+   *
+   * @example trigger:schedule:prepare
+   * ```ts
+   * api.hooks.modify("trigger:schedule:prepare", (args) => {
+   *   args.intervalMs *= 0.5;
+   * }, { triggerIds: ["pump"] });
+   * ```
+   *
+   * @example progression:cost:prepare
+   * ```ts
+   * api.hooks.modify("progression:cost:prepare", (args) => {
+   *   if (args.currencyId === "gold") args.amount *= 0.9;
+   * });
+   * ```
+   *
+   * @example resource:collection:prepare
+   * ```ts
+   * api.hooks.modify("resource:collection:prepare", (args) => {
+   *   args.amount *= 2;
+   * }, { resourceIds: ["fluxite"] });
+   * ```
+   *
+   * @example resource:delivery:prepare
+   * ```ts
+   * api.hooks.modify("resource:delivery:prepare", (args) => {
+   *   args.mode = "collection";
+   * }, { resourceIds: ["fluxite"] });
+   * ```
+   *
+   * @example resource:balance:prepare
+   * ```ts
+   * api.hooks.modify("resource:balance:prepare", (args) => {
+   *   args.balance += api.storage.get("example", "gold") ?? 0;
+   * }, { resourceIds: ["gold"] });
+   * ```
+   *
+   * @example gold:removal:prepare
+   * ```ts
+   * api.hooks.modify("gold:removal:prepare", (args) => {
+   *   const banked = api.storage.get("example", "gold") ?? 0;
+   *   args.shortfall = Math.max(0, args.shortfall - banked);
+   * });
+   * ```
+   *
+   * @example gold:removal:settle
+   * ```ts
+   * api.hooks.modify("gold:removal:settle", (args) => {
+   *   const banked = api.storage.get("example", "gold") ?? 0;
+   *   const covered = Math.min(banked, args.shortfall);
+   *   api.storage.set("example", "gold", banked - covered);
+   *   args.shortfall -= covered;
+   * });
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function modify<K extends ModifyHookId>(
     hookId: K,

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

@@ -10,7 +10,15 @@ export namespace i18n {
    *
    * @param key - Translation key.
    * @param params - Placeholder values for the key template.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.t`
+   *
+   * @example
+   * ```ts
+   * const message = api.i18n.t("mods|example|count", {
+   *   count: 3,
+   * });
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function t(key: string, params?: Record<string, string | number>): string;
 
@@ -19,14 +27,22 @@ export namespace i18n {
    *
    * @param locale - Locale code (e.g. `en`).
    * @param translations - Map of keys to translated strings.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.register`
+   *
+   * @example
+   * ```ts
+   * api.i18n.register("en", {
+   *   "mods|example|title": "Example",
+   * });
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function register(locale: Locale, translations: Record<string, string>): void;
 
   /**
    * Returns the active locale code.
    *
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.getLocale`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getLocale(): Locale;
 
@@ -35,7 +51,8 @@ export namespace i18n {
    *
    * @param key - Translation key.
    * @param locale - Optional locale; defaults to the active locale.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.hasTranslation`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function hasTranslation(key: string, locale?: Locale): boolean;
 
@@ -43,21 +60,22 @@ export namespace i18n {
    * Sets the active locale.
    *
    * @param locale - Locale code to activate.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.setLocale`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function setLocale(locale: Locale): Promise<void>;
 
   /**
    * Returns metadata for all known languages.
    *
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.getLanguages`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getLanguages(): { code: Locale; nativeName: string; englishName: string; enabled: boolean; }[];
 
   /**
    * Returns locale codes that have registered translations.
    *
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.getAvailableLocales`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getAvailableLocales(): Locale[];
 
@@ -66,7 +84,15 @@ export namespace i18n {
    *
    * @param value - Number to format.
    * @param options - Intl-style number format options.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.formatNumber`
+   *
+   * @example
+   * ```ts
+   * const formatted = api.i18n.formatNumber(1234.5, {
+   *   maximumFractionDigits: 1,
+   * });
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function formatNumber(value: number, options?: I18nNumberFormatOptions): string;
 
@@ -74,13 +100,15 @@ export namespace i18n {
    * Joins key parts into a single translation key.
    *
    * @param parts - Key segments joined with `.`.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.joinKey`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function joinKey(...parts: string[]): string;
 
   /**
    * @deprecated Use {@link joinKey} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.i18n.joinKey`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function key(...parts: string[]): string;
 
@@ -88,7 +116,16 @@ export namespace i18n {
    * Returns the display name from a definition with nameKey or name.
    *
    * @param definition - Object with `nameKey` or `name`.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.getName`
+   *
+   * @example
+   * ```ts
+   * const name = api.i18n.getName({
+   *   name: "Example Machine",
+   *   nameKey: "structures|exampleMachine|name",
+   * });
+   * ```
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getName(definition: { nameKey?: string; name?: string; }): string;
 
@@ -96,7 +133,8 @@ export namespace i18n {
    * Returns the description from a definition with descriptionKey or description.
    *
    * @param definition - Object with `descriptionKey` or `description`.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.getDescription`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getDescription(definition: { descriptionKey?: string; description?: string; }): string;
 
@@ -105,13 +143,15 @@ export namespace i18n {
    *
    * @param key - Translation key.
    * @param fallback - Text used when no translation is registered.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.createTranslatable`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function createTranslatable(key: string, fallback: string): { __translatable: true; key: string; fallback: string; };
 
   /**
    * @deprecated Use {@link createTranslatable} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.i18n.createTranslatable`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function translatable(key: string, fallback: string): { __translatable: true; key: string; fallback: string; };
 
@@ -120,7 +160,8 @@ export namespace i18n {
    *
    * @param key - Global helper key.
    * @param value - Static string or function that returns the current value.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.setGlobal`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function setGlobal(key: string, value: string | (() => string)): void;
 
@@ -128,7 +169,8 @@ export namespace i18n {
    * Returns a global translation helper value.
    *
    * @param key - Global helper key.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.getGlobal`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getGlobal(key: string): string | undefined;
 
@@ -136,20 +178,22 @@ export namespace i18n {
    * Removes a global translation helper value.
    *
    * @param key - Global helper key.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.removeGlobal`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function removeGlobal(key: string): void;
 
   /**
    * @deprecated Use {@link removeGlobal} instead.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — deprecated alias of `api.i18n.removeGlobal`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function clearGlobal(key: string): void;
 
   /**
    * Returns all global translation helper values.
    *
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.getGlobals`
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function getGlobals(): Record<string, string>;
 
@@ -157,7 +201,8 @@ export namespace i18n {
    * Formats a key code for display in UI.
    *
    * @param keyCode - Keyboard key code or binding name.
-   * @see https://sandustry.com/sandkit.html Official Sandkit API — Main entry `api.i18n.formatKeyForDisplay`
+   *
+   * @see [Official docs](https://sandustry.com/sandkit.html#api-access-heading)
    */
   export function formatKeyForDisplay(keyCode: string): string;
 

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

@@ -12,6 +12,21 @@ export namespace input {
    * @param defaultKeys - Default key codes (for example `"Control+KeyC"`).
    * @param definition - Display metadata and press/release handlers.
    * @returns The registered binding id.
+   *
+   * @example
+   * ```ts
+   * api.input.registerBinding("ExampleToggle", ["KeyO"], {
+   *   displayName: "Toggle example",
+   *   displayNameKey: "mods|example|toggle",
+   *   subsection: {
+   *     title: "Example controls",
+   *     titleKey: "mods|example|controlsTitle",
+   *     description: "Bindings installed by the example mod.",
+   *     descriptionKey: "mods|example|controlsDescription",
+   *   },
+   *   handlers: { down: toggleExample },
+   * });
+   * ```
    */
   export function registerBinding(bindingId: BindingId, defaultKeys: KeyCode[], definition: InputBindingDefinition): BindingId;
 

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

@@ -24,6 +24,13 @@ export namespace items {
    * Updates fields on an existing item definition.
    * @param itemId - Registered item id.
    * @param partial - Fields to merge into the definition.
+   *
+   * @example
+   * ```ts
+   * api.items.updateDefinition("exampleTool", {
+   *   name: "Updated Example Tool",
+   * });
+   * ```
    */
   export function updateDefinition(itemId: ItemId, partial: Partial<ItemDefinition>): void;
   /**