Merge branch 'master' into extension-details

README.md

@@ -30,3 +30,11 @@ $ ./publish_sh
 ```
 
 Publishing documentation to GCS is done with the `gsutil` which is part of the Google Cloud SDK. It's automatically installed if needed.
+
+## Installing Google Cloud SDK & Getting access
+
+1. Go to https://cloud.google.com/sdk/docs/quickstart-macos and download the correct package.
+2. Run the `install.sh` script.
+3. Run `gcloud init` logging into your King account (`[email protected]`).
+4. Select the `defold-web` project when asked which should be the active project. If you don't see it in the list ask Samuel or Jonas about access.
+5. Everything should be OK now and you should have permission to run the `./publish_sh` script.

docs/en/en.json

@@ -21,7 +21,7 @@
                     {
                         "path": "/tutorials/astronaut",
                         "name": "Walking astronaut"
-                    },                    
+                    },
                     {
                         "path": "/tutorials/movement",
                         "name": "Movement"
@@ -72,7 +72,7 @@
                         "name": "Building a car"
                     }
                 ]
-            },           
+            },
             {
                 "name": "Code samples",
                 "items": [
@@ -144,12 +144,12 @@
                     {
                         "path": "/manuals/glossary",
                         "name": "Glossary"
-                    }                    
+                    }
                 ]
             },
             {
                 "name": "WORKFLOW",
-                "items": [            
+                "items": [
                     {
                         "path": "/manuals/workflow",
                         "name": "Workflow"
@@ -220,7 +220,7 @@
                     {
                         "path": "/manuals/atlas",
                         "name": "Atlas"
-                    },                    
+                    },
                     {
                         "path": "/manuals/spine",
                         "name": "Spine animation"
@@ -257,18 +257,6 @@
                         "path": "/manuals/label",
                         "name": "Label"
                     },
-                    {
-                        "path": "/manuals/material",
-                        "name": "Material"
-                    },
-                    {
-                        "path": "/manuals/render",
-                        "name": "Render"
-                    },
-                    {
-                        "path": "/manuals/shader",
-                        "name": "Shader"
-                    },
                     {
                         "path": "/manuals/factory",
                         "name": "Factory"
@@ -353,6 +341,23 @@
                     }
                 ]
             },
+            {
+                "name": "RENDERING",
+                "items": [
+                    {
+                        "path": "/manuals/render",
+                        "name": "Render"
+                    },
+                    {
+                        "path": "/manuals/material",
+                        "name": "Material"
+                    },
+                    {
+                        "path": "/manuals/shader",
+                        "name": "Shader"
+                    }
+                ]
+            },
             {
                 "name": "PROJECT SETUP",
                 "items": [
@@ -408,7 +413,7 @@
                     {
                         "path": "/manuals/live-update",
                         "name": "Live update"
-                    }                    
+                    }
                 ]
             },
             {

docs/en/faq/faq.md

@@ -153,6 +153,14 @@ Why does my HTML5-app freeze at the splash screen in Chrome?
   $ python -m SimpleHTTPServer [port]
   ```
 
+Why am I getting a java exception when I try to start Defold?
+
+: `javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target`
+
+  This exception occurs when the editor tries to make an https connection but the certificate chain provided by the server cannot be verified.
+
+  See [this link](https://github.com/defold/editor2-issues/blob/master/faq/pkixpathbuilding.md) for details on this error.
+
 ## Linux issues
 
 When I try to create a new project, or open an existing one, the editor crashes.
@@ -319,6 +327,14 @@ Can I use string type script properties?
   preferrable since the editor automatically populate a drop-down with relevant url:s
   for you. See the [Script properties documentation](/manuals/script-properties) for details.
 
+How do I access the individual cells of a matrix (created using [vmath.matrix4()](/ref/vmath/#vmath.matrix4:m1) or similar)?
+
+: You access the cells using `mymatrix.m11`, `mymatrix.m12`, `mymatrix.m21` etc
+
+I am getting `Not enough resources to clone the node` when using [gui.clone()](ref/gui/#gui.clone:node) or [gui.clone_tree()](/ref/gui/#gui.clone_tree:node)
+
+: Increase the `Max Nodes` value of the gui component. You find this value in the Properties panel when selecting the root of the component in the Outline.
+
 ## Lua
 
 Which Lua standard libraries are included in Defold?

docs/en/manuals/bob.md

@@ -31,9 +31,13 @@ usage: bob [options] [commands]
                                      extensions)
  -ce,--certificate <arg>             Certificate (Android)
  -d,--debug                          Use debug version of dmengine (when
-                                     bundling)
+                                     bundling). Deprecated, use --variant
+                                     instead
     --defoldsdk <arg>                What version of the defold sdk (sha1)
                                      to use
+    --with-symbols                   When using native extensions, the debug
+                                     symbols are also returned (where
+                                     applicable)
  -e,--email <arg>                    User email
  -h,--help                           This help message
  -i,--input <arg>                    Source directory. Default is current
@@ -50,10 +54,17 @@ usage: bob [options] [commands]
  -pk,--private-key <arg>             Private key (Android)
  -r,--root <arg>                     Build root directory. Default is
                                      current directory
+    --strip-executable               Strip the dmengine of debug symbols
+                                     (when bundling iOS or Android)
  -tc,--texture-compression <arg>     Use texture compression as specified
-                                     in texture profiles (boolean)
+                                     in texture profiles
+ -tp,--texture-profiles <arg>        Use texture profiles (deprecated)
  -u,--auth <arg>                     User auth token
  -v,--verbose                        Verbose output
+    --variant <arg>                  Specify debug, release or headless
+                                     version of dmengine (when bundling)
+    --version                        Prints the version number to the
+                                     output
 ```
 
 Available commands:
@@ -65,33 +76,36 @@ Available commands:
 : Delete all files in the build directory.
 
 `build`
-: Builds all project data. Add the "--archive" option to build a data archive file ("game.darc" in the build directory).
+: Builds all project data. Add the `--archive` option to build a data archive file ("game.darc" in the build directory).
 
 `bundle`
-: Creates a platform specific application bundle. Bundling requires that a built archive is present (`build` with the `--archive` option) and that a target platform is specified (with the `--platform` option). Bob creates the bundle in the output directory unless a different directory is specified with the `--bundle-output` option. The bundle is named according to the project name setting in *game.project*.
+: Creates a platform specific application bundle. Bundling requires that a built archive is present (`build` with the `--archive` option) and that a target platform is specified (with the `--platform` option). Bob creates the bundle in the output directory unless a different directory is specified with the `--bundle-output` option. The bundle is named according to the project name setting in *game.project*. The `--variant` specifies which type of executable to build when bundling and it together with the `--strip-executable` option replaces the `--debug` option. If no `--variant` is specified you will get a release version of the engine (stripped of symbols on Android and iOS). Setting `--variant` to debug and omitting `--strip-executable` yields the same type of executable as `--debug` used to do.
 
 `resolve`
 : Resolve all external library dependencies.
 
 Available platforms:
 
-`x86-darwin`
-: Mac OSX
-
 `x86_64-darwin`
 : Mac OSX 64 bit
 
+`x86_64-win32`
+: Windows 64 bit
+
 `x86-win32`
-: Windows
+: Windows 32 bit
 
-`x86-linux`
-: Linux
+`x86_64-linux`
+: Linux 64 bit
+
+`arm64-darwin`
+: iOS 64 bit
 
 `armv7-darwin`
-: iOS
+: iOS 32 bit
 
 `armv7-android`
-: Android
+: Android 32 bit
 
 `js-web`
 : HTML5
@@ -102,7 +116,7 @@ By default, Bob looks in the current directory for a project to build. If you ch
 $ cd /Applications/Defold-beta/branches/14/4/main
 $ java -jar bob.jar
 100%
-$ 
+$
 ```
 
 You can string commands together to perform a sequence of tasks in one go. The following example resolves libraries, wipes the build directory, builds archive data and bundles an OSX application (named *My Game.app*):

docs/en/manuals/camera.md

@@ -5,61 +5,50 @@ brief: This manual describes the functionality of the Defold camera component.
 
 # Cameras
 
-A camera in Defold is a component that changes the viewport into the game world. By default, no camera is needed, but if your game requires scrolling through a level, Defold contains a primitive camera component that you use.
+A camera in Defold is a component that changes the viewport and projection of the game world. Out of the box, Defold ships with a built in render script that renders the game with no need of a camera component but you can easily replace the built in script with one that renders the game to your liking.
 
-Cameras are very simple objects that in essence does the following:
+The camera component defines a bare bones perspective camera that provides a view and projection matrix to the render script. If you need advanced features like chasing, zooming, shake etc you will need to implement it. There are a few library camera solutions that implements common camera features. They are available from the Defold community assets portal:
 
-1. They have a location in space---either 2D or 3D.
-2. They can be moved around in space---by moving the containing game object.
-3. They provide the render script with the data necessary to render with computed view and projection matrices.
-
-Cameras in OpenGL are expressed as coordinate systems with a viewer, or eye, position, a near and a far clipping plane. The near clipping plane equals the viewing plane, or the screen.
-
-![Camera planes](images/cameras/cameras_planes.png)
-
-A 3D camera usually has a viewing volume, a _frustum_, that is shaped like a cut off pyramid. The effect of this is that objects further away from the camera will be rendered smaller--the perspective will be realistic. The wider the _field of view_, the more the camera sees of the scenery, and the more dramatic the difference between near and far objects will be.
-
-![Camera field of view](images/cameras/cameras_fov.png)
+- [Rendercam](https://www.defold.com/community/projects/84064/) by Ross Grams.
+- [Ortographic camera](https://www.defold.com/community/projects/76573/) by Björn Ritzl.
 
 ## Creating a camera
 
-To create a camera, add a _Camera component_ to a game object:
+To create a camera, <kbd>right click</kbd> a game object and select <kbd>Add Component ▸ Camera</kbd>. You can alternatively create a component file in your project hierarchy and add the component file to the game object.
 
-![Create camera component](images/cameras/cameras_create_component.png)
+![create camera component](images/camera/create.png){srcset="images/camera/[email protected] 2x"}
 
-The camera component has a set of properties that defines the camera frustum.
+The camera component has the following properties that defines the camera *frustum*:
 
-![Camera properties](images/cameras/cameras_properties.png)
+![camera settings](images/camera/settings.png){srcset="images/camera/[email protected] 2x"}
 
-::: important
-The current default FOV value is misleading. It is not expressed in degrees but in radians. For a 45 degree FOV, change the value to 0.785 (&#120529; / 4).
-:::
+Id
+: The id of the component
 
-aspect_ratio
-: The ratio between the frustum width and height. 1.0 means that you assume a quadratic view. 1.33 is good for a 4:3 view like 1024x768. 1.78 is good for a 16:9 view.
+Aspect Ratio
+: The ratio between the frustum width and height. 1.0 means that you assume a quadratic view. 1.33 is good for a 4:3 view like 1024x768. 1.78 is good for a 16:9 view. This setting is ignored if *Auto Aspect Ratio* is set.
 
-fov
-: The camera field of view expressed in _radians_.
+Fov
+: The *vertical* camera field of view expressed in _radians_. The wider the field of view, the more the camera will see. Note that the current default value (45) is misleading. For a 45 degree field of view, change the value to 0.785 ($\pi / 4$).
 
-near_z
+Near Z
 : The Z-value of the near clipping plane.
 
-far_z
+Far Z
 : The Z-value of the far clipping plane.
 
-auto_aspect_ratio
-: Set this to 1 to let the camera automatically set the aspect ratio based on the game's screen settings.
+Auto Aspect Ratio
+: Set this to let the camera automatically calculate the aspect ratio.
 
+## Using the camera
 
-## Camera focus
-
-To activate the camera and have it feed its view and projection matrices, you send the component an `acquire_camera_focus` message:
+To activate a camera and have it feed its view and projection matrices to the render script, you send the component an acquire_camera_focus message:
 
 ```lua
 msg.post("#camera", "acquire_camera_focus")
 ```
 
-As soon as the camera component has camera focus, each frame it will send a `set_view_projection` message to the `@render` socket, i.e. to your render script:
+Each frame, the camera component that currently has camera focus will send a `"set_view_projection"` message to the "@render" socket, i.e. it will arrive to your render script:
 
 ```lua
 -- example.render_script
@@ -67,100 +56,45 @@ As soon as the camera component has camera focus, each frame it will send a `set
 function update(self)
     ...
     render.set_view(self.view)
-
     render.set_projection(self.projection)
     ...
 end
 
 function on_message(self, message_id, message)
     if message_id == hash("set_view_projection") then
-    	-- Camera view and projection arrives here. Store them.
-        self.view = message.view
+        self.view = message.view                    -- [1]
         self.projection = message.projection
     end
 end
 ```
+1. The message posted from the camera component includes a view matrix and a projection matrix.
 
-If you use both camera view and projection in your render script you will get a camera view into your game world with 3D perspective, even if your game content is strictly 2D. This is sometimes useful. You can, for instance, move the camera back to reveal more of the level. A simple camera script that measures the current camera move speed and pulls it back relative that speed could look like this:
-
-```lua
--- camera.script
---
-function init(self)
-	msg.post("#camera", "acquire_camera_focus")
-
-    -- Track current position and where someone told us to look at.
-	self.pos = go.get_world_position()
-	self.look_at = self.pos
-end
-
-function update(self, dt)
-	-- Calculate a new position based on current pos interpolated towards current
-	-- target position.
-	self.pos = vmath.lerp(0.03, self.pos, self.look_at)
-	
-	-- Measure speed on the 2D plane (zero Z)
-	local v1 = go.get_world_position()
-	v1.z = 0
-	local v2 = self.pos
-	v2.z = 0
-	local speed = vmath.length(v2 - v1)
-
-	-- Depending on how fast player is moving, pull camera back or push it forward.
-	self.pos.z = 500 + speed * speed * 10
-	go.set_position(self.pos)
-end
-
-function on_message(self, message_id, message, sender)
-    -- This camera reacts to "look_at" messages with a position as where
-    -- to go.
-	if message_id == hash("look_at") then	
-		self.look_at = message.position
-	end
-end
-```
-
-![Camera speed distance](images/cameras/cameras_speed_distance.png)
+## Projections
 
-Of course, we're not limited to moving the camera around. We can also rotate it along its X, Y and Z axis.
-
-```lua
--- 0.314 radians is about 18 degrees.
-go.set_rotation(vmath.quat_rotation_z(0.314) * vmath.quat_rotation_y(0.314))
-```
+The camera component currently supplies the render script with a perspective projection. This is well suited for 3D games. For 2D games, it is often desirable to render the scene with *orthographic projection*. This means that the view of the camera is no longer dictated by a frustum, but by a box. Orthographic projection is unrealistic in that it does not alter the size of objects based on their distance. An object 1000 units away will render at the same size as an object right in front of the camera.
 
-![Rotated camera](images/cameras/cameras_camera_rotated.png)
+![projections](images/camera/projections.png){srcset="images/camera/[email protected] 2x"}
 
-## Orthographic projection
-
-For many 2D games, the business of having a camera that can move back and forth becomes a problem, especially if you have content that you would like to render pixel perfect. Instead of trying to place your camera at the perfect Z distance to get the view you want, you should instead set up a camera with _orthographic projection_. This means that the view of the camera is no longer dictated by a frustum, but by a much simpler box.
-
-![Orthographic projection](images/cameras/cameras_orthographic.png)
-
-Orthographic projection is unrealistic in that it does not alter the size of objects based on their distance. A person standing 10000 meters away will still render at the same size as the person standing right in front of the camera. However, this method of projecting graphics is sometimes useful and 2D games often benefit from using it. To use orthographic projection you just have to modify your render script:
+To use orthographic projection you can ignore the projection matrix sent by the camera component and instead provide one yourself in the render script, just like the default renderscript does:
 
 ```lua
--- example.render_script
+-- example_orthographic.render_script
 --
 function update(self)
     ...
     render.set_view(self.view)
-    -- Set up an orthographic projection based on the width and height of the
-    -- game window.
-	local w = render.get_width()
-	local h = render.get_height()
-	render.set_projection(vmath.matrix4_orthographic(- w / 2, w / 2, -h / 2, h / 2, -1000, 1000))
+    local w = render.get_width() / 2
+    local h = render.get_height() / 2
+    local ortho = vmath.matrix4_orthographic(-w, w, -h, h, -1, 1)
+    render.set_projection(ortho)                    -- [1]
     ...
 end
 
 function on_message(self, message_id, message)
     if message_id == hash("set_view_projection") then
-    	-- Camera view and projection arrives here. We only need the view.
-        self.view = message.view
+        self.view = message.view                    -- [2]
     end
 end
 ```
-
-This is almost what the default render script does, with the difference that the above example centers the screen at the camera position.
-
-(Some of the graphic assets used are made by Kenney: http://kenney.nl/assets)
+1. Set up an orthographic projection based on the width and height of the game window. The center of view is the camera's position. Note that the default render script sets the lower left corner of the view at the camera's position.
+2. Only care about camera view since the projection is done separately.

docs/en/manuals/collection-proxy.md

@@ -29,7 +29,7 @@ When the Defold engine starts it loads and instanciates all game objects from a
 
 To fit the game objects and their components the engine allocates the memory needed for the whole "game world" into which the contents of the bootstrap collection are instanciated. A separate physics world is also created for any collision objects and physics simulation.
 
-Since script components need to be able to address all objects in the game, even from outside the bootstrap world, it is given a unique name: the *Id* property that you set in the collection file:
+Since script components need to be able to address all objects in the game, even from outside the bootstrap world, it is given a unique name: the *Name* property that you set in the collection file:
 
 ![bootstrap](images/collection-proxy/collection_id.png){srcset="images/collection-proxy/[email protected] 2x"}
 
@@ -48,7 +48,7 @@ msg.post("#myproxy", "load")
 
 The proxy component will instruct the engine to allocate space for a new world. A separate runtime physics world is also created and all the game objects in the collection "mylevel.collection" are instantiated.
 
-The new world gets its name from the *Id* property in the collection file, in this example it is set to "mylevel". The name has to be unique. If the *Id* set in the collection file is already used for a loaded world, the engine will signal a name collision error:
+The new world gets its name from the *Name* property in the collection file, in this example it is set to "mylevel". The name has to be unique. If the *Name* set in the collection file is already used for a loaded world, the engine will signal a name collision error:
 
 ```txt
 ERROR:GAMEOBJECT: The collection 'default' could not be created since there is already a socket with the same name.
@@ -72,7 +72,7 @@ end
 `"load"`
 : This message tells the collection proxy component to start loading its collection into a new world. The proxy will send back a message called `"proxy_loaded"` when it's done.
 
-`"load_async"`
+`"async_load"`
 : This message tells the collection proxy component to start background loading its collection into a new world. The proxy will send back a message called `"proxy_loaded"` when it's done.
 
 `"init"`
@@ -83,7 +83,7 @@ end
 
 ## Addressing into the new world
 
-The *Id* set in the collection file properties is used to address game objects and components in the loaded world. If you, for instance, create a loader object in the bootstrap collection you may need to communicate with it from any loaded collection:
+The *Name* set in the collection file properties is used to address game objects and components in the loaded world. If you, for instance, create a loader object in the bootstrap collection you may need to communicate with it from any loaded collection:
 
 ```lua
 -- tell the loader to load the next level:

docs/en/manuals/community.md

@@ -111,7 +111,7 @@ Assets are community pages which either has a) *enabled library use*, or b) *add
 If your asset is suited for library use (i.e. if you have made a library or an extension), choose "Add library URL" to add your library to your community page. This will allow you to choose hosting for your asset:
 
 Easy hosting
-: If you have your project hosted on the Defold servers (if you created your project from dashboard.defold.com), choosing this option will generate a library URL, usable by the community. Please note that you need to have folders added in *Include dirs* in your "game.project" file.
+: If you have your project hosted on the Defold servers (if you created your project from defold.com/dashboard), choosing this option will generate a library URL, usable by the community. Please note that you need to have folders added in *Include dirs* in your "game.project" file.
 
 <!-- Note: It is very important for us that we can provide a stable hosting solution for people depending on assets hosted on Defold’s servers, which is why *it’s not possible to remove releases* hosted via Easy hosting, in order to never break dependencies to people using the library. However—this naturally does not prevent you from switching visibility setting back to "Private" (if you no longer want your asset to be public), or make new releases (if you find that there are bugs in your latest release)—*but projects which use your library or extension can always continue to do so.* If you are worried about breaking dependencies, it could be a good idea to locally download and store libraries and extensions you are using. -->
 

docs/en/manuals/dev-app.md

@@ -1,6 +1,6 @@
 ---
 title: Running the development app on device
-brief: This manual explains how to put the development app on your device for iterative wireless development on device.
+brief: This manual explains how to put the development app on your device for iterative development on device.
 ---
 
 # The mobile development app
@@ -50,11 +50,11 @@ Success
 
 The development "dmengine" app is now available on the device.
 
-![dmengine on the device](images/android/dmengine_on_device.png)
+![dmengine on the device](images/dev-app/dmengine_on_device.png)
 
 ## Launching your game
 
-To launch your game on your device, the dev app and editor must be able to connect, over the same wifi network.
+To launch your game on your device, the dev app and editor must be able to connect, over the same wifi network or using USB (see below).
 
 1. Make sure the editor is up and running.
 2. Launch the dev app on the device.
@@ -64,6 +64,28 @@ To launch your game on your device, the dev app and editor must be able to conne
 
 ![launch](images/dev-app/launch.png)
 
+### Connecting to an iOS device using USB on Windows
+
+When connecting over USB on Windows to a dev app running on an iOS device you first need to [install iTunes](https://www.apple.com/lae/itunes/download/). When iTunes is installed you also need to [enable Personal Hotspot](https://support.apple.com/en-us/HT204023) on your iOS device from the Settings menu. If you see an alert that says tap "Trust This Computer?" tap Trust. The device should now show up under <kbd>Project ▸ Targets</kbd> when the dev app is running.
+
+### Connecting to an iOS device using USB on Linux
+
+On Linux you need to enable Personal Hotspot on your device from the Settings menu when connected using USB. If you see an alert that says tap "Trust This Computer?" tap Trust. The device should now show up under <kbd>Project ▸ Targets</kbd> when the dev app is running.
+
+### Connecting to an iOS device using USB on OSX
+
+On newer iOS versions the device will automatically open a new ethernet interface between the device and computer when connected using USB on OSX. The device should show up under <kbd>Project ▸ Targets</kbd> when the dev app is running.
+
+On older iOS versions you need to enable Personal Hotspot on your device from the Settings menu when connected using USB on OSX. If you see an alert that says tap "Trust This Computer?" tap Trust. The device should now show up under <kbd>Project ▸ Targets</kbd> when the dev app is running.
+
+### Connecting to an Android device using USB on OSX
+
+On OSX it is possible to connect over USB to a running dev app on an Android device when the device is in USB Tethering Mode. On MacOS you need to install a third-party driver such as [HoRNDIS](https://joshuawise.com/horndis#available_versions). When HoRNDIS is installed you also need to allow it to run via the Security & Privacy settings. Once USB Tethering is enabled the device will show up under <kbd>Project ▸ Targets</kbd> when the dev app is running.
+
+### Connecting to an Android device using USB on Windows or Linux
+
+On Windows and Linux it is possible to connect over USB to a running dev app on an Android device when the device is in USB Tethering Mode. Once USB Tethering is enabled the device will show up under <kbd>Project ▸ Targets</kbd> when the dev app is running.
+
 ## Troubleshooting
 
 Unable to download application

docs/en/manuals/facebook.md

@@ -9,10 +9,6 @@ The Facebook API allows you to interact with Facebook's game connectivity featur
 
 The Defold Facebook API brings the various platform specific Facebook APIs under a unified set of functions that work the same on iOS, Android and HTML5 (through Facebook Canvas). To get started with Facebook connectivity in your games, you need a Facebook account.
 
-::: important
-As of Defold 1.2.92, the Facebook API is redesigned with a new way of interacting with Facebook. The previous API still works, no breaking changes were introduced. However, the old API should be considered deprecated and not used in new applications.
-:::
-
 ## Registering as a Facebook developer
 
 To develop for Facebook you must sign up as a Facebook developer. This allows you to create Facebook applications that your Defold game can communicate with.

docs/en/manuals/font.md

@@ -44,6 +44,12 @@ Set the *Font* property to the font file and set the font properties as needed.
   - `TYPE_BITMAP` converts the imported OTF or TTF file into a font sheet texture where the bitmap data is used to render text nodes. The color channels are used to encode the face shape, outline and drop shadow. For *.fnt* files, the source texture bitmap is used as is.
   - `TYPE_DISTANCE_FIELD` The imported font is converted into a font sheet texture where the pixel data represents not screen pixels but distances to the font edge. See below for details.
 
+*Render Mode*
+: The render mode to use for glyph rendering.
+
+  - `MODE_SINGLE_LAYER` produces a single quad for each character.
+  - `MODE_MULTI_LAYER` produces separate quads for the glyph shape, outline and shadows respectively. The layers are rendered in back-to-front order, which prevents a character from obscuring previously rendered characters if the outline is wider than the distance between glyphs. This render mode also enables proper drop shadow offsetting, as specified by the Shadow X/Y properties in the font resource.
+
 *Size*
 : The target size of the glyphs in pixels.
 
@@ -63,14 +69,14 @@ Set the *Font* property to the font file and set the font properties as needed.
 : The transparency of the generated shadow. 0.0--1.0.
 
 ::: sidenote
-Shadow rendering of fonts is disabled in the default built-in material shaders because of performance reasons. It is fairly easy to write a custom shader that renders shadows (at some cost) if you need them.
+Shadow support is enabled by the built-in font material shaders and handles both the single and multi layered render mode. If you don't need layered font rendering or shadow support, it is best to use a simpler shader such as the builtins/font-singlelayer.fp.
 :::
 
 *Shadow Blur*
-: The blur radius in pixels for the generated shadow.
+: For bitmap fonts, this setting indicates the number of times a small blur kernel will be applied to each font glyph. For distance field fonts, this setting equals the actual pixel width of the blur.
 
 *Shadow X/Y*
-: The horizontal and vertical offset in pixels of the generated shadow.
+: The horizontal and vertical offset in pixels of the generated shadow. This setting will only affect the glyph shadow when the output format is set to `MODE_MULTI_LAYER`.
 
 *Extra Characters*
 : By default the font will include the ASCII printable characters (character codes 32-126). To manually include additional characters, list them in this property field.
@@ -134,4 +140,25 @@ Distance field fonts need to be rendered to a target size that is big enough to
 
 ![Distance field artifacts](images/font/df_artifacts.png){srcset="images/font/[email protected] 2x"}
 
+If you don't want shadow or outline support, set their respective alpha values to zero. Otherwise, shadow and outline data will still be generated, taking up unnecessary memory.
+
+## Font Cache
+A font resource in Defold will result in two things at runtime, a texture and the font data.
+
+* The font data consist of a list of glyph entries, each containing some basic kerning info and the bitmap data for that glyph.
+* The texture is internally called the "glyph cache texture" and it will be used when rendering text for a specific font.
+
+At runtime, when rendering text, the engine will first loop through the glyphs to be rendered to check which glyphs are available in the texture cache. Each glyph that is missing from the glyph texture cache will trigger a texture upload from the bitmap data stored in the font data.
+
+Each glyph is placed internally in the cache according to the font baseline, which enables calculating local texture coordinates of the glyph within its corresponding cache cell in a shader. This means that you can achieve certain text effects such as gradients or texture overlays dynamically. The engine exposes metrics about the cache to the shader via a special shader constant called `texture_size_recip`, which contains the following information in the vector components:
+
+* `texture_size_recip.x` is the inverse of the cache width
+* `texture_size_recip.y` is the inverse of the cache height
+* `texture_size_recip.z` is the ratio of cache cell width to the cache width
+* `texture_size_recip.w` is the ratio of cache cell height to the cache height
+
+For example - to generate a gradient in a shader fragment, simply write:
+
+`float horizontal_gradient = fract(var_texcoord0.y / texture_size_recip.w);`
 
+For more information about shader uniforms, see the [Shader manual](/manuals/shader).

docs/en/manuals/gui-clipping.md

@@ -5,56 +5,65 @@ brief: This manual describes how to create GUI nodes that mask other nodes throu
 
 # Clipping
 
-GUI nodes with textures or text add graphics to the GUI. However, sometimes it is convenient to be able to _mask_ what is being shown, to be able to _remove_ particular parts of the graphics from the screen.
+GUI nodes can be used as *clipping* nodes---masks that control how other nodes are rendered. This manual explains how this feature works.
 
-Say, for instance, that you want to create an on-screen HUD element containing a mini-map that players can use to help orient themselves in your game.
+## Creating a clipping node
 
-![Minimap HUD](images/clipping/clipping_minimap.png)
+Box, Text and Pie nodes nodes can be used for clipping. To create a clipping node, add a node in your GUI, then set its properties accordingly:
 
-Using a pie node with clipping makes creating the minimap a very easy task:
+Clipping Mode
+: The mode used for clipping.
+  - `None` renders the node without any clipping taking place.
+  - `Stencil` makes the node writing to the current stencil mask.
 
-![Making the minimap](images/clipping/clipping_making_minimap.png)
+Clipping Visible
+: Check to render the content of the node.
 
-- Add a pie node. It will act as a "keyhole" for the map.
-- Add a box node and apply the map texture to it.
-- Child the box node to the pie node.
-- Set the *Clipping* property of the pie node to "Stencil".
+Clipping Inverted
+: Check to write the inversion of the node's shape to the mask.
 
-![Clipping preview](images/clipping/clipping_preview.png)
+Then add the node(s) you want to be clipped as children to the clipping node.
 
-Now the parent node will act as a "keyhole" down to its children. Only graphics bound by the parent clipping node will show so the parent node will define the graphical outer bounds of the map. We are therefore free to move the map node around and whatever part is currently within the parent bounds will show.
+![Create clipping](images/gui-clipping/create.png){srcset="images/gui-clipping/[email protected] 2x"}
 
-Clipping can be applied to box nodes and pie nodes. Text nodes can not clip other nodes. Two different types of clipping are available and a node can be set to *Visible clipper* which draws the clipper shape, and *Inverted clipper* which inverts how the clipper affects the clipping mask (see below for details).
+## Stencil mask
 
-![Clipping properties](images/clipping/clipping_properties.png)
+Clipping works by having nodes writing to a *stencil buffer*. This buffer contains clipping masks: information that that tells the graphics card whether a pixel should be rendered or not.
 
-Stencil clipping can be applied to box nodes and pie nodes. Stencils have some limitations:
+- A node with no clipper parent but with clipping mode set to `Stencil` will write its shape (or its inverse shape) to an new clipping mask stored in the stencil buffer.
+- If a clipping node has a clipper parent it will instead clip the parent's clipping mask. A clipping child node can never _extend_ the current clipping mask, only clip it further.
+- Non clipper nodes that are children to clippers will be rendered with the clipping mask created by the parent hierarchy.
 
-- The total number of stencil clippers can not exceed 256.
-- The maximum nesting depth of child _stencil_ nodes is 8 levels deep. (Only nodes with stencil clipping count.)
-- The maximum number of stencil node siblings is 127. For each level down a stencil hierarchy, the max limit is halved.
-- Inverted nodes have a higher cost. There is a limit to 8 inverted clipping nodes and each will halve the max amount of non-inverted clipping nodes.
-- Stencils render a stencil mask from the _geometry_ of the node (not the texture). It is possible to invert the mask by setting the *Inverted clipper* property.
+![Clipping hierarchy](images/gui-clipping/setup.png){srcset="images/gui-clipping/[email protected] 2x"}
 
-## Stencil mask
+Here, three nodes are set up in a hierarchy:
 
-To understand how stencil clipping works, it is useful to imagine how a hierarchy of stencils apply their individual clipping shapes, in turn down the hierarchy, to the total mask. The mask set of a clipping node is inherited by the children of that node and the children can never _extend_ the mask, only clip it. Let's look at a concrete example:
+- The hexagon and square shapes are both stencil clippers.
+- The hexagon creates a new clipping mask, the square clips it further.
+- The circle node is a regular pie node so it will be rendered with the clipping mask created by its parent clippers.
 
-![Clipping hierarchy](images/clipping/clipping_hierarchy.png)
+Four combinations of normal and inverted clippers are possible for this hierarchy. The green area marks the part of the circle that is rendered. The rest is masked:
 
-The hexagon and square shapes are both set to stencil clippers. Setting the *Inverted clipper* property inverts the mask as inherited by that node. For the hierarchy above, four combinations of normal and inverted clippers are possible:
+![Stencil masks](images/gui-clipping/modes.png){srcset="images/gui-clipping/[email protected] 2x"}
 
-![Stencil masks](images/clipping/clipping_stencil_masks.png)
+## Stencil limitations
 
-If a node below an inverted node is also set to *Inverted clipper*, the part of the mask bound by the child node is in turn inverted. By childing inverted clippers to each other, it is thus possible to cut multiple holes in a node:
+- The total number of stencil clippers can not exceed 256.
+- The maximum nesting depth of child _stencil_ nodes is 8 levels deep. (Only nodes with stencil clipping count.)
+- The maximum number of stencil node siblings is 127. For each level down a stencil hierarchy, the max limit is halved.
+- Inverted nodes have a higher cost. There is a limit to 8 inverted clipping nodes and each will halve the max amount of non-inverted clipping nodes.
+- Stencils render a stencil mask from the _geometry_ of the node (not the texture). It is possible to invert the mask by setting the *Inverted clipper* property.
 
-![Two inverters cutting a node](images/clipping/clipping_two_inverters.png)
 
 ## Layers
 
-Layers can be used to control rendering order (and batching) of nodes. When using layers and clipping nodes the usual layering order is overridden. Clipping order take precedence over layer order, meaning that regardless of what layer a node belongs to, it will be clipped according to the node hierarchy. Layers only affect the draw order of graphics--and furthermore, the layer set on a clipping node only affects the draw order _in that clipper's hierarchy_.
+Layers can be used to control rendering order (and batching) of nodes. When using layers and clipping nodes the usual layering order is overridden.
+
+- Clipping order take precedence over layer order---regardless of what layer a node belongs to, it will be clipped according to the node hierarchy.
+- Layers only affect the draw order of graphics---and furthermore, the layer set on a clipping node only affects the draw order _in that clipper's hierarchy_.
 
-To illustrate, consider this clipper node "window_and_shadow" that has an inner shadow texture applied to it. By setting the node's *Visible clipper* property and then layering it ("layer2") in relation to the clipped "map" node ("layer0"), the clipper's texture is rendered on top of the child "map". Note that neither the layer set on "map", nor the one on "window_and_shadow", has any effect on its render order in relation to "blue_box" ("layer2") and "orange_box" ("layer1"). If you want to change the render order of "window_and_shadow" in relation to "blue_box" and "orange_box", simply change their order in the node tree.
+![Layers and clipping](images/gui-clipping/layers.png){srcset="images/gui-clipping/[email protected] 2x"}
 
-![Layers and clipping](images/clipping/clipping_layers.png)
+Here the clipper node "ocular" is set to "layer3" and the "bean" node is set to "layer1". The ocular clipper's texture is therefore rendered on top of the clipped bean.
 
+The node "shield" is set to "layer2", but it has no effect on the node's render order in relation to "ocular" or "bean". To change the render order of "shield", change the node tree index order.

docs/en/manuals/gui-layouts.md

@@ -5,62 +5,74 @@ brief: Defold supports GUIs that automatically adapt to screen orientation chang
 
 # Layouts
 
-Defold supports GUIs that automatically adapt to screen orientation changes on mobile devices. Using this feature allows you to design GUIs that adapt to the orientation and aspect ratio of the screen. It is also possible to create layouts that match certain device models.
+Defold supports GUIs that automatically adapt to screen orientation changes on mobile devices. By using this feature you can design GUIs that adapt to the orientation and aspect ratio of a range of screen sizes. It is also possible to create layouts that match particular device models.
 
-## Display profiles
+## Creating display profiles
 
-Each project contains a `builtins/render/default.display_profiles` with two profiles:
+By default, the "game.project" settings specify that a built in display profiles settings file ("builtins/render/default.display_profiles") is used. The default profiles are "Landscape" (1280 pixels wide and 720 pixels high) and "Portrait" (720 pixels wide and 1280 pixels high). No device models are set on the profiles so they will match on any device.
 
-![Default display profiles](images/layouts/layouts_display_profiles.png)
+To create a new profiles settings file, either copy the one from the "builtins" folder or <kbd>right click</kbd> a suitable location in the *Assets* view and select <kbd>New... ▸ Display Profiles</kbd>. Give the new file a suitable name and click <kbd>Ok</kbd>.
 
-Landscape
-: 1280 pixels wide and 720 pixels high
+The editor now opens the new file for editing. Add new profiles by clicking the <kbd>+</kbd> in the *Profiles* list. For each profile, add a set of *qualifiers* for the profile:
 
-Portrait
-: 720 pixels wide and 1280 pixels high
+Width
+: The pixel width of the qualifier.
 
-Device models
-: None
+Height
+: The pixel height of the qualifier.
 
-The dynamic layout of GUIs works by matching display profiles qualifiers to the current width and height of the display that the game is running on and any device models specified as reported by `sys.get_sys_info()`.
+Device Models
+: A comma separated list of device models. The device model matches the start of the device model name, e.g. `iPhone10` will match "iPhone10,\*" models. Model names with commas should be enclosed in quotes, i.e. `"iPhone10,3", "iPhone10,6"` matches iPhone X models (see https://www.theiphonewiki.com/wiki/Models). Note that the only platforms reporting a device model when calling `sys.get_sys_info()` is Android and iOS. Other platforms return an empty string and will therefore never pick a display profile that has a device model qualifier.
+
+![New display profiles](images/gui-layouts/new_profiles.png){srcset="images/gui-layouts/[email protected] 2x"}
+
+You also need to specify that the engine should use your new profiles. Open "game.project" and select the display profiles file in the *Display Profiles* setting under *display*:
+
+![Settings](images/gui-layouts/settings.png){srcset="images/gui-layouts/[email protected] 2x"}
 
 ::: sidenote
-The only platforms reporting a device model when calling `sys.get_sys_info()` is Android and iOS. Other platforms return an empty string.
+The current development app for iOS does not respect the *Dynamic Orientation* setting but will always change orientation dynamically.
 :::
 
-For devices with an aspect ratio of 16:9 these profiles are probably enough. Even if the actual physical dimensions of the screen are higher or lower, the engine will automatically select the a profile that is closest.
+If you want the engine to automatically switch between portrait and landscape layouts on device rotation, check the *Dynamic Orientation* box. The engine will dynamically select a matching layout and also change the selection if the device changes orientation.
 
-The device models qualifier is a comma separated string where a display profile can be targeted against one or more specific device models. Adding for example `"iPhone10"` to the device model qualifier means that the profile will only be eligible for selection for devices **starting with** that same string, for example `iPhone10,3` and `iPhone10,6`.
+## GUI layouts
 
-If you need to alter the default profiles, simply copy the built in file to a new place within your project or create a new file, then change the setting in `project.settings` so the engine knows which profiles-file to use:
+The current set of display profiled can be used to create layout variants of your GUI node setup. To add a new layout to a GUI scene, right-click the *Layouts* icon in the *Outline* view and select <kbd>Add ▸ Layout ▸ ...</kbd>:
 
-![Project settings](images/layouts/layouts_project_settings.png)
+![Add layout to scene](images/gui-layouts/add_layout.png){srcset="images/gui-layouts/[email protected] 2x"}
 
-The project settings also allow you to enable *dynamic_orientation* which means that the engine will dynamically select a matching layout and also change the selection if the device changes orientation.
+When editing a GUI scene, all nodes are edited on a particular layout. The currently selected layout is indicated in the GUI scene layout dropdown in the toolbar. If no layout is chosen, the nodes are edited in the *Default* layout.
 
-::: sidenote
-The current development app for iOS does not respect the *dynamic_orientation* setting but will always change orientation dynamically.
-:::
+![Layouts toolbar](images/gui-layouts/toolbar.png){srcset="images/gui-layouts/[email protected] 2x"}
 
-## GUI layouts
+![portrait edit](images/gui-layouts/portrait.png){srcset="images/gui-layouts/[email protected] 2x"}
 
-The defined display profiles can then be used to create layouts in the GUI editor. When working in the editor, a *Default* layout is used by default. If you have not added any additional layout(s), the default layout will be used. To add a new layout, right-click the *Layouts* icon in the *Outline* view and select the <kbd>Layout ▸ ...</kbd> menu item:
+Each change to a node property that you do with a layout selected _overrides_ the property in respect to the *Default* layout. Properties that are overridden are marked in blue. Nodes with overridden properties are also marked in blue. You can click on the reset button next to any overridden property to reset it to the original value.
 
-![Add layout to scene](images/layouts/layouts_add.png)
+![landscape edit](images/gui-layouts/landscape.png){srcset="images/gui-layouts/[email protected] 2x"}
 
-::: sidenote
-The *Default* layout is only used if there are no other layouts added to the GUI scene. So, if you add a "Landscape" layout, that will be the best match for all orientations until you also add a "Portrait" layout.
-:::
+A layout cannot delete or create new nodes, only override properties. If you need to remove a node from a layout you can either move the node off-screen or delete it with script logic. You should also pay attention to the currently selected layout. If you add a layout to your project, the new layout will be set up according to the currently selected layout. Also, copying and pasting nodes considers the currently selected layout, when copying *and* when pasting.
 
-When editing a GUI scene, all nodes are edited on a particular layout. The currently selected layout is indicated in the gui scene layout dropdown.
+## Dynamic profile selection
 
-![Editing default layout](images/layouts/layouts_default.png)
+The dynamic layout matcher scores each display profile qualifier according to the following rules:
 
-You also get visual feedback on whether a node overrides a property on the currently selected layout (other than *Default*) or not. Each change to a node property that you do with a layout selected _overrides_ the property in respect to the *Default* layout. Properties that are overridden are marked in blue. You can click on the reset button next to the property to reset the property to the default value.
+1. If there is no device model set, or the device model matches, a score $S$ is calculated for the qualifier.
 
-![Editing with layouts](images/layouts/layouts_modified.png)
+2. The score ($S$) is calculated with the area of the display ($A$), the area from the qualifier ($A_Q$), the aspect ratio of the display ($R$) and the aspect ratio of the qualifier ($R_Q$):
 
-Note that layouts only override properties. A layout cannot delete or create new nodes. If you need to remove a node from a layout you can either move the node off-screen or delete it with script logic. You should also pay attention to the currently selected layout. If you add a layout to your project, the new layout will be set up according to the currently selected layout. Also, copying and pasting nodes considers the currently selected layout, when copying *and* when pasting.
+   $$
+   S=\left|1 - \frac{A}{A_Q}\right| + \left|1 - \frac{R}{R_Q}\right|
+   $$
+
+3. The profile with the lowest scoring qualifier is selected, if the orientation (landscape or portrait) of the qualifier matches the display.
+
+4. If no profile with a qualifier of the same orientation is found, the profile with the best scoring qualifier of the other orientation is selected.
+
+5. If no profile can be selected, the *Default* fallback profile is used.
+
+Since the *Default* layout is used as fallback in runtime if there are no better matching layout it means that if you add a "Landscape" layout, it will be the best match for *all* orientations until you also add a "Portrait" layout.
 
 ## Layout change messages
 
@@ -68,13 +80,11 @@ When the engine switches layout as a result of device rotation, a `layout_change
 
 ```lua
 function on_message(self, message_id, message, sender)
-    if message_id == hash("layout_changed") and message.id == hash("Landscape") then
-        -- switching layout to landscape
-    ...
-    elseif message_id == hash("layout_changed") and message.id == hash("Portrait") then
+  if message_id == hash("layout_changed") and message.id == hash("My Landscape") then
+    -- switching layout to landscape
+  elseif message_id == hash("layout_changed") and message.id == hash("My Portrait") then
     -- switching layout to portrait
-    ...
-    end
+  end
 end
 ```
 
@@ -82,19 +92,11 @@ In addition, the current render script receives a message whenever the window (g
 
 ```lua
 function on_message(self, message_id, message)
-    if message_id == hash("window_resized") then
-      -- The window was resized. message.width and message.height contain the
-      -- new dimensions of the window.
-    end
+  if message_id == hash("window_resized") then
+    -- The window was resized. message.width and message.height contain the
+    -- new dimensions of the window.
+  end
 end
 ```
 
-## In game content
-
-Note that when orientation is switched, the GUI layout manager will automatically rescale and reposition GUI nodes according to your layout and node properties. For in-game content, the view is rendered as is, by default stretch-fit into the current window.
-
-![Orientation rendering](images/layouts/layouts_orientation.png)
-
-If your game design puts specific contraints on how the game view should be rendered, you can change the render script and implement precisely the behavior you need, taking camera, viewport and whatnot into consideration.
-
-(Some of the graphic assets used are made by Kenney: http://kenney.nl/assets)
+When orientation is switched, the GUI layout manager will automatically rescale and reposition GUI nodes according to your layout and node properties. In-game content, however, is rendered in a separate pass (by default) with a stretch-fit projection into the current window. To change this behavior, either supply your own modified render script, or use a camera [library](/community/assets/).

docs/en/manuals/gui-pie.md

@@ -5,31 +5,52 @@ brief: This manual explains how to use pie nodes in Defold GUI scenes.
 
 # GUI pie nodes
 
-Pie nodes can be used to create circular or ellipsoid objects. In its simplest form, a pie node is simply a circle or ellipse inscribed in the node bounding box. If the width and height are identical, the circle's diameter will be that value. If the width and height differ, the node will instead be an ellipse with the node width being the horizontal extent of the ellipse and the height being the vertical extent. The texture set for the node is applied straight, with the corners of the texture correlating to the corners of the node bounding box.
+Pie nodes are used to create circular or ellipsoid objects ranging from plain circles to pies and square donut shapes.
 
-![Pie node](images/gui/gui_pie_create.png)
+## Creating a pie node
 
-Pie nodes have a set of properties that make it possible to use them to create a wide range of shapes. All of these properties can be changed programmatically (see [GUI API documentation](/ref/gui) for details) and some can be animated.
+<kbd>Right click</kbd> the *Nodes* section in the *Outline* and select <kbd>Add ▸ Pie</kbd>. The new pie node is selected and you can modify its properties.
 
-![Pie properties](images/gui/gui_pie_properties.png)
+![Create pie node](images/gui-pie/create.png){srcset="images/gui-pie/[email protected] 2x"}
 
-Inner radius
+The following properties are unique to pie nodes:
+
+Inner Radius
 : The inner radius of the node, expressed along the X axis.
 
-Outer bounds
-: Extend the node to the outer radius (`Ellipse`) or to the node's bounding box (`Rectangle`).
+Outer Bounds
+: The shape of the outer bounds of the node. 
+  
+  - `Ellipse` will extend the node to the outer radius.
+  - `Rectangle` will extend the node to the node's bounding box.
 
-Perimeter vertices
+Perimeter Vertices
 : The number of segments that will be used to build the shape, expressed as the number of vertices required to fully circumscribe the 360 degree perimeter of the node.
 
-Pie fill angle
+Pie Fill Angle
 : How much of the pie should be filled. Expressed as a counter-clockwise angle starting from the right.
 
-![Radius and angle](images/gui/gui_pie_radius_angle.png)
+![Properties](images/gui/properties.png){srcset="images/gui-pie/[email protected] 2x"}
+
+If you set a texture on the node, the texture image is applied flat, with the corners of the texture correlating to the corners of the node bounding box. 
+
+## Modify pie nodes at runtime
+
+Pie nodes respond to any generic node manipulation functions for setting size, pivot, color and so forth. A few text node only functions and properties exist:
+
+```lua
+local pienode = gui.get_node("my_pie_node")
 
-With the *Outer bounds* option set to `Rectangle` the shape extends to the node bounding box. Together with an *Inner radius* and/or a *Pie fill angle*, complex shapes can be created.
+-- get the outer bounds
+local fill_angle = gui.get_fill_angle(pienode)
 
-![Rectangle bounds](images/gui/gui_pie_rectangular.png)
+-- increase perimeter vertices
+local vertices = gui.get_perimeter_vertices(pienode)
+gui.set_perimeter_vertices(pienode, vertices + 1)
 
-![Rectangle bounds and angle](images/gui/gui_pie_rectangular_angle.png)
+-- change outer bounds
+gui.set_outer_bounds(pienode, gui.PIEBOUNDS_RECTANGLE)
 
+-- animate the inner radius
+gui.animate(pienode, "inner_radius", 100, gui.EASING_INOUTSINE, 2, 0, nil, gui.PLAYBACK_LOOP_PINGPONG)
+```

docs/en/manuals/gui-spine.md

@@ -5,19 +5,21 @@ brief: This manual explains how to use bone animated Spine nodes in Defold GUI s
 
 # GUI Spine nodes
 
-Spine bone animations are available in GUI animations as well as in game objects. This manual explains how to use imported Spine animation data in GUI scenes.
+Spine animated models can be added as GUI nodes as well as game object components. This manual explains how to use imported Spine animation data in GUI scenes.
 
-Any imported Spine bone animation is available in GUI scenes as well as in game objects (through the *SpineModel* component). In order to work with Spine bone animations in Defold, you first have to import the animation data and set up a Spine Scene resource. The [Spine animation](/manuals/spine) documentation describes how to do that.
+## Creating a spine node
 
-To make the contents of a Spine Scene resource available in a GUI scene, add it to the scene by right-clicking the *Spine Scenes* section of the scene in the *Outline* and select <kbd>Add Spine Scene</kbd>. Choose the Spine Scene you wish to use in the scene.
+First you have to import the animation data and set up a Spine Scene resource. The [Spine animation](/manuals/spine) documentation describes how to do that.
 
-![Add Spine Scene](images/gui/gui_spine_add_scene.png)
+Second, the contents of your Spine Scene resource must be available in your GUI scene. Add it by <kbd>right-clicking</kbd> the *Spine Scenes* section of the scene in the *Outline* and select <kbd>Add ▸ Spine Scenes...</kbd>. Choose the Spine Scenes (one or more) you wish to use in the scene.
 
-![Added Spine Scene](images/gui/gui_spine_added_scene.png)
+![Add Spine Scene](images/gui-spine/add.png){srcset="images/gui-spine/[email protected] 2x"}
 
-Now, if you create a Spine node (right click in the *Nodes* section of the *Outline* and select <kbd>Add Spine Node</kbd>) you are able to set the properties of the new Spine node accordingly:
+Third, create a Spine node by <kbd>right clicking</kbd> the *Nodes* section of the *Outline* and selecting <kbd>Add ▸ Spine</kbd>).
 
-![Spine node](images/gui/gui_spine_node.png)
+![New spine node](images/gui-spine/new_node.png){srcset="images/gui-spine/[email protected] 2x"}
+
+The new node is automatically selected. Make sure to set its properties:
 
 Spine Scene
 : The Spine Scene to use as a data source for this node.
@@ -42,9 +44,9 @@ end)
 
 ## The bone hierarchy
 
-The individual bones in the Spine skeleton exist as GUI nodes. The nodes are named according to their names in the Spine setup.
+The individual bones in the Spine skeleton can be accessed as GUI nodes. The nodes are named according to their names in the Spine setup.
 
-![Spine bone names](images/gui/gui_spine_bones.png)
+![Spine bone names](images/gui-spine/bone.png){srcset="images/gui-spine/[email protected] 2x"}
 
 For instance, to attach another node to an existing bone node, fetch the bone node by name with [`gui.get_spine_bone()`](/ref/gui#gui.get_spine_bone) and attach the child to it:
 
@@ -56,7 +58,7 @@ local tail = gui.get_spine_bone(cat, "tail")
 gui.set_parent(textnode, tail)
 ```
 
-All bones are also accessible through [`gui.get_node()`](/ref/gui#gui.get_node), by the bone name prefixed by the name of the name of the Spine node and a slash (`/`):
+Bones are also accessible through [`gui.get_node()`](/ref/gui#gui.get_node), by the bone name prefixed by the name of the name of the Spine node and a slash (`/`):
 
 ```lua
 -- Attach a text node to the tail of the cat

docs/en/manuals/gui-template.md

@@ -5,46 +5,58 @@ brief: This manual explains the Defold GUI template system that is used to creat
 
 # GUI template nodes
 
-GUI template nodes provide a simple but powerful mechanism to create reusable visual GUI components based on shared templates or "prefabs". This manual explains the feature and how to use it.
+GUI template nodes provide a powerful mechanism to create reusable GUI components based on shared templates or "prefabs". This manual explains the feature and how to use it.
 
-GUI templates are GUI scenes that are inserted into another GUI scene as a compound node, much like sub-collections can be placed inside other collections. But while a placed sub-collection can override the position of the sub-collection's root and any defined script-properties, a GUI template node can override any property values. Also, like sub-collections, GUI template nodes do not exist as a runtime concept, only as an editing tool.
+A GUI template is a GUI scene that is instanciated, node for node, in another GUI scene. Any property values in the original template nodes can then be overridden.
 
-## Creating and using a template
+## Creating a template
 
-Since a GUI template is a plain GUI scene, there's nothing special about how they are created. Suppose we want to create and use a button template. We can then make a default button in a GUI scene and save it in a file:
+A GUI template is a plain GUI scene so it is created just like any other GUI scene. <kbd>Right click</kbd> a location in the *Assets* pane and select <kbd>New... ▸ Gui</kbd>.
 
-![Button template](images/gui-templates/gui-templates-button.png)
+![Create template](images/gui-templates/create.png){srcset="images/gui-templates/[email protected] 2x"}
 
-Now we can add any number of instances of the button to another GUI scene. Create or open a new scene, then select <kbd>Gui ▸ Add Template Node</kbd> or right-click *Nodes* in the *Outline* and select <kbd>Add Template</kbd> from the drop-down.
+Create the template and save it. Note that the nodes of the instance will be placed relative to origo so it is a good idea to create the template at position 0, 0, 0.
 
-![Add template](images/gui-templates/gui-templates-add-template.png)
+## Creating instances from a template
 
-Select the GUI scene file to use as a template, in this case *button.gui*. You can add any number of nodes, each an instance based on the same template. If we change the template, each instance updates immediately in the editor, reflecting the changes. Notice that all nodes present in the template node are accessible in the *Outline* view. Nodes under a template node are automatically named with a prefix "[template node id]/".
+You can create any number of instances based on the instance. Create or open the GUI scene where you want to place the template, then <kbd>right click</kbd> the *Nodes* section in the *Outline* and select <kbd>Add ▸ Template</kbd>.
 
-![Node instances](images/gui-templates/gui-templates-instances.png)
+![Create instance](images/gui-templates/create_instance.png){srcset="images/gui-templates/[email protected] 2x"}
 
-The template itself is represented in the node tree with an item: "button" and "button1" above. Even though they look like they are nodes, they *are not*. Adding a template to a scene adds all the template nodes. There is no "template root node" or similar. If you need a root node to manipulate all nodes in a template, you have to add the root node to the template scene.
+Set the *Template* property to the template GUI scene file.
 
-## Overloading properties
+You can add any number of template instances, and for each instance you can override the properties of each node and change instance node's position, coloring, size, texture and so forth.
 
-Each instance node can overload any of the properties set in the template. Simply mark the node you wish to edit and change the property you want to alter. Nodes that have any overloaded properties are marked green in the *Outline* view. An overloaded property is marked blue. Click the blue property name to reset the property's value to the default.
+![Instances](images/gui-templates/instances.png){srcset="images/gui-templates/[email protected] 2x"}
 
-![Overloaded properties](images/gui-templates/gui-templates-overloaded.png)
+Any property that you change is marked blue in the editor. Press the reset button by the property to set its value to the template value:
 
-## Layouts
+![Properties](images/gui-templates/properties.png){srcset="images/gui-templates/[email protected] 2x"}
 
-Layouts behave as expected. Any property settings done to a particular layout in the template file are reflected in the layout of the instance nodes, given that the layout exists. Conversely, overloads to the template node instances affect the layout that is currently selected.
+Any node that has overridden properties is also colored blue in the *Outline*:
 
-![Overloading in layouts](images/gui-templates/gui-templates-layouts.png)
+![Outline](images/gui-templates/outline.png){srcset="images/gui-templates/[email protected] 2x"}
 
-## Scripting
+The template instance is listed as a collapsible entry in the *Outline* view. However, it is important to note that this item in the outline *is not a node*. The template instance does not exist in runtime either, but all nodes that are part of the instance does.
 
-Writing Lua scripts to manipulate or query nodes added through the template node mechanism works exactly as usual. Just remember to address the nodes by their _full_ name, including the template node base prefix:
+Nodes that are part of a template instance are automatically named with a prefix and a slash (`"/"`) attached to their *Id*. The prefix is the *Id* set in the template instance.
+
+::: important
+Overriding template instance node values in *Layouts* is currently not working in Editor 2. If you need to use layouts in conjunction with templates, please use Editor 1 until the issue is resolved.
+
+See https://github.com/defold/editor2-issues/issues/1124
+:::
+
+## Modifying templates in runtime
+
+Scripts that manipulate or query nodes added through the templating mechanism only need to consider the naming of instance nodes and include the template instance *Id* as a node name prefix:
 
 ```lua
-if gui.pick_node(gui.get_node("button_ok/frame"), x, y) then
+if gui.pick_node(gui.get_node("button_1/button"), x, y) then
     -- Do something...
 end
 ```
 
-Note that there is no template node present during runtime. All nodes under a template node are added to the game but the template node itself exists only in the editor. Also, if you add a script to the template GUI scene, the script will be ignored, only one script is tied to each GUI scene and is set on the scene root node in the *Outline* view as usual.
+There is no node corresponding to the template instance itself. If you need a root node for an instance, add it to the template.
+
+If a script is associated with a template GUI scene, the script is not part of the instance node tree. You may attach one single script to each GUI scene so your script logic needs to sit on the GUI scene where you have instanciated your templates.

docs/en/manuals/gui.md

@@ -27,7 +27,7 @@ Defold now automatically opens the file in the GUI scene editor.
 
 The *Outline* lists all the GUI:s content: it's list of nodes and any dependencies (see below).
 
-The central editing area shows the GUI. The toolbar in the top right corner of the editing area contains *Move*, *Rotate* and *Scale* tools, as well as a [layout](/manuals/gui-layout) selector.
+The central editing area shows the GUI. The toolbar in the top right corner of the editing area contains *Move*, *Rotate* and *Scale* tools, as well as a [layout](/manuals/gui-layouts) selector.
 
 ![toolbar](images/gui/toolbar.png){srcset="images/gui/[email protected] 2x"}
 
@@ -244,7 +244,7 @@ Clipping Inverted (box, pie and spine nodes)
 
 ## Draw order 
 
-All nodes are rendered in the order they are listed under the "Nodes" folder. The node on top of the list is drawn first and will appear behind every other node. The last node in the list is drawn last, meaning it will appear in front of all other nodes. The Z-values on nodes does not control the draw order. You can override the index ordering of nodes with layers (see below).
+All nodes are rendered in the order they are listed under the "Nodes" folder. The node at the top of the list is drawn first and will thus appear behind every other node. The last node in the list is drawn last, meaning it will appear in front of all other nodes. Altering the Z-value on a node does not control its draw order; however, if you set the Z-value outside of your render script's render range the node will no longer be rendered to screen. You can override the index ordering of nodes with layers (see below).
 
 ![Draw order](images/gui/draw_order.png){srcset="images/gui/[email protected] 2x"}
 

docs/en/manuals/hot-reload.md

@@ -22,7 +22,7 @@ To then reload an updated resource  simply select the menu item <kbd>File ▸ Ho
 
 ## Hot reloading on device
 
-Hot reloading works wirelessly on device as well as on desktop. To use it on device, run a debug build of your game, or the [development app](/manuals/dev-app) on your mobile device, then chose it as target in the editor:
+Hot reloading works on device as well as on desktop. To use it on device, run a debug build of your game, or the [development app](/manuals/dev-app) on your mobile device, then chose it as target in the editor:
 
 ![target device](images/hot-reload/target.png){srcset="images/hot-reload/[email protected] 2x"}
 
@@ -40,7 +40,7 @@ When you hot reload a file, the engine will print each reloaded resource file in
 
 ## Reloading scripts
 
-Any Lua script file that is reloaded will be re-executed in the running Lua environment. 
+Any Lua script file that is reloaded will be re-executed in the running Lua environment.
 
 ```lua
 local my_value = 10