Write and edit overridable_functions.rst, remove scripting_continued.rst

tutorials/scripting/index.rst

@@ -38,6 +38,7 @@ below will help you make the most of Godot.
    idle_and_physics_processing
    groups
    nodes_and_scene_instances
+   overridable_functions
    cross_language_scripting
    creating_script_templates
    change_scenes_manually

tutorials/scripting/overridable_functions.rst

@@ -0,0 +1,145 @@
+.. _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 uses a 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. 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()``. It ensures that all children
+have entered the scene tree first, so you can safely call ``get_node()`` in 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.
+    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, respectively, every frame and every physics frame. 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 both use to receive
+and process individual input events. The ``_unhandled_input()`` method receives
+every key press, mouse click, etc. that had not been handled already in an
+``_input()`` callback or in a piece of user interface. 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.
+
+There's a lot to say about input handling in Godot. You'll find a lot more
+information in 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.