feat(block): introduce Block::captureState method for capturing the c…

…urrent block state

include/endstone/block/block.h

@@ -23,6 +23,8 @@
 
 namespace endstone {
 
+class BlockState;
+
 class Dimension;
 
 /**
@@ -156,6 +158,16 @@ class Block {
      * @return Location of block
      */
     [[nodiscard]] virtual Location getLocation() const = 0;
+
+    /**
+     * Captures the current state of this block.
+     * <p>
+     * The returned object will never be updated, and you are not guaranteed that (for example) a sign is still a
+     * sign after you capture its state.
+     *
+     * @return BlockState with the current state of this block.
+     */
+    [[nodiscard]] virtual std::shared_ptr<BlockState> captureState() const = 0;
 };
 
 }  // namespace endstone

include/endstone/detail/block/block.h

@@ -37,6 +37,7 @@ class EndstoneBlock : public Block {
     [[nodiscard]] int getY() const override;
     [[nodiscard]] int getZ() const override;
     [[nodiscard]] Location getLocation() const override;
+    [[nodiscard]] std::shared_ptr<BlockState> captureState() const override;
 
     [[nodiscard]] BlockPos getPosition() const;
     [[nodiscard]] ::Block &getMinecraftBlock() const;

python/src/endstone/_internal/endstone_python.pyi

@@ -319,6 +319,10 @@ class Block:
     """
     def __str__(self) -> str:
         ...
+    def capture_state(self) -> BlockState:
+        """
+        Captures the current state of this block. The returned object will never be updated, and you are not guaranteed that (for example) a sign is still a sign after you capture its state.
+        """
     @typing.overload
     def get_relative(self, offset_x: int, offset_y: int, offset_z: int) -> Block:
         """

src/endstone_core/block/block.cpp

@@ -14,6 +14,8 @@
 
 #include "endstone/detail/block/block.h"
 
+#include <endstone/detail/block/block_state.h>
+
 #include "bedrock/world/level/dimension/dimension.h"
 #include "bedrock/world/level/level.h"
 #include "endstone/detail/block/block_data.h"
@@ -140,6 +142,11 @@ Location EndstoneBlock::getLocation() const
     return {&getDimension(), getX(), getY(), getZ()};
 }
 
+std::shared_ptr<BlockState> EndstoneBlock::captureState() const
+{
+    return std::make_shared<EndstoneBlockState>(*this);
+}
+
 BlockPos EndstoneBlock::getPosition() const
 {
     return block_pos_;

src/endstone_python/block.cpp

@@ -78,6 +78,9 @@ void init_block(py::module_ &m, py::class_<Block> &block)
         .def_property_readonly("y", &Block::getY, "Gets the y-coordinate of this block")
         .def_property_readonly("z", &Block::getZ, "Gets the z-coordinate of this block")
         .def_property_readonly("location", &Block::getLocation, "Gets the Location of the block")
+        .def("capture_state", &Block::captureState,
+             "Captures the current state of this block. The returned object will never be updated, and you are not "
+             "guaranteed that (for example) a sign is still a sign after you capture its state.")
         .def("__str__", [](const Block &self) { return fmt::format("{}", self); });
 }