PR - UPBGE-Docs - Tutorials / Introducing Logic Nodes (#44)

* tutorials_introducing-logic-nodes images update & redesign

UPBGE-Docs / Tutorials / Introducing Logic Nodes :

reedited overall design of whole chapter
updated & added images
clearly renamed the images , including added numbering for easier future maintenance

source/manual/tutorials/introducing_logic_nodes/a_first_example.rst

@@ -2,110 +2,172 @@
 A First Example
 ===============
 
-Here we will try print some text to the console when a key is pressed. This could
-probably be called the "Hello World" example for the Logic Nodes.
+We will print some text to the console when a keyboard key is pressed. This is the "Hello World" example for the Logic Nodes.
+
+--------------
+System Console
+--------------
+UPBGE uses system console / terminal to print info and error messages. To see those messages:
+
+Windows users:
+
+* :menuselection:`Window --> Toggle System Console` menu.
+
+Linux and Mac users:
+
+* start UPBGE via console / terminal - navigate to blender executable file, and run:
+``./blender``
+
+.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_00_linux-terminal-run.png
+
+   Run UPBGE on Linux or Mac terminal
 
 ---------------------------------
 Activating the Logic Nodes Add-on
 ---------------------------------
 
-The *Logic Nodes* add-on cames pre-installed in UPBGE 0.3+. To activate it you have
-to go to ``Edit -> Preferences -> Add-ons`` and filter for Game Engine.
-There, check the box for the Logic Nodes and you're good to go.
+The *Logic Nodes* add-on comes preinstalled in UPBGE 0.3+. If not already, it needs to be activated:
+
+* :menuselection:`Edit -> Preferences -> Add-ons`
+
+.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_01_edit-menu_preferences.png
 
-.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-01.png
+   Navigate to Preferences
 
-   Activating Logic Nodes Add-on
+There, in *search / filter* field, filter for ``logic``, and check the box for *Logic Nodes+*.
+
+.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_02_preferences_filter_logic.png
+
+   Search for 'logic' and check the box
+
+Click the little arrow, next to the check box, to expand the *Logic Nodes+* add-on menu, and in the :menuselection:`Preferences` click :menuselection:`Install or Update Uplogic Module` button.
+
+.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_03_preferences_addons_logic-nodes-unfold.png
+
+   Install or Update Uplogic Module
+
+.. note::
+
+   This same :menuselection:`Preferences` menu can be used to report a bug - click on :menuselection:`Report a Bug` button (internet connection is required). The default web browser will open github.com web page. There, click :menuselection:`New issue` button, and follow the instructions. 
+
+Houston, the eagle has landed. We're good to go.
 
 -------------------------
-Creating A New Logic Tree
+Creating a New Logic Tree
 -------------------------
 
-Now, let's get started. First we will need to create a logic tree. For this, check
-the view menu for a new editor called Logic Tree Editor (Should be under "General").
+Now let's get started. First we need to create a logic tree. Switch the *Editor Type* to the :menuselection:`Logic Node Editor`.
 
-.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-02.png
+.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_04_editor.png
 
-   Set-up for Logic Nodes Editor
+   Select Logic Node Editor
 
-This editor is similar to the Shader Editor, so creating a new logic tree is the same as
-creating a new Material. Just click on New and a new tree (named NodeTree by default)
-should appear.
+This editor is similar to the *Shader Editor* or *Geometry Node Editor*. Click on :menuselection:`New` and a new empty tree (named *Logic Node Editor* by default) will be created.
 
-.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-03.png
+.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_05_new-logic-node-tree.png
 
-   Logic Nodes Editor
+   Click :menuselection:`New` button
 
+.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_06_n-panel-dashboard.png
 
-.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-04.png
-
-   Node Tree Created
+   New empty Node Tree with side Dashboard
 
 ------------
 Adding Nodes
 ------------
 
-Let's make something happen here. When you press :kbd:`Shift-A`, you'll notice that you
-can add new nodes now. Go ahead, take a look at what's at your disposal.
+With mouse cursor inside *Logic Node Editor*, press :kbd:`Shift-A`, or click :menuselection:`Add` button in top header. This will pop-up a menu with all available *Logic Nodes*, organized in sub-menus. Go ahead and take a look at what is available.
 
-.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-05.png
+.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_07_add-key-node.png
 
-   Adding Logic Nodes
+   Available Logic Nodes in Add menu
 
-For this example, we're looking for two nodes: the ``Key Down`` node and the ``Print`` node.
-If you can't find them, you can also search for those words.
+For this example, we're looking for two nodes: the ``Key`` and the ``Print`` node. If you can't find them:
 
-The ``Key Down`` node is a node of the condition type. These nodes do not actually do anything in-game,
-but they either provide a condition or can be used to check for a more complex set of conditions.
+* press :kbd:`Shift-A` hotkey, to add a node;
+* **immediately** after that start typing, i.e. ``print`` - UPBGE is smart and will search for it;
+* if accidentally wrong node is selected, press :kbd:`ESC` to cancel, and repeat.
 
-The ``Print`` node is an action type node. These nodes actually do something.
-They move objects, change properties, add constraints, you name it.
+.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_08_shift-a-search-print-node.png
 
-Now we need to link the two together. The ``Key Down`` node has a Condition Socket,
-they are colored red. Connect that to the condition socket of the ``Print`` node and enter "Hello World" in
-the text box. Also, if you didn't already, look at the ``Key Down`` node and you'll see that it asks you
-to choose a key. It should look something like this now:
+   Editor searches for node
 
-.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-06.png
+.. note::
 
-   Logic Nodes Added
+   Beside finding the node, *Search* pop-up also shows in which *sub-menu / sub-sub-menu* the nodes are.
+
+
+The ``Key`` node is a node of the **condition** type. These nodes do not actually do anything in-game; they either provide a condition, or can be used to check for a more complex set of conditions.
+
+The ``Print`` node is an **action** type node. These nodes actually do something. They move objects, change properties, add constraints etc. - you name it.
+
+Those two nodes need to be connected together. The ``Key`` node has an *If Pressed* output socket, colored red. Connect it (click-and-drag) to the *Condition* input socket of the ``Print`` node and enter "Hello World" in the text box at the bottom, next to *Value* input socket (blue sockets are for *strings*). Also, if not already, look at the ``Key`` node and you'll see that it expects user to choose a key. Click the bottom field and press :kbd:`SPACE` key, which will set that key as selected one. It should look something like this now:
+
+.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_09_nodes-added-connected.png
+
+   Logic Nodes added and connected
 
 --------------------
 Applying Logic Trees
 --------------------
 
-Once you've done that, all that's left is to apply the tree to an object. Logic trees work the
-following way: each tree can be applied to as many objects as you want, meaning it is executed
-by each object it is applied to separately.
+Once done, all that's left is to apply the tree to an object. Logic trees work the
+following way:
 
-Example: If you attached this tree to 4 objects and pressed the key ONCE,
+* each tree can be applied to as many objects as you want;
+* meaning it is executed by each object it is applied to, separately.
+
+Example: if this tree is attached to 4 objects and user presses :kbd:`SPACE` key **once**,
 the message would be printed 4 times, once for each object.
 
-To apply a tree to a cube, first add a cube, select it and press ``Apply to selected`` in the
-logic tree editor under the ``Item`` tab.
+To apply a tree to a cube, first a cube is added; select it and press :menuselection:`Apply to selected` button, in the *Dashboard* tab of side *N-panel*. Press :kbd:`N` to toggle *N-panel*, if it is hidden.
+
+.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_10_dashboard_tree-apply-to-selected.png
+
+   Apply Logic tree to selected object
 
 .. warning::
 
-   Be Careful, trees can be applied to multiple objects at once!
+   Be careful, trees can be applied to multiple objects at once!
 
-.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-07.png
+To see which objects have been applied with a *Logic Node* tree, scroll down the *Dashboard* tab, and check the *Tree applied to:* sub-panel at the bottom.
 
-   Applying Logic Tree
+.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_11_dashboard_tree-applied-to.png
 
---------------
-System Console
---------------
-Now, Last step! Hit Window -> Toggle System Console (for Linux and Mac users: save the file
-and start blender via console again), start your game and hit that key you entered before.
-Quit the game, check the system console and there should be your message, printed as many times as you hit the key.
+   Objects with applied Logic Node tree
+
+If needed, sub-panels can be rearranged:
+
+* for easier rearranging, first collapse sub-panels - click small arrow next to the sub-panel title;
+* click-and-drag top-right icon (4 by 2 dots) of sub-panel.
+
+.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_12_rearange-n-sub-panel.png
+
+   Collapsed and rearranged N-panel sub-panels
+
+What is left now is to run our example \'game\':
 
-.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-08.png
+* in *Render* panel of a *Properties* editor, click :menuselection:`Embedded Start` or :menuselection:`Standalone Start` (hotkey is :kbd:`P`) - the \'game\' shall start;
+* with \'game\' running, press :kbd:`SPACE` (or whichever keyboard key is assigned in ``Key`` node) once;
 
-   Console Output
+.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_13_render-properties_embedded-start.png
 
-This console is also the place where your errors will be printed if you are working in Debug Mode.
+   Start the game in Render panel
+
+Finally check the system console - it should have our message printed:
+
+* once if logic tree was applied to one object;
+* twice if logic tree was applied to two objects;
+* four times if logic tree was applied to two objects, and :kbd:`SPACE` was pressed twice etc.
+
+.. figure:: /images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_14_terminal_print-output.png
+
+   System console/terminal output
 
 .. note::
 
-   The ``Print`` node prints to the system console only, not to the python interactive console.
-   Sadly this is not changable.
+   See top of this page for System Console info.
+
+   The ``Print`` node prints to the system console only, not to the Python interactive console. This is a feature of Blender and is not changable.
+
+Press :kbd:`ESC` key to end the \'game\'.