Merge pull request #969 from godotengine/kcc_doc_revisions

Update Instancing doc and images

learning/step_by_step/instancing.rst

@@ -3,109 +3,113 @@
 Instancing
 ==========
 
-Rationale
+Introduction
 ---------
 
-Having a scene and throwing nodes into it might work for small projects, but as
-a project grows, you will naturally add more and more nodes and it can quickly
-become unmanageable. To solve this, Godot allows a project to be separated into
-several scenes. This, however, does not work the same way as in other game
-engines. In fact, it's quite different, so please do not skip this tutorial!
+Creating a single scene and adding nodes into it might work for small
+projects, but as a project grows in size and complexity, the number of nodes
+can quickly become unmanageable. To address this, Godot allows a project
+to be separated into any number scenes. This provides you with a powerful
+tool to organize the different components of your game.
 
-To recap: A scene is a collection of nodes organized as a tree, where
-they can have only one single node as the tree root.
+In :ref:`doc_scenes_and_nodes` you learned that a scene is a collection of
+nodes organized in a tree structure, with a single node as the tree root.
 
 .. image:: img/tree.png
 
-Recall that a scene can be created and saved to disk. You can create and save
-as many scenes as you desire.
+You can create as many scenes as you like and save them to disk. Scenes 
+saved in this manner are called "Packed Scenes" and have a ``.tscn`` filename
+extension.
 
 .. image:: img/instancingpre.png
 
-Afterwards, while editing any scene, you can instance other scenes as part of
-it:
+Once a scene has been saved, it can be instanced into another scene just as
+if it were any other node.
 
 .. image:: img/instancing.png
 
-In the above picture, Scene B was added to Scene A as an instance. It may seem
-weird at first, but by the end of this tutorial it should make complete sense.
+In the above picture, Scene B was added to Scene A as an instance.
 
-Instancing, step by step
-------------------------
+Instancing By Example
+---------------------
 
-To learn how to do instancing, let's start with downloading a sample
+To learn how instancing works, let's start by downloading a sample
 project: :download:`instancing.zip <files/instancing.zip>`.
 
-Unzip this project anywhere you like. Then, open Godot and add this project to
-the project manager using the 'Import' option:
+Unzip this project anywhere you like. Then open Godot and add this project to
+the project manager using the 'Import' button:
 
-.. image:: img/importproject.png
+.. image:: img/instancing_import.png
 
-Simply browse to the folder you extracted and open the "project.godot" file you
+Browse to the folder you extracted and open the "project.godot" file you
 can find inside it. After doing this, the new project will appear on the list
 of projects. Edit the project by pressing the 'Edit' button.
 
-This project contains two scenes, "ball.tscn" and "container.tscn". The ball
-scene is just a ball with physics, while the container scene has a nicely
-shaped collision, so balls can be dropped in there.
+This project contains two scenes: "Ball.tscn" and "Main.tscn". The ball
+scene uses a :ref:`RigidBody2D <class_RigidBody2D>` to provide physics
+behavior while the main scene has a set of obstacles for the ball to
+collide with (using :ref:`StaticBody2D <class_StaticBody2D>`).
 
-.. image:: img/ballscene.png
+.. image:: img/instancing_ballscene.png
 
-.. image:: img/contscene.png
+.. image:: img/instancing_mainscene.png
 
-Open the container scene, and then select the root node:
+Open the ``Main`` scene, and then select the root node:
 
-.. image:: img/controot.png
+.. image:: img/instancing_mainroot.png
 
-Afterwards, push the link shaped button. This is the instancing button!
+We want to add an instance of the ``Ball`` scene as a child of ``Main``.
+Click the "link"-shaped button (its hover-text says "Instance a scene file
+as a Node.") and select the ``Ball.tscn`` file.
 
-.. image:: img/continst.png
+.. image:: img/instancing_linkbutton.png
 
-Select the ball scene (ball.tscn). The ball should appear at the origin (0,0)
-which is at the top-left of the container scene. Drag the ball to the center of
-the scene, like this:
+The ball will be placed at the top-left corner of the screen area (this is
+``(0, 0)`` in screen coordinates). Click and drag the ball somewhere near
+the top-center of the scene:
 
-.. image:: img/continstanced.png
+.. image:: img/instancing_placeball.png
 
-Press Play and Voila!
+Press "Play" and watch the ball fall to the bottom of the screen:
 
-.. image:: img/playinst.png
+.. image:: img/instancing_playbutton.png
 
-The instanced ball should fall somewhere to the bottom of the pit before coming
-to rest.
+Multiple Instances
+------------------
 
-A little more
--------------
+You can add as many instances as you like to a scene, either by using the
+"Instance" button again, or by clicking on the ball instance and pressing
+"Duplicate" (Ctrl-D):
 
-You can create as many instances as you desire within a scene. Just try instancing
-more balls or duplicating them (via Ctrl-D or the duplicate button):
+.. image:: img/instancing_multiball.png
 
-.. image:: img/instmany.png
+Run the scene again and all of the balls will fall.
 
-Then try running the scene again:
-
-.. image:: img/instmanyrun.png
-
-Cool, huh? This is how instancing works.
+.. image:: img/instancing_multiball.gif
 
 Editing instances
 -----------------
 
-Select one of the many copies of the balls and go to the property
-editor. Let's make it bounce a lot more, so look for the Bounce
-parameter and set it to 1.0:
+Open the ``Ball`` scene and change the ``Bounce`` property in the Inspector
+to `1`. Press "Play" and notice that all of the instanced balls are now
+much more bouncy. Because the instanced balls are based on the saved scene,
+changes to that scene will affect all instances.
+
+You can also adjust individual instances. Set the bounce value back to ``0.5``
+and then in the ``Main`` scene, select one of the instanced balls. Set its
+``Bounce`` to ``1`` and press "Play".
 
-.. image:: img/instedit.png
+.. image:: img/instancing_property.png
 
-Grey "revert" button will appear. When
-this button is present, it means we modified a property in the
-instanced scene to override a specific value in this instance. Even
+Notice that a grey "revert" button appears next to the adjusted property. When
+this button is present, it means you modified a property in the
+instanced scene to override its value in the saved scene. Even
 if that property is modified in the original scene, the custom value
-will always overwrite it. Pressing the revert button will restore the
-property to the original value that came from the scene.
+will remain. Pressing the revert button will restore the property to the
+value in the saved scene.
 
 Conclusion
 ----------
 
-Instancing seems handy, but there is more to it than meets the eye!
-The next part of the instancing tutorial should cover the rest..
+Instancing can be very useful when you want to create many copies of the
+same object.

learning/step_by_step/your_first_game.rst

@@ -412,7 +412,7 @@ node and add this code:
 
 ::
 
-    func _on_Visible_screen_exited():
+    func _on_Visibility_screen_exited():
         queue_free()
 
 That completes the `Mob` scene.