amulet-core 2.0a5__cp311-cp311-macosx_10_9_universal2.whl

amulet/block.hpp

@@ -0,0 +1,119 @@
+#pragma once
+
+#include <map>
+#include <variant>
+#include <string>
+
+#include <amulet/io/binary_reader.hpp>
+#include <amulet/io/binary_writer.hpp>
+#include <amulet/version.hpp>
+#include <amulet_nbt/tag/int.hpp>
+#include <amulet_nbt/tag/string.hpp>
+
+
+namespace Amulet {
+    typedef std::variant<
+        AmuletNBT::ByteTag,
+        AmuletNBT::ShortTag,
+        AmuletNBT::IntTag,
+        AmuletNBT::LongTag,
+        AmuletNBT::StringTag
+    > PropertyValueType;
+
+    typedef std::map<std::string, PropertyValueType> BlockProperites;
+
+    class Block: public PlatformVersionContainer {
+        private:
+            std::string namespace_;
+            std::string base_name;
+            BlockProperites properties;
+        public:
+            const std::string& get_namespace() const { return namespace_; }
+            const std::string& get_base_name() const { return base_name; }
+            const BlockProperites& get_properties() const {
+                return properties;
+            }
+
+            template <typename versionT>
+            Block(
+                const PlatformType& platform,
+                const versionT& version,
+                const std::string& namespace_,
+                const std::string& base_name
+            ) :
+                PlatformVersionContainer(platform, version),
+                namespace_(namespace_),
+                base_name(base_name),
+                properties() {}
+
+            template <
+                typename versionT,
+                typename propertiesT
+            >
+            Block(
+                const PlatformType& platform,
+                const versionT& version,
+                const std::string& namespace_,
+                const std::string& base_name,
+                const propertiesT& properties
+            ):
+                PlatformVersionContainer(platform, version),
+                namespace_(namespace_),
+                base_name(base_name),
+                properties(properties) {}
+
+            void serialise(BinaryWriter&) const;
+            static std::shared_ptr<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;
+            };
+
+            std::string java_blockstate() const;
+            std::string bedrock_blockstate() const;
+            static std::shared_ptr<Block> from_java_blockstate(const PlatformType&, std::shared_ptr<VersionNumber>, const std::string&);
+            static std::shared_ptr<Block> from_bedrock_blockstate(const PlatformType&, std::shared_ptr<VersionNumber>, const std::string&);
+    };
+
+    class BlockStack {
+        private:
+            std::vector<std::shared_ptr<Block>> _blocks;
+        public:
+            const std::vector<std::shared_ptr<Block>>& get_blocks() const { return _blocks; }
+
+            template <typename T>
+            BlockStack(const T& blocks) : _blocks(blocks) {
+                if (_blocks.empty()) {
+                    throw std::invalid_argument("A BlockStack must contain at least one block");
+                }
+            }
+
+            void serialise(BinaryWriter&) const;
+            static std::shared_ptr<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 = *(*this)[i] <=> *other[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(); }
+            std::shared_ptr<Block> operator[](size_t index) const { return _blocks[index]; };
+    };
+}

amulet/block.pyi

@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+import collections.abc
+import types
+import typing
+
+import amulet.version
+import amulet_nbt
+
+__all__ = ["Block", "BlockStack", "PropertyValueType"]
+
+class Block(amulet.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`
+    >>>     }
+    >>> )
+    """
+
+    @staticmethod
+    def from_bedrock_blockstate(
+        platform: str, version: amulet.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.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, arg0: Block) -> bool: ...
+    @typing.overload
+    def __eq__(self, arg0: typing.Any) -> bool | types.NotImplementedType: ...
+    def __ge__(self, arg0: Block) -> bool: ...
+    def __getstate__(self) -> bytes: ...
+    def __gt__(self, arg0: Block) -> bool: ...
+    def __hash__(self) -> int: ...
+    def __init__(
+        self,
+        platform: str,
+        version: amulet.version.VersionNumber,
+        namespace: str,
+        base_name: str,
+        properties: dict[
+            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: ...
+    def __setstate__(self, arg0: bytes) -> None: ...
+    @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, arg0: typing.Any) -> bool: ...
+    @typing.overload
+    def __eq__(self, arg0: BlockStack) -> bool: ...
+    @typing.overload
+    def __eq__(self, arg0: typing.Any) -> bool | types.NotImplementedType: ...
+    def __ge__(self, arg0: BlockStack) -> bool: ...
+    @typing.overload
+    def __getitem__(self, arg0: int) -> Block: ...
+    @typing.overload
+    def __getitem__(self, arg0: slice) -> list: ...
+    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: typing.Any) -> int: ...
+    def index(
+        self, value: typing.Any, start: int = 0, stop: int = 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:
+        """
+        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
+        """
+
+PropertyValueType: typing.TypeAlias = (
+    amulet_nbt.ByteTag
+    | amulet_nbt.ShortTag
+    | amulet_nbt.IntTag
+    | amulet_nbt.LongTag
+    | amulet_nbt.StringTag
+)

amulet/block_entity.cpp

@@ -0,0 +1,12 @@
+#include <amulet/block_entity.hpp>
+
+namespace Amulet {
+
+	void BlockEntity::serialise(BinaryWriter&) const {
+		throw std::runtime_error("NotImplemented");
+	}
+	std::shared_ptr<BlockEntity> BlockEntity::deserialise(BinaryReader&) {
+		throw std::runtime_error("NotImplemented");
+	}
+
+}

amulet/block_entity.hpp

@@ -0,0 +1,56 @@
+#pragma once
+
+#include <map>
+#include <variant>
+#include <string>
+
+#include <amulet/io/binary_reader.hpp>
+#include <amulet/io/binary_writer.hpp>
+#include <amulet/version.hpp>
+#include <amulet_nbt/tag/named_tag.hpp>
+#include <amulet_nbt/tag/eq.hpp>
+
+
+namespace Amulet {
+    class BlockEntity: public PlatformVersionContainer {
+        private:
+            std::string _namespace;
+            std::string _base_name;
+            std::shared_ptr<AmuletNBT::NamedTag> _nbt;
+            
+        public:
+            const std::string& get_namespace() const { return _namespace; }
+            void set_namespace(const std::string& namespace_) { _namespace = namespace_; }
+            
+            const std::string& get_base_name() const { return _base_name; }
+            void set_base_name(const std::string& base_name) { _base_name = base_name; }
+            
+            std::shared_ptr<AmuletNBT::NamedTag> get_nbt() const { return _nbt; }
+            void set_nbt(std::shared_ptr<AmuletNBT::NamedTag> nbt) { _nbt = nbt; }
+
+            BlockEntity(
+                const PlatformType& platform,
+                std::shared_ptr<VersionNumber> version,
+                const std::string& namespace_,
+                const std::string& base_name,
+                std::shared_ptr<AmuletNBT::NamedTag> nbt
+            ):
+                PlatformVersionContainer(platform, version),
+                _namespace(namespace_),
+                _base_name(base_name),
+                _nbt(nbt)
+            {}
+
+            void serialise(BinaryWriter&) const;
+            static std::shared_ptr<BlockEntity> deserialise(BinaryReader&);
+
+            bool operator==(const BlockEntity& other) const {
+                return (
+                    PlatformVersionContainer::operator==(other) &&
+                    _namespace == other._namespace &&
+                    _base_name == other._base_name &&
+                    AmuletNBT::NBTTag_eq(*_nbt, *other._nbt)
+                );
+            };
+    };
+}

amulet/block_entity.pyi

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import types
+import typing
+
+import amulet.version
+import amulet_nbt
+
+__all__ = ["BlockEntity"]
+
+class BlockEntity(amulet.version.PlatformVersionContainer):
+    """
+    A class to contain all the data to define a BlockEntity.
+    """
+
+    @typing.overload
+    def __eq__(self, arg0: BlockEntity) -> bool: ...
+    @typing.overload
+    def __eq__(self, arg0: typing.Any) -> bool | types.NotImplementedType: ...
+    def __getstate__(self) -> bytes: ...
+    def __hash__(self) -> int: ...
+    def __init__(
+        self,
+        platform: str,
+        version: amulet.version.VersionNumber,
+        namespace: str,
+        base_name: str,
+        nbt: amulet_nbt.NamedTag,
+    ) -> None: ...
+    def __repr__(self) -> str: ...
+    def __setstate__(self, arg0: bytes) -> None: ...
+    @property
+    def base_name(self) -> str:
+        """
+        The base name of the block entity represented by the :class:`BlockEntity` object.
+
+        >>> block_entity: BlockEntity
+        >>> block_entity.base_name
+
+        :return: The base name of the block entity
+        """
+
+    @base_name.setter
+    def base_name(self, arg1: str) -> None: ...
+    @property
+    def namespace(self) -> str:
+        """
+        The namespace of the block entity represented by the :class:`BlockEntity` object.
+
+        >>> block_entity: BlockEntity
+        >>> block_entity.namespace
+
+        :return: The namespace of the block entity
+        """
+
+    @namespace.setter
+    def namespace(self, arg1: str) -> None: ...
+    @property
+    def namespaced_name(self) -> str:
+        """
+        The namespace:base_name of the block entity represented by the :class:`BlockEntity` object.
+
+        >>> block_entity: BlockEntity
+        >>> block_entity.namespaced_name
+
+        :return: The namespace:base_name of the block entity
+        """
+
+    @property
+    def nbt(self) -> amulet_nbt.NamedTag:
+        """
+        The nbt data for the block entity.
+        >>> block_entity: BlockEntity
+        >>> block_entity.nbt
+
+        :return: The NamedTag of the block entity
+        """
+
+    @nbt.setter
+    def nbt(self, arg1: amulet_nbt.NamedTag) -> None: ...

amulet/chunk.cpp

@@ -0,0 +1,16 @@
+#include <string>
+#include <unordered_map>
+#include <optional>
+#include <functional>
+#include <memory>
+
+#include <amulet/chunk.hpp>
+
+namespace Amulet {
+	namespace detail {
+		std::unordered_map<std::string, std::function<std::shared_ptr<Chunk>()>> chunk_constructors;
+	}
+	std::shared_ptr<Chunk> get_null_chunk(std::string chunk_id) {
+		return detail::chunk_constructors.at(chunk_id)();
+	}
+}

amulet/chunk.hpp

@@ -0,0 +1,99 @@
+#pragma once
+
+#include <string>
+#include <unordered_map>
+#include <optional>
+#include <functional>
+#include <memory>
+#include <stdexcept>
+
+// Requirements:
+// Split chunk data into components that are orthogonal to each other.
+// create a chunk with all components default initialised.
+// reconstruct a chunk from a subset of its components.
+// reconstruct a chunk with all components.
+// query if a chunk has a component. (isinstance/is_base_of/dynamic_cast or has_component)
+// get a component. (method/property or get_component)
+// set and validate a component. (method/property or set_component)
+// serialise loaded components.
+
+namespace Amulet {
+	typedef std::unordered_map<std::string, std::optional<std::string>> SerialisedComponents;
+
+    // The abstract chunk class
+	class Chunk {
+	public:
+		virtual ~Chunk() {}
+		virtual std::string get_chunk_id() const = 0;
+		virtual std::vector<std::string> get_component_ids() const = 0;
+	//private:
+	// These are public but may become private one day
+		virtual SerialisedComponents serialise_chunk() const = 0;
+		virtual void reconstruct_chunk(SerialisedComponents) = 0;
+	};
+
+	namespace detail {
+		extern std::unordered_map<std::string, std::function<std::shared_ptr<Chunk>()>> chunk_constructors;
+	}
+
+	std::shared_ptr<Chunk> get_null_chunk(std::string chunk_id);
+
+    // An object that concrete chunk classes must be registered with.
+    // This enables reconstructing the chunk class.
+	template <typename ChunkT>
+	class ChunkNullConstructor {
+	public:
+		ChunkNullConstructor() {
+			if (detail::chunk_constructors.contains(ChunkT::ChunkID)) {
+				throw std::runtime_error("A chunk class has already been registered with ID " + ChunkT::ChunkID);
+			}
+			detail::chunk_constructors[ChunkT::ChunkID] = []() {
+				return std::make_shared<ChunkT>();
+			};
+		};
+		~ChunkNullConstructor() {
+			detail::chunk_constructors.erase(ChunkT::ChunkID);
+		};
+	};
+
+    // A utility class to simplify component serialisation and deserialisation.
+	template <class ChunkBaseClass, class ... Components>
+	class ChunkComponentHelper: public ChunkBaseClass, public Components... {
+	public:
+		// Component list
+		std::vector<std::string> get_component_ids() const override {
+			std::vector<std::string> component_ids;
+			(
+				[&]{
+					component_ids.push_back(Components::ComponentID);
+				}(),
+				...
+			);
+			return component_ids;
+		}
+	// These are public but may become private one day
+		// Null constructor
+		ChunkComponentHelper() : Components()... {}
+	//private:
+		// Serialiser
+		SerialisedComponents serialise_chunk() const override {
+			SerialisedComponents component_data;
+			(
+				[&]{
+					component_data[Components::ComponentID] = Components::serialise();
+				}(),
+				...
+			);
+			return component_data;
+		}
+		// Deserialiser
+		void reconstruct_chunk(SerialisedComponents component_data) override {
+			(
+				[&]{
+					Components::deserialise(component_data.extract(Components::ComponentID).mapped());
+				}(),
+				...
+			);
+		}
+	};
+}

amulet/chunk.pyi

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+__all__ = ["Chunk", "get_null_chunk"]
+
+class Chunk:
+    """
+    A base class for all chunk classes.
+    """
+
+    def __getstate__(self) -> tuple: ...
+    def __setstate__(self, arg0: tuple) -> None: ...
+    def reconstruct_chunk(self, arg0: dict[str, bytes | None]) -> None:
+        """
+        This is private. Do not use this. It will be removed in the future.
+        """
+
+    def serialise_chunk(self) -> dict[str, bytes | None]:
+        """
+        This is private. Do not use this. It will be removed in the future.
+        """
+
+    @property
+    def chunk_id(self) -> str: ...
+    @property
+    def component_ids(self) -> list[str]: ...
+
+def get_null_chunk(arg0: str) -> Chunk:
+    """
+    This is a private function
+    """