@minecraft/creator-tools/lib/design/StructureDesignDefinition.d.ts

Minecraft Creator Tools command line and libraries.

/**
 * ARCHITECTURE DOCUMENTATION: StructureDesignDefinition
 * ======================================================
 *
 * This class persists structure design data as an accessory file alongside the
 * generated .mcstructure file. It enables:
 * 1. Design iteration - update existing structures without creating duplicates
 * 2. Context restoration - AI can reload the design spec to understand/modify it
 * 3. Preview regeneration - re-render from saved design on demand
 *
 * ## Accessory Folder Pattern
 *
 * For a structure file at:
 *   behavior_packs/my_pack/structures/wizard_tower.mcstructure
 *
 * The accessory folder is at:
 *   design_pack/project_item_data/behavior_packs/my_pack/structures/wizard_tower_mcstructure/
 *
 * And contains:
 *   - structure_design.json: The IBlockVolume specification
 *   - preview.png: Last rendered preview image
 *   - generation_meta.json: Timestamp, model used, etc.
 *
 * ## Related Files
 * - src/design/ModelDesignDefinition.ts - Similar pattern for model designs
 * - src/design/ImageEditsDefinition.ts - Original accessory pattern implementation
 * - src/app/ProjectItem.ts - ensureAccessoryFolder() implementation
 * - src/local/MinecraftMcpServer.ts - buildStructure tool that uses this
 */
import IFile from "../storage/IFile";
import { IEventHandler } from "ste-events";
import Project from "../app/Project";
import ProjectItem from "../app/ProjectItem";
/**
 * Block volume design - the structure specification.
 * Matches the format used by previewStructureDesign/exportStructureDesign.
 */
export interface IBlockVolumeDesign {
    /** The world position of the south-west-bottom corner of the structure */
    southWestBottom: {
        x: number;
        y: number;
        z: number;
    };
    /** Optional dimensions - inferred from data if not provided */
    size?: {
        x: number;
        y: number;
        z: number;
    };
    /** Y layers from bottom to top */
    blockLayersBottomToTop: string[][];
    /** Map single characters to block types */
    key: Record<string, {
        typeId: string;
        properties?: Record<string, string | number | boolean>;
    }>;
    /** Entities within the structure */
    entities?: Array<{
        typeId: string;
        locationWithinVolume: {
            x: number;
            y: number;
            z: number;
        };
    }>;
}
/**
 * Metadata about when/how the structure was generated.
 */
export interface IStructureGenerationMeta {
    /** When the structure was last generated */
    generatedAt: string;
    /** The AI model/tool that generated it (if known) */
    generatorModel?: string;
    /** The prompt or request that led to generation (if known) */
    prompt?: string;
    /** Version of the design schema */
    schemaVersion: "1.0.0";
}
/**
 * The complete persisted structure design data.
 */
export interface IStructureDesignData {
    /** The structure design specification */
    design: IBlockVolumeDesign;
    /** Generation metadata */
    meta: IStructureGenerationMeta;
    /** What feature rule this structure was wired to (if any) */
    wiredTo?: string;
}
/**
 * Manages persistence of structure design data in accessory folders.
 * Follows the same pattern as ModelDesignDefinition and ImageEditsDefinition.
 */
export default class StructureDesignDefinition {
    private _file?;
    private _previewFile?;
    private _isLoaded;
    data?: IStructureDesignData;
    project?: Project;
    private _onLoaded;
    get isLoaded(): boolean;
    get file(): IFile | undefined;
    set file(newFile: IFile | undefined);
    get onLoaded(): import("ste-events").IEvent<StructureDesignDefinition, StructureDesignDefinition>;
    get design(): IBlockVolumeDesign | undefined;
    get wiredTo(): string | undefined;
    /**
     * Updates the design data and persists it.
     */
    updateDesign(design: IBlockVolumeDesign, options?: {
        wiredTo?: string;
        generatorModel?: string;
        prompt?: string;
    }): Promise<void>;
    /**
     * Saves a preview image to the accessory folder.
     */
    savePreview(imageData: Uint8Array): Promise<void>;
    /**
     * Gets the preview image data if it exists.
     */
    getPreview(): Promise<Uint8Array | undefined>;
    /**
     * Creates or gets a StructureDesignDefinition for a ProjectItem's accessory folder.
     * Use this when you have the ProjectItem for the .mcstructure file.
     */
    static ensureAsAccessoryOnProjectItem(projectItem: ProjectItem): Promise<StructureDesignDefinition | undefined>;
    /**
     * Creates or gets a StructureDesignDefinition attached to a file.
     */
    static ensureOnFile(file: IFile, project: Project, loadHandler?: IEventHandler<StructureDesignDefinition, StructureDesignDefinition>): Promise<StructureDesignDefinition | undefined>;
    /**
     * Persists the design data to file (only if semantically different).
     */
    persist(): Promise<boolean>;
    /**
     * Saves the design data to file.
     */
    save(): Promise<void>;
    /**
     * Loads the design data from file.
     */
    load(): Promise<void>;
}