Merge branch 'master' of https://github.com/defold/doc

Author: britzl

.wordlist.txt

@@ -290,6 +290,7 @@ OpenType
 OSX
 OTF
 particlefx
+particlefxs
 PEM
 performant
 Phaser

docs/en/en.json

@@ -908,6 +908,20 @@
                 "description": "This course teaches you to build a farming RPG in Defold, covering player control, crop systems, day progression, sprite atlases, data management, and UI design. Basic Defold and Lua knowledge is needed. Gain skills for advanced and complex projects.",
                 "image": "/courses/images/zenva.png",
                 "author": "Zenva"
+            },
+            {
+                "path": "https://academy.zenva.com/product/defold-action-rpg-course/?utm_source=defold&utm_medium=partners&utm_campaign=defold&utm_content=defold-website",
+                "name": "Make a Fully-Fledged 2D Action RPG in Defold",
+                "description": "This course covers building a complete 2D action RPG in Defold, teaching core mechanics like player control, enemy AI, dynamic cameras, health bars, scene management, and spawning systems.",
+                "image": "/courses/images/zenva.png",
+                "author": "Zenva"
+            },
+            {
+                "path": "https://academy.zenva.com/product/defold-block-breaker-course/?utm_source=defold&utm_medium=partners&utm_campaign=defold&utm_content=defold-website",
+                "name": "Create a Block Breaker Game in Defold",
+                "description": "This course covers building a complete block breaker game in Defold, teaching physics-based gameplay, paddle and ball mechanics, and procedural block generation using scripting.",
+                "image": "/courses/images/zenva.png",
+                "author": "Zenva"
             }
         ],
         "resources": [

docs/en/manuals/debugging-native-code-ios.md

@@ -83,13 +83,13 @@ You have a few options to debug an app
 
 1. Either choose `Debug` -> `Attach to process...` and select the app from there
 
-1. Or choose the `Attach to process by PID or Process name`
+2. Or choose the `Attach to process by PID or Process name`
 
 	![select_device](images/extensions/debugging/ios/attach_to_process_name.png)
 
-1. Start the app on the device
+3. Start the app on the device
 
-1. In `Edit Scheme` add the <AppName>.app folder as the executable
+4. In `Edit Scheme` add the <AppName>.app folder as the executable
 
 ### Debug symbols
 

docs/en/manuals/debugging-native-code.md

@@ -102,21 +102,21 @@ You can [upload the debug symbols to Google Play](https://developer.android.com/
 	$ ls <project>/build/<platform>/[lib]dmengine[.exe|.so]
 ```
 
-1. Unzip to a folder:
+2. Unzip to a folder:
 
 ```sh
 	$ unzip dmengine.apk -d dmengine_1_2_105
 ```
 
-1. Find the callstack address
+3. Find the callstack address
 
 	E.g. in the non symbolicated callstack it could look like this
 
 	`#00 pc 00257224 libmy_game_name.so`
 
 	Where *`00257224`* is the address
 
-1. Resolve the address
+4. Resolve the address
 
 ```sh
     $ arm-linux-androideabi-addr2line -C -f -e dmengine_1_2_105/lib/armeabi-v7a/libdmengine.so _address_
@@ -133,13 +133,13 @@ Note: If you get hold of a stack trace from the [Android logs](/manuals/debuggin
 	# it will produce a Contents/Resources/DWARF/dmengine
 ```
 
-1. If you're not using Native Extensions, download the vanilla symbols:
+2. If you're not using Native Extensions, download the vanilla symbols:
 
 ```sh
 	$ wget http://d.defold.com/archive/<sha1>/engine/arm64-darwin/dmengine.dSYM
 ```
 
-1. Symbolicate using load address
+3. Symbolicate using load address
 
 	For some reason, simply putting the address from the callstack doesn't work (i.e. load address 0x0)
 

docs/en/manuals/editor-scripts.md

@@ -56,13 +56,17 @@ You can interact with the editor using `editor` package that defines this API:
   - for atlas animations: `images` (same as `images` in atlas)
   - for tilemaps: `layers` (list of editor nodes for layers in the tilemap)
   - for tilemap layers: `tiles` (an unbounded 2d grid of tiles), see `tilemap.tiles.*` for more info
+  - for particlefx: `emitters` (list of emitter editor nodes) and `modifiers` (list of modifier editor nodes)
+  - for particlefx emitters: `modifiers` (list of modifier editor nodes)
+  - for collision objects: `shapes` (list of collision shape editor nodes)
+  - for GUI files: `layers` (list of layer editor nodes)
   - some properties that are shown in the Properties view when you have selected something in the Outline view. These types of outline properties supported:
     - `strings`
     - `booleans`
     - `numbers`
     - `vec2`/`vec3`/`vec4`
     - `resources`
-
+    - `curves`
     Please note that some of these properties might be read-only, and some might be unavailable in different contexts, so you should use `editor.can_get` before reading them and `editor.can_set` before making editor set them. Hover over property name in Properties view to see a tooltip with information about how this property is named in editor scripts. You can set resource properties to `nil` by supplying `""` value.
 - `editor.can_get(node_id, property)` — check if you can get this property so `editor.get()` won't throw an error.
 - `editor.can_set(node_id, property)` — check if `editor.tx.set()` transaction step with this property won't throw an error.
@@ -123,16 +127,17 @@ return M
 Editor expects `get_commands()` to return an array of tables, each describing a separate command. Command description consists of:
 
 - `label` (required) — text on a menu item that will be displayed to the user
-- `locations` (required) — an array of either `"Edit"`, `"View"`, `"Project"`, `"Debug"`, `"Assets"`, `"Bundle"` or `"Outline"`, describes a place where this command should be available. `"Edit"`, `"View"`, `"Project"` and `"Debug"` mean menu bar at the top, `"Assets"` means context menu in Assets pane, `"Outline"` means context menu in Outline pane, and `"Bundle"` means **Project → Bundle** submenu.
+- `locations` (required) — an array of either `"Edit"`, `"View"`, `"Project"`, `"Debug"`, `"Assets"`, `"Bundle"`, `"Scene"` or `"Outline"`, describes a place where this command should be available. `"Edit"`, `"View"`, `"Project"` and `"Debug"` mean menu bar at the top, `"Assets"` means context menu in Assets pane, `"Outline"` means context menu in Outline pane, and `"Bundle"` means **Project → Bundle** submenu.
 - `query` — a way for command to ask editor for relevant information and define what data it operates on. For every key in `query` table there will be corresponding key in `opts` table that `active` and `run` callbacks receive as argument. Supported keys:
   - `selection` means this command is valid when there is something selected, and it operates on this selection.
     - `type` is a type of selected nodes command is interested in, currently these types are allowed:
       - `"resource"` — in Assets and Outline, resource is selected item that has a corresponding file. In menu bar (Edit or View), resource is a currently open file;
       - `"outline"` — something that can be shown in the Outline. In Outline it's a selected item, in menu bar it's a currently open file;
+      - `"scene"` — something that can be rendered to the Scene.
     - `cardinality` defines how many selected items there should be. If `"one"`, selection passed to command callback will be a single node id. If `"many"`, selection passed to command callback will be an array of one or more node ids.
   - `argument` — command argument. Currently, only commands in `"Bundle"` location receive an argument, which is `true` when the bundle command is selected explicitly and `false` on rebundle.
 - `id` - command identifier string, used e.g. for persisting the last used bundle command in `prefs`
-- `active` - a callback that is executed to check that command is active, expected to return boolean. If `locations` include `"Assets"` or `"Outline"`, `active` will be called when showing context menu. If locations include `"Edit"` or `"View"`, active will be called on every user interaction, such as typing on keyboard or clicking with mouse, so be sure that `active` is relatively fast.
+- `active` - a callback that is executed to check that command is active, expected to return boolean. If `locations` include `"Assets"`, `"Scene"` or `"Outline"`, `active` will be called when showing context menu. If locations include `"Edit"` or `"View"`, active will be called on every user interaction, such as typing on keyboard or clicking with mouse, so be sure that `active` is relatively fast.
 - `run` - a callback that is executed when user selects the menu item.
 
 ### Use commands to change the in-memory editor state
@@ -269,6 +274,214 @@ editor.transact({
 })
 ```
 
+#### Editing particlefx
+
+You can edit particlefx using `modifiers` and `emitters` properties. For example, adding a circle emitter with acceleration modifier is done like this:
+```lua
+editor.transact({
+    editor.tx.add("/fire.particlefx", "emitters", {
+        type = "emitter-type-circle",
+        modifiers = {
+          {type = "modifier-type-acceleration"}
+        }
+    })
+})
+```
+Many particlefx properties are curves or curve spreads (i.e. curve + some randomizer value). Curves are represented as a table with a non-empty list of `points`, where each point is a table with the following properties:
+- `x` - the x coordinate of the point, should start at 0 and end at 1
+- `y` - the value of the point
+- `tx` (0 to 1) and `ty` (-1 to 1) - tangents of the point. E.g., for an 80-degree angle, `tx` should be `math.cos(math.rad(80))` and `ty` should be `math.sin(math.rad(80))`.
+Curve spreads additionally have a `spread` number property. 
+
+For example, setting a particle lifetime alpha curve for an already existing emitter might look like this:
+```lua
+local emitter = editor.get("/fire.particlefx", "emitters")[1]
+editor.transact({
+    editor.tx.set(emitter, "particle_key_alpha", { points = {
+        {x = 0,   y = 0, tx = 0.1, ty = 1}, -- start at 0, go up quickly
+        {x = 0.2, y = 1, tx = 1,   ty = 0}, -- reach 1 at 20% of a lifetime
+        {x = 1,   y = 0, tx = 1,   ty = 0}  -- slowly go down to 0
+    }})
+})
+```
+Of course, it's also possible to use the `particle_key_alpha` key in a table when creating an emitter. Additionally, you can use a single number instead to represent a "static" curve.
+
+#### Editing collision objects
+
+In addition to default outline properties, collision objects define `shapes` node list property. Adding new collision shapes is done like this:
+```lua
+editor.transact({
+    editor.tx.add("/hero.collisionobject", "shapes", {
+        type = "shape-type-box" -- or "shape-type-sphere", "shape-type-capsule"
+    })
+})
+```
+Shape's `type` property is required during creation and cannot be changed after the shape is added. There are 3 shape types:
+- `shape-type-box` - box shape with `dimensions` property
+- `shape-type-sphere` - sphere shape with `diameter` property
+- `shape-type-capsule` - capsule shape with `diameter` and `height` properties
+
+#### Editing GUI files
+
+In addition to outline properties, GUI nodes defines the following properties:
+- `layers` — list of layer editor nodes (reorderable)
+- `materials` — list of material editor nodes
+
+It's possible to edit GUI layers using editor `layers` property, e.g.:
+```lua
+editor.transact({
+    editor.tx.add("/main.gui", "layers", {name = "foreground"}),
+    editor.tx.add("/main.gui", "layers", {name = "background"})
+})
+```
+Additionally, it's possible to reorder layers:
+```lua
+local fg, bg = table.unpack(editor.get("/main.gui", "layers"))
+editor.transact({
+    editor.tx.reorder("/main.gui", "layers", {bg, fg})
+})
+```
+Similarly, fonts, materials, textures, and particlefxs are edited using `fonts`, `materials`, `textures`, and `particlefxs` properties:
+```lua
+editor.transact({
+    editor.tx.add("/main.gui", "fonts", {font = "/main.font"}),
+    editor.tx.add("/main.gui", "materials", {name = "shine", material = "/shine.material"}),
+    editor.tx.add("/main.gui", "particlefxs", {particlefx = "/confetti.material"}),
+    editor.tx.add("/main.gui", "textures", {texture = "/ui.atlas"})
+})
+```
+These properties don't support reordering.
+
+Finally, you can edit GUI nodes using `nodes` list property, e.g.:
+```lua
+editor.transact({
+    editor.tx.add("/main.gui", "nodes", {
+        type = "gui-node-type-box",
+        position = {20, 20, 20}
+    }),
+    editor.tx.add("/main.gui", "nodes", {
+        type = "gui-node-type-template",
+        template = "/button.gui"
+    }),
+})
+```
+Built-in node types are:
+- `gui-node-type-box`
+- `gui-node-type-particlefx`
+- `gui-node-type-pie`
+- `gui-node-type-template`
+- `gui-node-type-text`
+
+If you are using spine extension, you can also use `gui-node-type-spine` node type.
+
+If the GUI file defines layouts, you can get and set the values from layouts using `layout:property` syntax, e.g.:
+```lua
+local node = editor.get("/main.gui", "nodes")[1]
+
+-- GET:
+local position = editor.get(node, "position")
+pprint(position) -- {20, 20, 20}
+local landscape_position = editor.get(node, "Landscape:position")
+pprint(landscape_position) -- {20, 20, 20}
+
+-- SET:
+editor.transact({
+    editor.tx.set(node, "Landscape:position", {30, 30, 30})
+})
+pprint(editor.get(node, "Landscape:position")) -- {30, 30, 30}
+```
+
+Layout properties that were set can be reset to their default values using `editor.tx.reset`:
+```lua
+print(editor.can_reset(node, "Landscape:position")) -- true
+editor.transact({
+    editor.tx.reset(node, "Landscape:position")
+})
+```
+Template node trees can be read, but not edited — you can only set node properties of the template node tree:
+```lua
+local template = editor.get("/main.gui", "nodes")[2]
+print(editor.can_add(template, "nodes")) -- false
+local node_in_template = editor.get(template, "nodes")[1]
+editor.transact({
+    editor.tx.set(node_in_template, "text", "Button text")
+})
+print(editor.can_reset(node_in_template, "text")) -- true (overrides a value in the template)
+```
+
+#### Editing game objects
+
+It's possible to edit components of a game object file using editor scripts. The components come in 2 flavors: referenced and embedded. Referenced components use type `component-reference` and act as references to other resources, only allowing overrides of go properties defined in scripts. Embedded components use types like `sprite`, `label`, etc., and allow editing of all properties defined in the component type, as well as adding sub-components like shapes of collision objects. For example, you can use the following code to set up a game object:
+```lua
+editor.transact({
+    editor.tx.add("/npc.go", "components", {
+        type = "sprite",
+        id = "view"
+    }),
+    editor.tx.add("/npc.go", "components", {
+        type = "collisionobject",
+        id = "collision",
+        shapes = {
+            {
+                type = "shape-type-box",
+                dimensions = {32, 32, 32}
+            }
+        }
+    }),
+    editor.tx.add("/npc.go", "components", {
+        type = "component-reference",
+        path = "/npc.script"
+        id = "controller",
+        __hp = 100 -- set a go property defined in the script
+    })
+})
+```
+
+#### Editing collections
+It's possible to edit collections using editor scripts. You can add game objects (embedded or referenced) and collections (referenced). For example:
+```lua
+local coll = "/char.collection"
+editor.transact({
+    editor.tx.add(coll, "children", {
+        -- embbedded game object
+        type = "go",
+        id = "root",
+        children = {
+            {
+                -- referenced game object
+                type = "go-reference",
+                path = "/char-view.go"
+                id = "view"
+            },
+            {
+                -- referenced collection
+                type = "collection-reference",
+                path = "/body-attachments.collection"
+                id = "attachments"
+            }
+        },
+        -- embedded gos can also have components
+        components = {
+            {
+                type = "collisionobject",
+                id = "collision",
+                shapes = {
+                    {type = "shape-type-box", dimensions = {2.5, 2.5, 2.5}}
+                }
+            },
+            {
+                type = "component-reference",
+                id = "controller",
+                path = "/char.script",
+                __hp = 100 -- set a go property defined in the script
+            }
+        }
+    })
+})
+```
+
+Like in the editor, referenced collections can only be added to the root of the edited collection, and game objects can only be added to embedded or referenced game objects, but not to referenced collections or game objects within these referenced collections.
+
 ### Use shell commands
 
 Inside the `run` handler, you can write to files (using `io` module) and execute shell commands (using `editor.execute()` command). When executing shell commands, it's possible to capture the output of a shell command as a string and then use it in code. For example, if you want to make a command for formatting JSON that shells out to globally installed [`jq`](https://jqlang.github.io/jq/), you can write the following command:

docs/en/manuals/extender-local-setup.md

@@ -72,7 +72,7 @@ Once you have the above mentioned software installed follow these steps to insta
     cp ${TMP_DIR}/$(ls ${TMP_DIR} | grep server-${EXTENDER_VERSION}.jar) ${APPLICATION_DIR}/extender.jar
     cp ${TMP_DIR}/$(ls ${TMP_DIR} | grep manifestmergetool-${MANIFESTMERGETOOL_VERSION}.jar) ${APPLICATION_DIR}/manifestmergetool.jar
    ```
-7. __Start the server__ - We can now start the server by running the docker compose main command:
+6. __Start the server__ - We can now start the server by running the docker compose main command:
 ```sh
 docker compose -p extender -f server/docker/docker-compose.yml --profile <profile> up
 ```

docs/en/manuals/factory.md

@@ -263,7 +263,6 @@ The project setting *max_instances* in *Collection related settings* limits the
 
 If you set *max_instances* to 1024 and have 24 manually placed game objects in your main collection, you can spawn an additional 1000 game objects. As soon as you delete a game object, you are free to spawn another instance.
 
-
 ## Pooling of game objects
 
 It may seem like a good idea to save spawned game objects in a pool and reuse them. However, the engine is already doing object pooling under the hood so additional overhead will only slow things down. It is both faster and cleaner to delete game objects and spawn new ones.

docs/en/manuals/gui.md

@@ -120,11 +120,9 @@ function init(self)
 
   -- get the new texture file assigned to the texture with id 'theme'
   print(go.get("#gui", "textures", { key = "theme" })) -- /assets/mytheme.atlas
-
 end
 ```
 
-
 ## Dependencies
 
 The resource tree in a Defold game is static so any dependencies that you need for your GUI nodes need to be added to the component. The *Outline* groups all dependencies by type under "folders":

docs/en/manuals/html5.md

@@ -191,6 +191,9 @@ DEFOLD_HEAP_SIZE
 DEFOLD_ENGINE_ARGUMENTS
 : Engine arguments specified in *game.project* `html5.engine_arguments` separated by `,` symbol.
 
+build-timestamp
+: Current build timestamp in seconds.
+
 
 ## Extra parameters
 

docs/en/manuals/importing-graphics.md

@@ -70,4 +70,4 @@ Learn more about particle effects in the [Particle fx manual](/manuals/particlef
 
   ![gui](images/graphics/gui.png)
 
-Learn more about GUIs in the [GUI manual](/manuals/gui).
+Learn more about GUIs in the [GUI manual](/manuals/gui).