Write nodes and scenes

Closes #4170

classes/class_node.rst

@@ -43,7 +43,7 @@ Finally, when a node is freed with :ref:`Object.free<class_Object_method_free>`
 Tutorials
 ---------
 
-- :doc:`../getting_started/step_by_step/scenes_and_nodes`
+- :doc:`../getting_started/step_by_step/nodes_and_scenes`
 
 Properties
 ----------

community/contributing/editor_and_docs_localization.rst

@@ -171,8 +171,8 @@ translating.
   a page that you want to translate, and then translate all the strings with the
   same source string location while comparing with the online version of that
   page in English. An example of source string location could be
-  ``getting_started/step_by_step/scenes_and_nodes.rst`` for the
-  page :ref:`doc_scenes_and_nodes`.
+  ``getting_started/step_by_step/nodes_and_scenes.rst`` for the
+  page :ref:`doc_nodes_and_scenes`.
 - The class reference's translation template is generated from the source XML
   files in **alphabetical order**, which is also the same as the order of the
   table of contents for the online version. You can therefore locate the source
@@ -184,7 +184,7 @@ translating.
 
 A handy tool to locate specific pages/classes is to use Weblate's advanced
 search feature, and especially the "Location strings" query (which can also be
-used with the ``location:`` token, e.g. ``location:scenes_and_nodes.rst``):
+used with the ``location:`` token, e.g. ``location:nodes_and_scenes.rst``):
 
 .. image:: img/l10n_05_search_location.png
 
@@ -194,9 +194,9 @@ used with the ``location:`` token, e.g. ``location:scenes_and_nodes.rst``):
 
     When a given source string is used in multiple source locations, they will
     all be concatenated into one. For example, the above
-    ``location:scenes_and_nodes.rst`` query would land first on the
+    ``location:nodes_and_scenes.rst`` query would land first on the
     "Introduction" source string which is used in dozens of pages, including
-    some that come before ``scenes_and_nodes.rst`` in the template. Clicking the
+    some that come before ``nodes_and_scenes.rst`` in the template. Clicking the
     "Next" button then brings us to the "Scene and nodes" title string displayed
     above.
     So it may happen that a given paragraph or section title is not at the

getting_started/step_by_step/index.rst

@@ -1,11 +1,22 @@
 Step by step
 ============
 
+This series builds upon the :ref:`Introduction to Godot
+<toc-learn-introduction>` and will get you started with the editor and the
+engine. You will learn more about nodes and scenes, code your first classes with
+GDScript, use signals to make nodes communicate with one another, and more.
+
+The following lessons are here to prepare you for :ref:`doc_your_first_game`, a
+step-by-step tutorial where you will code a game from scratch. By the end of it,
+you will have the necessary foundations to explore more features in other
+sections. We also included links to pages that cover a given topic in-depth
+where appropriate.
+
 .. toctree::
    :maxdepth: 1
    :name: toc-learn-step_by_step
 
-   scenes_and_nodes
+   nodes_and_scenes
    instancing
    instancing_continued
    scripting

getting_started/step_by_step/nodes_and_scenes.rst

@@ -0,0 +1,196 @@
+.. The goal of this page is to explain more than doc_key_concepts_overview about nodes and scenes, get the user to create their first concrete scene.
+
+.. _doc_nodes_and_scenes:
+
+Nodes and Scenes
+================
+
+In :ref:`doc_key_concepts_overview`, we saw that a Godot game is a tree of
+scenes and that each scene is a tree of nodes. In this lesson, we explain a bit
+more about them. You will also create your first scene.
+
+Nodes
+-----
+
+**Nodes are the fundamental building blocks of your game**. They are like the
+ingredients in a recipe. There are dozens of kinds that can display an image,
+play a sound, represent a camera, and much more.
+
+.. image:: img/nodes_and_scenes_nodes.png
+
+All nodes have the following attributes:
+
+- A name.
+- Editable properties.
+- They receive callbacks to update every frame.
+- You can extend them with new properties and functions.
+- You can add them to another node as a child.
+
+The last attribute is key. **Together, nodes form a tree**, which is a powerful
+feature to organize projects. Since different nodes have different functions,
+combining them produces more complex behavior. As we saw before, you can build a
+playable character the camera follows using a kinematic body node named
+"Character", a sprite node, a camera node, and a collision shape node.
+
+.. image:: img/nodes_and_scenes_character_nodes.png
+
+Scenes
+------
+
+When you organize nodes in a tree, like our character, we call this construct a
+scene. Once saved, scenes work like new node types in the editor, where you can
+add them as a child of an existing node. In that case, the instance of the scene
+appears as a single node with its internals hidden.
+
+Scenes allow you to structure your game's code however you want. You can
+**compose nodes** to create custom and complex node types, like a game character
+that runs and jumps, a life bar, a chest with which you can interact, and more.
+
+.. image:: img/nodes_and_scenes_3d_scene_example.png
+
+The Godot editor essentially is a **scene editor**. It has plenty of tools for
+editing 2D and 3D scenes, as well as user interfaces. A Godot project can
+contain as many of these scenes as you need. The engine only requires one as
+your application's **main scene**. This is the scene Godot will first load when
+you or a player runs the game.
+
+On top of acting like nodes, scenes have the following attributes:
+
+1. They always have one root node, like the "Character" in our example.
+2. You can save them to your hard drive and load them later.
+3. You can create as many instances of a scene as you'd like. You could have
+   five or ten characters in your game, created from your Character scene.
+
+Creating your first scene
+-------------------------
+
+Let's create our first scene with a single node. To do so, you will need to
+:ref:`create a new project <doc_creating_and_importing_projects>` first. After
+opening the project, you should see an empty editor.
+
+.. image:: img/nodes_and_scenes_01_empty_editor.png
+
+In an empty scene, the Scene dock on the left shows several options to add a
+root node quickly. "2D Scene" adds a Node2D node, "3D Scene" adds a Spatial
+node, "User Interface" adds a Control node, and "Other Node" lets you select any
+node. It is equivalent to pressing the "Add Child Node" button. These presets
+are here for convenience; they are not mandatory.
+
+We're going to add a single Label node to our scene. Its function is to draw
+text on the screen.
+
+Press the "Add Child Node" button at the top left of the Scene dock to create a
+node. This button adds the chosen node as a child of the currently selected one
+or, in an empty scene, as the root.
+
+.. image:: img/nodes_and_scenes_02_scene_dock.png
+
+The Create Node dialog opens, showing the long list of available nodes.
+
+.. image:: img/nodes_and_scenes_03_create_node_window.png
+
+Select the Label node. You can type its name to filter down the list.
+
+.. image:: img/nodes_and_scenes_04_create_label_window.png
+
+Click on the Label node to select it and click the Create button at the bottom
+of the window.
+
+.. image:: img/nodes_and_scenes_05_editor_with_label.png
+
+A lot happens when you add a scene's first node. The scene changes to the 2D
+workspace because Label is a 2D node type. The Label appears, selected, in the
+top-left corner of the viewport. The node appears in the Scene dock on the left,
+and the node's properties appear in the Inspector dock on the right.
+
+Changing a node's properties
+----------------------------
+
+The next step is to change the Label's "Text" property. Let's change it to
+"Hello World".
+
+Head to the Inspector dock on the right of the viewport. Click inside the field
+below the Text property and type "Hello World".
+
+.. image:: img/nodes_and_scenes_06_label_text.png
+
+You will see the text draw in the viewport as you type.
+
+.. seealso:: You can edit any property listed in the Inspector as we did with
+             the Text. For a complete reference of the Inspector dock, see the
+             :ref:`doc_editor_inspector_dock`.
+
+You can move your Label node in the viewport by selecting the move tool in the
+toolbar.
+
+.. image:: img/nodes_and_scenes_07_move_tool.png
+
+With the Label selected, click and drag anywhere in the viewport to
+move it to the center of the view delimited by the rectangle.
+
+.. image:: img/nodes_and_scenes_08_hello_world_text.png
+
+Running the scene
+-----------------
+
+Everything's ready to run the scene! Press the Play Scene button in the
+top-right of the screen or press :kbd:`F6`.
+
+.. image:: img/nodes_and_scenes_09_play_scene_button.png
+
+A popup invites you to save the scene, which is required to run it.
+
+.. image:: img/nodes_and_scenes_10_save_scene_popup.png
+
+Click the Yes button, and in the file browser that appears, press the Save
+button to save it as "Label.tscn".
+
+.. image:: img/nodes_and_scenes_11_save_scene_as.png
+
+.. note:: The Save Scene As dialog, like other file dialogs in the editor, only
+          allows you to save files inside the project. The ``res://`` path at
+          the top of the window represents the project's root directory and
+          stands for "resource path". For more information about file paths in
+          Godot, see :ref:`doc_filesystem`.
+
+The application should open in a new window and display the text "Hello World".
+
+.. image:: img/nodes_and_scenes_12_final_result.png
+
+Close the window or press :kbd:`F8` to quit the running scene.
+
+.. note::
+
+    If this doesn't immediately work and you have a hiDPI display on at least
+    one of your monitors, go to Project -> Project Settings -> Display ->
+    Window then enable Allow Hidpi under Dpi.
+
+Setting the main scene
+----------------------
+
+To run our test scene, we used the Play Scene button. Another button next to it
+allows you to set and run the project's main scene. You can press :kbd:`F5` to
+do so.
+
+.. image:: img/nodes_and_scenes_13_play_button.png
+
+A popup window appears and invites you to select the main scene.
+
+.. image:: img/nodes_and_scenes_14_main_scene_popup.png
+
+Click the Select button, and in the file dialog that appears, double click on
+Label.tscn.
+
+.. image:: img/nodes_and_scenes_15_select_main_scene.png
+
+The demo should run again. Moving forward, every time you run the project, Godot
+will use this scene as a starting point.
+
+.. note:: The editor saves the main scene's path in a project.godot file in your
+          project's directory. While you can edit this text file directly to
+          change project settings, you can also use the "Project -> Project
+          Settings" window to do so. For more information, see
+          :ref:`doc_project_settings`.
+
+In the next part, we will discuss another key concept in games and in Godot:
+creating instances of a scene.

getting_started/step_by_step/scenes_and_nodes.rst

@@ -1,216 +0,0 @@
-.. _doc_scenes_and_nodes:
-
-Scenes and nodes
-================
-
-Introduction
-------------
-
-.. image:: img/chef.png
-
-Imagine for a second that you are not a game developer anymore. Instead,
-you're a chef! Change your hipster outfit for a toque and a double
-breasted jacket. Now, instead of making games, you create new and
-delicious recipes for your guests.
-
-So, how does a chef create a recipe? Recipes are divided into two
-sections: the first is the ingredients and the second is the
-instructions to prepare it. This way, anyone can follow the recipe and
-savor your magnificent creation.
-
-Making games in Godot feels pretty much the same way. Using the engine
-feels like being in a kitchen. In this kitchen, *nodes* are like a
-refrigerator full of fresh ingredients with which to cook.
-
-There are many types of nodes. Some show images, others play sound,
-other nodes display 3D models, etc. There are dozens of them.
-
-Nodes
------
-
-But let's start with the basics. Nodes are fundamental building blocks for
-creating a game. As mentioned above, a node can perform a variety of specialized
-functions. However, any given node always has the following attributes:
-
--  It has a name.
--  It has editable properties.
--  It can receive a callback to process every frame.
--  It can be extended (to have more functions).
--  It can be added to another node as a child.
-
-.. image:: img/tree.png
-
-The last one is important. Nodes can have other nodes as
-children. When arranged in this way, the nodes become a **tree**.
-
-In Godot, the ability to arrange nodes in this way creates a powerful
-tool for organizing projects. Since different nodes have different
-functions, combining them allows for the creation of more complex functions.
-
-Don't worry if this doesn't click yet. We will continue to explore this over
-the next few sections. The most important fact to remember for now is that
-nodes exist and can be arranged this way.
-
-Scenes
-------
-
-.. image:: img/scene_tree_example.png
-
-Now that the concept of nodes has been defined, the next logical
-step is to explain what a Scene is.
-
-A scene is composed of a group of nodes organized hierarchically (in
-tree fashion). Furthermore, a scene:
-
--  always has one root node.
--  can be saved to disk and loaded back.
--  can be *instanced* (more on that later).
-
-Running a game means running a scene. A project can contain several scenes,
-but for the game to start, one of them must be selected as the main scene.
-
-Basically, the Godot editor is a **scene editor**. It has plenty of tools for
-editing 2D and 3D scenes as well as user interfaces, but the editor is based on
-the concept of editing a scene and the nodes that compose it.
-
-Editor
-------
-
-Open the project you made in :ref:`doc_intro_to_the_editor_interface`, or create a new one. This will
-open the Godot editor:
-
-.. image:: img/empty_editor.png
-
-As mentioned before, making games in Godot feels like being in a
-kitchen, so let's open the refrigerator and add some fresh nodes to the
-project. We'll begin with a "Hello World" message that we'll put on the
-screen.
-
-To do this we need to add a Label node. Press the "Add Child Node" button
-at the top left of the scene dock (the icon represents a plus symbol).
-This button is the main way to add new nodes to a scene, and will always
-add the chosen node as a child of the currently selected node (or, in an
-empty scene, as the "root" node).
-
-.. note::
-
-    In an empty scene (without root node), the scene dock shows several
-    options to quickly add a root node to the scene. "2D Scene" adds a
-    Node2D node, "3D Scene" adds a Spatial node, "User Interface" adds a
-    Control node, and "Other Node" which lets you select any node (so it
-    is equivalent to pressing the "Add Child Node" button). You can also
-    press the star-shaped icon to toggle the display of your favorited
-    nodes.
-
-    Note that these presets are here for convenience and are not mandatory
-    for the different types of scenes. Not every 3D scene needs a Spatial
-    node as its root node, likewise not every GUI or 2D scene needs a Control
-    node or Node2D as their root node.
-
-Now, to add a label node to this scene you can click on the Other Node
-button or the Add Node button at the top. In scenes that aren't empty you
-use the add node button to create every child node.
-
-.. image:: img/newnode_button.png
-
-This will open the Create Node dialog, showing the long list of nodes
-that can be created:
-
-.. image:: img/node_classes.png
-
-From there, select the "Label" node first. Searching for it is probably
-the fastest way:
-
-.. image:: img/node_search_label.png
-
-And finally, create the Label! A lot happens when Create is pressed:
-
-.. image:: img/editor_with_label.png
-
-First of all, the scene changes to the 2D editor (because Label is a 2D Node
-type), and the Label appears, selected, at the top left corner of the viewport.
-
-The node appears in the scene tree editor in the Scene dock, and the label
-properties appear in the Inspector dock.
-
-The next step will be to change the "Text" Property of the label. Let's
-change it to "Hello World":
-
-.. image:: img/hw.png
-
-Ok, everything's ready to run the scene! Press the PLAY SCENE Button on
-the top bar (or hit :kbd:`F6`):
-
-.. image:: img/playscene.png
-
-Aaaand... Oops.
-
-.. image:: img/neversaved.png
-
-Scenes need to be saved to be run, so save the scene to something like
-Hello.tscn in Scene -> Save:
-
-.. image:: img/save_scene.png
-
-And here's when something funny happens. The file dialog is a special
-file dialog, and only allows you to save inside the project. The project
-root is ``res://`` which means "resource path". This means that files can
-only be saved inside the project. For the future, when doing file
-operations in Godot, remember that ``res://`` is the resource path, and no
-matter the platform or install location, it is the way to locate where
-resource files are from inside the game.
-
-After saving the scene and pressing run scene again, the "Hello World"
-demo should finally execute:
-
-.. image:: img/helloworld.png
-
-Success!
-
-.. note::
-
-    If this doesn't immediately work and you have a hiDPI display on
-    at least one of your monitors, go to
-    **Project → Project Settings → Display → Window** then enable
-    **Allow Hidpi** under **Dpi**.
-
-.. _doc_scenes_and_nodes-configuring_the_project:
-
-Configuring the project
------------------------
-
-Ok, it's time to configure the project. Right now, the only way to run
-something is to execute the current scene. Projects, however, may have several
-scenes, so one of them must be set as the main scene. This is the scene that
-will be loaded any time the project is run.
-
-These settings are all stored in a project.godot file, which is a plaintext
-file in win.ini format (for easy editing). There are dozens of settings that
-you can change in this file to alter how a project executes. To simplify this
-process, Godot provides a project settings dialog, which acts as a sort of
-frontend to editing a project.godot file.
-
-To access that dialog, select Project -> Project Settings. Try it now.
-
-Once the window opens, let's select a main scene. Locate the
-`Application/Run/Main Scene` property and click on it to select 'Hello.tscn'.
-
-.. image:: img/main_scene.png
-
-Now, with this change, when you press the regular Play button (or F5), this
-scene will run, no matter which scene is actively being edited.
-
-The project settings dialog provides a lot of options that can be saved to a
-project.godot file and shows their default values. If you change a value, a
-tick is marked to the left of its name. This means that the property will be
-saved to the project.godot file and remembered.
-
-As a side note, it is also possible to add custom configuration options and
-read them in at run-time using the :ref:`ProjectSettings <class_ProjectSettings>` singleton.
-
-To be continued...
-------------------
-
-This tutorial talked about "scenes and nodes", but so far there has been
-only *one* scene and *one* node! Don't worry, the next tutorial will
-expand on that...

getting_started/step_by_step/your_first_game.rst

@@ -34,7 +34,7 @@ images and sounds you'll be using to make the game. Unzip these files in your
 project folder.
 
 .. note:: For this tutorial, we will assume you are familiar with the
-          Godot editor. If you haven't read :ref:`doc_scenes_and_nodes`, do so now
+          Godot editor. If you haven't read :ref:`doc_nodes_and_scenes`, do so now
           for an explanation of setting up a project and using the editor.
 
 This game is designed for portrait mode, so we need to adjust the size of the

tutorials/editor/index.rst

@@ -17,6 +17,8 @@ in other sections where appropriate. For example, the :ref:`animation editor
    :name: toc-editor-interface
 
    project_manager
+   inspector_dock
+   project_settings
    default_key_mapping
    customizing_editor
 

tutorials/editor/inspector_dock.rst

@@ -0,0 +1,39 @@
+
+.. _doc_editor_inspector_dock:
+
+The Inspector
+=============
+
+This page explains how the Inspector dock works in-depth. You will learn how to edit properties, fold and unfold areas, use the search bar, and more.
+
+.. warning:: This page is a work-in-progress.
+
+Overview of the interface
+-------------------------
+
+Let's start by looking at the dock's main parts.
+
+.. image:: img/inspector_overview.png
+
+At the top are the file and navigation buttons.
+
+.. image:: img/inspector_top_buttons.png
+
+Below it, you can find the selected node's name, its type, and the tools menu on the right side.
+
+.. image:: img/inspector_node_name_and_tools.png
+
+If you click the tool menu icon, a drop-down menu offers some view and edit options.
+
+.. image:: img/inspector_tools_menu.png
+
+Then comes the search bar. Type anything in it to filter displayed properties. Delete the text to clear the search.
+
+.. image:: img/inspector_search_bar.png
+
+.. break down inspector content in class name, property categories that are foldable, and individual properties.
+
+.. Using the buttons at the top.
+.. Using the tool menu
+.. List each property type and how to edit it
+.. For numerical inputs, mention and link to a page about formulas

tutorials/editor/project_manager.rst

@@ -13,6 +13,8 @@ editor's language.
 
 .. image:: img/editor_ui_intro_project_manager_02.png
 
+.. _doc_creating_and_importing_projects:
+
 Creating and importing projects
 -------------------------------
 
@@ -21,7 +23,7 @@ To create a new project:
 1. Click the ``New Project`` button on the right of the window.
 2. Give the project a name, choose an empty folder on your computer to save the
    files, and select a rendering backend.
-3. Click the Create & Edit button.
+3. Click the Create & Edit button to create the project folder and open it in the editor.
 
 .. image:: img/editor_ui_intro_project_manager_04.png
 

tutorials/editor/project_settings.rst

@@ -0,0 +1,14 @@
+.. _doc_project_settings:
+
+Project Settings
+================
+
+This page explains how to use the Project Settings window. If you would like to access and modify project settings via code, see :ref:`ProjectSettings <class_ProjectSettings>`.
+
+Godot stores the project settings in a project.godot file, a plain text file in INI format. There are dozens of settings you can change to control a project's execution. To simplify this process, Godot provides a project settings dialog, which acts as a front-end to editing a project.godot file.
+
+To access that dialog, select Project -> Project Settings.
+
+Once the window opens, let's select a main scene. Locate the `Application/Run/Main Scene` property and click on it to select 'Hello.tscn'.
+
+The project settings dialog provides a lot of options that can be saved to a project.godot file and shows their default values. If you change a value, a tick appears to the left of its name. This means that the property will be saved in the project.godot file and remembered.