feat: add DebugShape API

endstone/__init__.pyi

@@ -14,6 +14,7 @@ from . import (
     boss,
     command,
     damage,
+    debug,
     effect,
     enchantments,
     event,
@@ -36,6 +37,7 @@ from .ban import IpBanList, PlayerBanList
 from .block import BlockData
 from .boss import BarColor, BarFlag, BarStyle, BossBar
 from .command import CommandSender, ConsoleCommandSender
+from .debug import DebugArrow, DebugBox, DebugCircle, DebugLine, DebugSphere, DebugText
 from .form import ActionForm, MessageForm, ModalForm
 from .inventory import Inventory, ItemFactory, PlayerInventory
 from .lang import Language, Translatable
@@ -64,6 +66,7 @@ __all__ = [
     "boss",
     "command",
     "damage",
+    "debug",
     "effect",
     "enchantments",
     "event",
@@ -624,6 +627,23 @@ class Player(Mob):
         Sends a packet to the player.
         """
         ...
+    def add_debug_shape(
+        self, location: Location, shape: DebugBox | DebugSphere | DebugCircle | DebugLine | DebugArrow | DebugText
+    ) -> int:
+        """
+        Adds a debug shape visible only to this player.
+        """
+        ...
+    def remove_debug_shape(self, id: int) -> None:
+        """
+        Removes a specific debug shape from this player by its id.
+        """
+        ...
+    def remove_debug_shapes(self) -> None:
+        """
+        Removes all debug shapes visible to this player.
+        """
+        ...
 
 class ColorFormat:
     """

endstone/debug/__init__.py

@@ -0,0 +1,8 @@
+import lazy_loader as lazy
+
+__getattr__, __dir__, __all__ = lazy.attach(
+    "endstone._python",
+    submod_attrs={
+        "debug": ["DebugBox", "DebugSphere", "DebugCircle", "DebugLine", "DebugArrow", "DebugText"],
+    },
+)

endstone/debug/__init__.pyi

@@ -0,0 +1,243 @@
+"""
+Classes relating to debug shape drawing utilities.
+"""
+
+from endstone.util import Vector
+
+__all__ = ["DebugArrow", "DebugBox", "DebugCircle", "DebugLine", "DebugSphere", "DebugText"]
+
+class DebugBox:
+    """
+    Represents a debug box (cuboid) shape.
+    """
+    def __init__(self) -> None: ...
+    @property
+    def color(self) -> tuple[int, ...]:
+        """
+        The color of this shape.
+        """
+        ...
+    @color.setter
+    def color(self, arg1: tuple[int, ...]) -> DebugBox: ...
+    @property
+    def scale(self) -> float:
+        """
+        The uniform scale factor.
+        """
+        ...
+    @scale.setter
+    def scale(self, arg1: float) -> DebugBox: ...
+    @property
+    def rotation(self) -> Vector:
+        """
+        The rotation of this shape as Euler angles (pitch, yaw, roll).
+        """
+        ...
+    @rotation.setter
+    def rotation(self, arg1: Vector) -> DebugBox: ...
+    @property
+    def bound(self) -> Vector:
+        """
+        The bounding size of the box. Final size = bound * scale.
+        """
+        ...
+    @bound.setter
+    def bound(self, arg1: Vector) -> DebugBox: ...
+
+class DebugSphere:
+    """
+    Represents a debug sphere shape. Radius is controlled via scale.
+    """
+    def __init__(self) -> None: ...
+    @property
+    def color(self) -> tuple[int, ...]:
+        """
+        The color of this shape.
+        """
+        ...
+    @color.setter
+    def color(self, arg1: tuple[int, ...]) -> DebugSphere: ...
+    @property
+    def scale(self) -> float:
+        """
+        The uniform scale factor.
+        """
+        ...
+    @scale.setter
+    def scale(self, arg1: float) -> DebugSphere: ...
+    @property
+    def rotation(self) -> Vector:
+        """
+        The rotation of this shape as Euler angles (pitch, yaw, roll).
+        """
+        ...
+    @rotation.setter
+    def rotation(self, arg1: Vector) -> DebugSphere: ...
+
+class DebugCircle:
+    """
+    Represents a debug 2D circle shape. Radius is controlled via scale.
+    """
+    def __init__(self) -> None: ...
+    @property
+    def color(self) -> tuple[int, ...]:
+        """
+        The color of this shape.
+        """
+        ...
+    @color.setter
+    def color(self, arg1: tuple[int, ...]) -> DebugCircle: ...
+    @property
+    def scale(self) -> float:
+        """
+        The uniform scale factor.
+        """
+        ...
+    @scale.setter
+    def scale(self, arg1: float) -> DebugCircle: ...
+    @property
+    def rotation(self) -> Vector:
+        """
+        The rotation of this shape as Euler angles (pitch, yaw, roll).
+        """
+        ...
+    @rotation.setter
+    def rotation(self, arg1: Vector) -> DebugCircle: ...
+
+class DebugLine:
+    """
+    Represents a debug line segment shape.
+    """
+    def __init__(self) -> None: ...
+    @property
+    def color(self) -> tuple[int, ...]:
+        """
+        The color of this shape.
+        """
+        ...
+    @color.setter
+    def color(self, arg1: tuple[int, ...]) -> DebugLine: ...
+    @property
+    def scale(self) -> float:
+        """
+        The uniform scale factor.
+        """
+        ...
+    @scale.setter
+    def scale(self, arg1: float) -> DebugLine: ...
+    @property
+    def rotation(self) -> Vector:
+        """
+        The rotation of this shape as Euler angles (pitch, yaw, roll).
+        """
+        ...
+    @rotation.setter
+    def rotation(self, arg1: Vector) -> DebugLine: ...
+    @property
+    def length(self) -> float:
+        """
+        The length of the line segment.
+        """
+        ...
+    @length.setter
+    def length(self, arg1: float) -> DebugLine: ...
+
+class DebugArrow:
+    """
+    Represents a debug arrow shape.
+    """
+    def __init__(self) -> None: ...
+    @property
+    def color(self) -> tuple[int, ...]:
+        """
+        The color of this shape.
+        """
+        ...
+    @color.setter
+    def color(self, arg1: tuple[int, ...]) -> DebugArrow: ...
+    @property
+    def scale(self) -> float:
+        """
+        The uniform scale factor.
+        """
+        ...
+    @scale.setter
+    def scale(self, arg1: float) -> DebugArrow: ...
+    @property
+    def rotation(self) -> Vector:
+        """
+        The rotation of this shape as Euler angles (pitch, yaw, roll).
+        """
+        ...
+    @rotation.setter
+    def rotation(self, arg1: Vector) -> DebugArrow: ...
+    @property
+    def length(self) -> float:
+        """
+        The length of the arrow.
+        """
+        ...
+    @length.setter
+    def length(self, arg1: float) -> DebugArrow: ...
+    @property
+    def head_length(self) -> float:
+        """
+        The length of the arrow's head.
+        """
+        ...
+    @head_length.setter
+    def head_length(self, arg1: float) -> DebugArrow: ...
+    @property
+    def head_radius(self) -> float:
+        """
+        The radius of the arrow's head.
+        """
+        ...
+    @head_radius.setter
+    def head_radius(self, arg1: float) -> DebugArrow: ...
+    @property
+    def head_segments(self) -> int:
+        """
+        The number of segments for the arrow head's base circle.
+        """
+        ...
+    @head_segments.setter
+    def head_segments(self, arg1: int) -> DebugArrow: ...
+
+class DebugText:
+    """
+    Represents a debug billboard text label.
+    """
+    def __init__(self) -> None: ...
+    @property
+    def color(self) -> tuple[int, ...]:
+        """
+        The color of this shape.
+        """
+        ...
+    @color.setter
+    def color(self, arg1: tuple[int, ...]) -> DebugText: ...
+    @property
+    def scale(self) -> float:
+        """
+        The uniform scale factor.
+        """
+        ...
+    @scale.setter
+    def scale(self, arg1: float) -> DebugText: ...
+    @property
+    def rotation(self) -> Vector:
+        """
+        The rotation of this shape as Euler angles (pitch, yaw, roll).
+        """
+        ...
+    @rotation.setter
+    def rotation(self, arg1: Vector) -> DebugText: ...
+    @property
+    def text(self) -> str:
+        """
+        The text displayed by this label.
+        """
+        ...
+    @text.setter
+    def text(self, arg1: str) -> DebugText: ...

include/endstone/debug/shape.h

@@ -0,0 +1,30 @@
+// 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 <variant>
+
+#include "endstone/debug/shape/arrow.h"
+#include "endstone/debug/shape/box.h"
+#include "endstone/debug/shape/circle.h"
+#include "endstone/debug/shape/line.h"
+#include "endstone/debug/shape/sphere.h"
+#include "endstone/debug/shape/text.h"
+
+namespace endstone {
+
+using DebugShapeVariant = std::variant<DebugBox, DebugSphere, DebugCircle, DebugLine, DebugArrow, DebugText>;
+
+}  // namespace endstone