diff --git a/getting_started/step_by_step/scripting_continued.rst b/getting_started/step_by_step/scripting_continued.rst index ba70311e8..d3851bb72 100644 --- a/getting_started/step_by_step/scripting_continued.rst +++ b/getting_started/step_by_step/scripting_continued.rst @@ -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() ` -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() ` +is found in a script. It can be turned off and on with the :ref:`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() `: .. 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() `: @@ -140,17 +139,16 @@ calling var enemies = GetTree().GetNodesInGroup("enemies"); -More will be added about -:ref:`SceneTree ` -later. +The :ref:`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() ` function in your script: @@ -183,14 +181,14 @@ function in your script: } The documentation of each class in the :ref:`Class Reference ` -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() `. @@ -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 `. To create the actual node, the function :ref:`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.