Browse Source

Update singletons_autoload.rst

General phrasing for readability
steevm 9 years ago
parent
commit
9ad79b7b1c
1 changed files with 50 additions and 52 deletions
  1. 50 52
      tutorials/step_by_step/singletons_autoload.rst

+ 50 - 52
tutorials/step_by_step/singletons_autoload.rst

@@ -6,48 +6,46 @@ Singletons (AutoLoad)
 Introduction
 Introduction
 ------------
 ------------
 
 
-Scene Singletons are very useful things, as they represent a very common
-use case, but it's not clear at the beginning where their value is.
+Scene singletons are very useful, catering to a common use case where you need
+to store persistent information between scenes.
 
 
-The scene system is very useful, but by itself it has a few drawbacks:
+The scene system by istelf has a few drawbacks:
 
 
--  There is no "common" place to store information (such as core, items
-   obtained, etc) between two scenes.
--  It is possible to make a scene that loads other scenes as children
-   and frees them, while keeping that information, but then if that is
-   done, it's not possible to run a scene alone by itself and expect it
-   to work
--  It is also possible to store persistent information to disk in
-   \`user://\` and have scenes always load it, but saving/loading that
-   while changing scenes is cumbersome.
+-  There is no common place to store information (e.g. a player's items etc.)
+   required by more than one scene.
+-  While it is possible for a scene that loads and unloads other scenes as 
+   its children to store information common to these child scenes, it is no 
+   longer possible to run these scenes by themselves and expect them to work 
+   correctly.
+-  While information can be stored to disk in \`user://\` and this information 
+   can be loaded by scenes that require it, continuously saving and loading this 
+   data when changing scenes is cumbersome and may be slow.
 
 
-So, after using Godot for a while, it becomes clear that it is necessary
-to have parts of a scene that:
+However there is still a need in Godot to create parts of a scene that:
 
 
--  Are always loaded, no matter which scene is opened from the editor.
--  Can keep global variables, such as player information, items, money,
-   etc.
--  Can handle switching of scenes and transitions.
--  Just have something that acts like a singleton, since GDScript does
-   not support global variables by design.
+-  Are always loaded, no matter which scene is opened from the editor
+-  Can store global variables, such as player information, items, money
+   etc. and hare information between scenes
+-  Can handle switching scenes and transitions
+-  Acts like a singleton, since GDScript does not support global variables by design.
 
 
-For this, the option for auto-loading nodes and scripts exists.
+
+Auto-loading nodes and scripts caters to this need.
 
 
 AutoLoad
 AutoLoad
 --------
 --------
 
 
-AutoLoad can be a scene, or a script that inherits from Node (a Node
-will be created and the script will be set to it). They are added to the
-project in the Scene > Project Settings > AutoLoad tab.
+You can use AutoLoad to load a scene, or a script that inherits from Node (a Node
+will be created and the script will be set to it). 
 
 
-Each autoload needs a name, this name will be the node name, and the
-node will be always added to the root viewport before any scene is
-loaded.
+To autoload a scene or script, select Scene > Project Settings from the menu and switch
+to the AutoLoad tab. Each entry in the list requires a name, which is used as the name
+of the node, and the node is always added to the root viewport before any other scenes 
+are loaded.
 
 
 .. image:: /img/singleton.png
 .. image:: /img/singleton.png
 
 
-This means, that for a singleton named "playervariables", any node can
-access it by requesting:
+This means that any node can access a singleton named "playervariables" with:
 
 
 ::
 ::
 
 
@@ -56,49 +54,49 @@ access it by requesting:
 Custom scene switcher
 Custom scene switcher
 ---------------------
 ---------------------
 
 
-This short tutorial will explain how to make a scene switcher by using
+This short tutorial will explain how to make a scene switcher using
 autoload. For simple scene switching, the
 autoload. For simple scene switching, the
 :ref:`SceneTree.change_scene() <class_SceneTree_change_scene>`
 :ref:`SceneTree.change_scene() <class_SceneTree_change_scene>`
 method suffices (described in :ref:`doc_scene_tree`), so this method is for
 method suffices (described in :ref:`doc_scene_tree`), so this method is for
-more complex behaviors when switching scenes.
+more complex behavior when switching between scenes.
 
 
 First download the template from here:
 First download the template from here:
 :download:`autoload.zip </files/autoload.zip>`, then open it.
 :download:`autoload.zip </files/autoload.zip>`, then open it.
 
 
 Two scenes are present, scene_a.scn and scene_b.scn on an otherwise
 Two scenes are present, scene_a.scn and scene_b.scn on an otherwise
 empty project. Each are identical and contain a button connected to a
 empty project. Each are identical and contain a button connected to a
-callback for going to the opposite scene. When the project runs, it
-starts in scene_a.scn. However, this does nothing and pressing the
+callback for switching to the other scene. When the project runs, it
+starts in scene_a.scn. However, this currently does nothing and pressing the
 button does not work.
 button does not work.
 
 
 global.gd
 global.gd
 ---------
 ---------
 
 
-First of all, create a global.gd script. The easier way to create a
+First of all, create a global.gd script. The easy way to create a
 resource from scratch is from the resources tab:
 resource from scratch is from the resources tab:
 
 
 .. image:: /img/newscript.png
 .. image:: /img/newscript.png
 
 
-Save the script to a file global.gd:
+Save the script as `global.gd`:
 
 
 .. image:: /img/saveasscript.png
 .. image:: /img/saveasscript.png
 
 
-The script should be opened in the script editor. Next step will be
-adding it to autoload, for this, go to: Scene [STRIKEOUT:> Project
-Settings]> AutoLoad and add a new autoload with name "global" that
-points to this file:
+The script should open in the script editor. The next step is to add
+it to AutoLoad list. Select Scene [STRIKEOUT:> Project
+Settings] from the menu, switch to the AutoLoad tab and add a new entry 
+with name "global" that points to this file:
 
 
 .. image:: /img/addglobal.png
 .. image:: /img/addglobal.png
 
 
-Now, when any scene is run, the script will be always loaded.
+Now, whenever you run any of your scenes, the script is always loaded.
 
 
-So, going back to it, In the _ready() function, the current scene
-will be fetched. Both the current scene and global.gd are children of
+Returning to our script, the current scene needs to be fetched in the 
+_ready() function. Both the current scene and `global.gd` are children of
 root, but the autoloaded nodes are always first. This means that the
 root, but the autoloaded nodes are always first. This means that the
 last child of root is always the loaded scene.
 last child of root is always the loaded scene.
 
 
-Also, make sure that global.gd extends from Node, otherwise it won't be
-loaded.
+Note: Make sure that global.gd extends Node, otherwise it won't be
+loaded!
 
 
 ::
 ::
 
 
@@ -110,8 +108,8 @@ loaded.
             var root = get_tree().get_root()
             var root = get_tree().get_root()
             current_scene = root.get_child( root.get_child_count() -1 )
             current_scene = root.get_child( root.get_child_count() -1 )
 
 
-Next, is the function for changing scene. This function will erase the
-current scene and replace it by the requested one.
+Next up is the function for changing the scene. This function frees the
+current scene and replaces it with the requested one.
 
 
 ::
 ::
 
 
@@ -152,8 +150,8 @@ situation of having the current scene being deleted while being used
 (code from functions of it being run), so using
 (code from functions of it being run), so using
 :ref:`Object.call_deferred() <class_Object_call_deferred>`
 :ref:`Object.call_deferred() <class_Object_call_deferred>`
 is desired at this point. The result is that execution of the commands
 is desired at this point. The result is that execution of the commands
-in the second function will happen at an immediate later time when no
-code from the current scene is running.
+in the second function will happen at a later time when no code from
+the current scene is running.
 
 
 Finally, all that is left is to fill the empty functions in scene_a.gd
 Finally, all that is left is to fill the empty functions in scene_a.gd
 and scene_b.gd:
 and scene_b.gd:
@@ -174,8 +172,8 @@ and
     func _on_goto_scene_pressed():
     func _on_goto_scene_pressed():
             get_node("/root/global").goto_scene("res://scene_a.scn")
             get_node("/root/global").goto_scene("res://scene_a.scn")
 
 
-Finally, by running the project it's possible to switch between both
-scenes by pressing the button!
+Now if you run the project, you can switch between both scenes by pressing
+the button!
 
 
-(To load scenes with a progress bar, check out the next tutorial,
-:ref:`doc_background_loading`)
+To load scenes with a progress bar, check out the next tutorial,
+:ref:`doc_background_loading`