|
@@ -7,19 +7,18 @@ 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. Additionally, a
|
|
|
-lot can be done with animation players.
|
|
|
+so there is no need to write code that runs all the time.
|
|
|
|
|
|
-However, it is still a very common case to have a script process on every
|
|
|
+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 automatically when the method :ref:`Node._process() <class_Node__process>`
|
|
|
-is found in a script. It can be turned off (and back on) with the
|
|
|
+Idle processing is activated when the method :ref:`Node._process() <class_Node__process>`
|
|
|
+is found in a script. It can be turned off and on with the
|
|
|
:ref:`Node.set_process() <class_Node_set_process>` function.
|
|
|
|
|
|
-This method will be called every frame drawn, so it's fully depend on the
|
|
|
-frames per second (FPS) of the application:
|
|
|
+This method will be called every time a frame is drawn, so it's fully dependent on
|
|
|
+how many frames per second (FPS) the application is running at:
|
|
|
|
|
|
.. tabs::
|
|
|
.. code-tab:: gdscript GDScript
|
|
@@ -34,22 +33,23 @@ frames per second (FPS) of the application:
|
|
|
// do something...
|
|
|
}
|
|
|
|
|
|
-The delta parameter describes the time elapsed (in seconds, as a
|
|
|
-floating point) since the previous call to "_process()".
|
|
|
+The delta parameter contains the time elapsed in seconds, as a
|
|
|
+floating point, since the previous call to ``_process()``.
|
|
|
|
|
|
-This delta parameter can be used to make sure things always take the same time,
|
|
|
-regardless of the hardware the game is running on.
|
|
|
+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 the time delta to make the movement
|
|
|
-constant and independent from the frame rate.
|
|
|
+For example, movement is often multiplied with a time delta to make movement
|
|
|
+speed both constant and independent from the frame rate.
|
|
|
|
|
|
-Physics processing (``_physics_process()``) is similar, but it should be used for all the processes that
|
|
|
-must happen before each physics step. For example, to move a character.
|
|
|
-It always runs before a physics step and it is called at fixed time intervals,
|
|
|
-60 times per second by default. Change the value in the Project Settings.
|
|
|
+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() instead is not synced with physics. Its frame rate is not constant and dependent on hardware and game optimization.
|
|
|
-Its execution is done after the physics step on single thread games.
|
|
|
+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 test this is to create a scene with a single Label node,
|
|
|
with the following script:
|
|
@@ -83,14 +83,13 @@ Which will show a counter increasing each frame.
|
|
|
Groups
|
|
|
------
|
|
|
|
|
|
-Nodes can be added to groups (as many as desired per node). This is a
|
|
|
-simple yet useful feature for organizing large scenes. There are two
|
|
|
-ways to do this: the first is from the UI, from the Groups button under the Node panel:
|
|
|
+Nodes can be added to groups, as many as desired per node, and is a useful feature for organizing large scenes.
|
|
|
+There are two ways to do this. The first is from the UI, from the Groups button under the Node panel:
|
|
|
|
|
|
.. image:: img/groups_in_nodes.png
|
|
|
|
|
|
-And the second from code. One useful example would be to tag scenes
|
|
|
-which are enemies.
|
|
|
+And the second way is from code. One example would be to tag scenes
|
|
|
+which are enemies:
|
|
|
|
|
|
.. tabs::
|
|
|
.. code-tab:: gdscript GDScript
|
|
@@ -107,14 +106,14 @@ which are enemies.
|
|
|
AddToGroup("enemies");
|
|
|
}
|
|
|
|
|
|
-This way, if the player is discovered sneaking into the secret base,
|
|
|
-all enemies can be notified about the alarm sounding, by using
|
|
|
+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_call_group>`:
|
|
|
|
|
|
.. tabs::
|
|
|
.. code-tab:: gdscript GDScript
|
|
|
|
|
|
- func _on_discovered(): # this is a fictional function
|
|
|
+ func _on_discovered(): # this is a purely illustrative function
|
|
|
get_tree().call_group("enemies", "player_was_discovered")
|
|
|
|
|
|
.. code-tab:: csharp
|
|
@@ -124,10 +123,10 @@ all enemies can be notified about the alarm sounding, by using
|
|
|
GetTree().CallGroup("enemies", "player_was_discovered");
|
|
|
}
|
|
|
|
|
|
-The above code calls the function "player_was_discovered" on every
|
|
|
-member of the group "enemies".
|
|
|
+The above code calls the function ``player_was_discovered`` on every
|
|
|
+member of the group ``enemies``.
|
|
|
|
|
|
-Optionally, it is possible to get the full list of "enemies" nodes by
|
|
|
+It is also possible to get the full list of ``enemies`` nodes by
|
|
|
calling
|
|
|
:ref:`SceneTree.get_nodes_in_group() <class_SceneTree_get_nodes_in_group>`:
|
|
|
|
|
@@ -140,17 +139,16 @@ calling
|
|
|
|
|
|
var enemies = GetTree().GetNodesInGroup("enemies");
|
|
|
|
|
|
-More will be added about
|
|
|
-:ref:`SceneTree <class_SceneTree>`
|
|
|
-later.
|
|
|
+The :ref:`SceneTree <class_SceneTree>` documentation is currently incomplete,
|
|
|
+though more will be added later.
|
|
|
|
|
|
Notifications
|
|
|
-------------
|
|
|
|
|
|
-Godot has a system of notifications. This is 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. Simply
|
|
|
-add a
|
|
|
+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__notification>`
|
|
|
function in your script:
|
|
|
|
|
@@ -183,14 +181,14 @@ function in your script:
|
|
|
}
|
|
|
|
|
|
The documentation of each class in the :ref:`Class Reference <toc-class-ref>`
|
|
|
-shows the notifications it can receive. However, for most cases GDScript
|
|
|
+shows the notifications it can receive. However, in most cases GDScript
|
|
|
provides simpler overrideable functions.
|
|
|
|
|
|
Overrideable functions
|
|
|
----------------------
|
|
|
|
|
|
-Nodes provide many useful overrideable functions, which are described as
|
|
|
-follows:
|
|
|
+Such overrideable functions, which are described as
|
|
|
+follows, can be applied to nodes:
|
|
|
|
|
|
.. tabs::
|
|
|
.. code-tab:: gdscript GDScript
|
|
@@ -270,14 +268,14 @@ follows:
|
|
|
base._PhysicsProcess(delta);
|
|
|
}
|
|
|
|
|
|
-
|
|
|
-As mentioned before, it's best to use these functions.
|
|
|
+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, just like for any
|
|
|
-other class based datatype. Example:
|
|
|
+To create a node from code, call the ``.new()`` method, just like for any
|
|
|
+other class-based datatype. For example:
|
|
|
|
|
|
|
|
|
.. tabs::
|
|
@@ -300,7 +298,7 @@ other class based datatype. Example:
|
|
|
AddChild(_sprite); // add it as a child of this node
|
|
|
}
|
|
|
|
|
|
-To delete a node, be it inside or outside the scene, "free()" must be
|
|
|
+To delete a node, be it inside or outside the scene, ``free()`` must be
|
|
|
used:
|
|
|
|
|
|
.. tabs::
|
|
@@ -318,12 +316,12 @@ used:
|
|
|
|
|
|
When a node is freed, it also frees all its children nodes. Because of
|
|
|
this, manually deleting nodes is much simpler than it appears. Just free
|
|
|
-the base node and everything else in the sub-tree goes away with it.
|
|
|
+the base node and everything else in the subtree goes away with it.
|
|
|
|
|
|
-However, it might happen very often that we want to delete a node that
|
|
|
+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 result in crashing the game. Running Godot
|
|
|
-in the debugger often will catch this case and warn you about it.
|
|
|
+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_queue_free>`.
|
|
@@ -345,8 +343,8 @@ This erases the node safely during idle.
|
|
|
Instancing scenes
|
|
|
-----------------
|
|
|
|
|
|
-Instancing a scene from code is pretty easy and done in two steps. The
|
|
|
-first one is to load the scene from disk.
|
|
|
+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
|
|
@@ -358,14 +356,14 @@ first one is to load the scene from disk.
|
|
|
var scene = (PackedScene)ResourceLoader.Load("res://myscene.tscn"); // will load when the script is instanced
|
|
|
|
|
|
|
|
|
-Preloading it can be more convenient sometimes, as it happens at parse
|
|
|
-time.
|
|
|
+Preloading it can be more convenient, as it happens at parse
|
|
|
+time:
|
|
|
|
|
|
::
|
|
|
|
|
|
var scene = preload("res://myscene.tscn") # will load when parsing the script
|
|
|
|
|
|
-But 'scene' is not yet a node for containing subnodes. It's packed in a
|
|
|
+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_instance>`
|
|
@@ -384,6 +382,6 @@ the active scene:
|
|
|
AddChild(node);
|
|
|
|
|
|
The advantage of this two-step process is that a packed scene may be
|
|
|
-kept loaded and ready to use, so it can be used to create as many
|
|
|
+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, etc., in the active scene.
|
|
|
+several enemies, bullets, and other entities in the active scene.
|