@sandustry-modding/types 0.1.0 → 0.3.0

package/sandkit/api/effects.d.ts

@@ -1,76 +0,0 @@
-import { shared } from "../../shared";
-
-/**
- * `sandkit.api.effects` — visual effects, particles, lights, and lasers at world positions.
- * Main thread only.
- */
-declare namespace effects {
-  // Shared functions
-  /** Creates a short-lived light at world coordinates. */
-  export import createLightAtWorld = shared.api.effects.createLightAtWorld
-  /** Spawns particles at world coordinates. */
-  export import createParticlesAtWorld = shared.api.effects.createParticlesAtWorld
-  /** Creates a named screen effect at world coordinates. */
-  export import createEffectAtWorld = shared.api.effects.createEffectAtWorld
-  // Shared types
-  /** Options for generic screen effects. */
-  export import EffectOptions = shared.api.effects.EffectOptions
-  /** Options for temporary lights. */
-  export import TemporaryLightOptions = shared.api.effects.TemporaryLightOptions
-  /** Options for particle effects. */
-  export import ParticleEffectOptions = shared.api.effects.ParticleEffectOptions
-
-  /**
-   * Creates a distortion wave effect at world coordinates.
-   * @param worldX - World X coordinate in pixels.
-   * @param worldY - World Y coordinate in pixels.
-   * @param options - Style, duration, radius, intensity, and color.
-   */
-  export function createDistortionWaveAtWorld(worldX: number, worldY: number, options?: DistortionEffectOptions): void;
-  /**
-   * Creates a laser beam between two world points. Returns a handle to destroy it.
-   * @param startWorldX - Beam start world X in pixels.
-   * @param startWorldY - Beam start world Y in pixels.
-   * @param endWorldX - Beam end world X in pixels.
-   * @param endWorldY - Beam end world Y in pixels.
-   * @param options - Width, brightness, color, and glow options.
-   */
-  export function createLaserAtWorld(startWorldX: number, startWorldY: number, endWorldX: number, endWorldY: number, options?: LaserEffectOptions): LaserEffectHandle;
-  /**
-   * Removes a temporary light by its id.
-   * @param lightId - Light index from {@link createLightAtWorld}.
-   */
-  export function removeLightById(lightId: number): void;
-
-  /** Options for laser beam effects. */
-  export interface LaserEffectOptions {
-    /** Beam width in pixels. */
-    width?: number;
-    /** Beam brightness multiplier. */
-    brightness?: number;
-    /** Beam color as a packed integer. */
-    color?: number;
-    /** When true, draws a glow around the beam. */
-    glow?: boolean;
-  }
-
-  /** Handle returned by createLaserAtWorld. */
-  export interface LaserEffectHandle {
-    /** Removes the laser from the scene. */
-    destroy(): void;
-  }
-
-  /** Options for distortion wave effects. */
-  export interface DistortionEffectOptions {
-    /** Distortion style: implode or explode. */
-    style?: 'implode' | 'explode';
-    /** Effect duration in seconds. */
-    duration?: number;
-    /** Maximum radius of the wave. */
-    maxRadius?: number;
-    /** Visual intensity of the distortion. */
-    intensity?: number;
-    /** RGBA color components for the effect. */
-    color?: [number, number, number, number];
-  }
-}

package/sandkit/api/elements.d.ts

@@ -1,237 +0,0 @@
-import { CellCoordinates, Vector2 } from "../../shared/player";
-import { shared } from "../../shared";
-
-/**
- * `sandkit.api.elements` — register elements and read or change cells when idle.
- * Main thread only.
- */
-export namespace elements {
-
-  // Shared types
-  /** Numeric id for a registered element type. */
-  export import ElementType = shared.api.elements.ElementType;
-  /** Mod or built-in element string id. */
-  export import ElementId = shared.api.elements.ElementId;
-  /** Type handle or string id accepted by lookup helpers. */
-  export import ElementRef = shared.api.elements.ElementRef;
-  /** Matter category for element physics behavior. */
-  export import MatterType = shared.api.elements.MatterType;
-  /** Full definition used to register a custom element. */
-  export import ElementDefinition = shared.api.elements.ElementDefinition;
-  /** Options for create and replace calls. */
-  export import ElementCreateOptions = shared.api.elements.ElementCreateOptions;
-  /** Options for element removal. */
-  export import ElementRemovalOptions = shared.api.elements.ElementRemovalOptions;
-  /** Resolves a string element id to its numeric type. */
-  export import getTypeFromId = shared.api.elements.getTypeFromId;
-  /** Returns the definition for an element type. */
-  export import getDefinitionByType = shared.api.elements.getDefinitionByType;
-  /** Returns the element type at a cell, or null. */
-  export import getTypeAtCell = shared.api.elements.getTypeAtCell;
-  /** Returns the resolved element type at a cell, or null. */
-  export import getResolvedTypeAtCell = shared.api.elements.getResolvedTypeAtCell;
-  /** Returns the resolved element type from a cell id, or null. */
-  export import getResolvedTypeFromCellId = shared.api.elements.getResolvedTypeFromCellId;
-  /** Returns element info at a cell, or null. */
-  export import getInfoAtCell = shared.api.elements.getInfoAtCell;
-  /** Returns the matter type at a cell, or null. */
-  export import getMatterTypeAtCell = shared.api.elements.getMatterTypeAtCell;
-  /** Returns true when the cell contains the given element type. */
-  export import isTypeAtCell = shared.api.elements.isTypeAtCell;
-  /** Returns true when the element at the cell is free-falling. */
-  export import isFreeFallingAtCell = shared.api.elements.isFreeFallingAtCell;
-  /** Returns particle velocity at a cell, or null. */
-  export import getVelocityAtCell = shared.api.elements.getVelocityAtCell;
-  /** Returns a data field value at a cell, or null. */
-  export import getDataFieldAtCell = shared.api.elements.getDataFieldAtCell;
-
-  /** Optional tooltip metadata on structure interactions. */
-  export interface InteractionStructureMetadata {
-    /** i18n key for custom interaction label text. */
-    textKey?: string;
-    /** Hide the label when a data field matches a value. */
-    crossedOutWhen?: { dataField: number; equals: number; };
-    /** Show the label only when a data field matches a value. */
-    visibleWhen?: { dataField: number; equals: number; };
-    /** Require the text key to exist in the active locale. */
-    onlyWhenTranslated?: boolean;
-  }
-
-  /** Interaction that destroys specific items. */
-  export type InteractionDestroyer = {
-    kind: "destroyer";
-    /** Item ids removed by this interaction (for example `"drill"`). */
-    items: readonly string[];
-  };
-
-  /** Interaction that affects specific structures. */
-  export type InteractionStructure = InteractionStructureMetadata & {
-    kind: "structure";
-    /** Structure ids shown in the interaction tooltip. */
-    structures: readonly string[];
-  };
-
-  /** Interaction that affects specific entities. */
-  export type InteractionEntity = {
-    kind: "entity";
-    /** Entity type ids referenced by the interaction. */
-    entities: readonly string[];
-  };
-
-  /** Interaction that marks the element as flammable. */
-  export type InteractionFlammable = { kind: "flammable" };
-  /** Interaction that marks the element as meltable. */
-  export type InteractionMeltable = { kind: "meltable" };
-  /** Interaction that marks the element as freezable. */
-  export type InteractionFreezable = { kind: "freezable" };
-  /** Interaction handled by custom mod logic and tooltip text. */
-  export type InteractionCustom = InteractionStructureMetadata & { kind: "custom" };
-
-  /** Union of element interaction kinds for tool and structure logic. */
-  export type Interaction = InteractionDestroyer
-    | InteractionStructure
-    | InteractionEntity
-    | InteractionFlammable
-    | InteractionMeltable
-    | InteractionFreezable
-    | InteractionCustom;
-
-  /** Returns all registered element type ids. */
-  export function getRegisteredTypes(): ElementType[];
-
-  /**
-   * Registers a new element and returns its assigned type id.
-   * @param definition - Full element definition to register.
-   * @returns Object with the assigned `elementType`.
-   */
-  export function register(definition: ElementDefinition): { elementType: ElementType; };
-
-  /**
-   * Updates fields on an existing element definition.
-   * @param elementTypeOrId - Numeric type or string id.
-   * @param partial - Fields to merge onto the definition.
-   */
-  export function updateDefinition(elementTypeOrId: ElementRef, partial: Partial<ElementDefinition>): void;
-
-  /**
-   * Adds an interaction entry to an element definition.
-   * @param elementTypeOrId - Numeric type or string id.
-   * @param interaction - Interaction entry to append.
-   */
-  export function addInteractionInfo(elementTypeOrId: ElementRef, interaction: Interaction): void;
-
-  /**
-   * Returns the display name for an element type.
-   * @param elementType - Numeric element type.
-   */
-  export function getNameByType(elementType: ElementType): string;
-
-  /**
-   * Finds a free cell inside a structure footprint, or null.
-   * @param structureCellX - Structure anchor cell column.
-   * @param structureCellY - Structure anchor cell row.
-   * @param structureSize - Structure footprint size in cells.
-   * @returns Cell coordinates of a free cell, or null when none.
-   */
-  export function findFreeCellInStructure(structureCellX: number, structureCellY: number, structureSize: number): Vector2 | null;
-
-  /**
-   * Creates an element at a cell when the simulation is idle.
-   * @param cellX - Grid column of the target cell.
-   * @param cellY - Grid row of the target cell.
-   * @param elementType - Element type to place.
-   * @param options - Optional spawn overrides.
-   */
-  export function createAtCellWhenIdle(...args: [...CellCoordinates, elementType: ElementType, options?: ElementCreateOptions]): void;
-
-  /**
-   * Replaces the element at a cell when the simulation is idle.
-   * @param cellX - Grid column of the target cell.
-   * @param cellY - Grid row of the target cell.
-   * @param elementType - Element type to place.
-   * @param options - Optional spawn overrides.
-   */
-  export function replaceAtCellWhenIdle(...args: [...CellCoordinates, elementType: ElementType, options?: ElementCreateOptions]): void;
-
-  /**
-   * Removes the element at a cell when the simulation is idle.
-   * @param cellX - Grid column of the target cell.
-   * @param cellY - Grid row of the target cell.
-   * @param options - Optional removal flags.
-   */
-  export function removeAtCellWhenIdle(...args: [...CellCoordinates, options?: ElementRemovalOptions]): void;
-
-  /**
-   * Moves an element between cells when the simulation is idle.
-   * @param fromCellX - Source cell column.
-   * @param fromCellY - Source cell row.
-   * @param toCellX - Destination cell column.
-   * @param toCellY - Destination cell row.
-   */
-  export function teleportBetweenCellsWhenIdle(fromCellX: number, fromCellY: number, toCellX: number, toCellY: number): void;
-
-  /**
-   * Sets particle velocity at a cell when the simulation is idle.
-   * @param cellX - Grid column of the target cell.
-   * @param cellY - Grid row of the target cell.
-   * @param velocity - New velocity vector.
-   */
-  export function setVelocityAtCellWhenIdle(...args: [...CellCoordinates, velocity: Vector2]): void;
-
-  /**
-   * Adds velocity to a particle at a cell when the simulation is idle.
-   * @param cellX - Grid column of the target cell.
-   * @param cellY - Grid row of the target cell.
-   * @param velocity - Velocity delta to add.
-   * @param maxSpeed - Optional speed cap after the addition.
-   */
-  export function addParticleVelocityAtCellWhenIdle(...args: [...CellCoordinates, velocity: Vector2, maxSpeed?: number]): void;
-
-  /**
-   * Converts a cell element to a particle when the simulation is idle.
-   * @param cellX - Grid column of the target cell.
-   * @param cellY - Grid row of the target cell.
-   * @param velocity - Initial particle velocity.
-   */
-  export function convertToParticleAtCellWhenIdle(...args: [...CellCoordinates, velocity: Vector2]): void;
-
-  /**
-   * Converts a particle back to a solid element when the simulation is idle.
-   * @param cellX - Grid column of the target cell.
-   * @param cellY - Grid row of the target cell.
-   */
-  export function convertFromParticleAtCellWhenIdle(...args: CellCoordinates): void;
-
-  /**
-   * Sets a data field on the element at a cell when the simulation is idle.
-   * @param cellX - Grid column of the target cell.
-   * @param cellY - Grid row of the target cell.
-   * @param fieldNumber - Data field index (1–4).
-   * @param value - New field value.
-   */
-  export function setDataFieldAtCellWhenIdle(...args: [...CellCoordinates, fieldNumber: 1 | 2 | 3 | 4, value: number]): void;
-
-  /**
-   * Refreshes the rendered color at a cell when the simulation is idle.
-   * @param cellX - Grid column of the target cell.
-   * @param cellY - Grid row of the target cell.
-   */
-  export function refreshColorAtCellWhenIdle(...args: CellCoordinates): void;
-
-  /**
-   * Sets the physics skip mode at a cell when the simulation is idle.
-   * @param cellX - Grid column of the target cell.
-   * @param cellY - Grid row of the target cell.
-   * @param physicsState - Physics skip flags for the element.
-   */
-  export function setPhysicsAtCellWhenIdle(...args: [...CellCoordinates, physicsState: number]): void;
-
-  /**
-   * Sets element duration at a cell when the simulation is idle.
-   * @param cellX - Grid column of the target cell.
-   * @param cellY - Grid row of the target cell.
-   * @param duration - Duration in simulation units.
-   * @param options - When `updateMax` is true, also update max duration.
-   */
-  export function setDurationAtCellWhenIdle(...args: [...CellCoordinates, duration: number, options?: { updateMax?: boolean; }]): void;
-}

package/sandkit/api/events.d.ts

@@ -1,53 +0,0 @@
-import type { LooseString } from "../../shared/nominal";
-
-/**
- * `sandkit.api.events` — subscribe to and emit named game events.
- * Main thread only. The `events` object is frozen; do not replace `on` or `emit`.
- */
-export namespace events {
-  /**
-   * Subscribes to an event. Returns an unsubscribe function.
-   * @param eventId - Registered event name.
-   * @param callback - Called when the event is emitted.
-   */
-  export function on<K extends EventId>(eventId: K, callback: (payload: EventPayload<K>) => void): () => void;
-  /**
-   * Emits an event with a payload to all subscribers.
-   * @param eventId - Registered event name.
-   * @param payload - Serializable payload passed to listeners.
-   */
-  export function emit<K extends EventId>(eventId: K, payload: EventPayload<K>): void;
-
-  /**
-   * Mutable payload for `player:collision:prepare`.
-   * Listeners may change `maxStepCells` (clamped 1–8) and phasing flags.
-   */
-  export interface PlayerCollisionPreparePayload {
-    /** When true, terrain collision is skipped this sub-step. */
-    phaseThroughTerrain: boolean;
-    /** When true, structure collision is skipped this sub-step. */
-    phaseThroughStructures: boolean;
-    /** Max cells the player can step up when blocked horizontally (1–8). */
-    maxStepCells: number;
-  }
-
-  /** Known event payloads. Unlisted ids still use `unknown`. */
-  export interface EventPayloadMap {
-    "player:collision:prepare": PlayerCollisionPreparePayload;
-    "player:moved": {
-      /**
-       * Simulation step duration in seconds.
-       * `0` on teleports. The event runs after collision; landing already
-       * zeroes `velocity.y`. Vanilla gravity is applied after this event.
-       */
-      dt?: number;
-      state?: unknown;
-    };
-  }
-
-  /** Known event names plus any custom string id. */
-  export type EventId = LooseString<keyof EventPayloadMap>;
-
-  /** Event payload type for a given event id. */
-  export type EventPayload<K> = K extends keyof EventPayloadMap ? EventPayloadMap[K] : unknown;
-}

package/sandkit/api/excavation.d.ts

@@ -1,34 +0,0 @@
-/**
- * `sandkit.api.excavation` — register custom excavation tool dig profiles.
- * Main thread only.
- */
-export namespace excavation {
-  /**
-   * Registers an excavation profile by id.
-   * @param id - Unique profile id (1–128 chars: letters, numbers, `.`, `_`, `:`, `-`).
-   * @param definition - Pattern, power, and profile options.
-   */
-  export function registerProfile(id: string, definition: ExcavationProfileDefinitionV1): void;
-
-  /** Excavation tool profile definition. */
-  export interface ExcavationProfileDefinitionV1 {
-    /** Dig pattern grid; non-zero cells are removed. */
-    pattern: number[][];
-    /** Dig strength applied to matched cells. Clamped to 0–1000. */
-    power: number;
-    /** Optional profile-specific excavation flags. */
-    options?: ExcavationProfileOptions;
-  }
-
-  /** Options attached to an excavation profile definition. */
-  export interface ExcavationProfileOptions {
-    fromGun?: boolean;
-    fromRocketExplosion?: boolean;
-    fromDrill?: boolean;
-    useLiteralOutVelocity?: boolean;
-    destroyNonDestructible?: boolean;
-    forceRemoveAll?: boolean;
-    /** Clamped to 0–1000 when set. */
-    drillTierDamage?: number;
-  }
-}

package/sandkit/api/fire.d.ts

@@ -1,26 +0,0 @@
-import { CellCoordinates } from "../../shared/player";
-
-/**
- * `sandkit.api.fire` — ignite and burn elements at grid cells.
- * Main thread only.
- */
-export namespace fire {
-  /**
-   * Returns true when the element at the cell can burn.
-   * @param cellX - Grid cell X coordinate.
-   * @param cellY - Grid cell Y coordinate.
-   */
-  export function canBurnElementAtCell(...args: CellCoordinates): boolean;
-  /**
-   * Queues a burn at the cell when the simulation is idle.
-   * @param cellX - Grid cell X coordinate.
-   * @param cellY - Grid cell Y coordinate.
-   */
-  export function burnElementAtCellWhenIdle(...args: CellCoordinates): void;
-  /**
-   * Burns the element at the cell immediately. Returns true on success.
-   * @param cellX - Grid cell X coordinate.
-   * @param cellY - Grid cell Y coordinate.
-   */
-  export function burnElementAtCell(...args: CellCoordinates): boolean;
-}

package/sandkit/api/grid.d.ts

@@ -1,26 +0,0 @@
-import { CellCoordinates } from "../../shared/player";
-
-/**
- * `sandkit.api.grid` — iterate cells in rectangular and circular regions.
- * Main thread only.
- */
-export namespace grid {
-  /**
-   * Calls the callback for each cell in a rectangle.
-   * @param cellX - Origin cell column (top-left).
-   * @param cellY - Origin cell row (top-left).
-   * @param width - Rectangle width in cells.
-   * @param height - Rectangle height in cells.
-   * @param callback - Invoked for each cell with `(cellX, cellY)`.
-   */
-  export function forEachCellInRect(...args: [...CellCoordinates, width: number, height: number, callback: (...args: CellCoordinates) => void]): void;
-
-  /**
-   * Calls the callback for each cell inside a circle.
-   * @param centerCellX - Circle center cell column.
-   * @param centerCellY - Circle center cell row.
-   * @param radius - Circle radius in cells.
-   * @param callback - Invoked for each cell with `(cellX, cellY)`.
-   */
-  export function forEachCellInCircle(centerCellX: number, centerCellY: number, radius: number, callback: (...args: CellCoordinates) => void): void;
-}

package/sandkit/api/hooks.d.ts

@@ -1,52 +0,0 @@
-/**
- * `sandkit.api.hooks` — intercept and modify internal game hook points.
- * Main thread only.
- */
-export namespace hooks {
-  /**
-   * Registers an intercept hook. Returns an unsubscribe function.
-   * @param hookId - Registered hook identifier.
-   * @param callback - Called with hook arguments and context; may cancel the hook.
-   * @param options - Optional priority and filter options.
-   */
-  export function intercept<K extends keyof InterceptHookMap>(hookId: K, callback: (args: InterceptHookMap[K], context: HookContext) => void, options?: HookOptions): () => void;
-  /**
-   * Registers a modifier hook. Returns an unsubscribe function.
-   * @param hookId - Registered hook identifier.
-   * @param callback - Called with hook arguments; may mutate hook payload.
-   * @param options - Optional priority and filter options.
-   */
-  export function modify<K extends keyof ModifierHookMap>(hookId: K, callback: (args: ModifierHookMap[K]) => void, options?: HookOptions): () => void;
-
-  /** Map of intercept hook ids to argument shapes (not yet typed in declarations). */
-  export interface InterceptHookMap {
-    "input:boost-down": Record<string, never>;
-    "input:descend-down": Record<string, never>;
-    "input:keydown": {
-      key?: string;
-      code?: string;
-      event?: Event;
-    };
-    "input:keyup": {
-      key?: string;
-      code?: string;
-      event?: Event;
-    };
-    "input:escape": Record<string, never>;
-    "input:scroll": Record<string, unknown>;
-  }
-
-  /** Context passed to intercept hook callbacks. */
-  export interface HookContext {
-    /** When called, the intercepted action is skipped. */
-    cancel(): void;
-  }
-  /** Map of modifier hook ids to argument shapes (not yet typed in declarations). */
-  export type ModifierHookMap = unknown
-  /** Options for hook registration. */
-  export interface HookOptions {
-    /** Run this hook before others with lower priority. */
-    priority?: number;
-    [key: string]: unknown;
-  }
-}

package/sandkit/api/lights.d.ts

@@ -1,66 +0,0 @@
-import type { shared } from "../../shared";
-
-/**
- * `sandkit.api.lights` — temporary VFX lights and persistent world lights.
- * Main thread only.
- */
-export namespace lights {
-  /** Short-lived visual effect lights. */
-  export namespace vfx {
-    /**
-     * Creates a temporary light at world coordinates.
-     * @param worldX - World X coordinate in pixels.
-     * @param worldY - World Y coordinate in pixels.
-     * @param options - Brightness, duration, color, and dedup options.
-     */
-    export function createAtWorld(worldX: number, worldY: number, options?: TemporaryLightOptions): { index: number | null; };
-    /**
-     * Removes a temporary light by its id.
-     * @param lightId - Light index returned from {@link createAtWorld}.
-     */
-    export function removeById(lightId: number): void;
-  }
-
-  /** Lights that persist in the world save. */
-  export namespace persistent {
-    /**
-     * Creates a persistent light at world coordinates.
-     * @param worldX - World X coordinate in pixels.
-     * @param worldY - World Y coordinate in pixels.
-     * @param options - Brightness, size, color, and persistence options.
-     */
-    export function createAtWorld(worldX: number, worldY: number, options?: PersistentLightOptions): PersistentLightHandle;
-    /**
-     * Removes the persistent light at world coordinates.
-     * @param worldX - World X coordinate in pixels.
-     * @param worldY - World Y coordinate in pixels.
-     */
-    export function removeAtWorld(worldX: number, worldY: number): void;
-    /**
-     * Fades out the persistent light at world coordinates over durationMs.
-     * @param worldX - World X coordinate in pixels.
-     * @param worldY - World Y coordinate in pixels.
-     * @param durationMs - Fade duration in milliseconds.
-     */
-    export function fadeAtWorld(worldX: number, worldY: number, durationMs?: number): void;
-    /** Marks persistent lights dirty so they are saved on the next flush. */
-    export function markDirty(): void;
-  }
-
-  /** Options for temporary VFX lights. */
-  export type TemporaryLightOptions = shared.api.effects.TemporaryLightOptions;
-
-  /** Options for persistent world lights. */
-  export interface PersistentLightOptions {
-    /** Light brightness multiplier. */
-    brightness?: number;
-    /** Light radius in pixels. */
-    size?: number;
-    /** RGBA color components. */
-    color?: [number, number, number, number];
-    [key: string]: unknown;
-  }
-
-  /** Handle returned from {@link persistent.createAtWorld}. */
-  export type PersistentLightHandle = unknown
-}

package/sandkit/api/player.d.ts

@@ -1,84 +0,0 @@
-/**
- * Player position, movement, inventory, and building unlocks.
- *
- * Available as `sandkit.api.player`.
- *
- * @module
- */
-import { shared } from "../../shared";
-
-export namespace player {
-
-  // Shared
-  /** Return the player world position. */
-  export import getWorldPosition = shared.api.player.getWorldPosition
-  /** Return true when the player overlaps the given cell. */
-  export import isCollidingWithCell = shared.api.player.isCollidingWithCell
-  /** Return true when the player is within radius of the given cell. */
-  export import isWithinRadiusOfCell = shared.api.player.isWithinRadiusOfCell
-
-  /**
-   * Set the player world position.
-   * @param worldX - World x position in pixels.
-   * @param worldY - World y position in pixels.
-   */
-  export function setWorldPosition(worldX: number, worldY: number): void;
-
-  /**
-   * Set the player velocity.
-   * @param velocityX - Horizontal velocity in pixels per second.
-   * @param velocityY - Vertical velocity in pixels per second.
-   */
-  export function setVelocity(velocityX: number, velocityY: number): void;
-
-  /**
-   * Set the movement speed multiplier.
-   * @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`.
-   */
-  export function setMovementSpeedMultiplier(multiplier: number): void;
-
-  /**
-   * Set movement mode to normal or hover.
-   * @param mode - `"normal"` for default physics, or `"hover"` for hover flight.
-   * @returns True when the mode changes.
-   */
-  export function setMovementMode(mode: 'normal' | 'hover'): boolean;
-
-  /**
-   * Return true when the player is on ground.
-   * Tests solid cells 1 pixel below the hitbox. Do not use `player.onGround`
-   * on the store snapshot — that flag is not updated during play.
-   * @returns True when the player touches solid ground.
-   */
-  export function isOnGround(): boolean;
-
-  /** Move the player down until ground is found. */
-  export function teleportToGround(): void;
-
-  /**
-   * Return true when the world position has no collision.
-   * @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.
-   */
-  export function isWorldPositionClear(worldX: number, worldY: number): boolean;
-
-  /** Player inventory helpers. */
-  export namespace inventory {
-    /**
-     * Add an item to inventory by item id.
-     * @param itemId - Registered item id string.
-     */
-    export function addFromId(itemId: string): void;
-  }
-
-  /** Player building unlock helpers. */
-  export namespace buildings {
-    /**
-     * Unlock a structure type for building.
-     * @param structureId - Registered structure id string.
-     */
-    export function unlockByType(structureId: string): void;
-  }
-}