From 4d490eef6c7a027eb9924ddf454e6f8e9625ade9 Mon Sep 17 00:00:00 2001
From: Ryan Kegel <ryan.kegel@gmail.com>
Date: Tue, 25 Aug 2026 08:47:16 -0400
Subject: [PATCH] feat: Refactor head transformation logic and update driver
 paths for pivot integration

---
 master_rig.tscn            | 18 ++++++++++--------
 scripts/stickman_rig.gd    | 16 ++++++++++------
 scripts/stk_rig_adapter.gd |  4 ++--
 3 files changed, 22 insertions(+), 16 deletions(-)

diff --git a/master_rig.tscn b/master_rig.tscn
index 8c0417b..ddbd2d6 100644
--- a/master_rig.tscn
+++ b/master_rig.tscn
@@ -342,9 +342,9 @@ width = 16.0
 default_color = Color(0.445488, 0.445488, 0.445488, 1)
 
 [node name="Head" type="Node2D" parent="Body" unique_id=864822355]
-position = Vector2(28.397142, -447.61594)
-rotation = 0.40666866
-scale = Vector2(0.9999996, 0.9999996)
+position = Vector2(28.397173, -447.61597)
+rotation = 0.4066687
+scale = Vector2(0.9999997, 0.9999997)
 script = SubResource("GDScript_f0s26")
 
 [node name="Skeleton2D" type="Skeleton2D" parent="." unique_id=1854735445]
@@ -365,15 +365,17 @@ length = 90.0
 bone_angle = -90.0
 metadata/_local_pose_override_enabled_ = true
 
-[node name="RemoteTransform2D" type="RemoteTransform2D" parent="Skeleton2D/Torso/Head" unique_id=396112729]
-position = Vector2(0.050337255, -72.00002)
-remote_path = NodePath("../../../../Body/Head")
-update_scale = false
-
 [node name="RayCast_Aim" type="RayCast2D" parent="Skeleton2D/Torso/Head" unique_id=2000000004]
 position = Vector2(0, -90)
 target_position = Vector2(500, 0)
 
+[node name="Pivot" type="Node2D" parent="Skeleton2D/Torso/Head" unique_id=780672247]
+
+[node name="RemoteTransform2D" type="RemoteTransform2D" parent="Skeleton2D/Torso/Head/Pivot" unique_id=396112729]
+position = Vector2(0.050354004, -72.00006)
+remote_path = NodePath("../../../../../Body/Head")
+update_scale = false
+
 [node name="LeftUpperArm" type="Bone2D" parent="Skeleton2D/Torso" unique_id=1840957808]
 position = Vector2(0, -248)
 rotation = 0.047700156
diff --git a/scripts/stickman_rig.gd b/scripts/stickman_rig.gd
index b6ad47c..36cbd9e 100644
--- a/scripts/stickman_rig.gd
+++ b/scripts/stickman_rig.gd
@@ -271,13 +271,17 @@ func _apply_profile() -> void:
 	facing_profile_changed.emit(int(facing_profile))
 
 func _apply_head_flip() -> void:
-	if _body_container == null:
-		return
-	var head := _body_container.get_node_or_null("Head") as Node2D
-	if head != null:
+	var head := get_node_or_null("Skeleton2D/Torso/Head") as Node2D
+	var pivot := get_node_or_null("Skeleton2D/Torso/Head/Pivot") as Node2D
+	if pivot != null:
 		var is_left := (facing_profile == FacingProfile.LEFT)
-		# Keep local X positive (neck upright), invert local Y (mirror brim & face)
-		head.scale = Vector2(1.0, -1.0) if is_left else Vector2(1.0, 1.0)
+		if is_left:
+			# Mirror local X and invert double the bone's rotation to mirror in world space
+			pivot.scale = Vector2(-1.0, 1.0)
+			pivot.rotation = -1.0 * head.rotation
+		else:
+			pivot.scale = Vector2(1.0, 1.0)
+			pivot.rotation = 0.0
 
 ## Per-joint setter notify: updates the resolved TwoBoneIK mod's
 ## flip_bend_direction and emits bend_flag_changed. No-op before _ready (the
diff --git a/scripts/stk_rig_adapter.gd b/scripts/stk_rig_adapter.gd
index bf9d13a..6276e67 100644
--- a/scripts/stk_rig_adapter.gd
+++ b/scripts/stk_rig_adapter.gd
@@ -71,7 +71,7 @@ const BODY_PATHS: Dictionary = {
 ## its bone; its `global_rotation` is the bone frame used (Phase 9 Round 5) to
 ## convert the master-space guide_offset into a bone-relative placement.
 const DRIVER_PATHS: Dictionary = {
-	"head": "Skeleton2D/Torso/Head/RemoteTransform2D",
+	"head": "Skeleton2D/Torso/Head/Pivot/RemoteTransform2D",
 	"torso": "Skeleton2D/Torso/RemoteTransform2D",
 	"left_upper_arm": "Skeleton2D/Torso/LeftUpperArm/RemoteTransform2D",
 	"left_lower_arm": "Skeleton2D/Torso/LeftUpperArm/LeftLowerArm/RemoteTransform2D",
@@ -89,7 +89,7 @@ const IK_LEFT_LEG := "IK_Targets/Left_Leg"
 const IK_RIGHT_LEG := "IK_Targets/Right_Leg"
 
 const HEAD_BONE_PATH := "Skeleton2D/Torso/Head"
-const HEAD_DRIVER_PATH := "Skeleton2D/Torso/Head/RemoteTransform2D"
+const HEAD_DRIVER_PATH := "Skeleton2D/Torso/Head/Pivot/RemoteTransform2D"
 
 # ---------------------------------------------------------------------------
 # Public API