feat: add APIs for debug shape

docs/reference/python/debug_shape.md

@@ -0,0 +1 @@
+::: endstone.debug_shape

endstone/debugshape.py

@@ -0,0 +1,17 @@
+from endstone._internal.endstone_python import (
+    DebugArrow,
+    DebugBox,
+    DebugCircle,
+    DebugLine,
+    DebugSphere,
+    DebugText,
+)
+
+__all__ = [
+    "DebugArrow",
+    "DebugBox",
+    "DebugCircle",
+    "DebugLine",
+    "DebugSphere",
+    "DebugText",
+]

include/endstone/debugshape/debug_arrow.h

@@ -0,0 +1,149 @@
+// Copyright (c) 2024, The Endstone Project. (https://endstone.dev) All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include "endstone/debugshape/debug_shape.h"
+
+namespace endstone {
+
+/**
+ * @brief Represents a debug arrow.
+ */
+class DebugArrow : public DebugShape<DebugArrow> {
+public:
+    /**
+     * @brief Gets the end position of the arrow.
+     *
+     * @return The end position of the arrow.
+     */
+    [[nodiscard]] std::optional<Vector<float>> getEndPosition() const
+    {
+        return end_position_;
+    }
+
+    /**
+     * @brief Sets the end position of the arrow.
+     *
+     * @param end_position The desired end position of the arrow
+     * @return A reference to the current debug shape.
+     */
+    DebugArrow &setEndPosition(const std::optional<Vector<float>> end_position)
+    {
+        end_position_ = end_position;
+        onChange();
+        return *this;
+    }
+
+    /**
+     * @brief Gets the length of the arrowhead.
+     *
+     * @return The arrowhead length.
+     */
+    [[nodiscard]] std::optional<float> getArrowHeadLength() const
+    {
+        return arrow_head_length_;
+    }
+
+    /**
+     * @brief Sets the length of the arrowhead.
+     *
+     * @param arrow_head_length The desired length of the arrowhead.
+     * @return A reference to the current debug shape.
+     */
+    DebugArrow &setArrowHeadLength(const std::optional<float> arrow_head_length)
+    {
+        arrow_head_length_ = arrow_head_length;
+        onChange();
+        return *this;
+    }
+
+    /**
+     * @brief Gets the radius of the arrowhead.
+     *
+     * @return The arrowhead radius.
+     */
+    [[nodiscard]] std::optional<float> getArrowHeadRadius() const
+    {
+        return arrow_head_radius_;
+    }
+
+    /**
+     * @brief Sets the radius of the arrowhead.
+     *
+     * @param arrow_head_radius The desired radius of the arrowhead.
+     * @return A reference to the current debug shape.
+     */
+    DebugArrow &setArrowHeadRadius(const std::optional<float> arrow_head_radius)
+    {
+        arrow_head_radius_ = arrow_head_radius;
+        onChange();
+        return *this;
+    }
+
+    /**
+     * @brief Gets the number of segments used to render the arrowhead.
+     *
+     * @return The number of arrowhead segments.
+     */
+    [[nodiscard]] std::optional<std::uint8_t> getArrowHeadSegments() const
+    {
+        return arrow_head_segments_;
+    }
+
+    /**
+     * @brief Sets the number of segments used to render the arrowhead.
+     *
+     * @param arrow_head_segments The desired number of segments.
+     * @return A reference to the current debug shape.
+     */
+    DebugArrow &setArrowHeadSegments(const std::optional<std::uint8_t> arrow_head_segments)
+    {
+        arrow_head_segments_ = arrow_head_segments;
+        onChange();
+        return *this;
+    }
+
+    /**
+     * @brief Gets the scale of the arrowhead.
+     *
+     * @return The arrowhead scale.
+     */
+    [[nodiscard]] std::optional<float> getArrowHeadScale() const
+    {
+        return arrow_head_scale_;
+    }
+
+    /**
+     * @brief Sets the scale of the arrowhead.
+     *
+     * @param arrow_head_scale The desired scale of the arrowhead.
+     * @return A reference to the current debug shape.
+     */
+    DebugArrow &setArrowHeadScale(const std::optional<float> arrow_head_scale)
+    {
+        arrow_head_scale_ = arrow_head_scale;
+        onChange();
+        return *this;
+    }
+
+private:
+    std::optional<Vector<float>> end_position_;
+    std::optional<float> arrow_head_length_;
+    std::optional<float> arrow_head_radius_;
+    std::optional<std::uint8_t> arrow_head_segments_;
+    std::optional<float> arrow_head_scale_;
+};
+
+}  // namespace endstone

include/endstone/debugshape/debug_box.h

@@ -0,0 +1,77 @@
+// Copyright (c) 2024, The Endstone Project. (https://endstone.dev) All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include "endstone/debugshape/debug_shape.h"
+
+namespace endstone {
+
+/**
+ * @brief Represents a debug box.
+ */
+class DebugBox : public DebugShape<DebugBox> {
+public:
+    /**
+     * @brief Gets the scale of the box.
+     *
+     * @return The scale of the box.
+     */
+    [[nodiscard]] std::optional<float> getScale() const
+    {
+        return scale_;
+    }
+
+    /**
+     * @brief Sets the scale of the box.
+     *
+     * @param scale The desired scale of the box.
+     * @return A reference to the current debug shape.
+     */
+    DebugBox &setScale(const std::optional<float> scale)
+    {
+        scale_ = scale;
+        onChange();
+        return *this;
+    }
+
+    /**
+     * @brief Gets the bounds of the box.
+     *
+     * @return The bounds of the box.
+     */
+    [[nodiscard]] std::optional<Vector<float>> getBoxBounds() const
+    {
+        return box_bounds_;
+    }
+
+    /**
+     * @brief Sets the bounds of the box.
+     *
+     * @param box_bounds The desired bounds of the box.
+     * @return A reference to the current debug shape.
+     */
+    DebugBox &setBoxBounds(const std::optional<Vector<float>> box_bounds)
+    {
+        box_bounds_ = box_bounds;
+        onChange();
+        return *this;
+    }
+
+private:
+    std::optional<float> scale_;
+    std::optional<Vector<float>> box_bounds_;
+};
+
+}  // namespace endstone

include/endstone/debugshape/debug_circle.h

@@ -0,0 +1,78 @@
+// Copyright (c) 2024, The Endstone Project. (https://endstone.dev) All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include "endstone/debugshape/debug_shape.h"
+
+namespace endstone {
+
+
+/**
+ * @brief Represents a debug circle.
+ */
+class DebugCircle : public DebugShape<DebugCircle> {
+public:
+    /**
+     * @brief Gets the scale of the circle.
+     *
+     * @return The scale of the circle.
+     */
+    [[nodiscard]] std::optional<float> getScale() const
+    {
+        return scale_;
+    }
+
+    /**
+     * @brief Sets the scale of the circle.
+     *
+     * @param scale The desired scale of the circle.
+     * @return A reference to the current debug shape.
+     */
+    DebugCircle &setScale(const std::optional<float> scale)
+    {
+        scale_ = scale;
+        onChange();
+        return *this;
+    }
+
+    /**
+     * @brief Gets the number of segments used to render the circle.
+     *
+     * @return The number of circle segments.
+     */
+    [[nodiscard]] std::optional<std::uint8_t> getSegments() const
+    {
+        return segments_;
+    }
+
+    /**
+     * @brief Sets the number of segments used to render the circle.
+     *
+     * @param segments The desired number of segments.
+     * @return A reference to the current debug shape.
+     */
+    DebugCircle &setSegments(const std::optional<std::uint8_t> segments)
+    {
+        segments_ = segments;
+        onChange();
+        return *this;
+    }
+
+private:
+    std::optional<float> scale_;
+    std::optional<std::uint8_t> segments_;
+};
+
+}  // namespace endstone

include/endstone/debugshape/debug_line.h

@@ -0,0 +1,53 @@
+// Copyright (c) 2024, The Endstone Project. (https://endstone.dev) All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include "endstone/debugshape/debug_shape.h"
+
+namespace endstone {
+
+/**
+ * @brief Represents a debug line.
+ */
+class DebugLine : public DebugShape<DebugLine> {
+public:
+    /**
+     * @brief Gets the end position of the line.
+     *
+     * @return The end position of the line.
+     */
+    [[nodiscard]] std::optional<Vector<float>> getEndPosition() const
+    {
+        return end_position_;
+    }
+
+    /**
+     * @brief Sets the end position of the line.
+     *
+     * @param end_position The desired end position of the line
+     * @return A reference to the current debug shape.
+     */
+    DebugLine &setEndPosition(const std::optional<Vector<float>> end_position)
+    {
+        end_position_ = end_position;
+        onChange();
+        return *this;
+    }
+
+private:
+    std::optional<Vector<float>> end_position_;
+};
+
+}  // namespace endstone