Merge branch 'develop'

.vscode/settings.json

@@ -3,7 +3,7 @@
     "browser-preview.startUrl": "http://127.0.0.1:8000/",
     "browser-preview.format": "png",
     "workbench.preferredDarkColorTheme": "Default Light+",
-    "workbench.colorTheme": "Dracula Soft",
+    "workbench.colorTheme": "GitHub Dark Dimmed",
     "cSpell.words": [
         "tilemap",
         "toolkits"

CHANGELOG.MD

@@ -1,5 +1,10 @@
 # Change Log
 
+## v3.35.1 - Nov 1, 2022
+
+* Updates the user components docs with the new structure.
+* Updates the prefab properties new structure.
+
 ## v3.35.0 - Oct 14, 2022
 
 * Updates the "Code Editor" section.

conf.py

@@ -56,9 +56,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'v3.35.0'
+version = u'v3.35.1'
 # The full version, including alpha/beta/rc tags.
-release = u'v3.35.0'
+release = u'v3.35.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

scene-editor/prefab-user-properties-create.rst

@@ -3,13 +3,21 @@
 Creating a prefab user property
 ```````````````````````````````
 
-The **Prefab Properties** section of the |InspectorView|_ shows a button to create a new user property. This section is shown when you select the scene (click on a blank space of the scene).
+The **Prefab Properties** section of the |InspectorView|_ shows a button to create a new user property. This section is shown when you select the scene (click on a blank space of the scene), or when you select the **Prefab Properties** element in the |OutlineView|_:
+
+.. image:: ../images/prefab-user-props-node-outline-view-20221102.webp
+  :alt: The Prefabs Properties in the Outline view.
 
 Click on the **Add Property** button to create a new property. The button shows a menu with the different type of properties:
 
-.. image:: ../images/prefab-user-props-add-property-09102020.webp
+.. image:: ../images/prefab-user-props-add-property-20221102.webp
     :alt: Add prefab user property.
 
+The properties are shown as children of the **Prefab Properties** element. Click a property for editing it in the |InspectorView|_:
+
+.. image:: ../images/prefab-user-props-as-children-outline-20221102.webp
+  :alt: Display all properties of a prefab.
+
 All type of properties requires some common parameters that you should provide:
 
 * The **Name** of the property. It is used by the compiler to generate a property declaration code. It should be a valid JavaScript identifier.
@@ -18,16 +26,16 @@ All type of properties requires some common parameters that you should provide:
 * The **Default** value. 
 * The **Custom Definition** flag. If enabled, the |SceneCompiler|_ skips the generation of the code with the property declaration. It allows you writing a custom implementation of the property. For example, using a custom getter and setter. Learn more about `using properties with custom definition <prefab-user-properties-initializing.html#using-properties-with-custom-definition>`_.
 
-.. image:: ../images/prefab-user-props-common-params-07092021.webp
+.. image:: ../images/prefab-user-props-common-params-20221102.webp
     :alt: Common parameters of a property.
 
-In the title bar of the property, there is a menu with commands to: 
+The menu of the property section shows the following actions:
 
     * Move the property down/up.
     * Change the type of the property.
     * Delete the property.
 
 You can undo/redo all these changes.
 
-.. image:: ../images/prefab-user-props-menu-09102020.webp
+.. image:: ../images/prefab-user-props-menu-20221102.webp
     :alt: Property menu.

scene-editor/user-components-compiler.rst

@@ -10,8 +10,29 @@ Following, look at how an **HorizontalMove** component is compiled into JavaScri
 
 The component information:
 
-.. image:: ../images/scene-editor-user-components-demo-info-f_09172020.webp
-    :alt: Component metadata.    
+.. image:: ../images/scene-editor-user-components-editor-info-20221101.webp
+    :alt: Component metadata.
+
+The properties of the component:
+
+.. image:: ../images/scene-editor-user-components-props-20221101.webp
+  :alt: The properties
+
+**Horizontal Velocity**
+
+.. image:: ../images/scene-editor-user-components-prop-1-20221101.webp
+  :alt: Horizaontal move property.
+
+**Min X**
+
+.. image:: ../images/scene-editor-user-components-prop-2-20221101.webp
+  :alt: Min position X
+
+**Max X**
+
+.. image:: ../images/scene-editor-user-components-prop-3-20221101.webp
+  :alt: Max position Y.
+
 
 The generated code:
 

scene-editor/user-components-create-file.rst

@@ -16,8 +16,8 @@ These are the steps to create a new |UserComponents|_ file:
 
 #. Press the **Create** button. The file will be created and opened in the |UserComponentsEditor|_.
 
-.. image:: ../images/scene-editor-user-components-new-file-07202020.webp
- :alt: New User Components file.
+.. image:: ../images/scene-editor-user-components-new-file-20221101.webp
+  :alt: New User Components file.
 
 
 .. warning::

scene-editor/user-components-editor-add-component.rst

@@ -6,7 +6,8 @@ Add new component
 
 To add a new |UserComponent|_ you can: press the ``A`` key, click in the **Add Component** button in the |MainToolbar|_ or select the **Add Component** option in the context menu.
 
-.. image:: ../images/scene-editor-user-components-add-component-07212020.webp
+.. image:: ../images/scene-editor-user-components-add-component-20221101.webp
+  :alt: Add new user component.
 
 The newly created component has a default name, so probably you would like to change it, in the |InspectorView|_.
 

scene-editor/user-components-editor-edit-code.rst

@@ -7,12 +7,12 @@ To edit the `code generated <user-components-compiler.html>`_ for a component, y
 
 Also, you can select the component and press the ``Q`` key. It will open a Quick Edit dialog with a code editor:
 
-.. image:: ../images/scene-editor-user-components-edit-code-08042020.webp
+.. image:: ../images/scene-editor-user-components-edit-code-20221101.webp
     :alt: Edit component code in the Quick Edit dialog.
 
 The context menu shows all the options to edit the output file of a component:
 
-.. image:: ../images/scene-editor-user-components-open-editor-mnu-02242021.webp
+.. image:: ../images/scene-editor-user-components-open-editor-menu-20221101.webp
     :alt: Open output file options.
 
 The **Open Output File in Visual Studio Code** (``Ctrl+Alt+E``) command opens the output file in the configured external editor.

scene-editor/user-components-editor-edit-component.rst

@@ -11,14 +11,26 @@ This is the component metadata you can edit:
 * The name of the component class.
 * The type of the game object (or entity). Next to the field, you can open a menu with common possible options.
 * The super-class of the component class. It is optional. Next to the field, you can open a menu with common possible options and names used in other components.
-* The definition of the component's properties.
 
-.. image:: ../images/scene-editor-user-components-edit-props-07212020.webp
-    :alt: Edit component properties
+.. image:: ../images/scene-editor-user-components-edit-props-20221101.webp
+  :alt: Edit component info.
 
 The properties work the same as the `Prefab user properties <prefab-user-properties.html#creating-a-prefab-user-property>`_.
 
-The above image shows the **HorizontalMove** component. It has a game object type ``Phaser.GameObjects.Image``. It means you should add this component to that type of objects (entities). And the **horizVelocity**, **minX** and **minY** properties. This component is compiled into this JavaScript code:
+You can add new properties by pressing the **Add Property** button.
+
+The above image shows the **HorizontalMove** component. It has a game object type ``Phaser.GameObjects.Image``. It means you should add this component to that type of objects (entities). And the **horizVelocity**, **minX** and **minY** properties. 
+
+.. image:: ../images/scene-editor-user-components-props-20221101.webp
+  :alt: The component's properties.
+
+For editing the info of a property, select it in the editor and set the values in the Inspector view:
+
+.. image:: ../images/scene-editor-user-components-edit-property-20221101.webp
+  :alt: Edit property.
+
+
+This component is compiled into this JavaScript code:
 
 .. code::
 

scene-editor/user-components-in-prefab-object.rst

@@ -0,0 +1,61 @@
+
+.. include:: ../_header.rst
+
+Adding User Components to a Prefab 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In the previous section we shown how you can add a user component to an object. But, what does happen if you add a user component to a prefab? It is practically the same, but this component will be present in all the prefab instances too.
+
+Let's see this example of a moving platform prefab. It contains the **PlatformPhysics** and **HorizontalMove** components, but let's focus on the **HorizontalMove** one:
+
+.. image:: ../images/scene-editor-user-components-add-prefab-object-20221102.webp
+  :alt: The user components of a prefab.
+
+.. image:: ../images/scene-editor-user-components-add-prefab-object-props-20221102.webp
+  :alt: The user component properties.
+
+When you select an instance of this **MovingPlatform1** prefab, it also shows the **HorizontalMove** component, but highlighting that it belongs to the **MovingPlatform1** prefab:
+
+.. image:: ../images/scene-editor-user-components-prefab-instance-components.webp
+  :alt: Components of a prefab instance.
+
+The component's link contains the component's name and the name of the prefab it belongs to. If you click the prefab name, it opens the prefab file in a new editor, and selects the component. If you click on the component link, it selects the component and shows its properties in the |InspectorView|_. Look you can lock/unlock the properties:
+
+.. image:: ../images/scene-editor-user-components-obj-prefab-properties-20221102.webp
+    :alt: Editing properties of a component of a prefab instance.
+
+Generating the code for a component in a prefab instance
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The `user components compiler <user-components-compiler.html>`_ will generate the code to changing the component's properties like this:
+
+.. code::
+
+		// movingPlatform2 (components)
+		const movingPlatform2HorizontalMove = HorizontalMove
+                                           .getComponent(movingPlatform2);
+		movingPlatform2HorizontalMove.horizVelocity = -50;
+		movingPlatform2HorizontalMove.minX = 540;
+		movingPlatform2HorizontalMove.maxX = 1170;
+
+Note it doesn't create the component, else it gets the component from the **movingPlatform2** prefab instance.
+
+Hiding a component to the prefab instances
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Maybe you don't want to show the component of a prefab in the prefab instances. Because it is a component with local properties and behaviors and it could be perfectly hidden to the prefab instances. For doing this, you can uncheck the **Export** parameter of the component in the prefab:
+
+.. image:: ../images/scene-editor-user-components-export-parameter-20221102.webp
+  :alt: Export parameter.
+
+Actions for a component in a prefab instance
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These are the actions associated to the user component of a prefab instance:
+
+.. image:: ../images/scene-editor-user-components-instance-menu-20221102.webp
+  :alt: Actions for a user component instance.
+
+* **Select Objects With HorizontalMove**: selects in the scene all objects containing the **HorizontalMove** component.
+* **Open Definition Of HorizontalMove**: opens the definition of the component in the `User Components Editor <./user-components-editor.html>`_.
+* **Reveal in MovingPlatform1 File**: opens the prefab in a new Scene Editor and selects the **HorizontalMove** component.

scene-editor/user-components-instancing.rst

@@ -27,14 +27,24 @@ This is possible in the **User Components** section. It shows the **Add Componen
 
 When you click that button, it shows a dialog with all the components defined in the project (grouped by the ``*.components`` files). Select the one you want to add:
 
-.. image:: ../images/scene-editor-user-components-obj-add-component-05292021.webp
+.. image:: ../images/scene-editor-user-components-obj-add-component-20221102.webp
     :alt: Add a component to the object.
 
-Then, the properties of the components are shown in the same **User Components** section, and are ready to be set with new values:
+Then, the **HorizontalMove** component is shown as an object's child in the |OutlineView|_ and the User Components section shows a link to the component:
 
-.. image:: ../images/scene-editor-user-components-obj-edit-component-07302020.webp
+.. image:: ../images/scene-editor-user-components-show-components-20221102.webp
+  :alt: Showing the user components of an object.
+
+So, when you select the **HorizontalMove** component, the |InspectorView|_ shows the properties of the component:
+
+.. image:: ../images/scene-editor-user-components-obj-edit-component-20221102.webp
     :alt: Edit the user component instance properties.
 
+The **Select Parent Game Object** button is a shortcut for selecting the object containing the component.
+
+Generating the code for a component in an object
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 The `user components compiler <user-components-compiler.html>`_ will generate the code to create the component, just like if you write it by hand:
 
 .. code::
@@ -45,12 +55,21 @@ The `user components compiler <user-components-compiler.html>`_ will generate th
     bridge2HorizontalMove.minX = 10;
     bridge2HorizontalMove.maxX = 400;
 
-If the selected object is a prefab instance, then the components present in the prefab are shown too, and you can lock/unlock its properties:
+Actions for a component
+^^^^^^^^^^^^^^^^^^^^^^^
+
+These are the actions associated to the user component of an object:
+
+.. image:: ../images/scene-editor-user-components-component-menu-link-20221102.webp
+  :alt: Actions for a user component in an object.
+
+.. image:: ../images/scene-editor-user-components-component-menu-20221102.webp
+  :alt: Actions for a user component in an object.
+
+* **Select Objects With HorizontalMove**: selects in the scene all objects containing the **HorizontalMove** component.
+* **Open Definition Of HorizontalMove**: opens the definition of the component in the `User Components Editor <./user-components-editor.html>`_.
+* **Move Up**, **Move Down**: changes the order of the component.
+* **Delete**: deletes the component from the object.
 
-.. image:: ../images/scene-editor-user-components-obj-prefab-properties-07302020.webp
-    :alt: Editing properties of a component of a prefab instance.
 
-Look at the prefab and the |UserComponent|_ names: both are shown as links. If you click on it, it will open the prefab or the |UserComponent| in its editor. Also, each |UserComponent|_ panel has a menu icon. Click on it to list other options, like select in the scene all the objects with the same |UserComponent|_:
 
-.. image:: ../images/scene-editor-user-components-select-all-objects-07302020.webp
-    :alt: Select all objects with the same User Component.

scene-editor/user-components.rst

@@ -14,6 +14,7 @@ User Components
     user-components-super-class
     user-components-awake-event
     user-components-instancing
+    user-components-in-prefab-object
 
 A Component is a `design pattern <https://gameprogrammingpatterns.com/component.html>`_ that you can use to create reusable code and extend the behavior and data of a game object, using `composition over inheritance <https://en.wikipedia.org/wiki/Composition_over_inheritance>`_.