amulet-core 2.0.7a0__cp312-cp312-macosx_10_15_universal2.whl

amulet/core/__init__.py

@@ -0,0 +1,38 @@
+import logging as _logging
+
+from . import _version
+
+__version__ = _version.get_versions()["version"]
+
+# init a default logger
+_logging.basicConfig(level=_logging.INFO, format="%(levelname)s - %(message)s")
+
+
+def _init() -> None:
+    import os
+    import sys
+    import ctypes
+
+    if sys.platform == "win32":
+        lib_path = os.path.join(os.path.dirname(__file__), "amulet_core.dll")
+    elif sys.platform == "darwin":
+        lib_path = os.path.join(os.path.dirname(__file__), "libamulet_core.dylib")
+    elif sys.platform == "linux":
+        lib_path = os.path.join(os.path.dirname(__file__), "libamulet_core.so")
+    else:
+        raise RuntimeError(f"Unsupported platform {sys.platform}")
+
+    # Import dependencies
+    import amulet.utils
+    import amulet.zlib
+    import amulet.nbt
+
+    # Load the shared library
+    ctypes.cdll.LoadLibrary(lib_path)
+
+    from ._amulet_core import init
+
+    init(sys.modules[__name__])
+
+
+_init()

amulet/core/__init__.pyi

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from . import (
+    _amulet_core,
+    _version,
+    biome,
+    block,
+    block_entity,
+    chunk,
+    entity,
+    palette,
+    selection,
+    version,
+)
+
+__all__: list[str] = [
+    "biome",
+    "block",
+    "block_entity",
+    "chunk",
+    "compiler_config",
+    "entity",
+    "palette",
+    "selection",
+    "version",
+]
+
+def _init() -> None: ...
+
+__version__: str
+compiler_config: dict

amulet/core/__pyinstaller/__init__.py

@@ -0,0 +1,2 @@
+def get_hook_dirs() -> list[str]:
+    return __path__

amulet/core/__pyinstaller/hook-amulet.core.py

@@ -0,0 +1,4 @@
+from PyInstaller.utils.hooks import collect_data_files, collect_submodules
+
+hiddenimports = collect_submodules("amulet.core")
+datas = collect_data_files("amulet.core")

amulet/core/_amulet_core.pyi

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+import types
+
+__all__: list[str] = ["init"]
+
+def init(m: types.ModuleType) -> None: ...

amulet/core/_version.py

@@ -0,0 +1,21 @@
+
+# This file was generated by 'versioneer.py' (0.29) from
+# revision-control system data, or from the parent directory name of an
+# unpacked source archive. Distribution tarballs contain a pre-generated copy
+# of this file.
+
+import json
+
+version_json = '''
+{
+ "date": "2025-11-20T15:14:43+0000",
+ "dirty": false,
+ "error": null,
+ "full-revisionid": "ffdb0c69d97f35a4fd911063d8eef90f887901b7",
+ "version": "2.0.7a0"
+}
+'''  # END VERSION_JSON
+
+
+def get_versions():
+    return json.loads(version_json)

amulet/core/amulet_coreConfig.cmake

@@ -0,0 +1,23 @@
+if (NOT TARGET amulet_core)
+    message(STATUS "Finding amulet_core")
+
+    find_package(amulet_io CONFIG REQUIRED)
+    find_package(amulet_nbt CONFIG REQUIRED)
+    find_package(amulet_utils CONFIG REQUIRED)
+
+    set(amulet_core_INCLUDE_DIR "${CMAKE_CURRENT_LIST_DIR}/../..")
+    find_library(amulet_core_LIBRARY NAMES amulet_core PATHS "${CMAKE_CURRENT_LIST_DIR}")
+    message(STATUS "amulet_core_LIBRARY: ${amulet_core_LIBRARY}")
+
+    add_library(amulet_core_bin SHARED IMPORTED)
+    set_target_properties(amulet_core_bin PROPERTIES
+        IMPORTED_IMPLIB "${amulet_core_LIBRARY}"
+    )
+
+    add_library(amulet_core INTERFACE)
+    target_link_libraries(amulet_core INTERFACE amulet_io)
+    target_link_libraries(amulet_core INTERFACE amulet_nbt)
+    target_link_libraries(amulet_core INTERFACE amulet_utils)
+    target_link_libraries(amulet_core INTERFACE amulet_core_bin)
+    target_include_directories(amulet_core INTERFACE ${amulet_core_INCLUDE_DIR})
+endif()

amulet/core/biome/__init__.pyi

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import types
+import typing
+
+import amulet.core.version
+
+__all__: list[str] = ["Biome"]
+
+class Biome(amulet.core.version.PlatformVersionContainer):
+    """
+    A class to manage the state of a biome.
+
+    It is an immutable object that contains the platform, version, namespace and base name.
+
+    Here's a few examples on how create a Biome object:
+
+    >>> # Create a plains biome for Java 1.20.2
+    >>> plains = Biome("java", VersionNumber(3578), "minecraft", "plains")
+    >>> # The version number for Java is the Java data version
+
+    >>> # Create a plains biome for Bedrock
+    >>> plains = Biome("bedrock", VersionNumber(1, 21, 0, 3), "minecraft", "plains")
+    >>> # The biome version number is unused in Bedrock but it is here for completeness.
+    """
+
+    @typing.overload
+    def __eq__(self, other: Biome) -> bool: ...
+    @typing.overload
+    def __eq__(self, other: typing.Any) -> bool | types.NotImplementedType: ...
+    def __ge__(self, arg0: Biome) -> bool: ...
+    def __gt__(self, arg0: Biome) -> bool: ...
+    def __hash__(self) -> int: ...
+    def __init__(
+        self,
+        platform: str,
+        version: amulet.core.version.VersionNumber,
+        namespace: str,
+        base_name: str,
+    ) -> None: ...
+    def __le__(self, arg0: Biome) -> bool: ...
+    def __lt__(self, arg0: Biome) -> bool: ...
+    def __repr__(self) -> str: ...
+    @property
+    def base_name(self) -> str:
+        """
+        The base name of the :class:`Biome` object.
+
+        >>> biome: Biome
+        >>> biome.base_name
+
+        :return: The base name of the biome
+        """
+
+    @property
+    def namespace(self) -> str:
+        """
+        The namespace of the :class:`Biome` object.
+
+        >>> biome: Biome
+        >>> water.namespace
+
+        :return: The namespace of the biome
+        """
+
+    @property
+    def namespaced_name(self) -> str:
+        """
+        The namespaced id of the :class:`Biome` object.
+
+        >>> biome: Biome
+        >>> biome.namespaced_name
+
+        :return: The "namespace:base_name" of the biome
+        """

amulet/core/biome/biome.hpp

@@ -0,0 +1,53 @@
+#pragma once
+
+#include <string>
+
+#include <amulet/io/binary_reader.hpp>
+#include <amulet/io/binary_writer.hpp>
+
+#include <amulet/core/dll.hpp>
+#include <amulet/core/version/version.hpp>
+
+namespace Amulet {
+class Biome : public PlatformVersionContainer {
+private:
+    std::string _namespace;
+    std::string _base_name;
+
+public:
+    const std::string& get_namespace() const { return _namespace; }
+    const std::string& get_base_name() const { return _base_name; }
+
+    template <typename PlatformT, typename VersionT, typename NamespaceT, typename BaseNameT>
+    Biome(
+        PlatformT&& platform,
+        VersionT&& version,
+        NamespaceT&& namespace_,
+        BaseNameT&& base_name)
+        : PlatformVersionContainer(std::forward<PlatformT>(platform), std::forward<VersionT>(version))
+        , _namespace(std::forward<NamespaceT>(namespace_))
+        , _base_name(std::forward<BaseNameT>(base_name))
+    {
+    }
+
+    AMULET_CORE_EXPORT void serialise(BinaryWriter&) const;
+    AMULET_CORE_EXPORT static Biome deserialise(BinaryReader&);
+
+    auto operator<=>(const Biome& other) const
+    {
+        auto cmp = PlatformVersionContainer::operator<=>(other);
+        if (cmp != 0) {
+            return cmp;
+        }
+        cmp = _namespace <=> other._namespace;
+        if (cmp != 0) {
+            return cmp;
+        }
+        return _base_name <=> other._base_name;
+    }
+    bool operator==(const Biome& other) const
+    {
+        return (*this <=> other) == 0;
+    }
+};
+}

amulet/core/block/__init__.pyi

@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+import collections.abc
+import types
+import typing
+
+import amulet.core.version
+import amulet.nbt
+
+__all__: list[str] = ["Block", "BlockStack"]
+
+class Block(amulet.core.version.PlatformVersionContainer):
+    """
+    A class to manage the state of a block.
+
+    It is an immutable object that contains the platform, version, namespace, base name and properties.
+
+    Here's a few examples on how create a Block object:
+
+    >>> # Create a stone block for Java 1.20.2
+    >>> stone = Block("java", VersionNumber(3578), "minecraft", "stone")
+    >>> # The Java block version number is the Java data version
+
+    >>> # Create a stone block for Bedrock
+    >>> stone = Block("bedrock", VersionNumber(1, 21, 0, 3), "minecraft", "stone")
+    >>> # The Bedrock block version number is the value stored as an int with the block data.
+
+    >>> # Create a Java water block with the level property
+    >>> water = Block(
+    >>>     "java", VersionNumber(3578),
+    >>>     "minecraft",  # the namespace
+    >>>     "water",  # the base name
+    >>>     {  # A dictionary of properties.
+    >>>         # Keys must be strings and values must be a numerical or string NBT type.
+    >>>         "level": StringTag("0")  # define a property `level` with a string value `0`
+    >>>     }
+    >>> )
+    """
+
+    PropertyValue: typing.TypeAlias = (
+        amulet.nbt.ByteTag
+        | amulet.nbt.ShortTag
+        | amulet.nbt.IntTag
+        | amulet.nbt.LongTag
+        | amulet.nbt.StringTag
+    )
+    @staticmethod
+    def from_bedrock_blockstate(
+        platform: str, version: amulet.core.version.VersionNumber, blockstate: str
+    ) -> Block:
+        """
+        Parse a Bedrock format blockstate where values are all strings and populate a :class:`Block` class with the data.
+
+        >>> stone = Block.from_bedrock_blockstate("minecraft:stone")
+        >>> water = Block.from_bedrock_blockstate("minecraft:water["liquid_depth"=0]")
+
+        :param platform: The platform the block is defined in.
+        :param version: The version the block is defined in.
+        :param blockstate: The Bedrock blockstate string to parse.
+        :return: A Block instance containing the state.
+        """
+
+    @staticmethod
+    def from_java_blockstate(
+        platform: str, version: amulet.core.version.VersionNumber, blockstate: str
+    ) -> Block:
+        """
+        Parse a Java format blockstate where values are all strings and populate a :class:`Block` class with the data.
+
+        >>> stone = Block.from_java_blockstate("minecraft:stone")
+        >>> water = Block.from_java_blockstate("minecraft:water[level=0]")
+
+        :param platform: The platform the block is defined in.
+        :param version: The version the block is defined in.
+        :param blockstate: The Java blockstate string to parse.
+        :return: A Block instance containing the state.
+        """
+
+    @typing.overload
+    def __eq__(self, other: Block) -> bool: ...
+    @typing.overload
+    def __eq__(self, other: typing.Any) -> bool | types.NotImplementedType: ...
+    def __ge__(self, arg0: Block) -> bool: ...
+    def __gt__(self, arg0: Block) -> bool: ...
+    def __hash__(self) -> int: ...
+    def __init__(
+        self,
+        platform: str,
+        version: amulet.core.version.VersionNumber,
+        namespace: str,
+        base_name: str,
+        properties: collections.abc.Mapping[
+            str,
+            amulet.nbt.ByteTag
+            | amulet.nbt.ShortTag
+            | amulet.nbt.IntTag
+            | amulet.nbt.LongTag
+            | amulet.nbt.StringTag,
+        ] = {},
+    ) -> None: ...
+    def __le__(self, arg0: Block) -> bool: ...
+    def __lt__(self, arg0: Block) -> bool: ...
+    def __repr__(self) -> str: ...
+    @property
+    def base_name(self) -> str:
+        """
+        The base name of the blockstate represented by the :class:`Block` object.
+
+        >>> block: Block
+        >>> block.base_name
+
+        :return: The base name of the blockstate
+        """
+
+    @property
+    def bedrock_blockstate(self) -> str:
+        """
+        The Bedrock blockstate string of this :class:`Block` object.
+        Converts the property values to the SNBT format to preserve type.
+
+        >>> bell = Block(
+        >>>     "java", VersionNumber(3578),
+        >>>     "minecraft",
+        >>>     "bell",
+        >>>     {
+        >>>         "attachment":StringTag("standing"),
+        >>>         "direction":IntTag(0),
+        >>>         "toggle_bit":ByteTag(0)
+        >>>     }
+        >>> )
+        >>> bell.bedrock_blockstate
+        minecraft:bell["attachment"="standing","direction"=0,"toggle_bit"=false]
+
+        :return: The SNBT blockstate string
+        """
+
+    @property
+    def java_blockstate(self) -> str:
+        """
+        The Java blockstate string of this :class:`Block` object.
+        Note this will only contain properties with StringTag values.
+
+        >>> stone = Block("java", VersionNumber(3578), "minecraft", "stone")
+        >>> stone.java_blockstate
+        minecraft:stone
+        >>> water = Block("java", VersionNumber(3578), "minecraft", "water", {"level": StringTag("0")})
+        >>> water.java_blockstate
+        minecraft:water[level=0]
+
+        :return: The blockstate string
+        """
+
+    @property
+    def namespace(self) -> str:
+        """
+        The namespace of the blockstate represented by the :class:`Block` object.
+
+        >>> block: Block
+        >>> water.namespace
+
+        :return: The namespace of the blockstate
+        """
+
+    @property
+    def namespaced_name(self) -> str:
+        """
+        The namespace:base_name of the blockstate represented by the :class:`Block` object.
+
+        >>> block: Block
+        >>> block.namespaced_name
+
+        :return: The namespace:base_name of the blockstate
+        """
+
+    @property
+    def properties(
+        self,
+    ) -> dict[
+        str,
+        amulet.nbt.ByteTag
+        | amulet.nbt.ShortTag
+        | amulet.nbt.IntTag
+        | amulet.nbt.LongTag
+        | amulet.nbt.StringTag,
+    ]:
+        """
+        The properties of the blockstate represented by the :class:`Block` object as a dictionary.
+        >>> block: Block
+        >>> block.properties
+
+        :return: A mapping of the properties of the blockstate
+        """
+
+class BlockStack:
+    """
+    A stack of block objects.
+
+    Java 1.13 added the concept of waterlogging blocks whereby some blocks have a `waterlogged` property.
+    Bedrock achieved the same behaviour by added a layering system which allows the second block to be any block.
+
+    Amulet supports both implementations with a stack of one or more block objects similar to how Bedrock handles it.
+    Amulet places no restrictions on which blocks can be extra blocks.
+    Extra block may be discarded if the format does not support them.
+
+    Create a waterlogged stone block.
+    >>> waterlogged_stone = BlockStack(
+    >>>     Block("java", VersionNumber(3578), "minecraft", "stone"),
+    >>>     Block("java", VersionNumber(3578), "minecraft", "water", {"level": StringTag("0")})
+    >>> )
+
+    Get a block at an index
+    >>> stone = waterlogged_stone[0]
+    >>> water = waterlogged_stone[1]
+
+    Get the blocks as a list
+    >>> blocks = list(waterlogged_stone)
+    """
+
+    def __contains__(self, item: typing.Any) -> bool: ...
+    @typing.overload
+    def __eq__(self, other: BlockStack) -> bool: ...
+    @typing.overload
+    def __eq__(self, other: typing.Any) -> bool | types.NotImplementedType: ...
+    def __ge__(self, arg0: BlockStack) -> bool: ...
+    @typing.overload
+    def __getitem__(self, arg0: typing.SupportsInt) -> Block: ...
+    @typing.overload
+    def __getitem__(self, item: slice) -> list[Block]: ...
+    def __gt__(self, arg0: BlockStack) -> bool: ...
+    def __hash__(self) -> int: ...
+    def __init__(self, block: Block, *extra_blocks: Block) -> None: ...
+    def __iter__(self) -> collections.abc.Iterator[Block]: ...
+    def __le__(self, arg0: BlockStack) -> bool: ...
+    def __len__(self) -> int: ...
+    def __lt__(self, arg0: BlockStack) -> bool: ...
+    def __repr__(self) -> str: ...
+    def __reversed__(self) -> collections.abc.Iterator[Block]: ...
+    def count(self, value: Block) -> int: ...
+    def index(
+        self,
+        value: Block,
+        start: typing.SupportsInt = 0,
+        stop: typing.SupportsInt = 9223372036854775807,
+    ) -> int: ...
+    @property
+    def base_block(self) -> Block:
+        """
+        The first block in the stack.
+
+        >>> waterlogged_stone = BlockStack(
+        >>>     Block("java", VersionNumber(3578), "minecraft", "stone"),
+        >>>     Block("java", VersionNumber(3578), "minecraft", "water", {"level": StringTag("0")})
+        >>> )
+        >>> waterlogged_stone.base_block
+        Block("java", VersionNumber(3578), "minecraft", "stone")
+
+        :return: A Block object
+        """
+
+    @property
+    def extra_blocks(self) -> tuple[Block]:
+        """
+        The extra blocks in the stack.
+
+        >>> waterlogged_stone = BlockStack(
+        >>>     Block("java", VersionNumber(3578), "minecraft", "stone"),
+        >>>     Block("java", VersionNumber(3578), "minecraft", "water", {"level": StringTag("0")})
+        >>> )
+        >>> waterlogged_stone.extra_blocks
+        (Block("java", VersionNumber(3578), "minecraft", "water", {"level": StringTag("0")}),)
+
+        :return: A tuple of :class:`Block` objects
+        """

amulet/core/block/block.hpp

@@ -0,0 +1,156 @@
+#pragma once
+
+#include <map>
+#include <string>
+#include <variant>
+
+#include <amulet/io/binary_reader.hpp>
+#include <amulet/io/binary_writer.hpp>
+
+#include <amulet/nbt/tag/int.hpp>
+#include <amulet/nbt/tag/string.hpp>
+
+#include <amulet/core/dll.hpp>
+#include <amulet/core/version/version.hpp>
+
+namespace Amulet {
+
+class Block : public PlatformVersionContainer {
+public:
+    using PropertyValue = std::variant<
+        Amulet::NBT::ByteTag,
+        Amulet::NBT::ShortTag,
+        Amulet::NBT::IntTag,
+        Amulet::NBT::LongTag,
+        Amulet::NBT::StringTag>;
+
+    using PropertyMap = std::map<std::string, PropertyValue>;
+
+private:
+    std::string _namespace;
+    std::string _base_name;
+    PropertyMap _properties;
+
+public:
+    const std::string& get_namespace() const { return _namespace; }
+    const std::string& get_base_name() const { return _base_name; }
+    const PropertyMap& get_properties() const { return _properties; }
+
+    template <
+        typename PlatformT,
+        typename VersionT,
+        typename NamespaceT,
+        typename BaseNameT>
+    Block(
+        PlatformT&& platform,
+        VersionT&& version,
+        NamespaceT&& namespace_,
+        BaseNameT&& base_name)
+        : PlatformVersionContainer(std::forward<PlatformT>(platform), std::forward<VersionT>(version))
+        , _namespace(std::forward<NamespaceT>(namespace_))
+        , _base_name(std::forward<BaseNameT>(base_name))
+        , _properties()
+    {
+    }
+
+    template <
+        typename PlatformT,
+        typename VersionT,
+        typename NamespaceT,
+        typename BaseNameT,
+        typename PropertiesT>
+    Block(
+        PlatformT&& platform,
+        VersionT&& version,
+        NamespaceT&& namespace_,
+        BaseNameT&& base_name,
+        PropertiesT&& properties)
+        : PlatformVersionContainer(std::forward<PlatformT>(platform), std::forward<VersionT>(version))
+        , _namespace(std::forward<NamespaceT>(namespace_))
+        , _base_name(std::forward<BaseNameT>(base_name))
+        , _properties(std::forward<PropertiesT>(properties))
+    {
+    }
+
+    AMULET_CORE_EXPORT void serialise(BinaryWriter&) const;
+    AMULET_CORE_EXPORT static Block deserialise(BinaryReader&);
+
+    auto operator<=>(const Block& other) const
+    {
+        auto cmp = PlatformVersionContainer::operator<=>(other);
+        if (cmp != 0) {
+            return cmp;
+        }
+        cmp = _namespace <=> other._namespace;
+        if (cmp != 0) {
+            return cmp;
+        }
+        cmp = _base_name <=> other._base_name;
+        if (cmp != 0) {
+            return cmp;
+        }
+        return _properties <=> other._properties;
+    }
+    bool operator==(const Block& other) const
+    {
+        return (*this <=> other) == 0;
+    }
+
+    AMULET_CORE_EXPORT std::string java_blockstate() const;
+    AMULET_CORE_EXPORT std::string bedrock_blockstate() const;
+    AMULET_CORE_EXPORT static Block from_java_blockstate(const PlatformType&, const VersionNumber&, const std::string&);
+    AMULET_CORE_EXPORT static Block from_bedrock_blockstate(const PlatformType&, const VersionNumber&, const std::string&);
+};
+
+class BlockStack {
+private:
+    std::vector<Block> _blocks;
+
+public:
+    const std::vector<Block>& get_blocks() const { return _blocks; }
+
+    template <typename... Args>
+        requires std::is_constructible_v<std::vector<Block>, Args...>
+    BlockStack(Args&&... args)
+        : _blocks(std::forward<Args>(args)...)
+    {
+        if (_blocks.empty()) {
+            throw std::invalid_argument("A BlockStack must contain at least one block");
+        }
+    }
+
+    BlockStack(std::initializer_list<Block> blocks)
+        : _blocks(blocks)
+    {
+        if (_blocks.empty()) {
+            throw std::invalid_argument("A BlockStack must contain at least one block");
+        }
+    }
+
+    AMULET_CORE_EXPORT void serialise(BinaryWriter&) const;
+    AMULET_CORE_EXPORT static BlockStack deserialise(BinaryReader&);
+
+    auto operator<=>(const BlockStack& other) const
+    {
+        auto cmp = size() <=> other.size();
+        if (cmp != 0) {
+            return cmp;
+        }
+        for (size_t i = 0; i < size(); i++) {
+            cmp = at(i) <=> other.at(i);
+            if (cmp != 0) {
+                return cmp;
+            }
+        }
+        return std::strong_ordering::equal;
+    }
+    bool operator==(const BlockStack& other) const
+    {
+        return (*this <=> other) == 0;
+    }
+
+    size_t size() const { return _blocks.size(); }
+    const Block& at(size_t index) const { return _blocks.at(index); }
+};
+
+} // namespace Amulet