Adds Script Nodes vs User Components chapter.

Author: PhaserEditor2D

.vscode/settings.json

@@ -6,6 +6,7 @@
     "workbench.colorTheme": "Solarized Dark",
     "cSpell.words": [
         "tilemap",
+        "toctree",
         "toolkits"
     ],
     "restructuredtext.confPath": "${workspaceFolder}",

CHANGELOG.MD

@@ -9,6 +9,7 @@
 * Updates Depth commands.
 * Updates prefab instance dynamic sections.
 * Updates chapters with new user component dynamic sections.
+* New chapter Script Nodes vs User Components.
 
 ## v3.61.0 - May 18, 2022
 

scene-editor/script-node-vs-user-component.rst

@@ -0,0 +1,30 @@
+
+.. include:: ../_header.rst
+
+Script Nodes vs User Components
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Now you have two mechanisms for assigning behaviors to an object: the |ScriptNode|_ and the |UserComponents|_. Now you have to decide when to use one or another. In this chapter, we try to provide you with a small guide.
+
+**When to use a User Component?**
+
+Many users find a user component very handy because you can edit its properties right away, in the same place as the object's properties. You don't need to browse an object's tree of nodes. Also, components are familiar philosophy in the Phaser API. However, user components have a main restriction: it has a one-to-one relationship with the object. It means, you can assign only a single type of component to the object, so it should implement the whole behavior as a unit.
+
+These are some examples of modeling behaviors with user components:
+
+* An **AutoplayAnimation** user component that you can add to sprites. It has an **animationKey** property that is played automatically. Because you can play only one animation at a time in a sprite, it fits well in the one-to-one relationship constraint of user components.
+* A **BorderAnchor** component, with a **anchorTo** property with values like ``left``, ``top``, ``right``, ``bottom``. This component will auto re-position the object in a responsive scene. Because an object has only one position, it fits in the one-to-one restriction of user components.
+
+**When to use a Script Node?**
+
+The script nodes are logical game objects and you can make prefabs of them. The prefabs system in the editor is powerful and you can express complex behaviors in a hierarchical relationship. Also, you can add script nodes not only to objects else to scenes too. However, it is very easy that you start abusing the use of script nodes and making large hierarchies of logical nodes. We think for now it isn't a good idea, but in the end, it is up to you.
+
+Some examples of modeling behaviors with script nodes:
+
+* When you can make logical units that you can combine and make different behaviors. For example, you can make a **StartSceneAction** script node with a **sceneKey** property. This node will start the **sceneKey** scene when it is executed. You can use this script in different contexts:
+ * In a hierarchy of nodes for starting the Game scene after pressing a **Play** button. 
+ * You can use the same **StartSceneAction** in a hierarchy of nodes that listens to the SPACE key, so it starts the Game scene.
+* A **LevelGameplay** script node with the gameplay of a level. You can add this node to a different scene and changes the parameters of the gameplay, for making it harder.
+* A **PlayerCollider**, **DestroyObjectAction**, and a **ChangeHealthAction** scripts. You can combine them for expressing when a player hits an object in the level if it will destroy the object and how much it affects the player's health. You can create different combinations for the different kinds of objects in the level.
+
+As we said previously, it is up to you when to use the script nodes and how much you split the behaviors in a tree of small logical units. Our advice is to keep it simple and learn first from your game before making a complex framework of script nodes.

scene-editor/script-node.rst

@@ -6,6 +6,7 @@ Script Nodes
 
 .. toctree::
 
+    script-node-vs-user-component
     script-node-create
     script-node-class
     script-node-basic-scripts-project
@@ -14,14 +15,14 @@ Script Nodes
 
 A |ScriptNode|_ is a new type of object. It isn't a display object, else a logical object you can use with different purposes, especially, for expressing simple and complex behaviors.
 
-Until now, |UserComponents|_ were the way you had to add extra funcitonality to a game object. The |ScriptNode|_ is a more powerful and general tool, that you can use with the same purpose. 
+Until now, |UserComponents|_ were the only way you had to add extra functionality to a game object. The |ScriptNode|_ is a more powerful and general tool, that you can use with the same purpose. 
 
 Basically, a |ScriptNode|_ is a logical object you can add to an scene, a game object, or another |ScriptNode|_. But what is even more exciting, is that you can make reusable and extensible |ScriptNodes|_ in the same way you make reusable and extensible game objects: using prefabs_.
 
 This means, you can make a prefab of a |ScriptNode|_, add custom properties, create variants of the prefab, create nested prefabs, and append |ScriptNodes|_ to prefab instances.
 
 This allows expressing complex behaviors combining logical building blocks (|ScriptNode|_ prefabs) in a hierarchical structure.
 
-This concept of |ScriptNodes|_ is inspired by the `visual programming languages <https://en.wikipedia.org/wiki/Visual_programming_language>`_ and concepts like the `behavior tree <https://en.wikipedia.org/wiki/Behavior_tree_(artificial_intelligence,_robotics_and_control)>`_. However, we don't pretend to create a complete, full-featured, visual language. Our advice is using the |ScriptNodes|_ for making the blocks of repeated behaviors in your game. You can use it for dealing with the UI interface, menu screens, intro screens. You can use it in your gameplay, but not by combining a lot of general-purpose blocks, else by combining blocks you did especifically for your gameplay.
+This concept of |ScriptNodes|_ is inspired by the `visual programming languages <https://en.wikipedia.org/wiki/Visual_programming_language>`_ and concepts like the `behavior tree <https://en.wikipedia.org/wiki/Behavior_tree_(artificial_intelligence,_robotics_and_control)>`_. However, we don't pretend to create a complete, full-featured, visual language. Our advice is using the |ScriptNodes|_ for making the blocks of repeated behaviors in your game. You can use it for dealing with the UI interface, menu screens, intro screens. You can use it in your gameplay, but not by combining a lot of general-purpose blocks, else by combining blocks you did specifically for your gameplay.
 
-An argument about the advantage of using a visual scripting language is that creators with no traditional programming experience can make a game. But our concept with the |ScriptNodes|_, is that you, the JavaScript programmer, can implement the script nodes "framework" for your game, and deliver it to the game level designer for connecting the scripts with the game objects and scenes. A good start could be the `script-nodes-basic <http://github.com/PhaserEditor2D/script-nodes-basic>`_ project.
+An argument about the advantage of using a visual scripting language is that creators with no traditional programming experience can make a game. But our concept with the |ScriptNodes|_, is that you, the JavaScript programmer, can implement the script nodes "framework" for your game, and deliver it to the game level designer for connecting the scripts with the game objects and scenes. A good start could be the `script-nodes-basic <http://github.com/PhaserEditor2D/script-nodes-basic>`_ project.