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

Hierarchy

  • StructureManager

Constructors

Methods

  • 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}.

    • Optional saveMode: StructureSaveMode

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

      Optional

    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 ~ ~ ~

  • 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
    • Optional options: StructureCreateOptions

      Additional options for creating a structure from the world.

      Optional

    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 }
    );

  • 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");

  • 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");

  • 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();
    });

  • 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.

    • Optional options: StructurePlaceOptions

      Additional options for Structure placement.

      Optional

    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 } from "@minecraft/server";

    // Get structure from code example 'random_structure.js' @ StructureManager::createEmpty
    const structure = world.structureManager.get("mystructure:random");
    const player = world.getPlayers()[0];
    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
    );