Amulet Core

The amulet.api.selection package provides classes for managing selection boxes and groups of selection boxes.

Key Characteristics:

• Immutability: Both selection box classes and selection group classes are immutable. Any operation that modifies a selection will return a new instance rather than modifying the existing one.

The UnboundedPartial3DArray is designed to solve the problem of storing 3D data (like blocks or biomes) with an unlimited vertical height without consuming infinite memory.

Instead of one massive array, it uses a sparse approach: it stores a dictionary of numpy.ndarray objects, where each array represents a 16x16x16 volume called a sub-chunk (or section).

Key concepts:

• Sub-chunk/Section: A 16x16x16 block volume.
• Sub-chunk coordinate: The vertical (y) index of a sub-chunk within a chunk. This is distinct from the raw block y-coordinate.
• Unbounded vs Bounded: UnboundedPartial3DArray has no vertical limit. When you access a slice of it using numpy-like syntax, it returns a BoundedPartial3DArray, which represents a finite volume but remains linked to the original data. Modifying the bounded view will modify the original unbounded array.

In Amulet Core, block and biome data is stored as numerical values in arrays to optimize space. The amulet.api.registry package provides a two-way mapping system that allows you to convert these numerical values back into meaningful objects or strings, and vice versa.

• Numerical to Object/String: Converts an integer from the data arrays into an amulet.api.block.Block object or a biome string.
• Object/String to Numerical: Converts a Block or biome string into the integer value required before adding it to the underlying data arrays.

These registries are managed via the palettes stored in the level and chunks, specifically through the block_palette and biome_palette attributes of a BaseLevel object.

Amulet provides different level classes depending on the type of data you are interacting with:

• World: Use this class when you are editing full world data.
• Structure: Use this class when you are editing specific structure files (e.g., .schematic, .mcstructure, .schem).
• ImmutableStructure: Use this class when you need to extract a section of a world without modifying the original source (for example, when performing a copy operation). This is typically obtained via the BaseLevel.extract_structure method.

In Amulet, Level classes act as containers for all data related to a specific world or structure, including chunk data and history management for reverting changes.

All data within these classes is stored in a universal format. This is a consistent internal representation that all data is converted to, regardless of its original source (e.g., different game versions or platforms). This abstraction allows for:

• Consistent Editing: You can edit data from different platforms using the same logic.
• World Conversion: The universal format can be converted out to any supported format, enabling seamless transitions between different world types.

The translation system provides three distinct ways to represent version numbers to ensure compatibility across different data formats:

• VersionNumberInt: Represents a version number as a single integer.
• VersionNumberTuple: Represents a version number as a tuple of integers (e.g., (1, 2, 3)).
• VersionNumberAny: A flexible type that can represent a version number in multiple formats.

Amulet uses a custom universal format to represent block states. This format is designed as a superset of all block formats from every platform and game version, ensuring no data loss during conversion.

Critical Warning for Developers

Do not hard-code data in the universal format. The universal format is subject to change as new game versions are released to support new features. Hard-coding these values will cause your code to break when Amulet is updated.

Recommended Workflow for Editing Block Data

To safely manipulate block data, follow this pattern:

1. Use the translator to convert the universal representation into a specific platform and game version format.
2. Edit the data in that specific, historical game format (which is stable and safe to hard-code).
3. Convert the data back to the universal format.
4. Write the universal format data back to the chunk.

Amulet uses the modern block state system rather than the legacy numerical ID system used by older editors like MCEdit.

In the modern format, chunks contain an array of integers that serve as indexes into a block palette (a list of block states) stored within the chunk. A block state consists of:

1. A namespaced name (e.g., minecraft:spruce_leaves).
2. A dictionary of properties (e.g., distance, persistent).

This approach allows for arbitrary integer indexing and avoids the issues caused by modded clients remapping numerical IDs, as the specific identity and properties of a block are explicitly defined in the palette.

{
    "Name": "minecraft:spruce_leaves",
    "Properties": {
        "distance": "1",
        "persistent": "false"
    }
}