kustom-mc 0.1.0

package/dist/types/index.d.ts

@@ -0,0 +1,2094 @@
+import './globals.js';
+/**
+ * A fully qualified namespaced identifier.
+ * Format: packId:type/name (e.g., "mypack:item/sword")
+ *
+ * Used to uniquely identify resources across different packs.
+ */
+export interface NamespacedId {
+    /** The pack ID (e.g., "mypack") */
+    readonly packId: string;
+    /** The resource type (e.g., "script", "item", "block") */
+    readonly type: string;
+    /** The resource name (e.g., "sword", "main") */
+    readonly name: string;
+}
+/**
+ * Parse a namespaced ID string into its components.
+ * Returns null if the string is not a valid namespaced ID.
+ *
+ * @example
+ * ```typescript
+ * const id = parseNamespacedId("mypack:item/sword");
+ * // { packId: "mypack", type: "item", name: "sword" }
+ * ```
+ */
+export declare function parseNamespacedId(fullId: string): NamespacedId | null;
+/**
+ * Check if a string is a fully qualified namespaced ID.
+ *
+ * @example
+ * ```typescript
+ * isNamespacedId("mypack:item/sword"); // true
+ * isNamespacedId("sword"); // false
+ * ```
+ */
+export declare function isNamespacedId(id: string): boolean;
+/**
+ * Create a fully qualified namespaced ID string.
+ *
+ * @example
+ * ```typescript
+ * createNamespacedId("mypack", "item", "sword"); // "mypack:item/sword"
+ * ```
+ */
+export declare function createNamespacedId(packId: string, type: string, name: string): string;
+/**
+ * Cross-pack import information.
+ * Returned when parsing a cross-pack import path.
+ */
+export interface CrossPackImport {
+    /** The pack ID being imported from */
+    readonly packId: string;
+    /** The path within the pack */
+    readonly path: string;
+}
+/**
+ * Check if an import path is a cross-pack import.
+ * Cross-pack imports use the format: packId:path
+ *
+ * @example
+ * ```typescript
+ * isCrossPackImport("core-pack:scripts/utils"); // true
+ * isCrossPackImport("./utils"); // false
+ * ```
+ */
+export declare function isCrossPackImport(importPath: string): boolean;
+/**
+ * Parse a cross-pack import path.
+ * Returns null if not a valid cross-pack import.
+ *
+ * @example
+ * ```typescript
+ * parseCrossPackImport("core-pack:scripts/utils");
+ * // { packId: "core-pack", path: "scripts/utils" }
+ * ```
+ */
+export declare function parseCrossPackImport(importPath: string): CrossPackImport | null;
+/**
+ * Event schema for typed events.
+ * Define events with Props types, just like props.
+ *
+ * @example
+ * ```typescript
+ * events: {
+ *   onSuccess: Props.Boolean(),
+ *   onError: Props.String(),
+ *   onProgress: Props.Number(),
+ * }
+ * ```
+ */
+export type EventSchema = Record<string, PropAPI>;
+/**
+ * Empty event schema marker for scripts without events.
+ */
+export type EmptyEventSchema = Record<string, never>;
+/**
+ * Infer the event payload type from an EventSchema.
+ */
+export type InferEventPayload<E extends EventSchema, K extends keyof E> = InferPropType<E[K]>;
+export interface ScriptConfig<P extends PropSchema, E extends EventSchema = EmptyEventSchema> {
+    /** Props schema with types and defaults */
+    props?: P;
+    /**
+     * Events schema with typed payloads.
+     * Define events that this script can emit to parent processes.
+     *
+     * @example
+     * ```typescript
+     * events: {
+     *   onSuccess: Props.Boolean(),
+     *   onUnlock: Props.String(),
+     * }
+     * ```
+     */
+    events?: E;
+    /**
+     * Script entry point.
+     * The `this` context is the McModuleAPI (process), allowing direct access to:
+     * - this.exit(value) - Exit the script with a return value
+     * - this.emit(event, ...args) - Emit events to parent process
+     * - this.getPlayer(name) - Get a player by name
+     *
+     * @param ctx Script context with props, executor, and subsystems
+     */
+    run: (this: TypedMcModuleAPI<E>, ctx: ScriptContext<InferProps<P>, E>) => void;
+}
+export interface ScriptDefinition<P extends PropSchema, E extends EventSchema = EmptyEventSchema> {
+    props?: P;
+    events?: E;
+    /** Internal run function - called by Java runtime with process context */
+    readonly __run: (this: TypedMcModuleAPI<E>, ctx: ScriptContext<InferProps<P>, E>) => void;
+    /** Internal type marker - set by defineScript */
+    readonly __type: "script";
+}
+/**
+ * Exported script type - what defineScript() returns.
+ * Combines the definition metadata with a callable run() method for imports.
+ *
+ * When a script is imported, it has:
+ * - props/events schemas for type inference
+ * - run(props) method that creates a new process
+ */
+export type ExportedScript<P extends PropSchema, E extends EventSchema = EmptyEventSchema> = Omit<ScriptDefinition<P, E>, '__run'> & ScriptModule<P, E>;
+export interface BlockConfig {
+    /** Unique identifier for the block (e.g., "tower", "custom_chair") */
+    id: string;
+    /** Model path (e.g., "kustom:block/tower") or BetterModel ID */
+    model: string;
+    /** Collision type: "full" (1x1x1), "slab" (half), "none", or custom dimensions */
+    collision?: "full" | "slab" | "none" | CollisionConfig;
+    /** Auto-generate placement item for this block */
+    autoPlace?: boolean;
+    /** Called when a player clicks the block */
+    onClick?: (event: BlockClickEvent) => void;
+    /** Called when the block is broken. Return false to prevent breaking. */
+    onBreak?: (event: BlockBreakEvent) => boolean | void;
+    /** Called when the block is placed */
+    onPlace?: (event: BlockPlaceEvent) => void;
+}
+export interface BlockDefinition extends BlockConfig {
+    readonly __type: "block";
+}
+export interface CollisionConfig {
+    /** Width in blocks (X axis) */
+    width: number;
+    /** Height in blocks (Y axis) */
+    height: number;
+    /** Depth in blocks (Z axis) */
+    depth: number;
+    /** Corner offset X */
+    cornerX?: number;
+    /** Corner offset Y */
+    cornerY?: number;
+    /** Corner offset Z */
+    cornerZ?: number;
+}
+export interface BlockClickEvent {
+    /** The block instance that was clicked */
+    readonly instance: ShaperBlockInstance;
+    /** The player who clicked */
+    readonly player: ScriptablePlayer;
+    /** Collision hit information, if available */
+    readonly collisionInfo: ScriptableCollisionInfo | null;
+    /** Cancel the click event */
+    cancel(): void;
+    /** Check if the event is cancelled */
+    isCancelled(): boolean;
+}
+export interface BlockBreakEvent {
+    /** The block instance being broken */
+    readonly instance: ShaperBlockInstance;
+    /** The player breaking the block (null for non-player causes) */
+    readonly player: ScriptablePlayer | null;
+    /** Collision hit information, if available */
+    readonly collisionInfo: ScriptableCollisionInfo | null;
+    /** Cancel the break event */
+    cancel(): void;
+    /** Check if the event is cancelled */
+    isCancelled(): boolean;
+}
+export interface BlockPlaceEvent {
+    /** The newly placed block instance */
+    readonly instance: ShaperBlockInstance;
+    /** The location where the block was placed */
+    readonly location: ScriptableLocation;
+    /** The player who placed the block (null for non-player placement) */
+    readonly player: ScriptablePlayer | null;
+    /** Cancel the place event */
+    cancel(): void;
+    /** Check if the event is cancelled */
+    isCancelled(): boolean;
+}
+export interface ItemConfig {
+    /** Unique identifier for the item (e.g., "magic_wand") */
+    id: string;
+    /** Base material (e.g., "STICK", "DIAMOND_SWORD") */
+    material: string;
+    /** Model path (e.g., "kustom:item/magic_wand") */
+    model: string;
+    /** Display name with MiniMessage formatting (e.g., "<gold>Magic Wand") */
+    displayName?: string;
+    /** Item description/lore */
+    description?: string;
+    /** Hide from creative menu / give commands */
+    hidden?: boolean;
+    /** Block ID this item places when right-clicked */
+    placesBlock?: string;
+    /** Called when right-clicking with the item */
+    onRightClick?: (event: ItemInteractEvent) => void;
+    /** Called when left-clicking with the item */
+    onLeftClick?: (event: ItemInteractEvent) => void;
+    /** Called when the item is dropped */
+    onDrop?: (event: ItemDropEvent) => void;
+    /** Called when the item is picked up */
+    onPickup?: (event: ItemPickupEvent) => void;
+    /** Called when the item is consumed (food/potion) */
+    onConsume?: (event: ItemConsumeEvent) => void;
+    /** Called when damaging an entity with the item */
+    onDamageEntity?: (event: ItemDamageEntityEvent) => void;
+    /** Called when shooting a bow/crossbow */
+    onShootBow?: (event: ItemShootBowEvent) => void;
+    /** Called when the item is selected in hotbar */
+    onHoldStart?: (event: ItemHoldEvent) => void;
+    /** Called when the item is deselected from hotbar */
+    onHoldEnd?: (event: ItemHoldEvent) => void;
+    /** Called when swapping item between hands */
+    onSwapHand?: (event: ItemSwapHandEvent) => void;
+    /** Called when item durability changes */
+    onDurabilityChange?: (event: ItemDurabilityEvent) => void;
+    /** Called when the item breaks from durability */
+    onBreak?: (event: ItemBreakEvent) => void;
+    /** Called when interacting with an entity */
+    onInteractEntity?: (event: ItemEntityInteractEvent) => void;
+    /** Called when breaking a block with the item */
+    onBlockBreak?: (event: ItemBlockBreakEvent) => void;
+    /** Called when placing a block with the item */
+    onBlockPlace?: (event: ItemBlockPlaceEvent) => void;
+}
+export interface ItemDefinition extends ItemConfig {
+    readonly __type: "item";
+}
+/**
+ * Context passed to script run function.
+ * Contains all APIs and subsystems available to scripts.
+ */
+export interface ScriptContext<P = Record<string, unknown>, E extends EventSchema = EmptyEventSchema> {
+    /** Process API for script management (typed for events if declared) */
+    process: TypedMcModuleAPI<E>;
+    /** Validated props */
+    props: P;
+    /** Who executed this script */
+    executor: ProcessExecutorAPI;
+    /** Camera system for cinematic views */
+    camera: CameraAPI;
+    /** Chat session system */
+    session: SessionAPI;
+    /** Chat GUI system */
+    chatGUI: ChatGUIAPI;
+    /** Command registration system */
+    command: CommandManager;
+    /** BetterModel entity system */
+    entity: BetterModelEntityAPI;
+    /** Shaper (custom block) system */
+    shaper: ShaperAPI;
+    /** Custom item system */
+    items: ItemAPI;
+    /** Model definition builder */
+    definition: DefinitionBuilder;
+    /** Persistent storage system */
+    storage: StorageAPI;
+}
+export interface PropSchema {
+    [key: string]: PropAPI;
+}
+export interface StringPropAPI {
+    readonly __brand: 'StringPropAPI';
+    readonly defaultValue?: string;
+}
+export interface NumberPropAPI {
+    readonly __brand: 'NumberPropAPI';
+    readonly defaultValue?: number;
+}
+export interface BooleanPropAPI {
+    readonly __brand: 'BooleanPropAPI';
+    readonly defaultValue?: boolean;
+}
+export interface ObjectPropAPI {
+    readonly __brand: 'ObjectPropAPI';
+    readonly defaultValue?: object;
+}
+export interface ArrayPropAPI {
+    readonly __brand: 'ArrayPropAPI';
+    readonly defaultValue?: unknown[];
+}
+export interface UnionPropAPI<T = unknown> {
+    readonly __brand: 'UnionPropAPI';
+    readonly defaultValue?: T;
+}
+export interface GenericPropAPI<T = unknown> {
+    readonly __brand: 'GenericPropAPI';
+    readonly defaultValue?: T;
+}
+/** Base PropAPI type - union of all specific prop types */
+export type PropAPI = StringPropAPI | NumberPropAPI | BooleanPropAPI | ObjectPropAPI | ArrayPropAPI | UnionPropAPI | GenericPropAPI;
+export type InferProps<P extends PropSchema> = {
+    [K in keyof P]: InferPropType<P[K]>;
+};
+/**
+ * Infer the actual type from a PropAPI definition.
+ * Used for both props and events.
+ */
+export type InferPropType<T> = T extends StringPropAPI ? string : T extends NumberPropAPI ? number : T extends BooleanPropAPI ? boolean : T extends ObjectPropAPI ? object : T extends ArrayPropAPI ? unknown[] : T extends UnionPropAPI<infer U> ? U : T extends GenericPropAPI<infer U> ? U : unknown;
+export interface ScreenConstructor {
+    /** Create a screen with vanilla background (no custom texture) */
+    new (size: number, options?: ScreenOptions): Screen;
+    /** Create a screen with custom texture */
+    new (texture: string, size: number, options?: ScreenOptions): Screen;
+}
+export interface ElementFactory {
+    item(item: ScriptableItem): Element;
+    button(texture: string, title: string | null): Element;
+    display(texture: string): Element;
+    /** Create a content slot that accepts player items */
+    contentSlot(): Element;
+    /** Create a content slot with a placeholder texture */
+    contentSlotWithPlaceholder(placeholderTexture: string): Element;
+}
+export interface ScriptableLocationFactory {
+    create(x: number, y: number, z: number, worldName: string): ScriptableLocation;
+}
+/**
+ * Screen constructor - create new screens for GUIs.
+ * Actual value is injected by Java at runtime.
+ * Build system strips imports, resolving to Java-injected global.
+ */
+export declare const Screen: ScreenConstructor;
+/**
+ * Container constructor - create child containers within screens.
+ * Actual value is injected by Java at runtime.
+ */
+export declare const Container: ContainerConstructor;
+/**
+ * Element factory - create GUI elements (buttons, items, slots).
+ * Actual value is injected by Java at runtime.
+ */
+export declare const Element: ElementFactory;
+/**
+ * Props factory - create property type definitions for scripts.
+ * Actual value is injected by Java at runtime.
+ */
+export declare const Props: PropsAPI;
+/**
+ * CellState utility - slot state management constants and helpers.
+ * Actual value is injected by Java at runtime.
+ */
+export declare const CellState: CellStateUtils;
+/**
+ * ScriptableLocation factory - create location objects.
+ * Actual value is injected by Java at runtime.
+ */
+export declare const ScriptableLocation: ScriptableLocationFactory;
+declare global {
+    function setTimeout(callback: () => void, delay: number): number;
+    function clearTimeout(id: number): void;
+    function setInterval(callback: () => void, delay: number): number;
+    function clearInterval(id: number): void;
+    interface Console {
+        log(...args: unknown[]): void;
+        warn(...args: unknown[]): void;
+        error(...args: unknown[]): void;
+        info(...args: unknown[]): void;
+        debug(...args: unknown[]): void;
+    }
+}
+/**
+ * Lightweight class for per-slot background color overrides.
+ * Used to set a specific color for a single slot, overriding the inherited color.
+ */
+export interface BackgroundSlot {
+    /**
+     * Set the background color for this slot.
+     * @param hex Color in hex format (e.g., "#FF0000")
+     * @returns this for chaining
+     */
+    setColor(hex: string): BackgroundSlot;
+    /**
+     * Clear the override and use inherited color from parent.
+     */
+    clear(): void;
+    /**
+     * Check if this slot has an explicit color override.
+     */
+    hasOverride(): boolean;
+    /**
+     * Get the local index of this slot within its parent.
+     */
+    getLocalIndex(): number;
+}
+/**
+ * Cell state enum representing the state of a GUI slot.
+ * Used to determine slot behavior for item movement and click events.
+ */
+export type CellState = "EMPTY" | "CONTENT" | "BUTTON";
+/**
+ * Utility interface for CellState operations.
+ * Access via CellState global constant.
+ */
+export interface CellStateUtils {
+    /** Empty slot - allows item placement */
+    readonly EMPTY: CellState;
+    /** Content slot - contains player-placed items, allows movement */
+    readonly CONTENT: CellState;
+    /** Button slot - interactive element, blocks item movement */
+    readonly BUTTON: CellState;
+    /** Get the priority of a cell state (BUTTON > CONTENT > EMPTY) */
+    getPriority(state: CellState): number;
+    /** Check if the state allows item movement (EMPTY and CONTENT do) */
+    allowsItemMovement(state: CellState): boolean;
+    /** Check if the state fires click events (BUTTON does) */
+    firesClickEvents(state: CellState): boolean;
+    /** Get the higher priority state between two states */
+    max(a: CellState, b: CellState): CellState;
+}
+export interface ContainerConstructor {
+    new (config: ContainerConfig): Container;
+}
+export interface ScreenOptions {
+    persistenceKey?: string;
+    /**
+     * Use player inventory slots for GUI components (default: false).
+     * - When false: Player sees their normal inventory below the chest with "Inventory" label
+     * - When true: Player inventory becomes extended GUI space (slots 54-89), items stored, no label
+     */
+    usePlayerInventorySlots?: boolean;
+    /** Unique identifier for persistence path */
+    id?: string;
+    /**
+     * Enable content slot persistence for this screen and its children.
+     * Default: true when persistenceKey is set, false otherwise.
+     * Children inherit this value unless they override it.
+     */
+    persist?: boolean;
+    /**
+     * Enable scroll position persistence for this screen and its children.
+     * Default: false. Children inherit this value unless they override it.
+     */
+    persistScroll?: boolean;
+}
+/**
+ * Screen is the root component of the new GUI system.
+ * It manages the inventory, title rendering, and component tree.
+ * Note: In runtime, Screen extends Container, but for type safety we define it separately.
+ */
+export interface Screen {
+    createContainer(config: ContainerConfig): Container;
+    add(component: GuiComponentType): Screen;
+    /** Add a button at a specific slot */
+    addButton(slot: number, texture: string, title: string | null, onClick?: (event: ElementClickEvent) => void): Element;
+    removeButton(slot: number): void;
+    getButton(slot: number): Element | null;
+    appendText(text: string, size: number, y: number, centered: boolean): GuiText;
+    clearText(): void;
+    /**
+     * Set the background color for this screen.
+     * All child containers and slots inherit this color unless they override it.
+     * Default is #C6C6C6 (vanilla inventory gray).
+     * @param hex Color in hex format (e.g., "#222222")
+     */
+    setBackgroundColor(hex: string): void;
+    /**
+     * Get or create a background slot override for a specific screen slot.
+     * Use this to set a custom color for a single slot.
+     * @param slot The screen slot index
+     * @returns BackgroundSlot for chaining (e.g., putBackground(0).setColor("#FF0000"))
+     */
+    putBackground(slot: number): BackgroundSlot;
+    open(player: ScriptablePlayer | string): void;
+    close(): void;
+    refresh(): void;
+    /**
+     * Set or remove the custom texture.
+     * Pass null or empty string to switch to vanilla background.
+     */
+    setTexture(texture: string | null): void;
+    /** Get the current texture name, or null if using vanilla background */
+    getTexture(): string | null;
+    getSize(): number;
+    getId(): string;
+    getPersistenceKey(): string | null;
+    isPersistent(): boolean;
+    getViewerCount(): number;
+    /** Get total slots including player inventory if enabled */
+    getTotalSlots(): number;
+    /** Check if a screen slot maps to the player's inventory */
+    isPlayerInventorySlot(screenSlot: number): boolean;
+    /** Convert a screen slot to a player inventory slot (0-35) */
+    toPlayerInventorySlot(screenSlot: number): number;
+    /** Convert a player inventory slot (0-35) to a screen slot */
+    fromPlayerInventorySlot(playerSlot: number): number;
+    /**
+     * Check if player inventory slots are being used for GUI components.
+     * When true, player inventory becomes extended GUI space (slots 54-89).
+     */
+    isUsingPlayerInventorySlots(): boolean;
+    /**
+     * Enable/disable using player inventory slots for GUI components.
+     * - When false (default): Player sees vanilla inventory below chest with "Inventory" label
+     * - When true: Player inventory becomes extended GUI (items stored, no label, covered)
+     */
+    setUsePlayerInventorySlots(enabled: boolean): void;
+    /** Get the cell state at a specific slot */
+    getCellState(slot: number): CellState;
+    /** Save the screen state to disk (content slots and scroll positions) */
+    save(): void;
+    /** Load persisted state from disk (called automatically on first open) */
+    load(): void;
+    /** Destroy the screen and delete persisted data */
+    destroy(): void;
+    onEvent(eventName: "open" | "close", callback: (player: ScriptablePlayer) => void): Screen;
+    /** Register an event callback */
+    on(eventName: string, callback: (...args: unknown[]) => void): void;
+}
+export interface ContainerConfig {
+    startSlot?: number;
+    rows?: number;
+    cols?: number;
+    /** Layout type: "grid" (default) or "flex" */
+    layout?: "grid" | "flex";
+    /** Flow direction: "row" (default) or "column" */
+    direction?: "row" | "column";
+    /** Gap between children (for flex layout) */
+    gap?: number;
+    /** Enable scrolling */
+    scrollable?: boolean;
+    /** Maximum number of children */
+    maxCapacity?: number;
+    /**
+     * Unique identifier for persistence.
+     * Required if persist is true and container has content to save.
+     */
+    id?: string;
+    /**
+     * Enable content slot persistence.
+     * Default: inherited from parent (true if screen has persistenceKey).
+     */
+    persist?: boolean;
+    /**
+     * Enable scroll position persistence.
+     * Default: inherited from parent (false).
+     */
+    persistScroll?: boolean;
+}
+export interface ContentAreaConfig {
+    startSlot: number;
+    rows: number;
+    cols: number;
+}
+/**
+ * Container groups elements in a region of the GUI.
+ * Supports both static (grid) and scrollable layouts.
+ */
+export interface Container {
+    /** Add a child at the next available index */
+    addChild(child: Element | Container): Container;
+    /** Add a child at a specific virtual index */
+    addChildAt(index: number, child: Element | Container): Container;
+    /** Remove a child at a specific index */
+    removeChildAt(index: number): Container;
+    /** Get a child at a specific index */
+    getChildAt(index: number): Element | Container | null;
+    /** Get the number of children */
+    getChildCount(): number;
+    /** Clear all children */
+    clear(): Container;
+    /** Add a button at the next available index */
+    addButton(texture: string, title: string | null, onClick?: (event: ElementClickEvent) => void): Element;
+    /** Add a button at a specific index */
+    addButtonAt(index: number, texture: string, title: string | null, onClick?: (event: ElementClickEvent) => void): Element;
+    /** Add a content slot at the next available index */
+    addContentSlot(): Element;
+    /** Add a content slot at a specific index */
+    addContentSlotAt(index: number): Element;
+    /** Add a nested container at the next available index */
+    addContainer(config: ContainerConfig): Container;
+    /** Add a nested container at a specific index */
+    addContainerAt(index: number, config: ContainerConfig): Container;
+    /** Alias for addChild */
+    add(element: Element | Container): Container;
+    /** Alias for addChildAt */
+    addAt(index: number, element: Element | Container): Container;
+    /** Push a button at the next available index */
+    pushButton(texture: string, title: string | null, onClick?: (event: ElementClickEvent) => void): Element;
+    /** Put a button at a specific index */
+    putButton(index: number, texture: string, title: string | null, onClick?: (event: ElementClickEvent) => void): Element;
+    /** Push a content slot at the next available index */
+    pushContentSlot(): Element;
+    /** Put a content slot at a specific index */
+    putContentSlot(index: number): Element;
+    /** Push a nested container at the next available index */
+    pushContainer(config: ContainerConfig): Container;
+    /** Put a nested container at a specific index */
+    putContainer(index: number, config: ContainerConfig): Container;
+    /**
+     * Set the background color for this container.
+     * All slots within this container inherit this color unless they have an explicit override.
+     * @param hex Color in hex format (e.g., "#333333")
+     */
+    setBackgroundColor(hex: string): void;
+    /**
+     * Get or create a background slot override for a specific local slot index.
+     * Use this to set a custom color for a single slot within the container.
+     * @param localIndex The local slot index within this container
+     * @returns BackgroundSlot for chaining (e.g., putBackground(0).setColor("#FF0000"))
+     */
+    putBackground(localIndex: number): BackgroundSlot;
+    /** Set the layout type */
+    setLayout(layout: "grid" | "flex"): Container;
+    /** Set the flow direction */
+    setDirection(direction: "row" | "column"): Container;
+    /** Set the gap between children (flex layout) */
+    setGap(gap: number): Container;
+    /** Set the start slot (top-left corner) */
+    setStartSlot(slot: number): Container;
+    /** Set the number of rows */
+    setRows(rows: number): Container;
+    /** Set the number of columns */
+    setCols(cols: number): Container;
+    getLayout(): "grid" | "flex";
+    getDirection(): "row" | "column";
+    getGap(): number;
+    getStartSlot(): number;
+    getRows(): number;
+    getCols(): number;
+    getSlotCount(): number;
+    /** Alias for getChildCount */
+    getElementCount(): number;
+    /** Alias for getChildAt */
+    getElementAt(index: number): Element | Container | null;
+    /**
+     * Get the virtual index (position in parent's children map).
+     * This is the key used to identify this container within its parent.
+     */
+    getIndex(): number;
+    /** Set the unique identifier for persistence */
+    setId(id: string): Container;
+    /** Get the unique identifier */
+    getId(): string | null;
+    /** Set whether content slots should be persisted */
+    setPersist(persist: boolean): Container;
+    /** Get effective persist value (accounting for inheritance) */
+    isPersist(): boolean;
+    /** Set whether scroll position should be persisted */
+    setPersistScroll(persistScroll: boolean): Container;
+    /** Get effective persistScroll value (accounting for inheritance) */
+    isPersistScroll(): boolean;
+    /** Enable or disable scrolling */
+    setScrollable(scrollable: boolean): Container;
+    /** Check if scrollable */
+    isScrollable(): boolean;
+    /** Set the maximum number of children */
+    setMaxCapacity(max: number): Container;
+    /** Get the maximum capacity */
+    getMaxCapacity(): number;
+    /** Check if at max capacity */
+    isFull(): boolean;
+    /** Get remaining capacity */
+    getRemainingCapacity(): number;
+    /** Scroll by an offset (positive = forward, negative = backward) */
+    scroll(offset: number): void;
+    /** Scroll by one page (direction: 1 = next, -1 = previous) */
+    scrollPage(direction: 1 | -1): void;
+    /** Scroll to a specific virtual index */
+    scrollTo(virtualIndex: number): void;
+    /** Scroll to a specific page */
+    scrollToPage(page: number): void;
+    /** Get the number of items that fit on one page */
+    getPageSize(): number;
+    /** Get the total number of pages */
+    getPageCount(): number;
+    /** Get the current page (0-based) */
+    getCurrentPage(): number;
+    /** Get the current scroll offset */
+    getScrollOffset(): number;
+    /** Get the virtual size (highest index + 1) */
+    getVirtualSize(): number;
+    /** Check if there's a next page */
+    hasNextPage(): boolean;
+    /** Check if there's a previous page */
+    hasPreviousPage(): boolean;
+    /** Convert a relative slot to an absolute screen slot */
+    toAbsoluteSlot(relativeSlot: number): number;
+    /** Convert an absolute screen slot to a relative slot */
+    toRelativeSlot(absoluteSlot: number): number;
+    /** Convert virtual index to GUI slot (accounting for scroll) */
+    virtualIndexToSlot(virtualIndex: number): number;
+    /** Convert GUI slot to virtual index (accounting for scroll) */
+    slotToVirtualIndex(slot: number): number;
+    /** Get the cell state at a specific slot */
+    getCellState(slot: number): CellState;
+    /** Register an event callback */
+    on(eventName: string, callback: (...args: unknown[]) => void): void;
+    on(event: "click", callback: (slot: number, virtualIndex: number) => void): void;
+    on(event: "scroll", callback: (offset: number, page: number) => void): void;
+    on(event: "childAdded", callback: (child: Element | Container, index: number) => void): void;
+    on(event: "childRemoved", callback: (child: Element | Container, index: number) => void): void;
+    on(event: "cleared", callback: () => void): void;
+    on(event: "capacityReached", callback: () => void): void;
+}
+/**
+ * Element is the unified item/button type.
+ * Can represent items, buttons, display-only elements, or content slots.
+ */
+export interface Element {
+    setTexture(texture: string): Element;
+    setTitle(title: string | null): Element;
+    setLore(lines: string[]): Element;
+    setHideTooltip(hide: boolean): Element;
+    setInteractive(interactive: boolean): Element;
+    setPickupable(pickupable: boolean): Element;
+    setData(data: unknown): Element;
+    getTexture(): string | null;
+    getTitle(): string | null;
+    getLore(): string[];
+    getData(): unknown;
+    isInteractive(): boolean;
+    isPickupable(): boolean;
+    getType(): "item" | "button" | "display" | "content_slot";
+    /** Get the cell state for this element's slot */
+    getCellState(slot: number): CellState;
+    /**
+     * Get the virtual index (position in parent's children map).
+     * This is the key used to identify this element within its parent container.
+     */
+    getIndex(): number;
+    /**
+     * Get the computed real slot based on parent's scroll context.
+     * For non-scrollable containers, this equals the virtual index.
+     * For scrollable containers, this accounts for scroll offset.
+     */
+    getRealSlot(): number;
+    /** Get the item stored in this content slot */
+    getStoredItem(): ScriptableItem | null;
+    /** Set the item stored in this content slot */
+    setStoredItem(item: ScriptableItem | null): void;
+    /** Check if this content slot has an item */
+    hasStoredItem(): boolean;
+    /** Clear the stored item */
+    clearStoredItem(): void;
+    /**
+     * Set whether this content slot should be persisted.
+     * Only applicable for CONTENT_SLOT type.
+     * If not set, inherits from parent container.
+     */
+    setPersist(persist: boolean): Element;
+    /**
+     * Get effective persist value for this content slot.
+     * Only applicable for CONTENT_SLOT type.
+     */
+    isPersist(): boolean;
+    onClick(callback: (event: ElementClickEvent) => void): Element;
+    onLeftClick(callback: (event: ElementClickEvent) => void): Element;
+    onRightClick(callback: (event: ElementClickEvent) => void): Element;
+    onShiftClick(callback: (event: ElementClickEvent) => void): Element;
+    onMiddleClick(callback: (event: ElementClickEvent) => void): Element;
+    /** Register a generic event callback */
+    on(eventName: string, callback: (...args: unknown[]) => void): void;
+    /** Called before item placement (CONTENT_SLOT only) - return false to cancel */
+    on(event: "beforeItemPlace", callback: (item: ScriptableItem, player: ScriptablePlayer) => boolean | void): void;
+    /** Called after item placement (CONTENT_SLOT only). Index is the virtual index of this element. */
+    on(event: "afterItemPlace", callback: (item: ScriptableItem, player: ScriptablePlayer, index: number) => void): void;
+    /** Called before item removal (CONTENT_SLOT only) - return false to cancel */
+    on(event: "beforeItemTake", callback: (player: ScriptablePlayer) => boolean | void): void;
+    /** Called after item removal (CONTENT_SLOT only). Index is the virtual index of this element. */
+    on(event: "afterItemTake", callback: (player: ScriptablePlayer, index: number) => void): void;
+}
+/**
+ * Click event for Element interactions.
+ */
+export interface ElementClickEvent {
+    getElement(): Element;
+    getSlot(): number;
+    getClickType(): "left" | "right" | "middle" | "shift_left" | "shift_right" | "double_click" | "drop" | "control_drop" | "number_key" | "unknown";
+    isShiftClick(): boolean;
+    getData(): unknown;
+    cancel(): void;
+    isCancelled(): boolean;
+}
+export type GuiComponentType = Container | Element;
+export interface ContainerClickEvent {
+    index: number;
+}
+export interface PropsAPI {
+    String: (defaultValue?: string) => StringPropAPI;
+    Number: (defaultValue?: number) => NumberPropAPI;
+    Boolean: (defaultValue?: boolean) => BooleanPropAPI;
+    Object: (defaultValue?: object) => ObjectPropAPI;
+    Array: (defaultValue?: unknown[]) => ArrayPropAPI;
+    Union: <T extends readonly (string | number | boolean)[]>(...values: T) => UnionPropAPI<T[number]>;
+    Generic: <T = unknown>(defaultValue?: T) => GenericPropAPI<T>;
+}
+export type ExtractPropType<T> = InferPropType<T>;
+export type PropsObject<T> = {
+    [K in keyof T]: InferPropType<T[K]>;
+};
+/**
+ * Base McModuleAPI interface with untyped emit.
+ * Use TypedMcModuleAPI for typed events.
+ */
+export interface McModuleAPI {
+    getProp: (key: string) => unknown;
+    emit: (event: string, ...args: unknown[]) => void;
+    exit: (value: unknown) => void;
+    getPlayer: (player: string) => ScriptablePlayer;
+    defineProps<T extends Record<string, unknown>>(props: T): PropsObject<T>;
+    open: (scriptName: string, props: Record<string, unknown>) => ScriptProcess;
+    camera: CameraAPI;
+    session: SessionAPI;
+    chatGUI: ChatGUIAPI;
+    command: CommandManager;
+    entity: BetterModelEntityAPI;
+    executor: ProcessExecutorAPI;
+    shaper: ShaperAPI;
+    items: ItemAPI;
+    definition: DefinitionBuilder;
+    storage: StorageAPI;
+}
+/**
+ * Typed McModuleAPI with event type inference.
+ * When events are declared, emit() is typed to only accept declared event names.
+ * When no events are declared (EmptyEventSchema), emit() accepts any string (backward compatible).
+ */
+export type TypedMcModuleAPI<E extends EventSchema = EmptyEventSchema> = E extends EmptyEventSchema ? McModuleAPI : Omit<McModuleAPI, 'emit'> & {
+    /**
+     * Emit a typed event to parent process.
+     * Only declared event names are allowed.
+     *
+     * @param event Event name (must be declared in events schema)
+     * @param value Event payload (type checked against schema)
+     */
+    emit<K extends keyof E>(event: K, value: InferPropType<E[K]>): void;
+};
+/**
+ * Base ScriptProcess interface with untyped events.
+ * Use TypedScriptProcess for type-safe event handling.
+ */
+export interface ScriptProcess {
+    /** Listen for events emitted by the script */
+    on(event: string, callback: (...args: unknown[]) => void): ScriptProcess;
+    /** Listen for an event only once (auto-removes after first call) */
+    once(event: string, callback: (...args: unknown[]) => void): ScriptProcess;
+    /** Remove event listener(s). If callback is omitted, removes all listeners for that event. */
+    off(event: string, callback?: (...args: unknown[]) => void): ScriptProcess;
+    /** Call a method on the script */
+    call(method: string, ...args: unknown[]): void;
+    /** Emit an event to the script */
+    emit(event: string, ...args: unknown[]): void;
+    /** Get the process ID */
+    getId(): number;
+    /** Check if the process has exited */
+    hasExited(): boolean;
+    /** Wait for the process to complete and get the return value */
+    then(callback: (value: unknown) => void): ScriptProcess;
+    /** Handle errors from the process */
+    catch(callback: (error: unknown) => void): ScriptProcess;
+}
+/**
+ * Typed ScriptProcess with event type inference.
+ * When the script declares events, on/once callbacks are typed.
+ *
+ * @example
+ * ```typescript
+ * // If digicode declares: events: { onSuccess: Props.Boolean() }
+ * const child = digicode.run({ code: "1234" });
+ * child.on("onSuccess", (value) => {
+ *   // value is typed as boolean
+ * });
+ * ```
+ */
+export interface TypedScriptProcess<E extends EventSchema = EmptyEventSchema> extends Omit<ScriptProcess, 'on' | 'once' | 'off'> {
+    /**
+     * Listen for events emitted by the script.
+     * When events are declared, only declared event names are allowed.
+     */
+    on<K extends keyof E>(event: K, callback: (value: InferPropType<E[K]>) => void): TypedScriptProcess<E>;
+    on(event: string, callback: (...args: unknown[]) => void): TypedScriptProcess<E>;
+    /**
+     * Listen for an event only once (auto-removes after first call).
+     * When events are declared, only declared event names are allowed.
+     */
+    once<K extends keyof E>(event: K, callback: (value: InferPropType<E[K]>) => void): TypedScriptProcess<E>;
+    once(event: string, callback: (...args: unknown[]) => void): TypedScriptProcess<E>;
+    /**
+     * Remove event listener(s).
+     * If callback is omitted, removes all listeners for that event.
+     */
+    off<K extends keyof E>(event: K, callback?: (value: InferPropType<E[K]>) => void): TypedScriptProcess<E>;
+    off(event: string, callback?: (...args: unknown[]) => void): TypedScriptProcess<E>;
+}
+/**
+ * Represents an imported script module.
+ * Scripts can import other scripts and invoke them with typed props and events.
+ *
+ * @example
+ * ```typescript
+ * import digicode from "./digicode";
+ *
+ * // Run the imported script with props
+ * const process = digicode.run({ code: "1234" });
+ *
+ * // Listen for typed events (if digicode declares events)
+ * process.on("onSuccess", (value) => {
+ *   // value is typed based on event declaration
+ * });
+ *
+ * process.then(result => console.log("Result:", result));
+ * ```
+ */
+export interface ScriptModule<P extends PropSchema = PropSchema, E extends EventSchema = EmptyEventSchema> {
+    /**
+     * Run the imported script with the given props.
+     * Creates a new process for the script execution.
+     *
+     * @param props Props to pass to the script
+     * @returns A TypedScriptProcess handle for the running script (with event types if declared)
+     */
+    run(props: InferProps<P>): TypedScriptProcess<E>;
+    /**
+     * Get the script name/path.
+     */
+    readonly name: string;
+}
+/**
+ * Type helper to infer ScriptModule type from a ScriptDefinition.
+ * Extracts both props AND events for full type inference.
+ *
+ * @example
+ * ```typescript
+ * // digicode.ts
+ * export default defineScript({
+ *   props: { code: Props.String() },
+ *   events: { onSuccess: Props.Boolean() },
+ *   run({ props }) { ... }
+ * });
+ *
+ * // main.ts - TypeScript infers both props and events
+ * import digicode from "./digicode";
+ * const child = digicode.run({ code: "1234" }); // Props type-safe!
+ * child.on("onSuccess", (val) => { ... }); // Events type-safe! val is boolean
+ * ```
+ */
+export type InferScriptModule<T> = T extends ScriptDefinition<infer P, infer E> ? ScriptModule<P, E> : T extends ScriptDefinition<infer P> ? ScriptModule<P, EmptyEventSchema> : ScriptModule<PropSchema, EmptyEventSchema>;
+/**
+ * GuiText represents a text overlay in a GUI title.
+ * Returned by Screen.appendText().
+ * Supports dynamic updates and centering.
+ */
+export interface GuiText {
+    /**
+     * Update the text content and refresh the GUI title.
+     * Supports MiniMessage format for colors and formatting.
+     * @param text The new text content
+     * @returns this for method chaining
+     */
+    update(text: string): GuiText;
+    /**
+     * Set text to be centered in the GUI title.
+     * @returns this for method chaining
+     */
+    centered(): GuiText;
+    /**
+     * Check if text is centered.
+     * @returns true if centered
+     */
+    isCentered(): boolean;
+    /**
+     * Set the line break width in pixels.
+     * Text will wrap to the next line when exceeding this width.
+     * Default is 160 pixels.
+     * @param pixels The width in pixels at which to break lines
+     * @returns this for method chaining
+     */
+    lineBreakAt(pixels: number): GuiText;
+    /**
+     * Get the line break width in pixels.
+     * @returns The line break width
+     */
+    getLineBreakAt(): number;
+}
+export interface ScriptablePlayer {
+    giveItem(item: ScriptableItem): void;
+    getName(): string;
+    getUUID(): string;
+    hasPermission(permission: string): boolean;
+    sendMessage(message: string): void;
+    clearChat(): void;
+    /** Get current location as ScriptableLocation */
+    getLocation(): ScriptableLocation;
+    /** Get eye location as ScriptableLocation */
+    getEyeLocation(): ScriptableLocation;
+    /** Teleport to a location */
+    teleport(location: ScriptableLocation): void;
+    /** Teleport to coordinates in current world */
+    teleportTo(x: number, y: number, z: number): void;
+    isOnline(): boolean;
+    exists(): boolean;
+    getWorld(): string | null;
+    getHealth(): number;
+    getMaxHealth(): number;
+    getFoodLevel(): number;
+    getExperienceLevel(): number;
+    getGamemode(): string;
+    getChatSessionId(): string | null;
+    getChatSession(): unknown | null;
+    setChatSession(session: unknown): void;
+}
+/**
+ * Wrapper for items - supports both vanilla Minecraft items and custom items.
+ *
+ * Properties:
+ * - `type` - Item name for custom items (e.g., "magic_sword"), Material name for vanilla (e.g., "DIAMOND_SWORD")
+ * - `isCustom` - true if this is a custom item registered with Kustom
+ * - `amount` - Stack amount
+ * - `material` - Material name (always available)
+ * - `air` - true if this is an air item
+ * - `customItem` - Access to underlying ScriptableCustomItem (null for vanilla)
+ *
+ * @example
+ * ```typescript
+ * slot.on("afterItemPlace", (item, player) => {
+ *   if (item.isCustom) {
+ *     console.log("Custom item: " + item.type); // "magic_sword"
+ *   } else {
+ *     console.log("Vanilla item: " + item.type); // "DIAMOND_SWORD"
+ *   }
+ * });
+ * ```
+ */
+export interface ScriptableItem {
+    /**
+     * Get the item type.
+     * For custom items: returns the custom item name (e.g., "magic_sword")
+     * For vanilla items: returns the Material name (e.g., "DIAMOND_SWORD")
+     */
+    readonly type: string;
+    /** Check if this is a custom item registered with Kustom */
+    readonly isCustom: boolean;
+    /** Get the item stack amount */
+    readonly amount: number;
+    /** Get the material name (e.g., "DIAMOND_SWORD") */
+    readonly material: string;
+    /** Check if this item is air/empty */
+    readonly air: boolean;
+    /**
+     * Get the underlying custom item wrapper (null for vanilla items).
+     * Use this to access custom item-specific methods and properties.
+     */
+    readonly customItem: ScriptableCustomItem | null;
+    /** Get the underlying ItemStack (internal use) */
+    getItemStack(): unknown;
+}
+/**
+ * Wrapper for CustomItem - provides access to custom item properties.
+ */
+export interface ScriptableCustomItem {
+    /** Get the custom item name/ID */
+    readonly name: string;
+    /** Get the base material of this item */
+    getMaterial(): string;
+    /** Get an ItemStack for this item */
+    getItemStack(): unknown;
+    /** Get an ItemStack with a specific amount */
+    getItemStack(amount: number): unknown;
+    /** Check if this item is valid */
+    isValid(): boolean;
+}
+export interface CameraAPI {
+    create(x: number, y: number, z: number): Camera;
+    create(x: number, y: number, z: number, yaw: number, pitch: number): Camera;
+    createAtEyeLevel(x: number, y: number, z: number): Camera;
+    get(id: string): Camera | null;
+    get(id: string | object): Camera | null;
+    isPlayerSpectating(playerName: string): boolean;
+    getPlayerCamera(playerName: string): Camera | null;
+    getCount(): number;
+    getSpectatorCount(): number;
+    remove(id: string): boolean;
+    remove(id: string | object): boolean;
+    startCameraMode(playerName: string, cameraId: string): boolean;
+    stopSpectating(playerName: string): boolean;
+    getAnimation(): CameraAnimationAPI;
+}
+export interface Camera {
+    getId(): string;
+    getLocation(): [number, number, number];
+    setLocation(x: number, y: number, z: number): void;
+    setLocation(x: number, y: number, z: number, yaw: number, pitch: number): void;
+    getYaw(): number;
+    setYaw(yaw: number): void;
+    getPitch(): number;
+    setPitch(pitch: number): void;
+    setRotation(yaw: number, pitch: number): void;
+    getDirection(): [number, number, number];
+    setDirection(x: number, y: number, z: number): void;
+    isActive(): boolean;
+    getSpectator(): string | null;
+    getSpectatorCount(): number;
+    startCameraMode(playerName: string): boolean;
+    move(dx: number, dy: number, dz: number): void;
+    moveTo(x: number, y: number, z: number): void;
+    rotate(yaw: number, pitch: number): void;
+    lookAt(x: number, y: number, z: number): void;
+    lookAtPlayer(playerName: string): void;
+    isTransparentViewEnabled(): boolean;
+    setTransparentView(enabled: boolean): void;
+    toggleTransparentView(): void;
+    clearTransparentView(): void;
+    forceUpdateTransparentView(): void;
+    setTarget(x: number, y: number, z: number): void;
+    setTargetPlayer(playerName: string): void;
+    clearTarget(): void;
+    hasTarget(): boolean;
+    stopSpectating(): boolean;
+    remove(): boolean;
+    forceUpdate(): void;
+    createFakeEntity(): void;
+    toString(): string;
+}
+export interface CameraAnimationAPI {
+    createAnimation(): CameraAnimationBuilder;
+    createTargetAnimation(x: number, y: number, z: number): TargetAnimationBuilder;
+    createEntityTargetAnimation(entityName: string): EntityTargetAnimationBuilder;
+    createAnimationSet(): AnimationSetBuilder;
+    startFollowing(cameraId: string, playerName: string, offsetX: number, offsetY: number, offsetZ: number): void;
+    isFollowing(cameraId: string): boolean;
+    stopFollowing(cameraId: string): void;
+    getPath(): PathAPI;
+    getCurve(): CurveAPI;
+}
+export interface CameraAnimationBuilder {
+    start(x: number, y: number, z: number): CameraAnimationBuilder;
+    end(x: number, y: number, z: number): CameraAnimationBuilder;
+    duration(seconds: number): CameraAnimationBuilder;
+    framerate(fps: number): CameraAnimationBuilder;
+    camera(cameraId: string): CameraAnimationBuilder;
+    onStart(callback: () => void): CameraAnimationBuilder;
+    onEnd(callback: () => void): CameraAnimationBuilder;
+    build(): AnimationSet;
+}
+export interface TargetAnimationBuilder {
+    duration(seconds: number): TargetAnimationBuilder;
+    camera(cameraId: string): TargetAnimationBuilder;
+    moveTo(offsetX: number, offsetY: number, offsetZ: number): AnimationSet;
+}
+export interface EntityTargetAnimationBuilder {
+    duration(seconds: number): EntityTargetAnimationBuilder;
+    camera(cameraId: string): EntityTargetAnimationBuilder;
+    orbit(radius: number, height: number, startAngle: number, endAngle: number): AnimationSet;
+}
+export interface AnimationSetBuilder {
+    append(animation: CameraAnimation): AnimationSetBuilder;
+    delay(seconds: number): AnimationSetBuilder;
+    onComplete(callback: () => void): AnimationSetBuilder;
+    build(): AnimationSet;
+}
+export interface CameraAnimation {
+    start(): void;
+    stop(): void;
+    isRunning(): boolean;
+}
+export interface TargetAnimation extends CameraAnimation {
+}
+export interface EntityTargetAnimation extends CameraAnimation {
+}
+export interface AnimationSet {
+    start(): void;
+    stop(): void;
+    isRunning(): boolean;
+}
+export interface PathAPI {
+    line(): Path;
+    circle(): Path;
+    spiral(radius: number, height: number, rotations: number): Path;
+    figure8(width: number, height: number): Path;
+    zigzag(width: number, height: number, segments: number): Path;
+    bounce(height: number, bounces: number): Path;
+    wave(amplitude: number, frequency: number, length: number): Path;
+}
+export interface Path {
+    getPosition(startX: number, startY: number, startZ: number, endX: number, endY: number, endZ: number, progress: number): [number, number, number];
+}
+export interface CurveAPI {
+    linear(): Curve;
+    easeIn(): Curve;
+    easeOut(): Curve;
+    easeInOut(): Curve;
+    bounce(): Curve;
+    elastic(): Curve;
+    sine(): Curve;
+    exponential(): Curve;
+    back(): Curve;
+    circular(): Curve;
+    step(steps: number): Curve;
+    pulse(): Curve;
+}
+export interface Curve {
+    getValue(progress: number): number;
+}
+export interface SessionAPI {
+    create(sessionId: string, callback: (playerName: string, message: string, sessionId: string) => void): ChatSession;
+    get(sessionId: string): ChatSession | null;
+    close(sessionId: string): void;
+    getCount(): number;
+    getTotalPlayers(): number;
+    isPlayerInSession(playerName: string): boolean;
+}
+export interface ChatSession {
+    getSessionId(): string;
+    getViewerCount(): number;
+    hasPlayer(playerName: string): boolean;
+    addPlayer(playerName: string): void;
+    removePlayer(playerName: string): void;
+    sendMessage(message: string): void;
+    sendMessageToPlayer(playerName: string, message: string): void;
+    close(): void;
+    setClusterMode(clusterMode: boolean): void;
+    isClusterMode(): boolean;
+    clearPlayerChat(playerName: string): void;
+}
+export interface ChatGUIAPI {
+    create(): ChatGUI;
+    getCount(): number;
+}
+export interface ChatGUI {
+    onInput(callback: (playerName: string, message: string, guiId: string) => void): void;
+    setId(guiId: string): void;
+    getId(): string;
+    setBlocking(blocking: boolean): void;
+    isBlocking(): boolean;
+    addLine(content: string | ((line: ChatGUILine) => void)): void;
+    addLine(lineWrapper: ChatGUILine): void;
+    addEmptyLine(): void;
+    createLine(): ChatGUILine;
+    setLine(index: number, callback: (line: ChatGUILine) => void): void;
+    updateLine(lineIndex: number, callback: (line: ChatGUILine) => void): void;
+    removeLine(index: number): void;
+    clear(): void;
+    size(): number;
+    ensureSize(minSize: number): void;
+    addLineAt(index: number, callback: (line: ChatGUILine) => void): void;
+    addLineAt(index: number, lineWrapper: ChatGUILine): void;
+    setGlobalBackground(color: string): void;
+    removeGlobalBackground(): void;
+    open(playerName: string): void;
+    close(playerName: string): void;
+    close(): void;
+    rerender(): void;
+    rerenderForPlayer(playerName: string): void;
+}
+export interface ChatGUILine {
+    padding(padding: number): ChatGUILine;
+    spaceDistribution(distribution: "start" | "center" | "end" | "space_between" | "space_around" | "space_evenly"): ChatGUILine;
+    spaceBetween(): ChatGUILine;
+    spaceAround(): ChatGUILine;
+    spaceEvenly(): ChatGUILine;
+    center(): ChatGUILine;
+    end(): ChatGUILine;
+    background(color: string): ChatGUILine;
+    noBackground(): ChatGUILine;
+    addText(text: string): ChatGUILine;
+    addText(text: string, color: string): ChatGUILine;
+    addText(text: string, color: string, bold: boolean): ChatGUILine;
+    addBoldText(text: string): ChatGUILine;
+    addBoldText(text: string, color: string): ChatGUILine;
+    addButton(text: string, command: string): ChatGUILine;
+    addButton(text: string, command: string, hoverText: string): ChatGUILine;
+    addButton(text: string, command: string, hoverText: string, color: string): ChatGUILine;
+    addColumn(config: (config: ColumnConfig) => void): ChatGUILine;
+    build(): unknown;
+    hasBackground(): boolean;
+}
+export interface ColumnConfig {
+    setType(type: "text" | "bold" | "button"): ColumnConfig;
+    setText(text: string): ColumnConfig;
+    setCommand(command: string): ColumnConfig;
+    setHoverText(hoverText: string): ColumnConfig;
+    setColor(color: string): ColumnConfig;
+    setWidth(width: number): ColumnConfig;
+    setAlign(align: "left" | "center" | "right"): ColumnConfig;
+    setMargin(margin: number): ColumnConfig;
+}
+export interface CommandManager {
+    register(name: string, callback: () => unknown): number;
+    registerWithArgs(name: string, callback: (sender: string, args: string[]) => unknown): number;
+    unregister(commandId: number): void;
+    givePlayer(playerName: string, commandId: number): void;
+    removePlayer(playerName: string, commandId: number): void;
+    getPlayerCommands(playerName: string): string[];
+    hasPlayerAccess(playerName: string, commandId: number): boolean;
+    getCommand(commandId: number): [number, string] | null;
+    getAllCommands(): [number, string][];
+    getCommandCount(): number;
+    getPlayerCount(): number;
+    executeCommand(commandId: number, sender: string, ...args: unknown[]): unknown;
+}
+export interface BetterModelEntityAPI {
+    hasModel(modelName: string): boolean;
+    spawn(modelName: string, x: number, y: number, z: number, worldName?: string): EntityInstance | null;
+    spawnBlock(modelName: string, x: number, y: number, z: number, onInteract: BlockInteractionCallback, worldName?: string): EntityInstance | null;
+    disguisePlayer(playerName: string, modelName: string): EntityInstance | null;
+    undisguisePlayer(playerName: string): boolean;
+    playAnimationOnPlayer(playerName: string, animationName: string): boolean;
+    mountPlayer(passengerName: string, vehicleName: string): boolean;
+    unmountPlayer(playerName: string): boolean;
+    hideModelFromPlayer(targetPlayerName: string, viewerPlayerName: string): boolean;
+    showModelToPlayer(targetPlayerName: string, viewerPlayerName: string): boolean;
+    getStats(): EntityStats;
+    cleanup(): void;
+}
+export interface EntityInstance {
+    /** Entity ID */
+    readonly id: string;
+    /** Model name */
+    readonly modelName: string;
+    /** Entity type ("dummy" or "entity") */
+    readonly type: string;
+    /** Check if destroyed (also available as method) */
+    readonly isDestroyed: boolean;
+    /** Check if this is a disguised player */
+    readonly isDisguised: boolean;
+    getId(): string;
+    getModelName(): string;
+    getType(): string;
+    /**
+     * Play an animation on this entity
+     * @param animationName Name of the animation to play
+     * @param animationType Optional animation type: "PLAY_ONCE", "LOOP", "HOLD_ON_LAST"
+     * @returns true if successful
+     */
+    playAnimation(animationName: string, animationType?: "PLAY_ONCE" | "LOOP" | "HOLD_ON_LAST"): boolean;
+    /** Get list of available animations */
+    getAvailableAnimations(): string[];
+    /** Get information about a specific animation */
+    getAnimationInfo(animationName: string): unknown | null;
+    /** Stop all animations */
+    stopAnimation(): boolean;
+    hideFromPlayer(playerName: string): boolean;
+    showToPlayer(playerName: string): boolean;
+    mountOn(vehicleEntityId: string): boolean;
+    unmount(): boolean;
+    /** Change the mount controller */
+    changeMountController(controllerName: string): boolean;
+    destroy(): boolean;
+    /** Remove disguise from player (if this is a disguised player) */
+    removeDisguise(): boolean;
+    getInfo(): EntityInfo;
+}
+export interface EntityStats {
+    dummyEntities: number;
+    entityTrackers: number;
+    trackedByScript: number;
+}
+export interface EntityInfo {
+    id: string;
+    modelName: string;
+    type: string;
+    destroyed: boolean;
+    entityType?: string;
+    entityUUID?: string;
+    world?: string;
+    x?: number;
+    y?: number;
+    z?: number;
+}
+export type BlockInteractionCallback = (playerName: string | null, trackerId: string, interactionType: BlockInteractionType, ...extraArgs: unknown[]) => unknown;
+export type BlockInteractionType = 'LEFT_CLICK' | 'RIGHT_CLICK' | 'DAMAGE' | 'START_BREAKING' | 'BREAKING_PROGRESS' | 'BREAK_COMPLETE' | 'BREAKING_CANCELLED' | 'REMOVE';
+export interface ProcessExecutorAPI {
+    getType(): string;
+    getName(): string;
+    getDisplayName(): string;
+    isPlayer(): boolean;
+    isConsole(): boolean;
+    hasLocation(): boolean;
+    getLocation(): ExecutorLocation | null;
+    getWorldName(): string | null;
+    asPlayer(): ScriptablePlayer | null;
+    getInfo(): ExecutorInfo;
+}
+export interface ExecutorLocation {
+    x: number;
+    y: number;
+    z: number;
+    world: string;
+    yaw: number;
+    pitch: number;
+}
+export interface ExecutorInfo {
+    type: string;
+    name: string;
+    displayName: string;
+    isPlayer: boolean;
+    isConsole: boolean;
+    hasLocation: boolean;
+    location?: ExecutorLocation;
+    worldName?: string;
+}
+export interface ShaperAPI {
+    create(templateId: string): ShaperTemplateBuilder;
+    getTemplate(templateId: string): ShaperTemplateWrapper | null;
+    hasTemplate(templateId: string): boolean;
+    getTemplateIds(): string[];
+    getInstance(instanceId: string): ShaperBlockInstance | null;
+    getInstanceIds(): string[];
+    spawn(templateId: string, location: ScriptableLocation, yawDegrees: number): ShaperBlockInstance | null;
+    spawnAt(templateId: string, x: number, y: number, z: number, worldName: string, yawDegrees: number): ShaperBlockInstance | null;
+    removeInstance(instanceId: string): boolean;
+    getInstanceCount(): number;
+    getTemplateCount(): number;
+}
+export interface ShaperTemplateBuilder {
+    /**
+     * Set the model for this shaper.
+     * Accepts either a string path or a ModelNode from DefinitionBuilder.
+     */
+    withModel(modelOrPath: string | ModelNode): ShaperTemplateBuilder;
+    withBetterModel(modelId: string): ShaperTemplateBuilder;
+    modelOffset(x: number, y: number, z: number): ShaperTemplateBuilder;
+    modelScale(x: number, y: number, z: number): ShaperTemplateBuilder;
+    addCollisionRect(width: number, height: number, depth: number, cornerX: number, cornerY: number, cornerZ: number): ShaperTemplateBuilder;
+    fullBlockCollision(): ShaperTemplateBuilder;
+    slabCollision(height: number): ShaperTemplateBuilder;
+    /**
+     * Enable or disable automatic block placement when right-clicking with the item.
+     * By default, shaper blocks are automatically placeable.
+     * When disabled, the auto-generated item is also marked as hidden.
+     * @param enabled true to enable auto-placement (default), false to disable
+     */
+    autoPlace(enabled: boolean): ShaperTemplateBuilder;
+    onClick(callback: (event: ShaperClickEvent) => void): ShaperTemplateBuilder;
+    onBreak(callback: (event: ShaperBreakEvent) => void): ShaperTemplateBuilder;
+    onPlace(callback: (event: ShaperPlaceEvent) => void): ShaperTemplateBuilder;
+    register(): ShaperTemplateWrapper;
+}
+export interface ShaperTemplateWrapper {
+    readonly id: string;
+    hasBetterModel(): boolean;
+    getBetterModelId(): string | null;
+    spawn(location: ScriptableLocation, yawDegrees: number): ShaperBlockInstance | null;
+    spawnAt(location: ScriptableLocation): ShaperBlockInstance | null;
+    spawnAtCoords(x: number, y: number, z: number, worldName: string, yawDegrees: number): ShaperBlockInstance | null;
+}
+export interface ShaperBlockInstance {
+    readonly id: string;
+    readonly templateId: string;
+    readonly rotation: number;
+    readonly isSpawned: boolean;
+    readonly isDestroyed: boolean;
+    getLocation(): ScriptableLocation | null;
+    setRotation(degrees: number): void;
+    addRotation(degrees: number): void;
+    teleport(location: ScriptableLocation): void;
+    teleportWithRotation(location: ScriptableLocation, yawDegrees: number): void;
+    getState(key: string): unknown;
+    getStateWithDefault(key: string, defaultValue: unknown): unknown;
+    setState(key: string, value: unknown): void;
+    getBetterModelEntityId(): string | null;
+    hasBetterModel(): boolean;
+    playAnimation(animationName: string): boolean;
+    playAnimation(animationName: string, animationType: "PLAY_ONCE" | "LOOP" | "HOLD_ON_LAST"): boolean;
+    saveBetterModelState(): void;
+    remove(): void;
+    despawn(): void;
+}
+export interface ShaperClickEvent {
+    readonly instance: ShaperBlockInstance;
+    readonly player: ScriptablePlayer;
+    readonly collisionInfo: ScriptableCollisionInfo | null;
+    readonly clickedFace: string;
+    readonly hand: "MAIN_HAND" | "OFF_HAND";
+    cancel(): void;
+    isCancelled(): boolean;
+    setCancelled(cancelled: boolean): void;
+    isSneaking(): boolean;
+    getPlacementLocation(): ScriptableLocation;
+}
+export interface ShaperBreakEvent {
+    readonly instance: ShaperBlockInstance;
+    readonly player: ScriptablePlayer | null;
+    readonly collisionInfo: ScriptableCollisionInfo | null;
+    cancel(): void;
+    isCancelled(): boolean;
+}
+export interface ShaperPlaceEvent {
+    readonly instance: ShaperBlockInstance;
+    readonly location: ScriptableLocation;
+    readonly player: ScriptablePlayer | null;
+    cancel(): void;
+    isCancelled(): boolean;
+}
+export interface ScriptableCollisionInfo {
+    readonly shaperId: string;
+    readonly scale: number;
+    readonly clickedFace: string;
+    readonly hand: "MAIN_HAND" | "OFF_HAND";
+    readonly sneaking: boolean;
+    readonly mainHandItem: unknown;
+    readonly offHandItem: unknown;
+    getLocation(): ScriptableLocation | null;
+    isValid(): boolean;
+    getPlacementLocation(): ScriptableLocation;
+    isCancelled(): boolean;
+    cancel(): void;
+    setCancelled(cancelled: boolean): void;
+}
+export interface ScriptableLocation {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+    readonly yaw: number;
+    readonly pitch: number;
+    readonly worldName: string;
+    getX(): number;
+    getY(): number;
+    getZ(): number;
+    getYaw(): number;
+    getPitch(): number;
+    getWorldName(): string;
+    getWorld(): ScriptableWorld;
+    getBlockX(): number;
+    getBlockY(): number;
+    getBlockZ(): number;
+    toBukkit(): unknown;
+    toObject(): {
+        x: number;
+        y: number;
+        z: number;
+        yaw: number;
+        pitch: number;
+        world: string;
+    };
+    add(x: number, y: number, z: number): ScriptableLocation;
+    subtract(x: number, y: number, z: number): ScriptableLocation;
+    multiply(factor: number): ScriptableLocation;
+    copy(): ScriptableLocation;
+    distance(other: ScriptableLocation): number;
+    distanceSquared(other: ScriptableLocation): number;
+    getBlockLocation(): ScriptableLocation;
+    getCenter(): ScriptableLocation;
+    getBlockCenter(): ScriptableLocation;
+    setDirection(x: number, y: number, z: number): ScriptableLocation;
+    getDirection(): {
+        x: number;
+        y: number;
+        z: number;
+    };
+    isSameBlock(other: ScriptableLocation): boolean;
+    isSameWorld(other: ScriptableLocation): boolean;
+}
+export interface ScriptableWorld {
+    readonly name: string;
+    readonly environment: string;
+    readonly seed: number;
+    readonly time: number;
+    getName(): string;
+    getTimeValue(): number;
+    setTime(time: number): void;
+    getFullTime(): number;
+    setFullTime(time: number): void;
+    isRaining(): boolean;
+    setStorm(storm: boolean): void;
+    isThundering(): boolean;
+    setThundering(thundering: boolean): void;
+    setWeatherDuration(duration: number): void;
+    clearWeather(): void;
+    getPlayers(): ScriptablePlayer[];
+    getPlayerCount(): number;
+    getSpawnLocation(): ScriptableLocation;
+    setSpawnLocation(location: ScriptableLocation): void;
+    setSpawnLocationAt(x: number, y: number, z: number): void;
+    getHighestBlockYAt(x: number, z: number): number;
+    getHighestBlockAt(x: number, z: number): ScriptableLocation;
+    spawnParticle(particleType: string, location: ScriptableLocation, count: number, offsetX: number, offsetY: number, offsetZ: number, speed: number): void;
+    spawnParticleAt(particleType: string, x: number, y: number, z: number, count: number, offsetX: number, offsetY: number, offsetZ: number, speed: number): void;
+    playSound(location: ScriptableLocation, soundName: string, volume: number, pitch: number): void;
+    playSoundAt(x: number, y: number, z: number, soundName: string, volume: number, pitch: number): void;
+    createExplosion(location: ScriptableLocation, power: number, setFire: boolean, breakBlocks: boolean): void;
+    createExplosionAt(x: number, y: number, z: number, power: number, setFire: boolean, breakBlocks: boolean): void;
+    strikeLightning(location: ScriptableLocation): void;
+    strikeLightningEffect(location: ScriptableLocation): void;
+    strikeLightningAt(x: number, y: number, z: number): void;
+    strikeLightningEffectAt(x: number, y: number, z: number): void;
+    isValid(): boolean;
+    getDifficulty(): string;
+    isPvP(): boolean;
+    getWorldBorderSize(): number;
+}
+export interface DefinitionBuilder {
+    model(modelPath: string): ModelRef;
+    condition(property: string): ConditionNode;
+    select(property: string): SelectNode;
+    rangeDispatch(property: string): RangeDispatchNode;
+    composite(): CompositeNode;
+    bow(defaultModel: string, pulling0: string, pulling1: string, pulling2: string): ModelNode;
+    bowCustom(defaultModel: string, pullingModels: string[], thresholds: number[]): ModelNode;
+    elytra(normalModel: string, brokenModel: string): ModelNode;
+    crossbow(defaultModel: string, pulling0: string, pulling1: string, pulling2: string, arrowLoaded: string, rocketLoaded: string): ModelNode;
+    displayContext(guiModel: string, defaultModel: string): ModelNode;
+    displayContextFull(guiModel: string, groundModel: string, defaultModel: string): ModelNode;
+}
+export interface ModelNode {
+}
+export interface ModelRef extends ModelNode {
+    withConstantTint(argbColor: number): ModelRef;
+    withDyeTint(defaultColor: number): ModelRef;
+}
+export interface ConditionNode extends ModelNode {
+    onTrue(node: ModelNode): ConditionNode;
+    onFalse(node: ModelNode): ConditionNode;
+    component(componentId: string): ConditionNode;
+}
+export interface SelectNode extends ModelNode {
+    addCase(when: string, model: ModelNode): SelectNode;
+    addCase(when: string[], model: ModelNode): SelectNode;
+    fallback(node: ModelNode): SelectNode;
+    blockStateProperty(propertyName: string): SelectNode;
+    pattern(datePattern: string): SelectNode;
+}
+export interface RangeDispatchNode extends ModelNode {
+    entry(threshold: number, model: ModelNode): RangeDispatchNode;
+    fallback(node: ModelNode): RangeDispatchNode;
+    scale(scale: number): RangeDispatchNode;
+    period(period: number): RangeDispatchNode;
+    target(target: "spawn" | "lodestone" | "recovery" | "none"): RangeDispatchNode;
+    source(source: "daytime" | "random"): RangeDispatchNode;
+}
+export interface CompositeNode extends ModelNode {
+    add(model: ModelNode): CompositeNode;
+}
+export interface ItemAPI {
+    create(itemName: string): ItemTemplateBuilder;
+    get(itemName: string): ScriptableCustomItem | null;
+    hasItem(itemName: string): boolean;
+    getItemNames(): string[];
+    getItemCount(): number;
+    unregister(itemName: string): boolean;
+}
+export interface ItemTemplateBuilder {
+    withMaterial(materialName: string): ItemTemplateBuilder;
+    /**
+     * Set the model for this item.
+     * Accepts either a string path or a ModelNode from DefinitionBuilder.
+     */
+    withModel(modelOrPath: string | ModelNode): ItemTemplateBuilder;
+    withDisplayName(displayName: string): ItemTemplateBuilder;
+    withDescription(description: string): ItemTemplateBuilder;
+    /**
+     * Make this item place a block when right-clicked.
+     * @param blockPath The block to place (namespace:path format)
+     */
+    placesBlock(blockPath: string): ItemTemplateBuilder;
+    on(event: "rightClick", callback: (event: ItemInteractEvent) => void): ItemTemplateBuilder;
+    on(event: "leftClick", callback: (event: ItemInteractEvent) => void): ItemTemplateBuilder;
+    on(event: "drop", callback: (event: ItemDropEvent) => void): ItemTemplateBuilder;
+    on(event: "pickup", callback: (event: ItemPickupEvent) => void): ItemTemplateBuilder;
+    on(event: "consume", callback: (event: ItemConsumeEvent) => void): ItemTemplateBuilder;
+    on(event: "damageEntity", callback: (event: ItemDamageEntityEvent) => void): ItemTemplateBuilder;
+    on(event: "shootBow", callback: (event: ItemShootBowEvent) => void): ItemTemplateBuilder;
+    on(event: "holdStart", callback: (event: ItemHoldEvent) => void): ItemTemplateBuilder;
+    on(event: "holdEnd", callback: (event: ItemHoldEvent) => void): ItemTemplateBuilder;
+    on(event: "swapHand", callback: (event: ItemSwapHandEvent) => void): ItemTemplateBuilder;
+    on(event: "durabilityChange", callback: (event: ItemDurabilityEvent) => void): ItemTemplateBuilder;
+    on(event: "break", callback: (event: ItemBreakEvent) => void): ItemTemplateBuilder;
+    on(event: "interactEntity", callback: (event: ItemEntityInteractEvent) => void): ItemTemplateBuilder;
+    on(event: "blockBreak", callback: (event: ItemBlockBreakEvent) => void): ItemTemplateBuilder;
+    on(event: "blockPlace", callback: (event: ItemBlockPlaceEvent) => void): ItemTemplateBuilder;
+    once(event: "rightClick", callback: (event: ItemInteractEvent) => void): ItemTemplateBuilder;
+    once(event: "leftClick", callback: (event: ItemInteractEvent) => void): ItemTemplateBuilder;
+    once(event: "drop", callback: (event: ItemDropEvent) => void): ItemTemplateBuilder;
+    once(event: "pickup", callback: (event: ItemPickupEvent) => void): ItemTemplateBuilder;
+    once(event: "consume", callback: (event: ItemConsumeEvent) => void): ItemTemplateBuilder;
+    once(event: "damageEntity", callback: (event: ItemDamageEntityEvent) => void): ItemTemplateBuilder;
+    once(event: "shootBow", callback: (event: ItemShootBowEvent) => void): ItemTemplateBuilder;
+    once(event: "holdStart", callback: (event: ItemHoldEvent) => void): ItemTemplateBuilder;
+    once(event: "holdEnd", callback: (event: ItemHoldEvent) => void): ItemTemplateBuilder;
+    once(event: "swapHand", callback: (event: ItemSwapHandEvent) => void): ItemTemplateBuilder;
+    once(event: "durabilityChange", callback: (event: ItemDurabilityEvent) => void): ItemTemplateBuilder;
+    once(event: "break", callback: (event: ItemBreakEvent) => void): ItemTemplateBuilder;
+    once(event: "interactEntity", callback: (event: ItemEntityInteractEvent) => void): ItemTemplateBuilder;
+    once(event: "blockBreak", callback: (event: ItemBlockBreakEvent) => void): ItemTemplateBuilder;
+    once(event: "blockPlace", callback: (event: ItemBlockPlaceEvent) => void): ItemTemplateBuilder;
+    register(): ScriptableCustomItem;
+}
+export interface ScriptableCustomItem {
+    readonly name: string;
+    getMaterial(): string;
+    getItemStack(): unknown;
+    getItemStack(amount: number): unknown;
+    isValid(): boolean;
+}
+/**
+ * Persistent key-value storage API for scripts.
+ * Data is stored per-script in plugins/kustom-plugin/data/scripts/{scriptName}/
+ *
+ * @example
+ * ```typescript
+ * // Store data
+ * process.storage.set("config", { maxLevel: 100, debug: true });
+ * process.storage.set("player_Steve_coins", 500);
+ *
+ * // Retrieve data
+ * const config = process.storage.get("config");
+ * const coins = process.storage.get("player_Steve_coins");
+ *
+ * // Check existence
+ * if (process.storage.has("config")) { ... }
+ *
+ * // List all keys
+ * const keys = process.storage.keys();
+ *
+ * // Delete data
+ * process.storage.delete("oldKey");
+ * ```
+ */
+export interface StorageAPI {
+    /**
+     * Store a value for the given key.
+     * The value can be any JSON-serializable value (object, array, string, number, boolean).
+     *
+     * @param key The key to store under
+     * @param value The value to store
+     */
+    set(key: string, value: unknown): void;
+    /**
+     * Retrieve a value for the given key.
+     *
+     * @param key The key to retrieve
+     * @returns The stored value, or undefined if not found
+     */
+    get<T = unknown>(key: string): T | undefined;
+    /**
+     * Delete a stored value.
+     *
+     * @param key The key to delete
+     * @returns true if deleted, false if not found
+     */
+    delete(key: string): boolean;
+    /**
+     * Check if a key exists.
+     *
+     * @param key The key to check
+     * @returns true if the key exists
+     */
+    has(key: string): boolean;
+    /**
+     * Get all keys stored by this script.
+     *
+     * @returns Array of key names
+     */
+    keys(): string[];
+    /**
+     * Delete all data stored by this script.
+     *
+     * @returns Number of keys deleted
+     */
+    clear(): number;
+    /**
+     * Get the number of stored keys.
+     *
+     * @returns Number of keys
+     */
+    size(): number;
+}
+/**
+ * Interact event (rightClick, leftClick).
+ * The block property is a unified ScriptableBlock that works for both vanilla and custom blocks.
+ */
+export interface ItemInteractEvent {
+    readonly item: ScriptableCustomItem;
+    readonly player: ScriptablePlayer;
+    /** The block that was clicked (null if air was clicked). Use block.type to get the block type. */
+    readonly block: ScriptableBlock | null;
+    readonly blockFace: "UP" | "DOWN" | "NORTH" | "SOUTH" | "EAST" | "WEST" | null;
+    readonly clickType: "LEFT_CLICK" | "RIGHT_CLICK";
+    readonly hand: "MAIN_HAND" | "OFF_HAND";
+    readonly isBlockClick: boolean;
+    readonly isAirClick: boolean;
+    readonly isBreaking: boolean;
+    readonly sneaking: boolean;
+    cancel(): void;
+    isCancelled(): boolean;
+    setUseItemInHand(result: "ALLOW" | "DENY" | "DEFAULT"): void;
+    setUseInteractedBlock(result: "ALLOW" | "DENY" | "DEFAULT"): void;
+}
+export interface ItemDropEvent {
+    readonly item: ScriptableCustomItem;
+    readonly player: ScriptablePlayer;
+    readonly droppedItem: DroppedItemInfo;
+    cancel(): void;
+    isCancelled(): boolean;
+}
+export interface ItemPickupEvent {
+    readonly item: ScriptableCustomItem;
+    readonly player: ScriptablePlayer;
+    readonly pickedUpItem: DroppedItemInfo;
+    readonly remaining: number;
+    cancel(): void;
+    isCancelled(): boolean;
+}
+export interface ItemConsumeEvent {
+    readonly item: ScriptableCustomItem;
+    readonly player: ScriptablePlayer;
+    readonly hand: "MAIN_HAND" | "OFF_HAND";
+    cancel(): void;
+    isCancelled(): boolean;
+    setItem(itemName: string | null): void;
+    getReplacement(): string | null;
+}
+export interface ItemDamageEntityEvent {
+    readonly item: ScriptableCustomItem;
+    readonly player: ScriptablePlayer;
+    readonly target: ScriptableEntity;
+    readonly damage: number;
+    readonly finalDamage: number;
+    readonly cause: string;
+    cancel(): void;
+    isCancelled(): boolean;
+    setDamage(damage: number): void;
+    isCritical(): boolean;
+}
+export type ProjectileType = "ARROW" | "SPECTRAL_ARROW" | "FIREBALL" | "SMALL_FIREBALL" | "DRAGON_FIREBALL" | "WITHER_SKULL" | "SNOWBALL" | "EGG" | "TRIDENT" | "WIND_CHARGE" | "LLAMA_SPIT" | "SHULKER_BULLET";
+export interface ItemShootBowEvent {
+    readonly item: ScriptableCustomItem;
+    readonly player: ScriptablePlayer;
+    readonly force: number;
+    readonly hand: "MAIN_HAND" | "OFF_HAND";
+    readonly projectile: ScriptableEntity;
+    readonly consumable: ScriptableCustomItem | null;
+    cancel(): void;
+    isCancelled(): boolean;
+    setConsumeItem(consume: boolean): void;
+    shouldConsumeItem(): boolean;
+    setProjectileType(type: ProjectileType): void;
+    setProjectileSpeed(multiplier: number): void;
+    setProjectileFire(onFire: boolean): void;
+    setProjectileGravity(hasGravity: boolean): void;
+}
+export interface ItemHoldEvent {
+    readonly item: ScriptableCustomItem;
+    readonly player: ScriptablePlayer;
+    readonly previousSlot: number;
+    readonly newSlot: number;
+    readonly isStarting: boolean;
+    cancel(): void;
+    isCancelled(): boolean;
+}
+export interface ItemSwapHandEvent {
+    readonly item: ScriptableCustomItem;
+    readonly player: ScriptablePlayer;
+    readonly mainHandItem: ScriptableCustomItem | null;
+    readonly offHandItem: ScriptableCustomItem | null;
+    cancel(): void;
+    isCancelled(): boolean;
+    setMainHandItem(itemName: string | null): void;
+    setOffHandItem(itemName: string | null): void;
+}
+export interface ItemDurabilityEvent {
+    readonly item: ScriptableCustomItem;
+    readonly player: ScriptablePlayer;
+    readonly damage: number;
+    readonly originalDamage: number;
+    cancel(): void;
+    isCancelled(): boolean;
+    setDamage(damage: number): void;
+    getCurrentDurability(): number;
+    getMaxDurability(): number;
+    getRemainingDurability(): number;
+}
+export interface ItemBreakEvent {
+    readonly item: ScriptableCustomItem;
+    readonly player: ScriptablePlayer;
+}
+export interface ItemEntityInteractEvent {
+    readonly item: ScriptableCustomItem;
+    readonly player: ScriptablePlayer;
+    readonly target: ScriptableEntity;
+    readonly hand: "MAIN_HAND" | "OFF_HAND";
+    readonly clickPosition: [number, number, number] | null;
+    cancel(): void;
+    isCancelled(): boolean;
+}
+/**
+ * Block break event - fired when player breaks a block while holding the item.
+ * Works for both vanilla blocks and custom shaper blocks.
+ * Use `block.isCustom` to check if it's a custom block.
+ */
+export interface ItemBlockBreakEvent {
+    readonly item: ScriptableCustomItem;
+    readonly player: ScriptablePlayer;
+    /**
+     * The block being broken. Supports both vanilla and custom blocks.
+     * Use `block.isCustom` to distinguish between them.
+     * Use `block.shaper` to access shaper-specific methods for custom blocks.
+     */
+    readonly block: ScriptableBlock;
+    /** Experience to drop (vanilla blocks only) */
+    readonly expToDrop: number;
+    cancel(): void;
+    isCancelled(): boolean;
+    /** Set experience to drop (vanilla blocks only) */
+    setExpToDrop(exp: number): void;
+    /** Check if items will drop (vanilla blocks only) */
+    isDropItems(): boolean;
+    /** Set whether items should drop (vanilla blocks only) */
+    setDropItems(drop: boolean): void;
+}
+/**
+ * Block place event - fired when player places a block (if item is placeable).
+ * Both block and blockAgainst are unified ScriptableBlock objects.
+ */
+export interface ItemBlockPlaceEvent {
+    readonly item: ScriptableCustomItem;
+    readonly player: ScriptablePlayer;
+    /** The block being placed. Use block.type to get the block type. */
+    readonly block: ScriptableBlock;
+    /** The block this was placed against. Use blockAgainst.type to get the block type. */
+    readonly blockAgainst: ScriptableBlock;
+    readonly hand: "MAIN_HAND" | "OFF_HAND";
+    cancel(): void;
+    isCancelled(): boolean;
+}
+export interface DroppedItemInfo {
+    readonly itemStack: ScriptableCustomItem | null;
+    readonly location: ScriptableLocation;
+    getVelocity(): [number, number, number];
+    setVelocity(x: number, y: number, z: number): void;
+    getAmount(): number;
+    getPickupDelay(): number;
+    setPickupDelay(delay: number): void;
+    canPickup(): boolean;
+    getUuid(): string;
+    isValid(): boolean;
+}
+export interface ScriptableEntity {
+    readonly type: string;
+    readonly uuid: string;
+    readonly name: string;
+    getLocation(): ScriptableLocation;
+    isPlayer(): boolean;
+    asPlayer(): ScriptablePlayer | null;
+    getHealth(): number;
+    getMaxHealth(): number;
+    isDead(): boolean;
+    getWorld(): string;
+    isValid(): boolean;
+    getVelocity(): [number, number, number];
+    isOnGround(): boolean;
+}
+/**
+ * Block wrapper that supports both vanilla Bukkit blocks and custom shaper blocks.
+ * Provides a unified API for block interactions in JavaScript.
+ */
+export interface ScriptableBlock {
+    /** X coordinate */
+    readonly x: number;
+    /** Y coordinate */
+    readonly y: number;
+    /** Z coordinate */
+    readonly z: number;
+    /** World name */
+    readonly worldName: string;
+    /**
+     * Whether this is a custom shaper block.
+     * @returns true if this wraps a shaper, false for vanilla blocks
+     */
+    readonly isCustom: boolean;
+    /**
+     * Get the block type.
+     * - For custom blocks: "custom:template_id" (e.g., "custom:tower")
+     * - For vanilla blocks: Material name (e.g., "STONE", "DIRT")
+     */
+    readonly type: string;
+    /**
+     * Access the underlying shaper instance (null for vanilla blocks).
+     * Use this to access shaper-specific methods and properties.
+     */
+    readonly shaper: ShaperBlockInstance | null;
+    getLocation(): ScriptableLocation;
+    getWorld(): ScriptableWorld;
+    hasLocation(): boolean;
+}
+/**
+ * Sound categories matching Bukkit's SoundCategory enum.
+ * Categories affect which volume slider in player settings controls the sound.
+ */
+export type SoundCategory = "MASTER" | "MUSIC" | "RECORDS" | "WEATHER" | "BLOCKS" | "HOSTILE" | "NEUTRAL" | "PLAYERS" | "AMBIENT" | "VOICE";
+/**
+ * Options for playSound function.
+ */
+export interface PlaySoundOptions {
+    /** Volume level (default 1.0, affects range: ~16 blocks per 1.0) */
+    volume?: number;
+    /** Pitch (default 1.0, range 0.5-2.0) */
+    pitch?: number;
+    /** Sound category for player volume settings (optional, let Bukkit handle default) */
+    category?: SoundCategory;
+    /** Seed for randomized sounds (optional) */
+    seed?: number;
+}
+/**
+ * Target for sound playback.
+ * - ScriptablePlayer: Only that player hears
+ * - ScriptablePlayer[]: Only those players hear
+ * - "*": All online players hear
+ * - ScriptableLocation: World-based, nearby players hear
+ * - ScriptableEntity: Uses entity location, nearby players hear
+ */
+export type SoundTarget = ScriptablePlayer | ScriptablePlayer[] | "*" | ScriptableLocation | ScriptableEntity;
+/**
+ * Returned by playSound() for tracking and stopping sounds.
+ */
+export interface Sound {
+    /** Stop this sound for all original targets */
+    stop(): void;
+    /** Check if the sound has not been stopped */
+    isPlaying(): boolean;
+    /** The sound name that was played */
+    readonly name: string;
+    /** The category used (if specified) */
+    readonly category?: SoundCategory;
+}
+/**
+ * Play a sound to one or more targets.
+ *
+ * @param sound Sound name (vanilla like "ENTITY_EXPERIENCE_ORB_PICKUP" or custom like "custom:my_sound")
+ * @param target Where/who to play the sound to
+ * @param options Optional sound parameters
+ * @returns Sound object for stopping the sound later
+ *
+ * @example
+ * // Simple usage
+ * const sound = playSound("ENTITY_EXPERIENCE_ORB_PICKUP", player);
+ *
+ * // With options
+ * const music = playSound("MUSIC_DISC_13", player, {
+ *   volume: 0.5,
+ *   category: "RECORDS"
+ * });
+ *
+ * // Stop later
+ * music.stop();
+ *
+ * // Location-based (nearby players hear)
+ * playSound("BLOCK_ANVIL_LAND", location, { volume: 2.0 });
+ *
+ * // Multiple players
+ * playSound("ENTITY_FIREWORK_ROCKET_LAUNCH", [player1, player2]);
+ *
+ * // All online players
+ * playSound("ENTITY_ENDER_DRAGON_DEATH", "*");
+ */
+export declare function playSound(sound: string, target: SoundTarget, options?: PlaySoundOptions): Sound;
+/**
+ * Stop all sounds.
+ *
+ * @param target Optional - if provided, stops all sounds for that player.
+ *               If omitted, stops all sounds started by this script.
+ *
+ * @example
+ * // Stop all sounds from this script
+ * stopAllSounds();
+ *
+ * // Stop all sounds for a specific player
+ * stopAllSounds(player);
+ */
+export declare function stopAllSounds(target?: ScriptablePlayer): void;