From 191576f6a3590fb8e2c65477bd33d20524852fb9 Mon Sep 17 00:00:00 2001
From: lL1l1 <82986251+lL1l1@users.noreply.github.com>
Date: Wed, 13 Nov 2024 00:30:08 -0800
Subject: [PATCH] Add a sim utility function to draw bones (#6477)

In particular useful to debug collision beams.
---
 changelog/snippets/other.6477.md |  1 +
 engine/Sim/Entity.lua            |  9 ++++-----
 lua/SimUtils.lua                 | 25 +++++++++++++++++++++++++
 3 files changed, 30 insertions(+), 5 deletions(-)
 create mode 100644 changelog/snippets/other.6477.md

diff --git a/changelog/snippets/other.6477.md b/changelog/snippets/other.6477.md
new file mode 100644
index 0000000000..32bce33621
--- /dev/null
+++ b/changelog/snippets/other.6477.md
@@ -0,0 +1 @@
+- (#6477) Add the function `DrawBone(entity, bone, length)` to `SimUtils.lua`.
diff --git a/engine/Sim/Entity.lua b/engine/Sim/Entity.lua
index 40dfa49c25..978a9abffc 100644
--- a/engine/Sim/Entity.lua
+++ b/engine/Sim/Entity.lua
@@ -171,12 +171,11 @@ end
 function Entity:GetBoneCount()
 end
 
---- Returns separate three numbers representing the roll, pitch, yaw of the bone
----@see EulerToQuaternion(roll, pitch, yaw) if you need a quaternion instead
+--- Returns three separate numbers representing the X, Y, Z direction vector of the bone
 ---@param bone Bone
----@return number roll
----@return number pitch
----@return number yaw
+---@return number x
+---@return number y
+---@return number z
 function Entity:GetBoneDirection(bone)
 end
 
diff --git a/lua/SimUtils.lua b/lua/SimUtils.lua
index 558206ece8..66d92f082b 100644
--- a/lua/SimUtils.lua
+++ b/lua/SimUtils.lua
@@ -767,3 +767,28 @@ function OnAllianceResult(resultData)
 end
 
 import("/lua/simplayerquery.lua").AddResultListener("OfferAlliance", OnAllianceResult)
+
+local vectorCross = import('/lua/utilities.lua').Cross
+local upVector = Vector(0, 1, 0)
+
+--- Draw XYZ axes of an entity's bone for one tick
+---@param entity moho.entity_methods
+---@param bone Bone
+---@param length number? # length of axes, defaults to 0.2
+function DrawBone(entity, bone, length)
+    if not length then length = 0.2 end
+
+    local pos = entity:GetPosition(bone)
+    local dirX, dirY, dirZ = entity:GetBoneDirection(bone)
+
+    local forward = Vector(dirX, dirY, dirZ)
+    local left = vectorCross(upVector, forward)
+    local up = vectorCross(forward, left)
+
+    -- X axis
+    DrawLine(pos, pos + left * length, 'FF0000')
+    -- Y axis
+    DrawLine(pos, pos + up * length, '00ff00')
+    -- Z axis
+    DrawLine(pos, pos + forward * length, '0000ff')
+end