Merge pull request #616 from capnm/rst_clean_up5

Clean up markup

community/contributing/pr_workflow.rst

@@ -3,7 +3,7 @@
 Pull request workflow
 =====================
 
-.. highlight:: shell
+.. highlight:: none
 
 The so-called "PR workflow" used by Godot is common to many projects using
 Git, and should be familiar to veteran free software contributors. The idea
@@ -129,6 +129,7 @@ a feature branch:
 
     // Create the branch based on the current branch (master)
     $ git branch better-project-manager
+
     // Change the current branch to the new one
     $ git checkout better-project-manager
 
@@ -231,21 +232,27 @@ Here's how the shell history could look like on our example:
 
     // It's nice to know where you're starting from
     $ git log
+
     // Do changes to the project manager
     $ nano editor/project_manager.cpp
+
     // Find an unrelated bug in Control and fix it
     $ nano scene/gui/control.cpp
+
     // Review changes
     $ git status
     $ git diff
+
     // We'll do two commits for our unrelated changes,
     // starting by the Control changes necessary for the PM enhancements
     $ git add scene/gui/control.cpp
     $ git commit -m "Fix handling of margins in Control"
+
     // Check we did good
     $ git log
     $ git show
     $ git status
+
     // Make our second commit
     $ git add editor/project_manager.cpp
     $ git commit -m "Add a pretty banner to the project manager"
@@ -315,6 +322,7 @@ branch, push it to your fork, and the PR will be updated automatically:
 
     // Check out your branch again if you had changed in the meantime
     $ git checkout better-project-manager
+
     // Fix a mistake
     $ nano editor/project_manager.cpp
     $ git add editor/project_manager.cpp

development/compiling/introduction_to_the_buildsystem.rst

@@ -3,7 +3,7 @@
 Introduction to the buildsystem
 ===============================
 
-.. highlight:: shell
+.. highlight:: none
 
 SCons
 -----

learning/features/3d/environment_and_post_processing.rst

@@ -263,7 +263,7 @@ The real strength of this system, though, is to combine levels to create more in
 
 .. image:: img/environment_glow_layers2.png
  
-Finally, as the highest layers are created by stretching small blurred images, it is possible that some blockyness may be visible. Enabling **Bicubic Upscaling* gets rids of the it,
+Finally, as the highest layers are created by stretching small blurred images, it is possible that some blockyness may be visible. Enabling **Bicubic Upscaling** gets rids of the it,
 at a minimal performance cost.
 
 .. image:: img/environment_glow_bicubic.png

learning/scripting/gdscript/gdscript_basics.rst

@@ -373,10 +373,10 @@ and a ``d`` scalar distance.
 Quaternion is a datatype used for representing a 3D rotation. It's
 useful for interpolating rotations.
 
-:ref:`Rect3 <class_Rect3>`
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+:ref:`AABB <class_AABB>`
+^^^^^^^^^^^^^^^^^^^^^^^^
 
-Axis Aligned bounding box (or 3D box) contains 2 vectors fields: ``position``
+Axis-aligned bounding box (or 3D box) contains 2 vectors fields: ``position``
 and ``size``. Alternatively contains an ``end`` field which is
 ``position+size``.
 

learning/scripting/visual_script/visual_script_basics.rst

@@ -1,669 +0,0 @@
-.. _doc_visual_script:
-
-Visual Scripting
-================
-
-Introduction
-------------
-
-Visual Scripting is a tool designed to make the entry barrier to programming
-much lower. As code is more visual, it needs less abstract thinking to be
-understood. Any artist, animator, game designer, etc. can look at it and quickly
-grasp the flow of logic.
-
-The reason it does not make existing programming obsolete is, simply, that it does not scale as well.
-It takes considerably more time to create code with it, and it's often more difficult
-to modify than just writing a few characters.
-
-With the misunderstanding cleared up, the question that remains is what are the practical
-uses for Visual Scripting.
-
-The most common use cases are are as follows:
-
-* Game development beginners who want to learn an engine but have no programming experience yet.
-* Artists and Game Designers who have no experience in programming and want to create quick prototypes or simple games.
-* Programmers working in a team that want to make part of the game logic available to Artists or Game Designers in order to offload some of their work.
-
-These scenarios are far more common than one might think, so this is why Godot has added this feature.
-
-Visual Scripting in Godot
--------------------------
-
-As with everything in Godot, we prioritize a good experience over copying or integrating third party solutions 
-which might not fit nicely in the current workflow. This led us to write our own version of how we believe
-this feature would work best with the engine.
-
-In Godot, a Visual Script fits smoothly together with regular scripts in the Editor tab
-
-.. image:: img/visual_script1.png
-
-
-In fact, Visual Scripting integrates so well to Godot that it's hard to believe it was added only
-in version 3.0. This is because, when editing, the rest of Godot panels and docks act like a
-palette from where you can drag and drop all sorts of information to the script canvas:
-
-.. image:: img/visual_script2.png
-
-
-Creating a Script
------------------
-
-Creating scripts works the same as with other scripting languages: Just select any node in the scene
-and push the "New Script" button at the top right corner of the Scene Tree dock:
-
-.. image:: img/visual_script3.png
-
-
-Once it opens, the script type "Visual Script" must be selected from the drop down list. The script extension
-must be ".vs" (for Visual Script!).
-
-.. image:: img/visual_script4.png
-
-
-Finally, the Script Editor will open, allowing to start the editing of the visual script:
-
-.. image:: img/visual_script5.png
-
-
-Adding a Function
------------------
-
-Unlike other visual scripting implementations, Visual Scripting in Godot is heavily based on functions.
-This happens because it uses the same interface to communicate with the engine as other scripting engines.
-In Godot, the scripting interface is universal and all implementations conform to it.
-
-A function is an individual canvas with nodes connected.
-
-A single script can contain many functions, each of which will have a canvas of its own, allowing for more organization.
-
-There are three main ways to add functions in a script:
-
-Overriding a Virtual Function
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Most types of nodes and other types of objects in Godot contain virtual functions. These are functions that
-will be called (run your code) when something happens and can be looked up in the reference. Virtual functions
-are listed when pressing the "Override" icon in the member panel:
-
-.. image:: img/visual_script6.png
-
-
-In the following example, a function will be executed when the node is loaded and added to the running scene.
-For this, the _ready() virtual method will be overridden:
-
-.. image:: img/visual_script7.png
-
-
-Finally, a canvas appears for this function, showing the override:
-
-.. image:: img/visual_script8.png
-
-
-As some functions expect you to return a value, they will also add a return node where such value is supposed to be
-provided:
-
-.. image:: img/visual_script9.png
-
-
-Connecting a Signal to a Function
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Nodes in a tree emit signals when something happens. Godot uses signals for all sorts of things.
-A typical example would be a button that emits a "pressed" signal when actually pressed.
-
-For this, a node must be selected and the Node tab opened. This will allow inspecting the signals.
-Once they are displayed, connect the "pressed" signal:
-
-.. image:: img/visual_script10.png
-
-
-This will open the connection dialog. In this dialog, you must select the node where the signal will be
-connected to, and the function that will receive the signal:
-
-.. image:: img/visual_script11.png
-
-
-If this is done right, a new function will be created in our script and a signal will automatically be
-connected to it:
-
-.. image:: img/visual_script12.png
-
-
-Creating a Function Manually
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The last way to create functions is to do it manually. In general this is not as common unless you
-really need it. Custom functions work when another (or the same) script calls them manually.
-The main use case for this is to separate a function into more, or reusing your visual code.
-
-To create a function manually, push the big "Plus" button, and a new function will be added
-with a default name:
-
-.. image:: img/visual_script13.png
-
-
-This will add a new function, which can be renamed by simply double clicking its name:
-
-
-.. image:: img/visual_script14.png
-
-
-To edit the "arguments" this function can get (the values you pass to it when you call this function),
-simply click the Function node and check the inspector:
-
-.. image:: img/visual_script15.png
-
-
-More on that will be explained later in this document.
-
-
-Nodes and Terminology
-----------------------
-
-Before continuing, it must be noted that the *Node* terminology needs to be used with care. 
-When referring to *Visual Script Nodes* (or generally *Nodes*) this text will refer to the little boxes you connect with lines, which are part of a graph.
-When referring to *Scene Nodes*, it is implied that the elements that make up a Scene are being referred, which are part of a tree. Their naming is similar but their function is different.
-When referring to *Node* here, it will be implied that a *Visual Script Node* is referred to unless indicated otherwise.
-
-.. image:: img/visual_script16.png
-
-
-Node Properties
----------------
-
-Like in most visual scripting implementations, each node has editable properties. In Godot, though, we try to avoid
-bloating the nodes with editable controls for the sake of readability. 
-
-Nodes still display the required information as text, but editing is done via the *Inspector*. To edit them, just
-select any node and edit its properties in the *Inspector*.
-
-
-Ports and Connections
----------------------
-
-Programming in Godot Visual Scripting is done via *Nodes* and *Port Connections* inside each function. 
-
-
-Ports
-~~~~~
-
-Nodes in Godot Visual Scripting have *Ports*. These are endpoints that appear to the 
-left and right of nodes and which can be used to make *Connnections*:
-There are two types of *Ports*: *Sequence* and *Data*.
-
-.. image:: img/visual_script17.png
-
-
-*Sequence Ports* indicate the order in which operations are executed. 
-Typically when a *Node* is done processing, it will go to the next node from one of the ports at the right. 
-If nothing is connected the function may end, or another output *Sequence Port* might be tried (this depends on the node). 
-Thanks to this, it's easy to understand the logic within a function by just following the white lines.
-Not every *Node* has *Sequence Ports*. In fact, most do not.
-
-*Data Ports* ports contain typed values. Types can be any regular Godot types, 
-such as a boolean, an integer, a string, a Vector3, an array, any Object or Scene Node, etc. 
-A *Data Port* on the right side of a node is considered an output, while, 
-a port on the left side is an input. Connecting them allows information to flow to the next node. 
-
-Not all *Data Port* types are compatible and will allow connections, though.
-Pay special attention to colors and icons, as each type has a different representation:
-
-.. image:: img/visual_script18.png
-
-
-Connections
-~~~~~~~~~~~
-
-Connecting is a relatively simple process. Just drag an *Output Port* towards an *Input Port*. 
-
-.. image:: img/visual_script_connect.gif
-
-
-Disconnecting takes a bit more practice. Disconnecting in *Data Ports* happens by 
-dragging the *Input* away, while for *Sequence Ports*, this happens by dragging the *Output* away.
-
-.. image:: img/visual_script_disconnect.gif
-
-
-This may seem strange at the beginning, but it happens because *Data Ports* are 1:N 
-(A single output port can connect to many inputs), while *Sequence Ports* are N:1 
-(Many sequence outputs can be connected to a single input).
-
-Connecting to empty space (drag to connect but unpress over empty space) is also context sensitive, it will supply
-a list of most common operations. For sequences, it will be conditional nodes:
-
-.. image:: img/visual_script52.png
-
-
-While, for data, a contextual set/get/call menu will open:
-
-.. image:: img/visual_script53.png
-
-
-Adding Nodes
-------------
-
-Finally! We got to the fun part! But, before explaining in more detail what each type of node does, 
-let's take a short look at how nodes are most commonly added and dealt with.
-
-
-Accessing Scene Nodes
-~~~~~~~~~~~~~~~~~~~~~
-
-One of the most common tasks is accessing Scene Tree Nodes (again, not to mistake with *Visual Script Nodes*).
-Dragging from the Scene Tree and dropping into the canvas will ask you to *call a method* (sometimes referred to as *member function*) on this node. 
-
-.. image:: img/visual_script19.png
-
-
-While accessing properties is desired in most cases (more on that below), sometimes *calling methods* can be useful too.
-Methods execute specific actions on objects. In the above case, the mouse pointer can be warped to a position in local
-coordinates to the control. Another common use case is queueing a node for deletion, which is done with the *queue_free* method.
-
-.. image:: img/visual_script20.png
-
-
-Care must be taken that this only works if the scene being edited contains your *Visual Script* in one of the nodes! Otherwise, a warning will be shown.
-
-
-Accessing Scene Node Properties
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This is the most common way to edit *Scene Nodes* in Visual Scripting. Select a *Scene Node* from the *Scene Tree*, go to the Inspector, find *the Name* of the property you want to edit (hint, *not* the value!) and drag it to the canvas:
-
-.. image:: img/visual_script21.png
-
-
-The result is that this value can be changed from your script by writing to a *Data Port*.
-
-If instead reading this value is desired, just drag the node again but hold the *Control* key (or Command on Mac). This will create a getter:
-
-.. image:: img/visual_script22.png
-
-
-In this case, the value can be read from a *Data Port*.
-
-
-Variables
-~~~~~~~~~
-
-Variables are memory containers local to the script which can hold a value. This value can be read from any of the functions of the script or from other scripts via the method described in the previous step.
-
-To add a Variable, push the "+" button on the *Variables* section of the Members panel. Double-click the new variable to rename it:
-
-.. image:: img/visual_script23.png
-
-
-Right-clicking the variable allows you to configure its properties:
-
-.. image:: img/visual_script24.png
-
-.. image:: img/visual_script25.png
-
-
-As it can be seen above, the type and initial value of the variable can be changed, as well as some property hints (@TODO, document this).
-Ticking the "Export" options makes the variable visible in the Inspector when selecting the node. This also makes it available to other scripts via the method described in the previous step.
-
-.. image:: img/visual_script28.png
-
-
-To use the variable in the script, simply drag it to the canvas to create a getter:
-
-.. image:: img/visual_script26.png
-
-
-Likewise, hold *Control* (*Command* on Mac) to drop a setter:
-
-.. image:: img/visual_script27.png
-
-
-Signals
-~~~~~~~
-
-It is also possible to create your own signals in a script and use them. For this, do the same steps you did for variables in the previous step, except for *Signals*:
-
-.. image:: img/visual_script29.png
-
-
-A signal can also be edited via right-click menu to customize its arguments:
-
-.. image:: img/visual_script30.png
-
-
-The signal you have just created will appear in the Inspector along with the built-in node signals. This allows you to connect it from another script from another *Scene Node*:
-
-.. image:: img/visual_script31.png
-
-
-Finally, to emit the signal, simply drag it to the canvas:
-
-.. image:: img/visual_script32.png
-
-
-Remember that emitting a signal is a sequenced operation, so it must come from a Sequence port.
-
-
-Adding More Nodes
------------------
-
-Now that the basics are covered, let's discuss the large amount of utility nodes available for your canvas!
-Below the member panel, exists the list of all available node types:
-
-.. image:: img/visual_script33.png
-
-
-Ctrl-F (Command-F on Mac) allows you to search the list.
-
-Any of them can be dragged to the scene. Unlike nodes (e.g. dragging a property
-from the Inspector sets the context to the node being edited automatically), these are added without any "contextual" information, so this has to be done manually.
-
-.. image:: img/visual_script34.png
-
-
-Remember that you can check the class reference for what each node does, as they are documented there. That mentioned,
-a brief overview of node types follows:
-
-
-Constants
-~~~~~~~~~
-
-Constant nodes are nodes that provide values that, while not changing over time, can be useful as reference values. 
-Most of the time they are integer or float.
-
-.. image:: img/visual_script36.png
-
-
-The first one is "Constant" which allows you to select any value of any type as constant, from an integer (42) to a String ("Hello!"). In general this node is not used that often because of default input values in *Data Ports*, but it's good to know it exists.
-
-The second is the GlobalConstant node, which contains a long list of constants for global types in Godot. In there
-you can find some useful constants to refer to key names, joystick or mouse buttons, etc.
-
-The third one is MathConstant, which provides typical mathematical constants such as PI, E, etc.
-
-
-Data
-~~~~
-
-Data nodes deal with all sorts of access to information. Any information in Godot is accessed via these nodes, so
-they are some of the most important ones to use and pretty diverse.
-
-.. image:: img/visual_script37.png
-
-
-There are many types of nodes of interest here, so a short attempt to describe them will follow:
-
-
-Action
-^^^^^^
-
-Action nodes are vital when dealing with input from a device. You can read more about actions in the (@TODO ACTION TUTE LINK).
-In the following example below, the control is moved to the right when the "move_right" action is pressed.
-
-.. image:: img/visual_script38.png
-
-
-Engine Singleton
-^^^^^^^^^^^^^^^^
-
-Engine singletons are global interfaces (meaning they can be accessed without a reference, unlike Scene Nodes, they are always available).
-They have several purposes, but in general they are useful for low level access or OS-related access.
-
-.. image:: img/visual_script39.png
-
-
-Remember that dragging a connection to empty space will help you call functions or set/get properties on these:
-
-.. image:: img/visual_script40.png
-
-
-Local Variables
-^^^^^^^^^^^^^^^
-
-These are nodes you can use as temporary storage for your graphs. Just make sure they all have the same name and type when using them and they will reference the same piece of memory.
-
-.. image:: img/visual_script41.png
-
-
-As it can be seen above, there are two nodes available: A simple getter, and a sequenced getter (setting requires a sequence port).
-
-
-Scene Node
-^^^^^^^^^^
-
-This is just a reference to a node in the tree, but it's easier to use this node by just dragging the actual node 
-from the scene tree to the canvas (this will create it and configure it).
-
-
-Self
-^^^^
-
-In some rare ocassions, it may be desired to pass this Scene Node as argument. 
-It can be used to call functions and set/get properties, or just drag nodes (or event the node itself that has the script) from the Scene Tree to the canvas for this.
-
-
-SceneTree
-^^^^^^^^^
-
-This node is similar to the Singleton node because it references the SceneTree, which contains the active scene.
-SceneTree, however, only works when the node is sitting in the scene and active, otherwise accessing it will
-return as an error.
-
-SceneTree allows for many low level things, like setting stretch options, calling groups, make timers, or even
-load another scene. It's a good class to get familiar with.
-
-
-Preload
-^^^^^^^
-
-This does the same function as preload() in GDScript. It maintains this resource loaded and ready to use. Rather than
-instancing the node, it's simpler to just drag the desired resource from the filesystem dock to the canvas.
-
-
-Resource Path
-^^^^^^^^^^^^^
-
-This node is a simple helper to get a string with a path to a resource you can pick. It's useful in functions that
-load things from disk.
-
-
-Comment
-^^^^^^^
-
-A Comment node works as a node you can resize to put around other nodes. It will not try to get focus or be brought
-to top when selecting it. It can also be used to write text on it.
-
-.. image:: img/visual_script42.png
-
-
-Flow Control
-~~~~~~~~~~~~
-
-Flow control nodes allow the execution to take different branches, usually depending on a
-given condition.
-
-.. image:: img/visual_script43.png
-
-
-Condition
-^^^^^^^^^
-
-This is a simple node that checks a bool port. If true, it will go via the "true" sequence port. If false,
-the second. After going for either of them, it goes via the "done" port. Leaving sequence
-ports disconnected is fine if not all of them are used.
-
-
-Iterator
-^^^^^^^^
-
-Some data types in Godot (ie, arrays, dictionaries) are iterable. This means that a bit of code can run
-for each element that it has.
-
-The Iterator node goes through all elements and, for each of them, it goes via the "each" sequence port,
-making the element available in the "elem" data port. 
-
-When done, it goes via the "exit" sequence port.
-
-
-Return
-^^^^^^
-
-Some functions can return values. In general for virtual ones, Godot will add the Return node for you.
-A return node forces the function to end.
-
-
-Sequence
-^^^^^^^^
-
-This node is useful mostly for organizing your graph. It calls its sequence ports in order.
-
-
-TypeCast
-^^^^^^^^
-
-This is a very useful and commonly used node. You can use it to cast arguments or other objects
-to the type you desire. Afterwards, you can even drag the object output to get full completion.
-
-.. image:: img/visual_script55.png
-
-
-It is also possible to cast to a script, which will allow complete script properties and functions:
-
-.. image:: img/visual_script54.png
-
-
-Switch
-^^^^^^
-
-The Switch node is similar to the Condition node, but it matches many values at the same time.
-
-
-While
-^^^^^
-
-This is a more primitive form of iteration. "repeat" sequence output will be called as long as
-the condition in the "cond" data port is met.
-
-
-Functions
-~~~~~~~~~
-
-Functions are simple helpers, most of the time deterministic. They take some arguments as
-input and return an output. They are almost never sequenced.
-
-
-Built-In
-^^^^^^^^
-
-There is a list of built in helpers. The list is almost identical to the one from GDScript (@TODO, link to gdscript methods?).
-Most of them are mathematical functions, but others can be very useful helpers. Just make sure to take a look at the list
-at some point.
-
-
-By Type
-^^^^^^^
-
-Those are the methods available to basic types. For example, if you want a dot-product, you can search for "dot" intead of the Vector3 category.
-In most cases just search the list of nodes, it should be faster.
-
-
-Call
-^^^^
-
-This is the generic calling node. It is rarely used directly but by dragging to empty space on an already configured node.
-
-
-Constructors
-^^^^^^^^^^^^
-
-These are all the functions needed to create Godot basic datatypes. For example, If you need to create a Vector3 out of 3 floats, a constructor must be used.
-
-.. image:: img/visual_script44.png
-
-
-Destructor
-^^^^^^^^^^
-
-This is the opposite to Constructor, it allows to separate any basic type (ie, Vector3) into its sub-elements.
-
-.. image:: img/visual_script45.png
-
-
-Emit Signal
-^^^^^^^^^^^
-
-Emits signals from any object. In general it's not very useful, as dragging a signal to the canvas works better.
-
-
-Get/Set
-^^^^^^^
-
-Generic Getter/Setter node. Dragging properties from the Inspector works better, as they appear properly configured on drop.
-
-
-Wait
-^^^^
-
-The Wait nodes will suspend execution of the function until something happens (many frames can pass until resuming, in fact).
-Default nodes allow you to wait for a frame to pass, a fixed frame or a given amount of time until execution is resumed.
-
-
-Yield
-^^^^^
-
-This node completely suspends the execution of the script, and it wil make the function return a value that can be used to resume execution.
-
-
-Yield Signal
-^^^^^^^^^^^^
-
-Same as Yield, but will wait until a given signal is emitted.
-
-
-Index
-~~~~~
-
-Generic indexing operator, not often used but it's good that it exists just in case.
-
-
-Operators
-~~~~~~~~~
-
-These are mostly generic operators such as addition, multiplication, comparison, etc.
-By default, these mostly accept any datatype (and will error in run-time if the types
-feeded do not match for the operator). It is always recommended to set the right
-type for operators to catch errors faster and make the graph easier to read.
-
-.. image:: img/visual_script46.png
-
-
-Expression Node
-^^^^^^^^^^^^^^^
-
-Among the operators, the *Expression* node is the most powerful. If well used, it allows you to enormously simplify
-visual scripts that are math or logic heavy. Just type any expression on it and it will be executed in real-time.
-
-Expression nodes can:
-
-- Perform math and logic expressions based on custom inputs (eg: "a*5+b", where a and b are custom inputs):
-
-.. image:: img/visual_script47.png
-
-
-- Access local variables or properties:
-
-.. image:: img/visual_script48.png
-
-
-- Use most of the existing built-in functions that are available to GDScript, such as sin(),cos(),print(), as well as constructors, such as Vector3(x,y,z),Rect2(..), etc.:
-
-.. image:: img/visual_script49.png
-
-
-- Call API functions:
-
-.. image:: img/visual_script50.png
-
-
-- Use sequenced mode, which makes more sense in case of respecting the processing order:
-
-.. image:: img/visual_script51.png

learning/step_by_step/gui_tutorial.rst

@@ -1,176 +0,0 @@
-.. _doc_gui_tutorial:
-
-GUI tutorial
-============
-
-Introduction
-~~~~~~~~~~~~
-
-If there is something that most programmers hate with passion, it is
-programming graphical user interfaces (GUIs). It's boring, tedious and
-unchallenging. Several aspects make matters worse, such as:
-
--  Pixel alignment of UI elements is difficult (such that it looks just
-   like the designer intends).
--  UIs are changed constantly due to design and usability issues that
-   appear during testing.
--  Handling proper screen re-sizing for different display resolutions.
--  Animating several screen components, to make it look less static.
-
-GUI programming is one of the leading causes of programmer burnout.
-During the development of Godot (and previous engine iterations),
-several techniques and philosophies for UI development were put into
-practice, such as immediate mode, containers, anchors, scripting, etc.
-This was always done with the main goal of reducing the stress
-programmers had to face while putting together user interfaces.
-
-In the end, the resulting UI subsystem in Godot is an efficient solution
-to this problem, and works by mixing together a few different
-approaches. While the learning curve is a little steeper than in other
-toolkits, developers can put together complex user interfaces in very
-little time, by sharing the same set of tools with designers and
-animators.
-
-Control
-~~~~~~~
-
-The basic node for UI elements is :ref:`Control <class_Control>`
-(sometimes called "Widget" or "Box" in other toolkits). Every node that
-provides user interface functionality descends from it.
-
-When controls are put in a scene tree as a child of another control,
-its coordinates (position, size) are always relative to the parent.
-This sets the basis for editing complex user interfaces quickly and
-visually.
-
-Input and drawing
-~~~~~~~~~~~~~~~~~
-
-Controls receive input events by means of the
-:ref:`Control._gui_input() <class_Control__gui_input>`
-callback. Only one control, the one in focus, will receive
-keyboard/joypad events (see
-:ref:`Control.set_focus_mode() <class_Control_set_focus_mode>`
-and :ref:`Control.grab_focus() <class_Control_grab_focus>`).
-
-Mouse motion events are received by the control directly below the mouse
-pointer. When a control receives a "mouse button pressed" event, all
-subsequent motion events are received by the "pressed" control until that
-button is released, even if the pointer moves outside the control
-boundary.
-
-Like any class that inherits from :ref:`CanvasItem <class_CanvasItem>`
-(Control does), a :ref:`CanvasItem._draw() <class_CanvasItem__draw>`
-callback will be received at the beginning and every time the control
-needs to be redrawn (the programmer needs to call
-:ref:`CanvasItem.update() <class_CanvasItem_update>`
-to enqueue the CanvasItem for redraw). If the control is not visible
-(yet another CanvasItem property), the control does not receive any
-input.
-
-In general, though, the programmer does not need to deal with drawing and
-input events directly when building UIs (that is more useful when
-creating custom controls). Instead, controls emit different kinds of
-signals with contextual information for when an action occurs. For
-example, a :ref:`Button <class_Button>` emits
-a "pressed" signal when pressed, a :ref:`Slider <class_Slider>` will
-emit a "value_changed" when dragged, etc.
-
-Custom control mini tutorial
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Before going into more depth, creating a custom control will be a good
-way to get the picture on how controls works, as they are not as
-complex as it might seem.
-
-Additionally, even though Godot comes with dozens of controls for
-different purposes, it happens often that it's easier to attain a
-specific functionality by creating a new one.
-
-To begin, create a single-node scene. The node is of type "Control" and
-has a certain area of the screen in the 2D editor, like this:
-
-.. image:: img/singlecontrol.png
-
-Add a script to that node, with the following code:
-
-::
-
-    extends Control
-
-    var tapped=false
-
-    func _draw():
-
-        var r = Rect2( Vector2(), get_size() )
-        if (tapped):
-            draw_rect(r, Color(1,0,0) )
-        else:
-            draw_rect(r, Color(0,0,1) )
-
-    func _gui_input(ev):
-
-        if (ev is InputEventMouseButton and ev.pressed):
-            tapped=true
-            update()
-
-Then run the scene. When the rectangle is clicked/tapped, it will change
-color from blue to red. That synergy between the events and the drawing
-is pretty much how most controls work internally.
-
-.. image:: img/ctrl_normal.png
-
-.. image:: img/ctrl_tapped.png
-
-UI complexity
-~~~~~~~~~~~~~
-
-As mentioned before, Godot includes dozens of controls ready for use
-in a user interface. Such controls are divided into two categories. The
-first is a small set of controls that work well for creating most game
-user interfaces. The second (and most controls are of this type) are
-meant for complex user interfaces and uniform skinning through styles. A
-description is presented as follows to help understand which one should
-be used in which case.
-
-Simplified UI controls
-~~~~~~~~~~~~~~~~~~~~~~
-
-This set of controls is enough for most games, where complex
-interactions or ways to present information are not necessary. They can
-be skinned easily with regular textures.
-
--  :ref:`Label <class_Label>`: Node used for showing text.
--  :ref:`TextureRect <class_TextureRect>`: Displays a single texture,
-   which can be scaled or kept fixed.
--  :ref:`TextureButton <class_TextureButton>`: Displays a simple textured
-   button, states such as pressed, hover, disabled, etc. can be set.
--  :ref:`TextureProgress <class_TextureProgress>`: Displays a single
-   textured progress bar.
-
-Additionally, re-positioning of controls is most efficiently done with
-anchors in this case (see the :ref:`doc_size_and_anchors` tutorial for more
-information).
-
-In any case, it will happen often that even for simple games, more
-complex UI behaviors are required. An example of this is a scrolling
-list of elements (for a high score table, for example), which needs a
-:ref:`ScrollContainer <class_ScrollContainer>`
-and a :ref:`VBoxContainer <class_VBoxContainer>`.
-These kind of more advanced controls can be mixed with the regular ones
-seamlessly (they are all controls, after all).
-
-Complex UI controls
-~~~~~~~~~~~~~~~~~~~
-
-The rest of the controls (and there are dozens of them!) are meant for
-another set of scenarios, most commonly:
-
--  Games that require complex UIs, such as PC RPGs, MMOs, strategy,
-   sims, etc.
--  Creating custom development tools to speed up content creation.
--  Creating Godot Editor Plugins, to extend the engine functionality.
-
-Re-positioning controls for these kind of interfaces is more commonly
-done with containers (see the :ref:`doc_size_and_anchors` tutorial for more
-information).

learning/step_by_step/scripting.rst

@@ -72,7 +72,7 @@ well as any Common Language Infrastructure-compliant programming language, such
 F#, Boo or ClojureCLR. In practice however, C# is the only officially-supported .NET option.
 
 GDNative / C++
-~~~~~~~~~~~~
+~~~~~~~~~~~~~~
 
 Finally, this is one of our brightest additions for the 3.0 release.
 GDNative allows scripting in C++ without requiring to recompile (or even

learning/step_by_step/simple_2d_game.rst

@@ -1,270 +0,0 @@
-.. _doc_simple_2d_game:
-
-Simple 2D game
-==============
-
-Pong
-~~~~
-
-In this tutorial, a basic game of Pong will be created. There are plenty
-of more complex examples in the demos included with the engine, but this
-should get you introduced to the basic functionalities for 2D Games.
-
-To begin with, run the Godot Engine and start a new project.
-
-Assets
-~~~~~~
-
-Some assets are included for this tutorial:
-:download:`pong_assets.zip <files/pong_assets.zip>`. Unzip its content
-in your project folder.
-
-Scene setup
-~~~~~~~~~~~
-
-To pay homage to the olden times, the game will be in 640x400 pixels
-resolution. This can be configured in the Project Settings (see
-:ref:`doc_scenes_and_nodes-configuring_the_project`) under the Scene/Project
-settings menu. The default background color should be set to black:
-
-.. image:: img/clearcolor.png
-
-Create a :ref:`class_Node2D` node for the project root. Node2D is the
-base type for the 2D engine. After this, add some sprites
-(:ref:`class_Sprite` node) for the left and right paddles, the separator,
-and ball. You can set a custom name for each node, and set the texture
-for each sprite in the Inspector. 
-
-.. image:: img/pong_nodes.png
-
-Set nodes positions:
- - "left" node: (67, 183)
- - "right" node: (577, 187)
- - "separator" node: (320, 200)
- - "ball" node: (320, 188)
-
-
-The final scene layout should look similar to this (note: the ball is in
-the middle!):
-
-.. image:: img/pong_layout.png
-
-
-Save the scene as "pong.tscn" and set it as the main scene in the
-project
-properties.
-
-.. _doc_simple_2d_game-input_actions_setup:
-
-Input actions setup
-~~~~~~~~~~~~~~~~~~~
-
-Video games can be played using various input methods: Keyboard, Joypad,
-Mouse, Touchscreen (even multitouch)... Godot is able to use them all.
-However, it would be interesting to define the inputs as "Input Actions"
-instead of hardware actions that you'd manage separately. This way, any
-input method can be used: each of them only require the user to connect
-buttons to game actions that you define. 
-
-This is Pong. The only input that matters is for the pads going up and
-down.
-
-Open the project properties dialog again (Scene/Project settings), but
-this time move to the
-"Input Map" tab.
-
-In this tab, add 4 actions:
-``left_move_up``, ``left_move_down``, ``right_move_up``,
-``right_move_down``.
-Assign the keys that you desire. The A/Z keys (for the left player) and
-the Up/Down keys (for the right player) should work in most cases.
-
-.. image:: img/inputmap.png
-
-Script
-~~~~~~
-
-Create a script for the root node of the scene and open it (as explained
-in :ref:`doc_scripting-adding_a_script`). This script inherits Node2D:
-
-::
-
-    extends Node2D
-
-    func _ready():
-        pass
-        
-        
-First things first, we need to define some members for our script so it
-can store useful values. Such values are the dimensions of the screen, the pad
-and the initial direction of the ball.
-
-::
-
-    extends Node2D
-    
-    # Member variables
-    var screen_size
-    var pad_size
-    var direction = Vector2(1.0, 0.0)
-
-    func _ready():
-        pass
-
-
-As you know, the ``_ready()`` function is the first function called
-(after ``_enter_tree()`` which we don't need here). In this function,
-two things have to be done. The first one is to enable
-processing: this is the purpose of the ``set_process(true)`` function.
-The second one is to initialize our two member variables.
-
-::
-
-    extends Node2D
-
-    # Member variables
-    var screen_size
-    var pad_size
-    var direction = Vector2(1.0, 0.0)
-
-    func _ready():
-        screen_size = get_viewport_rect().size
-        pad_size = get_node("left").get_texture().get_size()
-        set_process(true)
-        
-We initialize the ``pad_size`` variable by getting one of the pads nodes
-(the left one here), and obtain its texture size. The ``screen_size`` is
-initialized using the ``get_viewport_rect()`` which returns a Rect
-object corresponding to the game window, and we store its size.
-
-
-Now, we need to add some other members to our script in order to make
-our ball move.
-
-::
-
-    extends Node2D
-
-    # Member variables
-    var screen_size
-    var pad_size
-    var direction = Vector2(1.0, 0.0)
-    
-    # Constant for ball speed (in pixels/second)
-    const INITIAL_BALL_SPEED = 80
-    # Speed of the ball (also in pixels/second)
-    var ball_speed = INITIAL_BALL_SPEED
-    # Constant for pads speed
-    const PAD_SPEED = 150
-
-    func _ready():
-        screen_size = get_viewport_rect().size
-        pad_size = get_node("left").get_texture().get_size()
-        set_process(true)
-
-    
-
-Finally, the ``_process()`` function. All the code below is contained by
-this function.
-
-We have to initialize some useful values for computation. The first one is the
-ball position (from the node),and the second one is the rectangle
-(``Rect2``) for each pad. These rectangles will be used for collision
-tests between the ball and the pads. Sprites center their textures by
-default, so a small adjustment of ``pad_size / 2`` must be added.
-
-::
-
-    func _process(delta):
-        var ball_pos = get_node("ball").get_position()
-        var left_rect = Rect2( get_node("left").get_position() - pad_size*0.5, pad_size )
-        var right_rect = Rect2( get_node("right").get_position() - pad_size*0.5, pad_size )
-
-Now, let's add some movement to the ball in the ``_process()`` function.
-Since the ball position is stored in the ``ball_pos`` variable,
-integrating it is simple:
-
-::
-
-        # Integrate new ball position
-        ball_pos += direction * ball_speed * delta
-
-This code line is called at each iteration of the ``_process()``
-function. That means the ball position will be updated at each new
-frame.
-
-Now that the ball has a new position, we need to test if it
-collides with anything. That is, the window borders and the pads. First,
-the floor and the roof:
-
-::
-
-        # Flip when touching roof or floor
-        if ((ball_pos.y < 0 and direction.y < 0) or (ball_pos.y > screen_size.y and direction.y > 0)):
-            direction.y = -direction.y
-
-Second, the pads: if one of the pads is touched, we need to invert the
-direction of the ball on the X axis so it goes back, and define a new
-random Y direction using the ``randf()`` function. We also increase its
-speed a little.
-
-::
-
-        # Flip, change direction and increase speed when touching pads
-        if ((left_rect.has_point(ball_pos) and direction.x < 0) or (right_rect.has_point(ball_pos) and direction.x > 0)):
-            direction.x = -direction.x
-            direction.y = randf()*2.0 - 1
-            direction = direction.normalized()
-            ball_speed *= 1.1
-
-Finally, if the ball moves off of the screen, it's game over. That is, we test if
-the X position of the ball is less than 0 or greater than the screen
-width. If so, the game restarts:
-
-::
-
-        # Check gameover
-        if (ball_pos.x < 0 or ball_pos.x > screen_size.x):
-            ball_pos = screen_size*0.5
-            ball_speed = INITIAL_BALL_SPEED
-            direction = Vector2(-1, 0)
-
-Once everything is done, the node is updated with the new position of
-the ball, which was computed before:
-
-::
-
-        get_node("ball").set_position(ball_pos)
-
-Next, we allow the pads to move. We only update their position according
-to player input. This is done using the Input class:
-
-::
-
-        # Move left pad
-        var left_pos = get_node("left").get_position()
-
-        if (left_pos.y > 0 and Input.is_action_pressed("left_move_up")):
-            left_pos.y += -PAD_SPEED * delta
-        if (left_pos.y < screen_size.y and Input.is_action_pressed("left_move_down")):
-            left_pos.y += PAD_SPEED * delta
-
-        get_node("left").set_position(left_pos)
-
-        # Move right pad
-        var right_pos = get_node("right").get_position()
-
-        if (right_pos.y > 0 and Input.is_action_pressed("right_move_up")):
-            right_pos.y += -PAD_SPEED * delta
-        if (right_pos.y < screen_size.y and Input.is_action_pressed("right_move_down")):
-            right_pos.y += PAD_SPEED * delta
-
-        get_node("right").set_position(right_pos)
-        
-We use the four actions previously defined in the Input actions setup
-section above. When the player activates the respective key, the
-corresponding action is triggered. As soon as this happens, we simply
-compute a new position for the pad in the desired direction and apply it
-to the node.
-
-That's it! A simple Pong game was written with a few lines of code.

learning/step_by_step/ui_introduction_to_the_ui_system.rst

@@ -1,3 +1,5 @@
+.. _doc_design_interfaces_with_the_control_nodes:
+
 Design interfaces with the Control nodes
 ========================================
 

learning/step_by_step/your_first_game.rst

@@ -600,7 +600,7 @@ Create the following children of the ``HUD`` node:
           origin, or the reference point for the edges of the node. Margins
           update automatically when you move or resize a control node. They
           represent the distance from the control node's edges to its anchor.
-          See :ref:`doc_gui_tutorial` for more details.
+          See :ref:`doc_design_interfaces_with_the_control_nodes` for more details.
 
 Arrange the nodes as shown below. Click the "Anchor" button to
 set a Control node's anchor: