Merge pull request #4344 from NathanLovato/edit/improve-scripting-section

Split and edit scripting_continued.rst, improve scripting section

getting_started/step_by_step/index.rst

@@ -10,7 +10,6 @@ Step by step
    instancing
    instancing_continued
    scripting
-   scripting_continued
    signals
    your_first_game
    exporting

getting_started/step_by_step/resources.rst

@@ -190,7 +190,7 @@ those values and saves the resource, the Inspector serializes the custom propert
 too! To save a resource from the Inspector, click the Inspector's tools menu (top right),
 and select "Save" or "Save As...".
 
-If the script's language supports :ref:`script classes <doc_scripting_continued_class_name>`,
+If the script's language supports :ref:`script classes <doc_gdscript_basics_class_name>`,
 then it streamlines the process. Defining a name for your script alone will add it to
 the Inspector's creation dialog. This will auto-add your script to the Resource
 object you create.

getting_started/step_by_step/scripting_continued.rst

@@ -1,425 +0,0 @@
-.. _doc_scripting_continued:
-
-Scripting (continued)
-=====================
-
-Processing
-----------
-
-Several actions in Godot are triggered by callbacks or virtual functions,
-so there is no need to write code that runs all the time.
-
-However, it is still common to need a script to be processed on every
-frame. There are two types of processing: idle processing and physics
-processing.
-
-Idle processing is activated when the method :ref:`Node._process() <class_Node_method__process>`
-is found in a script. It can be turned off and on with the
-:ref:`Node.set_process() <class_Node_method_set_process>` function.
-
-This method will be called every time a frame is drawn:
-
-.. tabs::
- .. code-tab:: gdscript GDScript
-
-    func _process(delta):
-        # Do something...
-        pass
-
- .. code-tab:: csharp
-
-    public override void _Process(float delta)
-    {
-        // Do something...
-    }
-
-It's important to bear in mind that the frequency with which ``_process()``
-will be called depends on how many frames per second (FPS) your application
-is running at. This rate can vary over time and devices.
-
-To help manage this variability, the ``delta`` parameter contains the time
-elapsed in seconds as a floating-point number since the previous call to ``_process()``.
-
-This parameter can be used to make sure things always take the same
-amount of time, regardless of the game's FPS.
-
-For example, movement is often multiplied with a time delta to make movement
-speed both constant and independent of the frame rate.
-
-Physics processing with ``_physics_process()`` is similar, but it should be used for processes that
-must happen before each physics step, such as controlling a character.
-It always runs before a physics step and it is called at fixed time intervals:
-60 times per second by default. You can change the interval from the Project Settings, under
-Physics -> Common -> Physics Fps.
-
-The function ``_process()``, however, is not synced with physics. Its frame rate is not constant and is dependent
-on hardware and game optimization. Its execution is done after the physics step on single-threaded games.
-
-A simple way to see the ``_process()`` function at work is to create a scene with a single Label node,
-with the following script:
-
-.. tabs::
- .. code-tab:: gdscript GDScript
-
-    extends Label
-
-    var accum = 0
-
-    func _process(delta):
-        accum += delta
-        text = str(accum) # 'text' is a built-in label property.
-
- .. code-tab:: csharp
-
-    public class CustomLabel : Label
-    {
-        private float _accum;
-
-        public override void _Process(float delta)
-        {
-            _accum += delta;
-            Text = _accum.ToString(); // 'Text' is a built-in label property.
-        }
-    }
-
-Which will show a counter increasing each frame.
-
-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
--------------
-
-Godot has a system of notifications. These are usually not needed for
-scripting, as it's too low-level and virtual functions are provided for
-most of them. It's just good to know they exist. For example,
-you may add an
-:ref:`Object._notification() <class_Object_method__notification>`
-function in your script:
-
-.. tabs::
- .. code-tab:: gdscript GDScript
-
-    func _notification(what):
-        match what:
-            NOTIFICATION_READY:
-                print("This is the same as overriding _ready()...")
-            NOTIFICATION_PROCESS:
-                print("This is the same as overriding _process()...")
-
- .. code-tab:: csharp
-
-    public override void _Notification(int what)
-    {
-        base._Notification(what);
-
-        switch (what)
-        {
-            case NotificationReady:
-                GD.Print("This is the same as overriding _Ready()...");
-                break;
-            case NotificationProcess:
-                var delta = GetProcessDeltaTime();
-                GD.Print("This is the same as overriding _Process()...");
-                break;
-        }
-    }
-
-The documentation of each class in the :ref:`Class Reference <toc-class-ref>`
-shows the notifications it can receive. However, in most cases GDScript
-provides simpler overridable functions.
-
-Overridable functions
----------------------
-
-Such overridable functions, which are described as
-follows, can be applied to nodes:
-
-.. tabs::
- .. code-tab:: gdscript GDScript
-
-    func _enter_tree():
-        # When the node enters the Scene Tree, it becomes active
-        # and  this function is called. Children nodes have not entered
-        # the active scene yet. In general, it's better to use _ready()
-        # for most cases.
-        pass
-
-    func _ready():
-        # This function is called after _enter_tree, but it ensures
-        # that all children nodes have also entered the Scene Tree,
-        # and became active.
-        pass
-
-    func _exit_tree():
-        # When the node exits the Scene Tree, this function is called.
-        # Children nodes have all exited the Scene Tree at this point
-        # and all became inactive.
-        pass
-
-    func _process(delta):
-        # This function is called every frame.
-        pass
-
-    func _physics_process(delta):
-        # This is called every physics frame.
-        pass
-
- .. code-tab:: csharp
-
-    public override void _EnterTree()
-    {
-        // When the node enters the Scene Tree, it becomes active
-        // and  this function is called. Children nodes have not entered
-        // the active scene yet. In general, it's better to use _ready()
-        // for most cases.
-        base._EnterTree();
-    }
-
-    public override void _Ready()
-    {
-        // This function is called after _enter_tree, but it ensures
-        // that all children nodes have also entered the Scene Tree,
-        // and became active.
-        base._Ready();
-    }
-
-    public override void _ExitTree()
-    {
-        // When the node exits the Scene Tree, this function is called.
-        // Children nodes have all exited the Scene Tree at this point
-        // and all became inactive.
-        base._ExitTree();
-    }
-
-    public override void _Process(float delta)
-    {
-        // This function is called every frame.
-        base._Process(delta);
-    }
-
-    public override void _PhysicsProcess(float delta)
-    {
-        // This is called every physics frame.
-        base._PhysicsProcess(delta);
-    }
-
-As mentioned before, it's better to use these functions instead of
-the notification system.
-
-Creating nodes
---------------
-
-To create a node from code, call the ``.new()`` method, like for any
-other class-based datatype. For example:
-
-
-.. tabs::
- .. code-tab:: gdscript GDScript
-
-    var s
-    func _ready():
-        s = Sprite.new() # Create a new sprite!
-        add_child(s) # Add it as a child of this node.
-
- .. code-tab:: csharp
-
-    private Sprite _sprite;
-
-    public override void _Ready()
-    {
-        base._Ready();
-
-        _sprite = new Sprite(); // Create a new sprite!
-        AddChild(_sprite); // Add it as a child of this node.
-    }
-
-To delete a node, be it inside or outside the scene, ``free()`` must be
-used:
-
-.. tabs::
- .. code-tab:: gdscript GDScript
-
-    func _someaction():
-        s.free() # Immediately removes the node from the scene and frees it.
-
- .. code-tab:: csharp
-
-    public void _SomeAction()
-    {
-        _sprite.Free(); // Immediately removes the node from the scene and frees it.
-    }
-
-When a node is freed, it also frees all its child nodes. Because of
-this, manually deleting nodes is much simpler than it appears. Free
-the base node and everything else in the subtree goes away with it.
-
-A situation might occur where we want to delete a node that
-is currently "blocked", because it is emitting a signal or calling a
-function. This will crash the game. Running Godot
-with the debugger will often catch this case and warn you about it.
-
-The safest way to delete a node is by using
-:ref:`Node.queue_free() <class_Node_method_queue_free>`.
-This erases the node safely during idle.
-
-.. tabs::
- .. code-tab:: gdscript GDScript
-
-    func _someaction():
-        s.queue_free() # Removes the node from the scene and frees it when it becomes safe to do so.
-
- .. code-tab:: csharp
-
-    public void _SomeAction()
-    {
-        _sprite.QueueFree(); // Removes the node from the scene and frees it when it becomes safe to do so.
-    }
-
-Instancing scenes
------------------
-
-Instancing a scene from code is done in two steps. The
-first one is to load the scene from your hard drive:
-
-.. tabs::
- .. code-tab:: gdscript GDScript
-
-    var scene = load("res://myscene.tscn") # Will load when the script is instanced.
-
- .. code-tab:: csharp
-
-    var scene = GD.Load<PackedScene>("res://myscene.tscn"); // Will load when the script is instanced.
-
-
-Preloading it can be more convenient, as it happens at parse
-time (GDScript only):
-
-.. tabs::
- .. code-tab:: gdscript GDScript
-
-    var scene = preload("res://myscene.tscn") # Will load when parsing the script.
-
-But ``scene`` is not yet a node. It's packed in a
-special resource called :ref:`PackedScene <class_PackedScene>`.
-To create the actual node, the function
-:ref:`PackedScene.instance() <class_PackedScene_method_instance>`
-must be called. This will return the tree of nodes that can be added to
-the active scene:
-
-.. tabs::
- .. code-tab:: gdscript GDScript
-
-    var node = scene.instance()
-    add_child(node)
-
- .. code-tab:: csharp
-
-    var node = scene.Instance();
-    AddChild(node);
-
-The advantage of this two-step process is that a packed scene may be
-kept loaded and ready to use so that you can create as many
-instances as desired. This is especially useful to quickly instance
-several enemies, bullets, and other entities in the active scene.
-
-.. _doc_scripting_continued_class_name:
-
-Register scripts as classes
----------------------------
-
-Godot has a "Script Class" feature to register individual scripts with the
-Editor. By default, you can only access unnamed scripts by loading the file
-directly.
-
-You can name a script and register it as a type in the editor with the
-``class_name`` keyword followed by the class's name. You may add a comma and an
-optional path to an image to use as an icon. You will then find your new type in
-the Node or Resource creation dialog.
-
-.. tabs::
- .. code-tab:: gdscript GDScript
-
-    extends Node
-
-    # Declare the class name here
-    class_name ScriptName, "res://path/to/optional/icon.svg"
-
-    func _ready():
-        var this = ScriptName           # reference to the script
-        var cppNode = MyCppNode.new()   # new instance of a class named MyCppNode
-
-        cppNode.queue_free()
-
-.. image:: img/script_class_nativescript_example.png
-
-
-.. warning:: In Godot 3.1:
-
-            - Only GDScript and NativeScript, i.e., C++ and other GDNative-powered languages, can register scripts.
-            - Only GDScript creates global variables for each named script.

tutorials/best_practices/autoloads_versus_internal_nodes.rst

@@ -68,7 +68,7 @@ or data across many scenes.
 
 In the case of functions, you can create a new type of ``Node`` that provides
 that feature for an individual scene using the :ref:`class_name
-<doc_scripting_continued_class_name>` keyword in GDScript.
+<doc_gdscript_basics_class_name>` keyword in GDScript.
 
 When it comes to data, you can either:
 

tutorials/best_practices/scenes_versus_scripts.rst

@@ -112,7 +112,7 @@ There are two systems for registering types...
 
    - Set up using :ref:`EditorPlugin.add_custom_type <class_EditorPlugin_method_add_custom_type>`.
 
-- :ref:`Script Classes <doc_scripting_continued_class_name>`
+- :ref:`Script Classes <doc_gdscript_basics_class_name>`
 
    - Editor and runtime accessible.
 

tutorials/io/saving_games.rst

@@ -25,9 +25,9 @@ sessions and what information we want to keep from those objects. For
 this tutorial, we will use groups to mark and handle objects to be saved,
 but other methods are certainly possible.
 
-We will start by adding objects we wish to save to the "Persist" group.
-As in the :ref:`doc_scripting_continued` tutorial, we can do this through
-either the GUI or script. Let's add the relevant nodes using the GUI:
+We will start by adding objects we wish to save to the "Persist" group. We can
+do this through either the GUI or script. Let's add the relevant nodes using the
+GUI:
 
 .. image:: img/groups.png
 

tutorials/plugins/editor/making_plugins.rst

@@ -137,7 +137,7 @@ custom behavior.
 
   Nodes added via an EditorPlugin are "CustomType" nodes. While they work
   with any scripting language, they have fewer features than
-  :ref:`the Script Class system <doc_scripting_continued_class_name>`. If you
+  :ref:`the Script Class system <doc_gdscript_basics_class_name>`. If you
   are writing GDScript or NativeScript, we recommend using Script Classes instead.
 
 To create a new node type, you can use the function

tutorials/scripting/gdscript/gdscript_basics.rst

@@ -1190,8 +1190,6 @@ There are 6 pattern types:
             "Sword", "Splash potion", "Fist":
                 print("Yep, you've taken damage")
 
-
-
 Classes
 ~~~~~~~
 
@@ -1208,7 +1206,12 @@ path. For example, if you name a script file ``character.gd``::
    var Character = load("res://path/to/character.gd")
    var character_node = Character.new()
 
-Instead, you can give your class a name to register it as a new type in Godot's
+.. _doc_gdscript_basics_class_name:
+
+Registering named classes
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can give your class a name to register it as a new type in Godot's
 editor. For that, you use the ``class_name`` keyword. You can optionally use
 the ``@icon`` annotation with a path to an image, to use it as an icon. Your
 class will then appear with its new icon in the editor::

tutorials/scripting/gdscript/static_typing.rst

@@ -107,7 +107,7 @@ Currently you can use three types of… types:
 1. :ref:`Built-in <doc_gdscript_builtin_types>`
 2. Core classes and nodes (``Object``, ``Node``, ``Area2D``,
    ``Camera2D``, etc.)
-3. Your own, custom classes. Look at the new :ref:`class_name <doc_scripting_continued_class_name>`
+3. Your own custom classes. Look at the new :ref:`class_name <doc_gdscript_basics_class_name>`
    feature to register types in the editor.
 
 .. note::

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 enters 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 an infiltration game. 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/idle_and_physics_processing.rst

@@ -0,0 +1,104 @@
+.. _doc_idle_and_physics_processing:
+
+Idle and Physics Processing
+===========================
+
+Games run in a loop. Each frame, you need to update the state of your game world
+before drawing it on screen. Godot provides two virtual methods in the Node
+class to do so: :ref:`Node._process() <class_Node_method__process>` and
+:ref:`Node._physics_process() <class_Node_method__physics_process>`. If you
+define either or both in a script, the engine will call them automatically.
+
+There are two types of processing available to you:
+
+1. **Idle processing** allows you to run code that updates a node every frame,
+   as often as possible.
+2. **Physics processing** happens at a fixed rate, 60 times per second by
+   default. This is independent of your game's actual framerate, and keeps physics
+   running smoothly. You should use it for anything that involves the physics
+   engine, like moving a body that collides with the environment.
+
+You can activate idle processing by defining the ``_process()`` method in a
+script. You can turn it off and back on by calling :ref:`Node.set_process()
+<class_Node_method_set_process>`.
+
+The engine calls this method every time it draws a frame:
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    func _process(delta):
+        # Do something...
+        pass
+
+ .. code-tab:: csharp
+
+    public override void _Process(float delta)
+    {
+        // Do something...
+    }
+
+Keep in mind that the frequency at which the engine calls ``_process()`` depends
+on your application's framerate, which varies over time and across devices.
+
+The function's ``delta`` parameter is the time elapsed in seconds since the
+previous call to ``_process()``. Use this parameter to make calculations
+independent of the framerate. For example, you should always multiply a speed
+value by ``delta`` to animate a moving object.
+
+Physics processing works with a similar virtual function:
+``_physics_process()``. Use it for calculations that must happen before each
+physics step, like moving a character that collides with the game world. As
+mentioned above, ``_physics_process()`` runs at fixed time intervals as much as
+possible to keep the physics interactions stable. You can change the interval
+between physics steps in the Project Settings, under Physics -> Common ->
+Physics Fps. By default, it's set to run 60 times per second.
+
+The engine calls this method every time it draws a frame:
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    func _physics_process(delta):
+        # Do something...
+        pass
+
+ .. code-tab:: csharp
+
+    public override void _PhysicsProcess(float delta)
+    {
+        // Do something...
+    }
+
+The function ``_process()`` is not synchronized with physics. Its rate depends on
+hardware and game optimization. It also runs after the physics step in
+single-threaded games.
+
+You can see the ``_process()`` function at work by creating a scene with a
+single Label node, with the following script attached to it:
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    extends Label
+
+    var time = 0
+
+    func _process(delta):
+        time += delta
+        text = str(time) # 'text' is a built-in Label property.
+
+ .. code-tab:: csharp
+
+    public class CustomLabel : Label
+    {
+        private float _time;
+
+        public override void _Process(float delta)
+        {
+            _time += delta;
+            Text = _time.ToString(); // 'Text' is a built-in Label property.
+        }
+    }
+
+When you run the scene, you should see a counter increasing each frame.

tutorials/scripting/index.rst

@@ -1,6 +1,19 @@
 Scripting
 =========
 
+This section covers programming languages and core features to code your games
+in Godot.
+
+Here, you will find information that is not already covered in more specific
+sections. For instance, to learn about inputs, we recommend you to read
+:ref:`Inputs <toc-learn-features-inputs>`.
+
+Programming languages
+---------------------
+
+The sections below each focus on a given programming language or, in GDNative's
+case, an interface that works with multiple languages.
+
 .. toctree::
    :maxdepth: 1
    :name: toc-learn-scripting
@@ -9,7 +22,23 @@ Scripting
    visual_script/index
    c_sharp/index
    gdnative/index
+
+Core features
+-------------
+
+Some features are specific to the engine and are available in all supported
+languages. Whether you code in GDScript, C#, or another language, the pages
+below will help you make the most of Godot.
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-scripting-core-features
+
    debug/index
+   idle_and_physics_processing
+   groups
+   nodes_and_scene_instances
+   overridable_functions
    cross_language_scripting
    creating_script_templates
    change_scenes_manually

tutorials/scripting/nodes_and_scene_instances.rst

@@ -0,0 +1,224 @@
+.. _doc_nodes_and_scene_instances:
+
+Nodes and scene instances
+=========================
+
+This guide explains how to get nodes, create nodes, add them as a child, and
+instantiate scenes from code.
+
+Getting nodes
+-------------
+
+You can get a reference to a node by calling the :ref:`Node.get_node()
+<class_Node_method_get_node>` method. For this to work, the child node must be
+present in the scene tree. Getting it in the parent node's ``_ready()`` function
+guarantees that.
+
+If, for example,  you have a scene tree like this, and you want to get a reference to the
+Sprite and Camera2D nodes to access them in your script.
+
+.. image:: img/nodes_and_scene_instances_player_scene_example.png
+
+To do so, you can use the following code.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    var sprite
+    var camera2d
+
+    func _ready():
+        sprite = get_node("Sprite")
+        camera2d = get_node("Camera2D")
+
+ .. code-tab:: csharp
+
+    private Sprite _sprite;
+    private Camera2D _camera2d;
+
+    public override void _Ready()
+    {
+        base._Ready();
+
+        _sprite = GetNode<Sprite>("Sprite");
+        _camera2d = GetNode<Camera2D>("Camera2D");
+    }
+
+Note that you get nodes using their name, not their type. Above, "Sprite" and
+"Camera2D" are the nodes' names in the scene.
+
+.. image:: img/nodes_and_scene_instances_sprite_node.png
+
+If you rename the Sprite node as Skin in the Scene dock, you have to change the
+line that gets the node to ``get_node("Skin")`` in the script.
+
+.. image:: img/nodes_and_scene_instances_sprite_node_renamed.png
+
+Node paths
+----------
+
+When getting a reference to a node, you're not limited to getting a direct child. The ``get_node()`` function
+supports paths, a bit like when working with a file browser. Add a slash to
+separate nodes.
+
+Take the following example scene, with the script attached to the UserInterface
+node.
+
+.. image:: img/nodes_and_scene_instances_ui_scene_example.png
+
+To get the Tween node, you would use the following code.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    var tween
+
+    func _ready():
+        tween = get_node("ShieldBar/Tween")
+
+ .. code-tab:: csharp
+
+    private Tween _tween;
+
+    public override void _Ready()
+    {
+        base._Ready();
+
+        _tween = GetNode<Tween>("ShieldBar/Tween");
+    }
+
+.. note:: As with file paths, you can use ".." to get a parent node. The best
+          practice is to avoid doing that though not to break encapsulation.
+          You can also start the path with a forward
+          slash to make it absolute, in which case your topmost node would be
+          "/root", the application's predefined root viewport.
+
+Syntactic sugar
+~~~~~~~~~~~~~~~
+
+You can use two shorthands to shorten your code in GDScript. Firstly, putting the
+``onready`` keyword before a member variable makes it initialize right before
+the ``_ready()`` callback.
+
+.. code-block:: gdscript
+
+    onready var sprite = get_node("Sprite")
+
+There is also a short notation for ``get_node()``: the dollar sign, "$". You
+place it before the name or path of the node you want to get.
+
+.. code-block:: gdscript
+
+    onready var sprite = $Sprite
+    onready var tween = $ShieldBar/Tween
+
+Creating nodes
+--------------
+
+To create a node from code, call its ``new()`` method like for any other
+class-based datatype.
+
+You can store the newly created node's reference in a variable and call
+``add_child()`` to add it as a child of the node to which you attached the
+script.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    var sprite
+
+    func _ready():
+        var sprite = Sprite.new() # Create a new Sprite.
+        add_child(sprite) # Add it as a child of this node.
+
+ .. code-tab:: csharp
+
+    private Sprite _sprite;
+
+    public override void _Ready()
+    {
+        base._Ready();
+
+        _sprite = new Sprite(); // Create a new Sprite.
+        AddChild(_sprite); // Add it as a child of this node.
+    }
+
+To delete a node and free it from memory, you can call its ``queue_free()``
+method. Doing so queues the node for deletion at the end of the current frame
+after it has finished processing. At that point, the engine removes the node from
+the scene and frees the object in memory.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    sprite.queue_free()
+
+ .. code-tab:: csharp
+
+    _sprite.QueueFree();
+
+Before calling ``sprite.queue_free()``, the remote scene tree looks like this.
+
+.. image:: img/nodes_and_scene_instances_remote_tree_with_sprite.png
+
+After the engine freed the node, the remote scene tree doesn't display the
+sprite anymore.
+
+.. image:: img/nodes_and_scene_instances_remote_tree_no_sprite.png
+
+You can alternatively call ``free()`` to immediately destroy the node. You
+should do this with care as any reference to it will instantly become ``null``.
+We recommend using ``queue_free()`` unless you know what you're doing.
+
+When you free a node, it also frees all its children. Thanks to this, to delete
+an entire branch of the scene tree, you only have to free the topmost parent
+node.
+
+Instancing scenes
+-----------------
+
+Scenes are templates from which you can create as many reproductions as you'd
+like. This operation is called instancing, and doing it from code happens in two
+steps:
+
+1. Loading the scene from the hard drive.
+2. Creating an instance of the loaded :ref:`PackedScene <class_PackedScene>`
+   resource.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    var scene = load("res://MyScene.tscn")
+
+ .. code-tab:: csharp
+
+    var scene = GD.Load<PackedScene>("res://MyScene.tscn");
+
+Preloading the scene can improve the user's experience as the load operation
+happens when the compiler reads the script and not at runtime. This feature is
+only available with GDScript.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    var scene = preload("res://MyScene.tscn")
+
+At that point, ``scene`` is a packed scene resource, not a node. To create the
+actual node, you need to call :ref:`PackedScene.instance()
+<class_PackedScene_method_instance>`. It returns a tree of nodes that you can
+as a child of your current node.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    var instance = scene.instance()
+    add_child(instance)
+
+ .. code-tab:: csharp
+
+    var instance = scene.();
+    AddChild(instance);
+
+The advantage of this two-step process is you can keep a packed scene loaded and
+create new instances on the fly. For example, to quickly instance several
+enemies or bullets.

tutorials/scripting/overridable_functions.rst

@@ -0,0 +1,144 @@
+.. _doc_overridable_functions:
+
+Overridable functions
+=====================
+
+Godot's Node class provides virtual functions you can override to update nodes
+every frame or on specific events, like when they enter the scene tree.
+
+This document presents the ones you'll use most often.
+
+.. seealso:: Under the hood, these functions rely on Godot's low-level
+             notifications system. To learn more about it, see
+             :ref:`doc_godot_notifications`.
+
+Two functions allow you to initialize and get nodes, besides the class's
+constructor: ``_enter_tree()`` and ``_ready()``.
+
+When the node enters the Scene Tree, it becomes active and the engine calls its
+``_enter_tree()`` method. That node's children may not be part of the active scene yet. As
+you can remove and re-add nodes to the scene tree, this function may be called
+multiple times throughout a node's lifetime.
+
+Most of the time, you'll use ``_ready()`` instead. This function is called only
+once in a node's lifetime, after ``_enter_tree()``. ``_ready()`` ensures that all children
+have entered the scene tree first, so you can safely call ``get_node()`` on it.
+
+.. seealso:: To learn more about getting node references, read
+             :ref:`doc_nodes_and_scene_instances`.
+
+Another related callback is ``_exit_tree()``, which the engine calls every time
+a node exits the scene tree. This can be when you call :ref:`Node.remove_child()
+<class_Node_method_remove_child>` or when you free a node.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    # Called every time the node enters the scene tree.
+    func _enter_tree():
+        pass
+
+    # Called when both the node and its children have entered the scene tree.
+    func _ready():
+        pass
+
+    # Called when the node is about to leave the scene tree, after all its
+    children received the _exit_tree() callback.
+    func _exit_tree():
+        pass
+
+ .. code-tab:: csharp
+
+    // Called every time the node enters the scene tree.
+    public override void _EnterTree()
+    {
+        base._EnterTree();
+    }
+
+    // Called when both the node and its children have entered the scene tree.
+    public override void _Ready()
+    {
+        base._Ready();
+    }
+
+    // Called when the node is about to leave the scene tree, after all its
+    children.
+    public override void _ExitTree()
+    {
+        base._ExitTree();
+    }
+
+The two virtual methods ``_process()`` and ``_physics_process()`` allow you to
+update the node, every frame and every physics frame respectively. For more
+information, read the dedicated documentation:
+:ref:`doc_idle_and_physics_processing`.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    # Called every frame, as often as possible.
+    func _process(delta):
+        pass
+
+    # Called every physics frame.
+    func _physics_process(delta):
+        pass
+
+ .. code-tab:: csharp
+
+    public override void _Process(float delta)
+    {
+        // Called every frame, as often as possible.
+        base._Process(delta);
+    }
+
+    public override void _PhysicsProcess(float delta)
+    {
+        // Called every physics frame.
+        base._PhysicsProcess(delta);
+    }
+
+Two more essential built-in node callback functions are
+:ref:`Node._unhandled_input() <class_Node_method__unhandled_input>` and
+:ref:`Node._input() <class_Node_method__input>`, which you use to both receive
+and process individual input events. The ``_unhandled_input()`` method receives
+every key press, mouse click, etc. that have not been handled already in an
+``_input()`` callback or in a user interface component. You want to use it for
+gameplay input in general. The ``_input()`` callback allows you to intercept and
+process input events before ``_unhandled_input()`` gets them.
+
+To learn more about inputs in Godot, see the :ref:`Input section <toc-learn-features-inputs>`.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    # Called once for every event.
+    func _unhandled_input(event):
+        pass
+
+    # Called once for every event, before _unhandled_input(), allowing you to
+    consume some events.
+    func _input(event):
+        pass
+
+ .. code-tab:: csharp
+
+    // Called once for every event.
+    public override void _UnhandledInput(InputEvent @event)
+    {
+        base._UnhandledInput(event);
+    }
+
+    // Called once for every event, before _unhandled_input(), allowing you to
+    consume some events.
+    public override void _Input(InputEvent @event)
+    {
+        base._Input(event);
+    }
+
+There are some more overridable functions like
+:ref:`Node._get_configuration_warning()
+<class_Node_method__get_configuration_warning>`. Specialized node types provide
+more callbacks like :ref:`CanvasItem._draw() <class_CanvasItem_method__draw>` to
+draw programmatically or :ref:`Control._gui_input()
+<class_Control_method__gui_input>` to handle clicks and input on UI elements.