Move and rewrite groups.rst from sripting_continued.rst

getting_started/step_by_step/scripting_continued.rst

@@ -2,75 +2,6 @@
 
 Scripting (continued)
 =====================
-
-Groups
-------
-
-Groups in Godot work like tags you might have come across in other software.
-A node can be added to as many groups as desired. This is a useful feature for
-organizing large scenes. There are two ways to add nodes to groups. The
-first is from the UI, using the Groups button under the Node panel:
-
-.. image:: img/groups_in_nodes.png
-
-And the second way is from code. The following script would add the current
-node to the ``enemies`` group as soon as it appeared in the scene tree.
-
-.. tabs::
- .. code-tab:: gdscript GDScript
-
-    func _ready():
-        add_to_group("enemies")
-
- .. code-tab:: csharp
-
-    public override void _Ready()
-    {
-        base._Ready();
-
-        AddToGroup("enemies");
-    }
-
-This way, if the player is discovered sneaking into a secret base,
-all enemies can be notified about its alarm sounding by using
-:ref:`SceneTree.call_group() <class_SceneTree_method_call_group>`:
-
-.. tabs::
- .. code-tab:: gdscript GDScript
-
-    func _on_discovered(): # This is a purely illustrative function.
-        get_tree().call_group("enemies", "player_was_discovered")
-
- .. code-tab:: csharp
-
-    public void _OnDiscovered() // This is a purely illustrative function.
-    {
-        GetTree().CallGroup("enemies", "player_was_discovered");
-    }
-
-The above code calls the function ``player_was_discovered`` on every
-member of the group ``enemies``.
-
-It is also possible to get the full list of ``enemies`` nodes by
-calling
-:ref:`SceneTree.get_nodes_in_group() <class_SceneTree_method_get_nodes_in_group>`:
-
-.. tabs::
- .. code-tab:: gdscript GDScript
-
-    var enemies = get_tree().get_nodes_in_group("enemies")
-
- .. code-tab:: csharp
-
-    var enemies = GetTree().GetNodesInGroup("enemies");
-
-The :ref:`SceneTree <class_SceneTree>` class provides many useful methods,
-like interacting with scenes, their node hierarchy and groups of nodes.
-It allows you to easily switch scenes or reload them,
-to quit the game or pause and unpause it.
-It even comes with interesting signals.
-So check it out if you have some time!
-
 Notifications
 -------------
 

tutorials/scripting/groups.rst

@@ -0,0 +1,124 @@
+.. _doc_groups:
+
+Groups
+======
+
+Groups in Godot work like tags in other software. You can add a node to as many
+groups as you want. Then, in code, you can use the SceneTree to:
+
+- Get a list of nodes in a group.
+- Call a method on all nodes in a group.
+- Send a notification to all nodes in a group.
+
+This is a useful feature to organize large scenes and decouple code.
+
+Adding nodes to a group
+-----------------------
+
+There are two ways to add nodes to groups:
+
+- Using the Node dock in the editor.
+- Calling :ref:`SceneTree.call_group() <class_SceneTree_method_call_group>`.
+
+Using the Node dock
+~~~~~~~~~~~~~~~~~~~
+
+You can add nodes in the current scene to groups using the Groups tab in the
+Node dock.
+
+.. image:: img/groups_node_tab.png
+
+Select one or more nodes in the Scene dock and write the group name in the
+field, then click Add.
+
+.. image:: img/groups_add_node_to_group.png
+
+You should now see the group appear.
+
+.. image:: img/groups_node_after_adding.png
+
+In a complex project, you may end up with many groups or large scenes with many
+nodes. You can add or remove any node to groups using the Group Editor window.
+To access it, click the Manage Groups button.
+
+.. image:: img/groups_manage_groups_button.png
+
+The Group Editor window appears. Here's a screenshot from a complex project to
+illustrate the tool's purpose.
+
+.. image:: img/groups_group_editor_window.png
+
+It has three columns:
+
+1. A list of groups used by nodes in the current scene.
+2. A list of nodes that are not part of the selected group.
+3. A list of nodes in the group.
+
+The fields at the bottom allow you to add new groups or filter nodes in the
+second and third columns.
+
+.. note:: Any node name that's greyed out means the node was added to the group
+          in a different scene and you cannot edit it here. This happens on
+          scene instances in particular.
+
+Using code
+~~~~~~~~~~
+
+You can also manage groups from scripts. The following code adds the node to
+which you attach the script to the ``guards`` group as soon as it entered the
+scene tree.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    func _ready():
+        add_to_group("guards")
+
+ .. code-tab:: csharp
+
+    public override void _Ready()
+    {
+        base._Ready();
+
+        AddToGroup("guards");
+    }
+
+Imagine you're creating a strategy game inspired by Metal Gear Solid. When an
+enemy spots the player, you want all guards and robots to be on alert.
+
+In the fictional example below, we use ``SceneTree.call_group()`` to alert all
+enemies that the player was spotted.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    func _on_Player_spotted():
+        get_tree().call_group("guards", "enter_alert_mode")
+
+ .. code-tab:: csharp
+
+    public void _OnPlayerDiscovered()
+    {
+        GetTree().CallGroup("guards", "enter_alert_mode");
+    }
+
+The above code calls the function ``enter_alert_mode`` on every member of the
+group ``guards``.
+
+To get the full list of nodes in the ``guards`` group as an array, you can call
+:ref:`SceneTree.get_nodes_in_group()
+<class_SceneTree_method_get_nodes_in_group>`:
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    var guards = get_tree().get_nodes_in_group("guards")
+
+ .. code-tab:: csharp
+
+    var guards = GetTree().GetNodesInGroup("guards");
+
+The :ref:`SceneTree <class_SceneTree>` class provides many more useful methods
+to interact with scenes, their node hierarchy, and groups. It allows you to
+switch scenes easily or reload them, quit the game or pause and unpause it. It
+also provides useful signals.

tutorials/scripting/index.rst

@@ -36,6 +36,7 @@ below will help you make the most of Godot.
 
    debug/index
    idle_and_physics_processing
+   groups
    cross_language_scripting
    creating_script_templates
    change_scenes_manually