From 99284482bccfc3a37736092be1d4b69baa43064d Mon Sep 17 00:00:00 2001
From: SysError99 <syserror99@outlook.com>
Date: Thu, 25 Jan 2024 00:05:19 +0700
Subject: [PATCH] [3.x] Add `SceneTree::get_first_node_in_group` following 4.x

---
 doc/classes/SceneTree.xml |  7 +++++++
 scene/main/scene_tree.cpp | 16 ++++++++++++++++
 scene/main/scene_tree.h   |  1 +
 3 files changed, 24 insertions(+)

diff --git a/doc/classes/SceneTree.xml b/doc/classes/SceneTree.xml
index 8b4e8becb34..e1da3977307 100644
--- a/doc/classes/SceneTree.xml
+++ b/doc/classes/SceneTree.xml
@@ -80,6 +80,13 @@
 				Creates and returns a new [SceneTreeTween].
 			</description>
 		</method>
+		<method name="get_first_node_in_group">
+			<return type="Node" />
+			<argument index="0" name="group" type="String" />
+			<description>
+				Returns the first node in the specified group, or [code]null[/code] if the group is empty or does not exist.
+			</description>
+		</method>
 		<method name="get_frame" qualifiers="const">
 			<return type="int" />
 			<description>
diff --git a/scene/main/scene_tree.cpp b/scene/main/scene_tree.cpp
index ca098afd2d5..e583180c297 100644
--- a/scene/main/scene_tree.cpp
+++ b/scene/main/scene_tree.cpp
@@ -1230,6 +1230,21 @@ Array SceneTree::_get_nodes_in_group(const StringName &p_group) {
 	return ret;
 }
 
+Node *SceneTree::_get_first_node_in_group(const StringName &p_group) {
+	Map<StringName, Group>::Element *E = group_map.find(p_group);
+	if (!E) {
+		return nullptr; // No group.
+	}
+
+	_update_group_order(E->get()); // Update order just in case.
+
+	if (E->get().nodes.empty()) {
+		return nullptr;
+	}
+
+	return E->get().nodes[0];
+}
+
 bool SceneTree::has_group(const StringName &p_identifier) const {
 	return group_map.has(p_identifier);
 }
@@ -2093,6 +2108,7 @@ void SceneTree::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("set_group", "group", "property", "value"), &SceneTree::set_group);
 
 	ClassDB::bind_method(D_METHOD("get_nodes_in_group", "group"), &SceneTree::_get_nodes_in_group);
+	ClassDB::bind_method(D_METHOD("get_first_node_in_group", "group"), &SceneTree::_get_first_node_in_group);
 
 	ClassDB::bind_method(D_METHOD("set_current_scene", "child_node"), &SceneTree::set_current_scene);
 	ClassDB::bind_method(D_METHOD("get_current_scene"), &SceneTree::get_current_scene);
diff --git a/scene/main/scene_tree.h b/scene/main/scene_tree.h
index ef8e6ccad40..292cdf23ec2 100644
--- a/scene/main/scene_tree.h
+++ b/scene/main/scene_tree.h
@@ -177,6 +177,7 @@ private:
 	_FORCE_INLINE_ void _update_group_order(Group &g, bool p_use_priority = false);
 
 	Array _get_nodes_in_group(const StringName &p_group);
+	Node *_get_first_node_in_group(const StringName &p_group);
 
 	Node *current_scene;