diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-01.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-01.png deleted file mode 100644 index 3420c891..00000000 Binary files a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-01.png and /dev/null differ diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-02.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-02.png deleted file mode 100644 index dbadabbf..00000000 Binary files a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-02.png and /dev/null differ diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-03.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-03.png deleted file mode 100644 index 1119c4e0..00000000 Binary files a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-03.png and /dev/null differ diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-04.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-04.png deleted file mode 100644 index 5ec032ad..00000000 Binary files a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-04.png and /dev/null differ diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-05.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-05.png deleted file mode 100644 index b542830f..00000000 Binary files a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-05.png and /dev/null differ diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-06.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-06.png deleted file mode 100644 index e6ab655c..00000000 Binary files a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-06.png and /dev/null differ diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-07.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-07.png deleted file mode 100644 index 0d2444a1..00000000 Binary files a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-07.png and /dev/null differ diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-08.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-08.png deleted file mode 100644 index 46acb101..00000000 Binary files a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials-introducing-logic-nodes-08.png and /dev/null differ diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_00_linux-terminal-run.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_00_linux-terminal-run.png new file mode 100644 index 00000000..cd65dbb3 Binary files /dev/null and b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_00_linux-terminal-run.png differ diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_01_edit-menu_preferences.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_01_edit-menu_preferences.png new file mode 100644 index 00000000..3aa6e207 Binary files /dev/null and b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_01_edit-menu_preferences.png differ diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_02_preferences_filter_logic.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_02_preferences_filter_logic.png new file mode 100644 index 00000000..a47c1bb4 Binary files /dev/null and b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_02_preferences_filter_logic.png differ diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_03_preferences_addons_logic-nodes-unfold.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_03_preferences_addons_logic-nodes-unfold.png new file mode 100644 index 00000000..97c5cc9b Binary files /dev/null and b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_03_preferences_addons_logic-nodes-unfold.png differ diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_04_editor.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_04_editor.png new file mode 100644 index 00000000..c4c796f2 Binary files /dev/null and b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_04_editor.png differ diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_05_new-logic-node-tree.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_05_new-logic-node-tree.png new file mode 100644 index 00000000..abc86e87 Binary files /dev/null and b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_05_new-logic-node-tree.png differ diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_06_n-panel-dashboard.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_06_n-panel-dashboard.png new file mode 100644 index 00000000..bbd6c6aa Binary files /dev/null and b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_06_n-panel-dashboard.png differ diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_07_add-key-node.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_07_add-key-node.png new file mode 100644 index 00000000..d38cea67 Binary files /dev/null and b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_07_add-key-node.png differ diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_08_shift-a-search-print-node.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_08_shift-a-search-print-node.png new file mode 100644 index 00000000..2b8d77ad Binary files /dev/null and b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_08_shift-a-search-print-node.png differ diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_09_nodes-added-connected.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_09_nodes-added-connected.png new file mode 100644 index 00000000..6e494e55 Binary files /dev/null and b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_09_nodes-added-connected.png differ diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_10_dashboard_tree-apply-to-selected.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_10_dashboard_tree-apply-to-selected.png new file mode 100644 index 00000000..c513e039 Binary files /dev/null and b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_10_dashboard_tree-apply-to-selected.png differ diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_11_dashboard_tree-applied-to.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_11_dashboard_tree-applied-to.png new file mode 100644 index 00000000..51fdf7c2 Binary files /dev/null and b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_11_dashboard_tree-applied-to.png differ diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_12_rearange-n-sub-panel.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_12_rearange-n-sub-panel.png new file mode 100644 index 00000000..89e9aa45 Binary files /dev/null and b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_12_rearange-n-sub-panel.png differ diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_13_render-properties_embedded-start.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_13_render-properties_embedded-start.png new file mode 100644 index 00000000..6a43e561 Binary files /dev/null and b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_13_render-properties_embedded-start.png differ diff --git a/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_14_terminal_print-output.png b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_14_terminal_print-output.png new file mode 100644 index 00000000..afd3c97b Binary files /dev/null and b/source/images/Tutorials/Introducing_Logic_Nodes/tutorials_introducing-logic-nodes_14_terminal_print-output.png differ diff --git a/source/manual/tutorials/introducing_logic_nodes/a_first_example.rst b/source/manual/tutorials/introducing_logic_nodes/a_first_example.rst index 93c29ac4..921f4660 100644 --- a/source/manual/tutorials/introducing_logic_nodes/a_first_example.rst +++ b/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\'.