Step by step: Improve flow and clarity for code replacement instructions

getting_started/step_by_step/scripting_first_script.rst

@@ -41,8 +41,8 @@ click the Other Node button.
 
 .. image:: img/scripting_first_script_click_other_node.png
 
-Type "Sprite2D" in the search bar to filter nodes and double-click on Sprite2D to
-create the node.
+Type "Sprite2D" in the search bar to filter nodes and double-click on Sprite2D
+to create the node.
 
 .. image:: img/scripting_first_script_add_sprite_node.png
 
@@ -50,16 +50,17 @@ Your Scene tab should now only have a Sprite2D node.
 
 .. image:: img/scripting_first_script_scene_tree.png
 
-A Sprite2D node needs a texture to display. In the Inspector on the right, you can
-see that the Texture property says "[empty]". To display the Godot icon, click
-and drag the file ``icon.png`` from the FileSystem dock onto the Texture slot.
+A Sprite2D node needs a texture to display. In the Inspector on the right, you
+can see that the Texture property says "[empty]". To display the Godot icon,
+click and drag the file ``icon.png`` from the FileSystem dock onto the Texture
+slot.
 
 .. image:: img/scripting_first_script_setting_texture.png
 
 .. note::
 
-    You can create Sprite2D nodes automatically by dragging and dropping images on
-    the viewport.
+    You can create Sprite2D nodes automatically by dragging and dropping images
+    on the viewport.
 
     .. image:: img/scripting_first_script_dragging_sprite.png
 
@@ -75,7 +76,7 @@ scene dock and select "Attach Script".
 
 .. image:: img/scripting_first_script_attach_script.png
 
-The Attach node Script window appears. It allows you to select the script's
+The Attach Node Script window appears. It allows you to select the script's
 language and file path, among other options.
 
 Change the Template from Default to Empty to start with a clean file. Leave the
@@ -83,8 +84,8 @@ other options by default and click the Create button to create the script.
 
 .. image:: img/scripting_first_script_attach_node_script.png
 
-The Script workspace should appear with your new file open and the following
-line of code:
+The Script workspace should appear with your new ``Sprite2D.gd`` file open and
+the following line of code:
 
 .. tabs::
  .. code-tab:: gdscript GDScript
@@ -207,8 +208,8 @@ instructions.
 
 The line inside the function, ``rotation += angular_speed * delta``, increments
 our sprite's rotation every frame. Here, ``rotation`` is a property inherited
-from the class ``Node2D``, which ``Sprite2D`` extends. It controls the rotation of
-our node and works with radians.
+from the class ``Node2D``, which ``Sprite2D`` extends. It controls the rotation
+of our node and works with radians.
 
 .. tip:: In the code editor, you can ctrl-click on any built-in property or
          function like ``position``, ``rotation``, or ``_process`` to open the
@@ -229,6 +230,7 @@ them.
  .. code-tab:: gdscript GDScript
 
     var velocity = Vector2.UP.rotated(rotation) * speed
+
     position += velocity * delta
 
 As we already saw, the ``var`` keyword defines a new variable. If you put it at
@@ -254,4 +256,26 @@ Run the scene to see the Godot head run in circles.
           walls or the floor. In :ref:`doc_your_first_2d_game`, you will learn
           another approach to moving objects while detecting collisions.
 
-Our node currently moves by itself. In the next part, we'll use player input to control it.
+Our node currently moves by itself. In the next part
+:ref:`doc_scripting_player_input`, we'll use player input to control it.
+
+Complete script
+---------------
+
+Here is the complete ``Sprite2D.gd`` file for reference.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    extends Sprite2D
+
+    var speed = 400
+    var angular_speed = PI
+
+
+    func _process(delta):
+        rotation += angular_speed * delta
+
+        var velocity = Vector2.UP.rotated(rotation) * speed
+
+        position += velocity * delta

getting_started/step_by_step/scripting_player_input.rst

@@ -7,8 +7,9 @@
 Listening to player input
 =========================
 
-Building upon the previous lesson, let's look at another important feature of
-any game: giving control to the player. To add this, we need to modify our code.
+Building upon the previous lesson :ref:`doc_scripting_first_script`, let's look
+at another important feature of any game: giving control to the player.
+To add this, we need to modify our ``Sprite2D.gd`` code.
 
 .. image:: img/scripting_first_script_moving_with_input.gif
 
@@ -26,21 +27,20 @@ You have two main tools to process the player's input in Godot:
 We're going to use the ``Input`` singleton here as we need to know if the player
 wants to turn or move every frame.
 
-For turning, we should use a new variable: ``direction``. Update the top of the
-``_process()`` function like so, up to the line where we increment the sprite's
-``rotation``.
+For turning, we should use a new variable: ``direction``. In our ``_process()``
+function, replace the ``rotation += angular_speed * delta`` line with the
+code below.
 
 .. tabs::
  .. code-tab:: gdscript GDScript
 
-    func _process(delta):
-        var direction = 0
-        if Input.is_action_pressed("ui_left"):
-            direction = -1
-        if Input.is_action_pressed("ui_right"):
-            direction = 1
+    var direction = 0
+    if Input.is_action_pressed("ui_left"):
+        direction = -1
+    if Input.is_action_pressed("ui_right"):
+        direction = 1
 
-        rotation += angular_speed * direction * delta
+    rotation += angular_speed * direction * delta
 
 Our ``direction`` local variable is a multiplier representing the direction in
 which the player wants to turn. A value of ``0`` means the player isn't pressing
@@ -81,14 +81,15 @@ velocity. Replace the line starting with ``var velocity`` with the code below.
     if Input.is_action_pressed("ui_up"):
         velocity = Vector2.UP.rotated(rotation) * speed
 
-    position += velocity * delta
-
 We initialize the ``velocity`` with a value of ``Vector2.ZERO``, another
 constant of the built-in ``Vector`` type representing a 2D vector of length 0.
 
 If the player presses the "ui_up" action, we then update the velocity's value,
 causing the sprite to move forward.
 
+Complete script
+---------------
+
 Here is the complete ``Sprite2D.gd`` file for reference.
 
 .. tabs::
@@ -140,5 +141,5 @@ button presses from the users. There are quite a few more.
 The ``Input`` singleton allows you to react to the players' input anywhere in
 your code. In particular, you'll get to use it in the ``_process()`` loop.
 
-In the next lesson, we'll build upon the relationship between scripts and nodes
-by having our nodes trigger code in scripts.
+In the next lesson :ref:`doc_signals`, we'll build upon the relationship between
+scripts and nodes by having our nodes trigger code in scripts.

getting_started/step_by_step/signals.rst

@@ -8,7 +8,7 @@
 
 .. _doc_signals:
 
-Using Signals
+Using signals
 =============
 
 In this lesson, we will look at signals. They are messages that nodes emit when
@@ -29,14 +29,18 @@ the bar to reflect the change. To do so, in Godot, you would use signals.
           observer pattern. You can learn more about it here:
           https://gameprogrammingpatterns.com/observer.html
 
-We will now use a signal to make our Godot icon from last part move and stop
-by pressing a button.
+We will now use a signal to make our Godot icon from the previous lesson
+(:ref:`doc_scripting_player_input`) move and stop by pressing a button.
 
 .. Example
 
 Scene setup
 -----------
 
+To add a button to our game, we will create a new main scene which will include
+both a button and the ``Sprite2D.tscn`` scene that we scripted in previous
+lessons.
+
 Create a new scene by going to the menu Scene -> New Scene.
 
 .. image:: img/signals_01_new_scene.png
@@ -46,14 +50,13 @@ root.
 
 .. image:: img/signals_02_2d_scene.png
 
-
 In the FileSystem dock, click and drag the ``Sprite2D.tscn`` file you saved
 previously onto the Node2D to instantiate it.
 
 .. image:: img/signals_03_dragging_scene.png
 
-We want to add another node as a sibling of the Sprite2D. To do so, right-click on
-Node2D and select Add Child Node.
+We want to add another node as a sibling of the Sprite2D. To do so, right-click
+on Node2D and select Add Child Node.
 
 .. image:: img/signals_04_add_child_node.png
 
@@ -81,12 +84,15 @@ Your scene tree and viewport should look like this.
 
 .. image:: img/signals_09_scene_setup.png
 
+Save your newly created scene. You can then run it with :kbd:`F6`.
+
 Connecting a signal in the editor
 ---------------------------------
 
 Here, we want to connect the Button's "pressed" signal to our Sprite2D, and we
 want to call a new function that will toggle its motion on and off. We need to
-have a script attached to the Sprite2D node, which we do from the previous lesson.
+have a script attached to the Sprite2D node, which we do from the previous
+lesson.
 
 You can connect signals in the Node dock. Select the Button node and, on the
 right side of the editor, click on the tab named "Node" next to the Inspector.
@@ -101,10 +107,10 @@ Double-click the "pressed" signal to open the node connection window.
 
 .. image:: img/signals_12_node_connection.png
 
-There, you can connect the signal to the Sprite2D node. The node needs a receiver
-method, a function that Godot will call when the Button emits the signal. The
-editor generates one for you. By convention, we name these callback methods
-"_on_NodeName_signal_name". Here, it'll be "_on_Button_pressed".
+There, you can connect the signal to the Sprite2D node. The node needs a
+receiver method, a function that Godot will call when the Button emits the
+signal. The editor generates one for you. By convention, we name these callback
+methods "_on_NodeName_signal_name". Here, it'll be "_on_Button_pressed".
 
 .. note::
 
@@ -133,8 +139,8 @@ connection. This feature is only available when connecting nodes in the editor.
 Let's replace the line with the ``pass`` keyword with code that'll toggle the
 node's motion.
 
-Our Sprite2D moves thanks to code in the ``_process()`` function. Godot provides a
-method to toggle processing on and off: :ref:`Node.set_process()
+Our Sprite2D moves thanks to code in the ``_process()`` function. Godot provides
+a method to toggle processing on and off: :ref:`Node.set_process()
 <class_Node_method_set_process>`. Another method of the Node class,
 ``is_processing()``, returns ``true`` if idle processing is active. We can use
 the ``not`` keyword to invert the value.
@@ -155,7 +161,7 @@ following code, which we saw two lessons ago:
 .. tabs::
  .. code-tab:: gdscript GDScript
 
-    func _process(delta: float) -> void:
+    func _process(delta):
         rotation += angular_speed * delta
         var velocity = Vector2.UP.rotated(rotation) * speed
         position += velocity * delta
@@ -170,11 +176,13 @@ Your complete ``Sprite2D.gd`` code should look like the following.
     var speed = 400
     var angular_speed = PI
 
-    func _process(delta: float) -> void:
+
+    func _process(delta):
         rotation += angular_speed * delta
         var velocity = Vector2.UP.rotated(rotation) * speed
         position += velocity * delta
 
+
     func _on_Button_pressed():
         set_process(not is_processing())
 
@@ -192,12 +200,14 @@ that's useful to implement skill cooldown times, weapon reloading, and more.
 Head back to the 2D workspace. You can either click the "2D" text at the top of
 the window or press :kbd:`Ctrl + F1` (:kbd:`Alt + 1` on macOS).
 
-In the Scene dock, right-click on the Sprite2D node and add a new child node. Search for
-Timer and add the corresponding node. Your scene should now look like this.
+In the Scene dock, right-click on the Sprite2D node and add a new child node.
+Search for Timer and add the corresponding node. Your scene should now look like
+this.
 
 .. image:: img/signals_15_scene_tree.png
 
-With the Timer node selected, go to the Inspector and check the **Autostart** property.
+With the Timer node selected, go to the Inspector and check the **Autostart**
+property.
 
 .. image:: img/signals_18_timer_autostart.png
 
@@ -214,6 +224,10 @@ We need to do two operations to connect the nodes via code:
           method of the node you want to listen to. In this case, we want to
           listen to the Timer's "timeout" signal.
 
+We want to connect the signal when the scene is intantiated, and we can do that
+using the :ref:`Node._ready() <class_Node_method__ready>` built-in function,
+which is called automatically by the engine when a node is fully instantiated.
+
 To get a reference to a node relative to the current one, we use the method
 :ref:`Node.get_node() <class_Node_method_get_node>`. We can store the reference
 in a variable.
@@ -221,10 +235,6 @@ in a variable.
 .. tabs::
  .. code-tab:: gdscript GDScript
 
-    extends Sprite2D
-
-    #...
-
     func _ready():
         var timer = get_node("Timer")
 
@@ -258,9 +268,45 @@ The ``visible`` property is a boolean that controls the visibility of our node.
 The line ``visible = not visible`` toggles the value. If ``visible`` is
 ``true``, it becomes ``false``, and vice-versa.
 
+Complete script
+---------------
+
+That's it for our little moving and blinking Godot icon demo!
+Here is the complete ``Sprite2D.gd`` file for reference.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    extends Sprite2D
+
+    var speed = 400
+    var angular_speed = PI
+
+
+    func _ready():
+        var timer = get_node("Timer")
+        timer.connect("timeout", self, "_on_Timer_timeout")
+
+
+    func _process(delta):
+        rotation += angular_speed * delta
+        var velocity = Vector2.UP.rotated(rotation) * speed
+        position += velocity * delta
+
+
+    func _on_Button_pressed():
+        set_process(not is_processing())
+
+
+    func _on_Timer_timeout():
+        visible = not visible
+
 Custom signals
 --------------
 
+.. note:: This section is a reference on how to define and use your own signals,
+          and does not build upon the project created in previous lessons.
+
 You can define custom signals in a script. Say, for example, that you want to
 show a game over screen when the player's health reaches zero. To do so, you
 could define a signal named "died" or "health_depleted" when their health