Class StructureManager

Manager for Structure related APIs. Includes APIs for creating, getting, placing and deleting Structures.

Methods

createEmpty createFromWorld delete get getWorldStructureIds place

Methods

createEmpty

  • createEmpty(
        identifier: string,
        size: Vector3,
        saveMode?: StructureSaveMode,
    ): Structure

  • Parameters

    • identifier: string

      The name of the structure. A valid identifier must include a namespace and must be unique.

    • size: Vector3

      The size of the structure. For example, to create a single block structure the size should be {x:1, y:1, z:1}.

    • OptionalsaveMode: StructureSaveMode

      How the Structure should be saved upon creation. Defaults to StructureSaveMode.Memory.

    Returns Structure

    Returns the newly created Structure.

    Remarks

    Creates an empty Structure in memory. Use Structure.setBlockPermutation to populate the structure with blocks and save changes with Structure.saveAs.

    This function can't be called in read-only mode.

    Throws

    Throws if the identifier is invalid. A valid identifier must include a namespace and must be unique.

    minecraftcommon.EngineError

    minecraftcommon.InvalidArgumentError

    Example: randomStructure.js

    import { BlockPermutation, StructureSaveMode, world } from "@minecraft/server";
    import { MinecraftBlockTypes } from "@minecraft/vanilla-data";
    const structure = world.structureManager.createEmpty(
        "mystructure:random",
        { x: 10, y: 10, z: 10 },
        StructureSaveMode.World
    );
    const concretes = [
        MinecraftBlockTypes.RedConcrete,
        MinecraftBlockTypes.YellowConcrete,
        MinecraftBlockTypes.BlueConcrete,
    ];

    for (let x = 0; x < 10; x++) {
        for (let y = 0; y < 10; y++) {
            for (let z = 0; z < 10; z++) {
                const permutation = BlockPermutation.resolve(
                    concretes[Math.floor(Math.random() * concretes.length)]
                );
                structure.setBlockPermutation({ x, y, z }, permutation);
            }
        }
    }
    // Run this command: /structure load mystructure:empty ~ ~ ~

createFromWorld

  • createFromWorld(
        identifier: string,
        dimension: Dimension,
        from: Vector3,
        to: Vector3,
        options?: StructureCreateOptions,
    ): Structure

  • Parameters

    • identifier: string

      The name of the structure. A valid identifier must include a namespace and must be unique.

    • dimension: Dimension

      The dimension where the blocks should be read from.

    • from: Vector3
    • to: Vector3
    • Optionaloptions: StructureCreateOptions

      Additional options for creating a structure from the world.

    Returns Structure

    Returns the newly created Structure.

    Remarks

    Creates a new Structure from blocks in the world. This is functionally equivalent to the /structure save command.

    This function can't be called in read-only mode.

    Throws

    Throws if the identifier is invalid. A valid identifier must include a namespace and must be unique. Throws if the structure bounds exceed the maximum size. Throws if the structure bounds contains blocks outside the world bounds.

    minecraftcommon.InvalidArgumentError

    Example: structureFromWorld.js

    import { StructureSaveMode, world } from "@minecraft/server";
    import { Vector3Builder, Vector3Utils } from "@minecraft/math";
    const player = world.getAllPlayers()[0];
    const from = player.location;
    const to = Vector3Utils.add(from, new Vector3Builder(15, 15, 15));
    world.structureManager.createFromWorld(
        "mystructure:test",
        player.dimension,
        from,
        to,
        { saveMode: StructureSaveMode.World }
    );

delete

  • delete(structure: string | Structure): boolean

  • Parameters

    • structure: string | Structure

      The structure identifier or Structure object that should be deleted. Note, a Structure object will become invalid after it is deleted.

    Returns boolean

    Returns whether the structure was removed.

    Remarks

    Deletes a structure from memory and from the world if it exists.

    This function can't be called in read-only mode.

    Throws

    Throws if a structure cannot be removed. For example, a structure loaded from a Behavior Pack.

    minecraftcommon.InvalidArgumentError

    Example: deleteStructure.js

    import { world } from "@minecraft/server";

    world.structureManager.delete("mystructure:test");

get

  • get(identifier: string): Structure

  • Parameters

    • identifier: string

      The name of the structure to get.

    Returns Structure

    Returns a Structure if it exists, otherwise undefined.

    Remarks

    Gets a Structure that is saved to memory or the world.

    This function can't be called in read-only mode.

    Example: getStructure.js

    import { world } from "@minecraft/server";

    world.structureManager.get("mystructure:test");

getWorldStructureIds

  • getWorldStructureIds(): string[]

  • Returns string[]

    Remarks

    This function can't be called in read-only mode.

    Example: getAllDiskStructures.ts

    import { world } from "@minecraft/server";

    world.structureManager.getWorldStructureIds().forEach((id) => {
        const structure = world.structureManager.get(id);
        structure.isValid();
    });

place

  • place(
        structure: string | Structure,
        dimension: Dimension,
        location: Vector3,
        options?: StructurePlaceOptions,
    ): void

  • Parameters

    • structure: string | Structure

      The structure's identifier or a Structure object.

    • dimension: Dimension

      The dimension where the Structure should be placed.

    • location: Vector3

      The location within the dimension where the Structure should be placed.

    • Optionaloptions: StructurePlaceOptions

      Additional options for Structure placement.

    Returns void

    Remarks

    Places a structure in the world. Structures placed in unloaded chunks will be queued for loading.

    This function can't be called in read-only mode.

    Throws

    Throws if the integrity value is outside of the range [0,1] Throws if the integrity seed is invalid. Throws if the placement location contains blocks that are outside the world bounds.

    minecraftcommon.ArgumentOutOfBoundsError

    minecraftcommon.InvalidArgumentError

    InvalidStructureError

    Example: placeRandom.js

    import {
        world,
        StructureAnimationMode,
        StructureSaveMode,
        BlockPermutation,
    } from "@minecraft/server";
    import { MinecraftBlockTypes } from "@minecraft/vanilla-data";

    function getRandomStructure() {
        // Return existing mystructure:random structure
        if (
            world.structureManager
                .getWorldStructureIds()
                .includes("mystructure:random")
        ) {
            return world.structureManager.get("mystructure:random");
        }

        // Create a new mystructure:random structure otherwise
        const structure = world.structureManager.createEmpty(
            "mystructure:random",
            { x: 10, y: 10, z: 10 },
            StructureSaveMode.World
        );
        const concretes = [
            MinecraftBlockTypes.RedConcrete,
            MinecraftBlockTypes.YellowConcrete,
            MinecraftBlockTypes.BlueConcrete,
        ];

        for (let x = 0; x < 10; x++) {
            for (let y = 0; y < 10; y++) {
                for (let z = 0; z < 10; z++) {
                    const permutation = BlockPermutation.resolve(
                        concretes[Math.floor(Math.random() * concretes.length)]
                    );
                    structure.setBlockPermutation({ x, y, z }, permutation);
                }
            }
        }

        return structure;
    }

    const structure = getRandomStructure();
    const player = world.getPlayers()[0];
    // Place structure on player's location
    world.structureManager.place(structure, player.dimension, player.location, {
        animationMode: StructureAnimationMode.Blocks,
        animationSeconds: 15,
    });

    Example: placeTestStructure.js

    import { world } from "@minecraft/server";
    const player = world.getPlayers()[0];
    world.structureManager.place(
        "mystructure:test",
        player.dimension,
        player.location
    );

Settings

Member Visibility

On This Page

Methods