nucleation 0.6.0 → 0.7.0

package/Schematic.d.mts

@@ -0,0 +1,734 @@
+// generated by diplomat-tool
+import type { BlockPos } from "./BlockPos.mjs"
+import type { BlockState } from "./BlockState.mjs"
+import type { Dimensions } from "./Dimensions.mjs"
+import type { NucleationError } from "./NucleationError.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+export class Schematic {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Create a new, empty schematic with the given name.
+     */
+    static create(name: string): Schematic;
+
+    /**
+     * Return an independent deep copy. Subsequent block, region, entity,
+     * metadata, or transform changes do not affect the original.
+     */
+    deepClone(): Schematic;
+
+    /**
+     * The allocated dimensions (width, height, length) of the schematic's
+     * bounding box.
+     */
+    dimensions(): Dimensions;
+
+    /**
+     * Returns `true` if a block was placed (out-of-range coordinates extend the
+     * schematic rather than erroring, matching `UniversalSchematic::set_block`).
+     */
+    setBlock(x: number, y: number, z: number, blockName: string): boolean;
+
+    /**
+     * The name of the block at a position. `NotFound` if the position is
+     * outside every region.
+     */
+    getBlockName(x: number, y: number, z: number): string;
+
+    /**
+     * Build a schematic from raw byte data, auto-detecting the format.
+     * Supports Litematic, Sponge Schematic, and McStructure (Bedrock) formats.
+     * `Parse` if a format was detected but failed to parse, `InvalidArgument` if
+     * no format was recognized.
+     */
+    static fromData(data: Array<number>): Schematic;
+
+    /**
+     * Build a schematic from Litematic data.
+     */
+    static fromLitematic(data: Array<number>): Schematic;
+
+    /**
+     * The schematic as Litematic bytes, base64-encoded.
+     */
+    toLitematicB64(): string;
+
+    /**
+     * Build a schematic from classic `.schematic` data.
+     */
+    static fromSchematic(data: Array<number>): Schematic;
+
+    /**
+     * The schematic as classic `.schematic` bytes, base64-encoded.
+     */
+    toSchematicB64(): string;
+
+    /**
+     * Build a schematic from snapshot (fast binary) data.
+     */
+    static fromSnapshot(data: Array<number>): Schematic;
+
+    /**
+     * The schematic as snapshot (fast binary) bytes, base64-encoded.
+     */
+    toSnapshotB64(): string;
+
+    /**
+     * Build a schematic from McStructure (Bedrock) data.
+     */
+    static fromMcstructure(data: Array<number>): Schematic;
+
+    /**
+     * The schematic as McStructure (Bedrock) bytes, base64-encoded.
+     */
+    toMcstructureB64(): string;
+
+    /**
+     * Import from a single MCA region file.
+     */
+    static fromMca(data: Array<number>): Schematic;
+
+    /**
+     * Import from MCA with coordinate bounds.
+     */
+    static fromMcaBounded(data: Array<number>, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): Schematic;
+
+    /**
+     * Import from a zipped world folder.
+     */
+    static fromWorldZip(data: Array<number>): Schematic;
+
+    /**
+     * Import from zipped world with coordinate bounds.
+     */
+    static fromWorldZipBounded(data: Array<number>, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): Schematic;
+
+    /**
+     * Import from a Minecraft world directory path.
+     */
+    static fromWorldDirectory(path: string): Schematic;
+
+    /**
+     * Import from world directory with coordinate bounds.
+     */
+    static fromWorldDirectoryBounded(path: string, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): Schematic;
+
+    /**
+     * Export the schematic as a Minecraft world: a JSON array of
+     * `{"path": <relative file path>, "data_b64": <base64 bytes>}` entries
+     * (the old `CFileMap`). `options_json` may be empty for defaults.
+     */
+    toWorldJson(optionsJson: string): string;
+
+    /**
+     * Export and write world files to a directory. `options_json` may be empty.
+     */
+    saveWorld(directory: string, optionsJson: string): void;
+
+    /**
+     * Export the schematic as a zipped Minecraft world, base64-encoded.
+     * `options_json` may be empty for defaults.
+     */
+    toWorldZipB64(optionsJson: string): string;
+
+    /**
+     * Set a block with properties given as a JSON object of string→string
+     * (the old `CProperty` array).
+     */
+    setBlockWithProperties(x: number, y: number, z: number, blockName: string, propertiesJson: string): void;
+
+    /**
+     * Set a block from a full block string, e.g.
+     * `minecraft:chest[facing=north]{Items:[...]}`.
+     */
+    setBlockFromString(x: number, y: number, z: number, blockString: string): void;
+
+    /**
+     * Pre-resolve a plain block name to a palette index for use with `place`.
+     * Pair them in hot loops with many unique block names to skip the per-call
+     * name → palette lookup.
+     */
+    prepareBlock(blockName: string): number;
+
+    /**
+     * Place a block by pre-resolved palette index (from `prepare_block`).
+     */
+    place(x: number, y: number, z: number, paletteIndex: number): void;
+
+    /**
+     * Batch-set blocks at multiple positions to the same block (name, block
+     * string with properties, or block string with NBT). `positions` is flat
+     * `[x0,y0,z0, x1,y1,z1, ...]` (length must be a multiple of 3).
+     * Returns the number of blocks set.
+     */
+    setBlocks(positions: Array<number>, blockName: string): number;
+
+    /**
+     * Batch-get block names at multiple positions. `positions` is flat
+     * `[x0,y0,z0, ...]` (length must be a multiple of 3). Writes a JSON array,
+     * one entry per position: the block name string, or `null` for
+     * empty/out-of-bounds positions.
+     */
+    getBlocksJson(positions: Array<number>): string;
+
+    /**
+     * Stamp a merged source box into the default region. Excluded blocks
+     * are skipped, preserving destination content. Empty string or `[]`
+     * means no exclusions.
+     */
+    stampBox(source: Schematic, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, targetX: number, targetY: number, targetZ: number, excludedBlocksJson: string): void;
+
+    /**
+     * Stamp one explicitly named source region into the default region.
+     * The region's minimum corner is mapped to the target position.
+     */
+    stampRegion(source: Schematic, sourceRegionName: string, targetX: number, targetY: number, targetZ: number, excludedBlocksJson: string): void;
+
+    /**
+     * Compatibility alias for `stamp_box`.
+     */
+    copyRegion(source: Schematic, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, targetX: number, targetY: number, targetZ: number, excludedBlocksJson: string): void;
+
+    /**
+     * The full block state at a position. `NotFound` if the position is
+     * outside every region.
+     */
+    getBlock(x: number, y: number, z: number): BlockState;
+
+    /**
+     * The block at a position with its properties, as a `BlockState`.
+     * Kept as an explicit alias for callers migrating from the older API.
+     */
+    getBlockWithProperties(x: number, y: number, z: number): BlockState;
+
+    /**
+     * The full block state at a position in one specific region. This
+     * avoids composite lookup ambiguity when regions overlap.
+     */
+    getBlockInRegion(regionName: string, x: number, y: number, z: number): BlockState;
+
+    /**
+     * The block string at a position in one specific region.
+     */
+    getBlockStringInRegion(regionName: string, x: number, y: number, z: number): string;
+
+    /**
+     * The full block string (name, properties, NBT) at a position.
+     */
+    getBlockString(x: number, y: number, z: number): string;
+
+    /**
+     * The block entity at a position as JSON
+     * `{"id": ..., "position": [x,y,z], "nbt": {...}}` (the old `CBlockEntity`).
+     */
+    getBlockEntityJson(x: number, y: number, z: number): string;
+
+    /**
+     * The block entity at a position in one specific region as JSON.
+     */
+    getBlockEntityJsonInRegion(regionName: string, x: number, y: number, z: number): string;
+
+    /**
+     * Every block entity as a JSON array of
+     * `{"id": ..., "position": [x,y,z], "nbt": {...}}`.
+     */
+    getAllBlockEntitiesJson(): string;
+
+    /**
+     * The number of mobile entities (not block entities).
+     */
+    entityCount(): number;
+
+    /**
+     * Every mobile entity as a JSON array of
+     * `{"id": ..., "position": [x,y,z], "nbt": {...}}` (the old `CEntityArray`).
+     */
+    getEntitiesJson(): string;
+
+    /**
+     * Add a mobile entity. `nbt_json` is a JSON object (may be empty).
+     */
+    addEntity(id: string, x: number, y: number, z: number, nbtJson: string): void;
+
+    /**
+     * Add an armor stand without hand-authoring entity NBT.
+     *
+     * `armor_material` accepts `diamond`, `netherite`, `iron`, etc.; an
+     * empty string creates an unarmored stand. `yaw` uses Minecraft degrees.
+     */
+    addArmorStand(x: number, y: number, z: number, yaw: number, armorMaterial: string): void;
+
+    /**
+     * Remove a mobile entity by index.
+     */
+    removeEntity(index: number): void;
+
+    /**
+     * The canonical in-memory data version (the forward-conversion target).
+     */
+    static canonicalDataVersion(): number;
+
+    /**
+     * Convert block/item/entity data between Minecraft data versions. Forward
+     * (`target >= source`) is lossless; reverse is lossy. Writes a JSON loss
+     * report (`[]` when lossless).
+     */
+    convertToDataVersion(targetDataVersion: number, sourceDataVersion: number): string;
+
+    /**
+     * Convert to `target_data_version` using the schematic's captured source
+     * version (else `mc_version`, else canonical) as origin, updating metadata
+     * to the target. Writes a JSON loss report (`[]` when lossless).
+     */
+    convertToVersion(targetDataVersion: number): string;
+
+    /**
+     * The Minecraft data version of the file this schematic was loaded from, or
+     * `-1` if none was captured (versionless / freshly built).
+     */
+    sourceDataVersion(): number;
+
+    /**
+     * Override the source data version for formats that carry no Java data
+     * version, so the converter knows what to convert *from*.
+     */
+    setSourceDataVersion(version: number): void;
+
+    /**
+     * Serialize a `.litematic` targeting a specific Minecraft data version. A
+     * COPY is converted and the matching Version header written; the schematic
+     * is left unchanged. Writes JSON
+     * `{"data_b64": <base64 .litematic>, "loss": <loss report>}`.
+     */
+    toLitematicForVersionJson(targetDataVersion: number): string;
+
+    /**
+     * The block entity's NBT as a typed SNBT string. Round-trips losslessly.
+     */
+    getBlockEntitySnbt(x: number, y: number, z: number): string;
+
+    /**
+     * Set (or replace) a block entity at a position from a typed SNBT string.
+     */
+    setBlockEntity(x: number, y: number, z: number, id: string, snbt: string): void;
+
+    /**
+     * Remove the block entity at a position. `NotFound` if none was there.
+     */
+    removeBlockEntity(x: number, y: number, z: number): void;
+
+    /**
+     * Every block entity as a JSON array of `{id, position: [x,y,z], snbt}`.
+     * The `snbt` is the inner data only (no `Id`/`Pos`).
+     */
+    getAllBlockEntitiesSnbtJson(): string;
+
+    /**
+     * Every mobile entity as a JSON array of typed SNBT strings (full compound
+     * incl. `id`/`Pos`).
+     */
+    getEntitiesSnbtJson(): string;
+
+    /**
+     * Add a mobile entity from a full SNBT entity compound (must contain `id`
+     * and `Pos`).
+     */
+    addEntityFromSnbt(snbt: string): void;
+
+    /**
+     * Every non-air block as a JSON array of
+     * `{"x", "y", "z", "name", "properties"}` (the old `CBlockArray`).
+     */
+    getAllBlocksJson(): string;
+
+    /**
+     * All blocks within a sub-region (chunk) of the schematic, as the same
+     * JSON array shape as `get_all_blocks_json`.
+     */
+    getChunkBlocksJson(offsetX: number, offsetY: number, offsetZ: number, width: number, height: number, length: number): string;
+
+    /**
+     * Split the schematic into chunks (default bottom-up strategy). Writes a
+     * JSON array of `{"chunk_x", "chunk_y", "chunk_z", "blocks": [...]}` where
+     * blocks have the `get_all_blocks_json` shape (the old `CChunkArray`).
+     */
+    getChunksJson(chunkWidth: number, chunkHeight: number, chunkLength: number): string;
+
+    /**
+     * Split the schematic into chunks with a loading strategy: one of
+     * `distance_to_camera`, `top_down`, `bottom_up`, `center_outward`,
+     * `random` (anything else falls back to `bottom_up`). Camera coordinates
+     * are only used by `distance_to_camera`. Same JSON shape as
+     * `get_chunks_json`.
+     */
+    getChunksWithStrategyJson(chunkWidth: number, chunkHeight: number, chunkLength: number, strategy: string, cameraX: number, cameraY: number, cameraZ: number): string;
+
+    /**
+     * The total number of non-air blocks in the schematic.
+     */
+    blockCount(): number;
+
+    /**
+     * The total volume of the schematic's bounding box.
+     */
+    volume(): number;
+
+    /**
+     * The names of all regions, as a JSON array of strings.
+     */
+    regionNamesJson(): string;
+
+    /**
+     * Basic debug info about the schematic (name + region count).
+     */
+    debugInfo(): string;
+
+    /**
+     * A formatted schematic layout string (old `schematic_print`).
+     */
+    printString(): string;
+
+    /**
+     * A formatted schematic layout string (old `schematic_print_schematic`;
+     * same output as `print_string`).
+     */
+    printSchematicString(): string;
+
+    /**
+     * A detailed debug string, including a visual layout (old `debug_schematic`).
+     */
+    debugString(): string;
+
+    /**
+     * A detailed debug string with a JSON layout (old `debug_json_schematic`).
+     */
+    debugJsonString(): string;
+
+    /**
+     * The schematic name. `NotFound` if not set.
+     */
+    name(): string;
+
+    /**
+     * Set the schematic name.
+     */
+    setName(name: string): void;
+
+    /**
+     * The schematic author. `NotFound` if not set.
+     */
+    author(): string;
+
+    /**
+     * Set the schematic author.
+     */
+    setAuthor(author: string): void;
+
+    /**
+     * The schematic description. `NotFound` if not set.
+     */
+    description(): string;
+
+    /**
+     * Set the schematic description.
+     */
+    setDescription(description: string): void;
+
+    /**
+     * The creation timestamp (milliseconds since epoch), or `-1` if not set.
+     */
+    created(): bigint;
+
+    /**
+     * Set the creation timestamp (milliseconds since epoch).
+     */
+    setCreated(created: bigint): void;
+
+    /**
+     * The modification timestamp (milliseconds since epoch), or `-1` if not set.
+     */
+    modified(): bigint;
+
+    /**
+     * Set the modification timestamp (milliseconds since epoch).
+     */
+    setModified(modified: bigint): void;
+
+    /**
+     * The Litematic format version, or `-1` if not set.
+     */
+    lmVersion(): number;
+
+    /**
+     * Set the Litematic format version.
+     */
+    setLmVersion(version: number): void;
+
+    /**
+     * The Minecraft data version, or `-1` if not set.
+     */
+    mcVersion(): number;
+
+    /**
+     * Set the Minecraft data version.
+     */
+    setMcVersion(version: number): void;
+
+    /**
+     * The WorldEdit version, or `-1` if not set.
+     */
+    weVersion(): number;
+
+    /**
+     * Set the WorldEdit version.
+     */
+    setWeVersion(version: number): void;
+
+    /**
+     * Mirror the default region along the X axis (in place). Block
+     * orientations, block entities, and entities are mirrored too.
+     */
+    flipX(): void;
+
+    /**
+     * Mirror the default region along the Y axis (in place).
+     */
+    flipY(): void;
+
+    /**
+     * Mirror the default region along the Z axis (in place).
+     */
+    flipZ(): void;
+
+    /**
+     * Rotate the default region about the X axis. +90° maps south (+Z)
+     * to down (-Y). Only multiples of 90 are accepted; invalid angles
+     * return `InvalidArgument` without changing the schematic. Negative
+     * values wrap.
+     */
+    rotateX(degrees: number): void;
+
+    /**
+     * Rotate the default region clockwise about the Y axis when viewed
+     * from above. +90° maps east (+X) to south (+Z).
+     */
+    rotateY(degrees: number): void;
+
+    /**
+     * Rotate the default region about the Z axis. +90° maps up (+Y) to
+     * west (-X).
+     */
+    rotateZ(degrees: number): void;
+
+    /**
+     * Move the default region and all attached block entities/entities.
+     */
+    translate(dx: number, dy: number, dz: number): void;
+
+    /**
+     * Mirror a named region along the X axis.
+     */
+    flipRegionX(regionName: string): void;
+
+    /**
+     * Mirror a named region along the Y axis.
+     */
+    flipRegionY(regionName: string): void;
+
+    /**
+     * Mirror a named region along the Z axis.
+     */
+    flipRegionZ(regionName: string): void;
+
+    /**
+     * Rotate a named region about the X axis by a multiple of 90 degrees.
+     */
+    rotateRegionX(regionName: string, degrees: number): void;
+
+    /**
+     * Rotate a named region clockwise about the Y axis by a multiple of
+     * 90 degrees.
+     */
+    rotateRegionY(regionName: string, degrees: number): void;
+
+    /**
+     * Rotate a named region about the Z axis by a multiple of 90 degrees.
+     */
+    rotateRegionZ(regionName: string, degrees: number): void;
+
+    /**
+     * Move one named region without affecting its siblings.
+     */
+    translateRegion(regionName: string, dx: number, dy: number, dz: number): void;
+
+    /**
+     * Rotate every region as one rigid schematic around the shared bounds.
+     */
+    rotateSchematicX(degrees: number): void;
+
+    /**
+     * Rotate every region as one rigid schematic around the shared bounds.
+     */
+    rotateSchematicY(degrees: number): void;
+
+    /**
+     * Rotate every region as one rigid schematic around the shared bounds.
+     */
+    rotateSchematicZ(degrees: number): void;
+
+    /**
+     * Mirror every region across the shared schematic X bounds.
+     */
+    flipSchematicX(): void;
+
+    /**
+     * Mirror every region across the shared schematic Y bounds.
+     */
+    flipSchematicY(): void;
+
+    /**
+     * Mirror every region across the shared schematic Z bounds.
+     */
+    flipSchematicZ(): void;
+
+    /**
+     * Move every region by the same delta, preserving their relative layout.
+     */
+    translateSchematic(dx: number, dy: number, dz: number): void;
+
+    /**
+     * Fill a cuboid with a block.
+     */
+    fillCuboid(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, blockName: string): void;
+
+    /**
+     * Fill a sphere with a block.
+     */
+    fillSphere(cx: number, cy: number, cz: number, radius: number, blockName: string): void;
+
+    /**
+     * Serialize to a named format, base64-encoded. `version` and `settings`
+     * may be empty strings for defaults.
+     */
+    saveAsB64(format: string, version: string, settings: string): string;
+
+    /**
+     * Serialize as a Sponge schematic targeting a specific format version,
+     * base64-encoded.
+     */
+    toSchematicVersionB64(version: string): string;
+
+    /**
+     * The available Sponge schematic exporter versions, as a JSON array of
+     * strings.
+     */
+    static availableSchematicVersionsJson(): string;
+
+    /**
+     * Set a block with NBT data given as a JSON object of string→string
+     * (may be empty).
+     */
+    setBlockWithNbt(x: number, y: number, z: number, blockName: string, nbtJson: string): void;
+
+    /**
+     * Set a block (by name) in a named region.
+     */
+    setBlockInRegion(regionName: string, x: number, y: number, z: number, blockName: string): void;
+
+    /**
+     * Whether a default or named schematic region exists.
+     */
+    hasRegion(regionName: string): boolean;
+
+    /**
+     * Create an empty named region. Its first block anchors its bounds.
+     */
+    createRegion(regionName: string): void;
+
+    /**
+     * Remove a named region. The default region cannot be removed.
+     */
+    removeRegion(regionName: string): void;
+
+    /**
+     * Rename a named region. The default region cannot be renamed.
+     */
+    renameRegion(oldName: string, newName: string): void;
+
+    /**
+     * The schematic bounding box as a JSON array
+     * `[min_x, min_y, min_z, max_x, max_y, max_z]`.
+     */
+    boundingBoxJson(): string;
+
+    /**
+     * A named region's bounding box as a JSON array
+     * `[min_x, min_y, min_z, max_x, max_y, max_z]`. `"default"`/`"Default"`
+     * address the default region.
+     */
+    regionBoundingBoxJson(regionName: string): string;
+
+    /**
+     * The merged-region palette block names, as a JSON array of strings.
+     */
+    paletteJson(): string;
+
+    /**
+     * The tight (content) dimensions.
+     */
+    tightDimensions(): Dimensions;
+
+    /**
+     * The allocated dimensions (same as `dimensions`; named for parity with
+     * the old `schematic_get_allocated_dimensions`).
+     */
+    allocatedDimensions(): Dimensions;
+
+    /**
+     * Every sign in the schematic, as a JSON array of
+     * `{"pos": [x,y,z], "text": [...]}`.
+     */
+    extractSignsJson(): string;
+
+    /**
+     * Compile the schematic's insign annotations to JSON.
+     */
+    compileInsignJson(): string;
+
+    /**
+     * Every region's palette, as a JSON object mapping region name → array of
+     * block names (the default region under `"default"`).
+     */
+    allPalettesJson(): string;
+
+    /**
+     * The default region's palette block names, as a JSON array of strings.
+     */
+    defaultRegionPaletteJson(): string;
+
+    /**
+     * A named region's palette block names, as a JSON array of strings.
+     * `"default"`/`"Default"` address the default region.
+     */
+    regionPaletteJson(regionName: string): string;
+
+    /**
+     * The minimum corner of the tight (content) bounds. `NotFound` when the
+     * schematic has no content.
+     */
+    tightBoundsMin(): BlockPos;
+
+    /**
+     * The maximum corner of the tight (content) bounds. `NotFound` when the
+     * schematic has no content.
+     */
+    tightBoundsMax(): BlockPos;
+}