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

docs/en/manuals/bob.md

@@ -38,16 +38,16 @@ usage: bob [options] [commands]
                                          binary will be placed. Default is
                                          "<build-output>/<platform>/"
  -bo,--bundle-output <arg>               Bundle output directory
- -br,--build-report <arg>                DEPRECATED in Defold 1.4.6! Use
+ -br,--build-report <arg>                DEPRECATED! Use
                                          --build-report-json instead
  -brhtml,--build-report-html <arg>       Filepath where to save a build
                                          report as HTML
  -brjson,--build-report-json <arg>       Filepath where to save a build
-                                         report as JSON (from Defold 1.4.6)
+                                         report as JSON
     --build-artifacts <arg>              If left out, will default to
                                          build the engine. Choices:
-                                         'engine', 'plugins'. Comma
-                                         separated list.
+                                         'engine', 'plugins', 'library'.
+                                         Comma separated list.
     --build-server <arg>                 The build server (when using
                                          native extensions)
     --build-server-header <arg>          Additional build server header to
@@ -58,6 +58,8 @@ usage: bob [options] [commands]
                                          instead
     --debug-ne-upload                    Outputs the files sent to build
                                          server as upload.zip
+    --debug-output-spirv <arg>           Force build SPIR-V shaders
+    --debug-output-wgsl <arg>            Force build WGSL shaders
     --defoldsdk <arg>                    What version of the defold sdk
                                          (sha1) to use
  -e,--email <arg>                        User email
@@ -66,11 +68,10 @@ usage: bob [options] [commands]
                                          create an empty Defold
                                          application for use as a build
                                          target
-    --exclude-build-folder <arg>         DEPRECATED from Defold 1.5.1! Use
-                                         '.defignore' file instead
+    --exclude-build-folder <arg>         DEPRECATED! Use '.defignore' file
+                                         instead
  -h,--help                               This help message
- -i,--input <arg>                        Source directory. Default is
-                                         current directory
+ -i,--input <arg>                        DEPRECATED! Use --root instead
     --identity <arg>                     Sign identity (iOS)
  -kp,--key-pass <arg>                    Password of the deployment key if
                                          different from the keystore
@@ -88,8 +89,13 @@ usage: bob [options] [commands]
     --manifest-public-key <arg>          Public key to use when signing
                                          manifest and archive.
     --max-cpu-threads <arg>              Max count of threads that bob.jar
-                                         can use (from Defold 1.4.6)
+                                         can use
  -mp,--mobileprovisioning <arg>          mobileprovisioning profile (iOS)
+    --ne-build-dir <arg>                 Specify a folder with includes or
+                                         source, to build a specific
+                                         library. More than one occurrance
+                                         is allowed.
+    --ne-output-name <arg>               Specify a library target name
  -o,--output <arg>                       Output directory. Default is
                                          "build/default"
  -p,--platform <arg>                     Platform (when building and
@@ -106,9 +112,9 @@ usage: bob [options] [commands]
     --resource-cache-remote-user <arg>   Username to authenticate access
                                          to the remote resource cache.
     --settings <arg>                     Path to a game project settings
-                                         file. More than one occurrance
-                                         are allowed. The settings files
-                                         are applied left to right.
+                                         file. More than one occurrance is
+                                         allowed. The settings files are
+                                         applied left to right.
     --strip-executable                   Strip the dmengine of debug
                                          symbols (when bundling iOS or
                                          Android)
@@ -117,8 +123,8 @@ usage: bob [options] [commands]
  -tp,--texture-profiles <arg>            DEPRECATED! Use
                                          --texture-compression instead
  -u,--auth <arg>                         User auth token
-    --use-async-build-server             DEPRECATED! Asynchronous build
-                                         is now the default.
+    --use-async-build-server             DEPRECATED! Asynchronous build is
+                                         now the default.
     --use-lua-bytecode-delta             Use byte code delta compression
                                          when building for multiple
                                          architectures

docs/en/manuals/editor-scripts-ui.md

@@ -5,7 +5,7 @@ brief: This manual explains how to create UI elements in the editor using Lua
 
 # Editor scripts and UI
 
-This manual explains how to create interactive UI elements in the editor using editor scripts written in Lua. To get started with editor scripts, see [Editor Scripts manual](/manuals/editor-scripts). Currently, it's only possible to create interactive dialogs, though we want to expand the UI scripting support to the rest of the editor in the future.
+This manual explains how to create interactive UI elements in the editor using editor scripts written in Lua. To get started with editor scripts, see [Editor Scripts manual](/manuals/editor-scripts). You can find the full editor API reference [here](https://defold.com/ref/alpha/editor/). Currently, it's only possible to create interactive dialogs, though we want to expand the UI scripting support to the rest of the editor in the future.
 
 ## Hello world
 
@@ -46,7 +46,7 @@ return M
 
 This code snippet defines a **View → Do with confirmation** command. When you execute it, you will see the following dialog:
 
-![Hello world dialog](images/editor_scripts/perform_action_dialog@2x.png)
+![Hello world dialog](images/editor_scripts/perform_action_dialog.png){srcset="images/editor_scripts/[email protected] 2x"}
 
 Finally, after pressing <kbd>Enter</kbd> (or clicking on the `Perform` button), you'll see the following line in the editor console:
 ```
@@ -76,7 +76,7 @@ editor.ui.label({
 ```
 The visible part is the `Hello` text, and it's aligned within the assigned component bounds:
 
-![Alignment](images/editor_scripts/alignment@2x.png)
+![Alignment](images/editor_scripts/alignment.png){srcset="images/editor_scripts/[email protected] 2x"}
 
 ## Built-in components
 
@@ -86,7 +86,7 @@ The editor defines various built-in components that can be used together to buil
 
 Layout components are used for placing other components next to each other. Main layout components are **`horizontal`**, **`vertical`** and **`grid`**. These components also define props such as **padding** and **spacing**, where padding is an empty space from the edge of the assigned bounds to the content, and spacing is an empty space between children:
 
-![Padding and Spacing](images/editor_scripts/padding_and_spacing@2x.png)
+![Padding and Spacing](images/editor_scripts/padding_and_spacing.png){srcset="images/editor_scripts/[email protected] 2x"}
 
 Editor defines `small`, `medium` and `large` padding and spacing constants. When it comes to spacing, `small` is intended for spacing between different sub-elements of an individual UI element, `medium` is for spacing between individual UI elements, and `large` is a spacing between groups of elements. Default spacing is `medium`. With paddings, `large` means padding from the edges of the window to content, `medium` is padding from the edges of a significant UI element, and `small` is a padding from the edges of small UI elements like context menus and tooltips (not implemented yet).
 
@@ -119,7 +119,7 @@ editor.ui.grid({
 ```
 The code above will produce the following dialog form:
 
-![New Level Dialog](images/editor_scripts/new_level_dialog@2x.png)
+![New Level Dialog](images/editor_scripts/new_level_dialog.png){srcset="images/editor_scripts/[email protected] 2x"}
 
 ### Data presentation components
 
@@ -184,7 +184,7 @@ When issue is specified, it changes how the input component looks, and adds a to
 
 Here is a demo of all inputs with their issue variants:
 
-![Inputs](images/editor_scripts/inputs_demo@2x.png)
+![Inputs](images/editor_scripts/inputs_demo.png){srcset="images/editor_scripts/[email protected] 2x"}
 
 ### Dialog-related components
 
@@ -258,7 +258,7 @@ end
 
 When you execute a menu command that runs this code, the editor will show a dialog with disabled `"Create File"` dialog at the start, but, when you type a name and press <kbd>Enter</kbd>, it will become enabled:
 
-![New File Dialog](images/editor_scripts/reactive_new_file_dialog@2x.png)
+![New File Dialog](images/editor_scripts/reactive_new_file_dialog.png){srcset="images/editor_scripts/[email protected] 2x"}
 
 So, how does it work? On the very first render, `use_state` hook creates a local state associated with the component and returns it with a setter for the state. When the setter function is invoked, it schedules a component re-render. On subsequent re-renders, the component function is invoked again, and `use_state` returns the updated state. New view component returned by the component function is then diffed against the old one, and the UI is updated where the changes were detected.
 

docs/en/manuals/editor-scripts.md

@@ -64,6 +64,8 @@ You can interact with the editor using `editor` package that defines this API:
 - `editor.transact(txs)` — modify the editor in-memory state using 1 or more transaction steps created with `editor.tx.*` functions.
 - `editor.ui.*` — various UI-related functions, see [UI manual](/manuals/editor-scripts-ui).
 
+You can find the full editor API reference [here](https://defold.com/ref/alpha/editor/).
+
 ## Commands
 
 If editor script module defines function `get_commands`, it will be called on extension reload, and returned commands will be available for use inside the editor in menu bar or in context menus in Assets and Outline panes. Example:

docs/en/manuals/material.md

@@ -47,7 +47,7 @@ Tags
 
 ## Attributes
 
-Shader attributes (also referred to as vertex streams), is a mechanism for how the GPU retrieves vertices from memory in order to render geometry. The vertex shader specifies a set of streams by using the `attribute` keyword and in most cases Defold produces and binds the data automatically under the hood based on the names of the streams. However, in some cases you might want to forward more data per vertex to achieve a specific effect that the engine does not produce. A vertex attribute can be configured with the following fields:
+Shader attributes (also referred to as vertex streams, or vertex attributes), is a mechanism for how the GPU retrieves vertices from memory in order to render geometry. The vertex shader specifies a set of streams by using the `attribute` keyword and in most cases Defold produces and binds the data automatically under the hood based on the names of the streams. However, in some cases you might want to forward more data per vertex to achieve a specific effect that the engine does not produce. A vertex attribute can be configured with the following fields:
 
 Name
 : The attribute name. Similar to shader constants, the attribute configuration will only be used if it matches an attribute specified in the vertex program.
@@ -55,15 +55,15 @@ Name
 Semantic type
 : A semantic type indicates the semantic meaning of *what* the attribute is and/or *how* it should be shown in the editor. For example, specifying an attribute with a `SEMANTIC_TYPE_COLOR` will show a color picker in the editor, while the data will still be passed in as-is from the engine to the shader.
 
-  - `SEMANTIC_TYPE_NONE` The default semantic type. Does not have any other effect on the attribute other than passing the material data for the attribute directly to the vertex buffer.
-  - `SEMANTIC_TYPE_POSITION` Produces per-vertex position data for the attribute. Can be used together with coordinate space to tell the engine how the positions will be calculated.
-  - `SEMANTIC_TYPE_TEXCOORD` Produces per-vertex texture coordinates for the attribute.
-  - `SEMANTIC_TYPE_PAGE_INDEX` Produces per-vertex page indices for the attribute.
-  - `SEMANTIC_TYPE_COLOR` Affects how the editor interprets the attribute. If an attribute is configured with a color semantic, a color picked widget will be shown in the inspector.
-
-::: sidenote
-The material system will assign a default semantic type automatically based on the name of the attribute during run-time for a specific set of names: position, texcoord0, page_index. If you have entries for these attributes in the material, the default semantic type will be overridden with whatever you have configured in the material editor!
-:::
+  - `SEMANTIC_TYPE_NONE` The default semantic type. Does not have any other effect on the attribute other than passing the material data for the attribute directly to the vertex buffer (default)
+  - `SEMANTIC_TYPE_POSITION` Produces per-vertex position data for the attribute. Can be used together with coordinate space to tell the engine how the positions will be calculated
+  - `SEMANTIC_TYPE_TEXCOORD` Produces per-vertex texture coordinates for the attribute
+  - `SEMANTIC_TYPE_PAGE_INDEX` Produces per-vertex page indices for the attribute
+  - `SEMANTIC_TYPE_COLOR` Affects how the editor interprets the attribute. If an attribute is configured with a color semantic, a color picked widget will be shown in the inspector
+  - `SEMANTIC_TYPE_NORMAL` Produces per-vertex normal data for the attribute
+  - `SEMANTIC_TYPE_TANGENT` Produces per-vertex tangent data for the attribute
+  - `SEMANTIC_TYPE_WORLD_MATRIX` Produces per-vertex world matrix data for the attribute
+  - `SEMANTIC_TYPE_NORMAL_MATRIX` Produces per-vertex normal matrix data for the attribute
 
 Data type
 : The data type of the backing data for the attribute.
@@ -74,10 +74,7 @@ Data type
   - `TYPE_UNSIGNED_SHORT` Unsigned 16-bit short values
   - `TYPE_INT` Signed integer values
   - `TYPE_UNSIGNED_INT` Unsigned integer values
-  - `TYPE_FLOAT` Floating point values
-
-Count
-: The *element count* of the attribute, e.g number of values in the attribute. A `vec4` in the shader has four elements and a `float` has one element. Note: Even if the shader has specified an attribute to be a `vec4` you can still specify a smaller count if you know you need less than four elements which can be useful to trim memory footprint.
+  - `TYPE_FLOAT` Floating point values (default)
 
 Normalize
 : If true, the attribute values will be normalized by the GPU driver. This can be useful when you don't need full precision, but want to calculate something without knowing the specific limits. E.g a color vector typically only need byte values of 0..255 while still being treated as a 0..1 value in the shader.
@@ -85,6 +82,23 @@ Normalize
 Coordinate space
 : Some semantic types support supplying data in different coordinate spaces. To implement a billboarding effect with sprites, you typically want a position attribute in local space as well as a fully transformed position in world space for most effective batching.
 
+Vector type
+: The vector type of the attribute.
+
+  - `VECTOR_TYPE_SCALAR` Single scalar value
+  - `VECTOR_TYPE_VEC2` 2D vector
+  - `VECTOR_TYPE_VEC3` 3D vector
+  - `VECTOR_TYPE_VEC4` 4D vector (default)
+  - `VECTOR_TYPE_MAT2` 2D matrix
+  - `VECTOR_TYPE_MAT3` 3D matrix
+  - `VECTOR_TYPE_MAT4` 4D matrix
+
+Step function
+: Specifies how the attribute data should be presented to the vertex function. This is only relevant for instancing.
+
+  - `Vertex` Once per vertex, e.g a position attribute will typically be given to the vertex function per vertex in the mesh (default)
+  - `Instance` Once per instance, e.g a world matrix attribute will typically be given to the vertex function once per instance
+
 Value
 : The value of the attribute. Attribute values can be overridden on a per-component basis, but otherwise this will act as the default value of the vertex attribute. Note: for *default* attributes (position, texture coordinates and page indices) the value will be ignored.
 
@@ -92,6 +106,24 @@ Value
 Custom attributes can also be used to trim memory footprint on both CPU and GPU by reconfiguring the streams to use a smaller data type, or a different element count.
 :::
 
+### Default attribute semantics
+
+The material system will assign a default semantic type automatically based on the name of the attribute in run-time for a specific set of names:
+
+  - `position` - semantic type: `SEMANTIC_TYPE_POSITION`
+  - `texcoord0` - semantic type: `SEMANTIC_TYPE_TEXCOORD`
+  - `texcoord1` - semantic type: `SEMANTIC_TYPE_TEXCOORD`
+  - `page_index` - semantic type: `SEMANTIC_TYPE_PAGE_INDEX`
+  - `color` - semantic type: `SEMANTIC_TYPE_COLOR`
+  - `normal` - semantic type: `SEMANTIC_TYPE_NORMAL`
+  - `tangent` - semantic type: `SEMANTIC_TYPE_TANGENT`
+  - `mtx_world` - semantic type: `SEMANTIC_TYPE_WORLD_MATRIX`
+  - `mtx_normal` - semantic type: `SEMANTIC_TYPE_NORMAL_MATRIX`
+
+If you have entries for these attributes in the material, the default semantic type will be overridden with whatever you have configured in the material editor.
+
+### Setting custom vertex attribute data
+
 Similar to user defined shader constants, you can also update vertex attributes in runtime by calling go.get, go.set and go.animate:
 
 ![Custom material attribute](images/materials/set_custom_attribute.png)
@@ -108,6 +140,56 @@ There are some caveats to updating the vertex attributes however, wether or not
 Setting custom vertex data in runtime is currently only supported for sprite components.
 :::
 
+### Instancing
+
+Instancing is a technique used to efficiently draw multiple copies of the same object in a scene. Instead of creating a separate copy of the object each time it's used, instancing allows the graphics engine to create a single object and then reuse it multiple times. For example, in a game with a large forest, instead of creating a separate tree model for each tree, instancing allows you to create one tree model and then place it hundreds or thousands of times with different positions and scales. The forest can now be rendered with a single draw call instead of individual draw calls for each tree.
+
+::: sidenote
+Instancing is currently only available for Model components.
+:::
+
+Instancing is enabled automatically when possible. Defold heavily relies on batching the draw state as much as possible - for instancing to work some requirements must be met:
+
+- The same material must be used for all instances. Instancing will still work if a custom material has been set by `render.enable_material`)
+- The material must be configured to use the 'local' vertex space
+- The material must have at least one vertex attribute that is repeated per instance
+- Constant values must be the same for all instances. Constant values can be put into custom vertex attributes or some other backing method instead (e.g a texture)
+- Shader resources, such as textures or storage buffers, must be the same for all instances
+
+Configuring a vertex attribute to be repeated per instance requires that the `Step function` is set to `Instance`. This is done automatically for certain semantic types based on name (see the `Default attribute semantics` table above), but it can also be set manually in the material editor by setting the `Step function` to `Instance`.
+
+As a simple example, the following scene has four gameobjects with a model component each:
+
+![Instancing setup](images/materials/instancing-setup.png){srcset="images/materials/[email protected] 2x"}
+
+The material is configured as such, with a single custom vertex attribute that is repeated per instance:
+
+![Instancing material](images/materials/instancing-material.png){srcset="images/materials/[email protected] 2x"}
+
+The vertex shader has multiple per-instance attributes specified:
+
+```glsl
+// Per vertex attributes
+attribute highp vec4 position;
+attribute mediump vec2 texcoord0;
+attribute mediump vec3 normal;
+
+// Per instance attributes
+attribute mediump mat4 mtx_world;
+attribute mediump mat4 mtx_normal;
+attribute mediump vec4 instance_color;
+```
+
+Note that the mtx_world and mtx_normal will be configured to use the step function `Instance` by default. This can be changed in the material editor by adding an entry for them and setting the `Step function` to `Vertex`, which will make the attribute be repeated per vertex instead of per instance.
+
+To verify that the instancing works in this case, you can look at the web profiler. In this case, since the only thing that changes between the instances of the box is the per-instance attributes, it can be rendered with a single draw call:
+
+![Instancing draw calls](images/materials/instancing-draw-calls.png){srcset="images/materials/[email protected] 2x"}
+
+#### Backwards compatability
+
+On OpenGL based graphcis adapters, instancing requires at least OpenGL 3.1 for desktop and OpenGL ES 3.0 for mobile. This means that very old devices that are using OpenGL ES2 or older OpenGL versions might not support instancing. In this case, rendering will still work by default without any special care from the developer, but it may not be as performant as if actual instancing was used. Currently, there is no way of detecting if instancing is supported or not, but this functionality will be added in the future so that a cheaper material can be used, or things like foliage or clutter that typically would be good candidates for instancing, could be skipped completely.
+
 ## Vertex and fragment constants
 
 Shader constants, or "uniforms" are values that are passed from the engine to vertex and fragment shader programs. To use a constant you define it in the material file as either a *Vertex Constant* property or a *Fragment Constant* property. Corresponding `uniform` variables need to be defined in the shader program. The following constants can be set in a material:

docs/en/manuals/physics-events.md

@@ -39,7 +39,8 @@ This event reports a contact point between two collision objects. It is useful f
    - `applied_impulse`: The impulse resulting from the contact.
    - `distance`: The penetration distance between the objects.
    - `a` and `b`: Objects representing the colliding entities, each containing:
-     - `position`: World position (vector3).
+     - `position`: World position of contact point (vector3).
+     - `instance_position`: World position game object instance (vector3).
      - `id`: Instance ID (hash).
      - `group`: Collision group (hash).
      - `relative_velocity`: Velocity relative to the other object (vector3).

docs/ko/manuals/bob.md

@@ -30,16 +30,16 @@ usage: bob [options] [commands]
                                          binary will be placed. Default is
                                          "<build-output>/<platform>/"
  -bo,--bundle-output <arg>               Bundle output directory
- -br,--build-report <arg>                DEPRECATED in Defold 1.4.6! Use
+ -br,--build-report <arg>                DEPRECATED! Use
                                          --build-report-json instead
  -brhtml,--build-report-html <arg>       Filepath where to save a build
                                          report as HTML
  -brjson,--build-report-json <arg>       Filepath where to save a build
-                                         report as JSON (from Defold 1.4.6)
+                                         report as JSON
     --build-artifacts <arg>              If left out, will default to
                                          build the engine. Choices:
-                                         'engine', 'plugins'. Comma
-                                         separated list.
+                                         'engine', 'plugins', 'library'.
+                                         Comma separated list.
     --build-server <arg>                 The build server (when using
                                          native extensions)
     --build-server-header <arg>          Additional build server header to
@@ -50,6 +50,8 @@ usage: bob [options] [commands]
                                          instead
     --debug-ne-upload                    Outputs the files sent to build
                                          server as upload.zip
+    --debug-output-spirv <arg>           Force build SPIR-V shaders
+    --debug-output-wgsl <arg>            Force build WGSL shaders
     --defoldsdk <arg>                    What version of the defold sdk
                                          (sha1) to use
  -e,--email <arg>                        User email
@@ -58,11 +60,10 @@ usage: bob [options] [commands]
                                          create an empty Defold
                                          application for use as a build
                                          target
-    --exclude-build-folder <arg>         DEPRECATED from Defold 1.5.1! Use
-                                         '.defignore' file instead
+    --exclude-build-folder <arg>         DEPRECATED! Use '.defignore' file
+                                         instead
  -h,--help                               This help message
- -i,--input <arg>                        Source directory. Default is
-                                         current directory
+ -i,--input <arg>                        DEPRECATED! Use --root instead
     --identity <arg>                     Sign identity (iOS)
  -kp,--key-pass <arg>                    Password of the deployment key if
                                          different from the keystore
@@ -80,8 +81,13 @@ usage: bob [options] [commands]
     --manifest-public-key <arg>          Public key to use when signing
                                          manifest and archive.
     --max-cpu-threads <arg>              Max count of threads that bob.jar
-                                         can use (from Defold 1.4.6)
+                                         can use
  -mp,--mobileprovisioning <arg>          mobileprovisioning profile (iOS)
+    --ne-build-dir <arg>                 Specify a folder with includes or
+                                         source, to build a specific
+                                         library. More than one occurrance
+                                         is allowed.
+    --ne-output-name <arg>               Specify a library target name
  -o,--output <arg>                       Output directory. Default is
                                          "build/default"
  -p,--platform <arg>                     Platform (when building and
@@ -98,9 +104,9 @@ usage: bob [options] [commands]
     --resource-cache-remote-user <arg>   Username to authenticate access
                                          to the remote resource cache.
     --settings <arg>                     Path to a game project settings
-                                         file. More than one occurrance
-                                         are allowed. The settings files
-                                         are applied left to right.
+                                         file. More than one occurrance is
+                                         allowed. The settings files are
+                                         applied left to right.
     --strip-executable                   Strip the dmengine of debug
                                          symbols (when bundling iOS or
                                          Android)
@@ -109,8 +115,8 @@ usage: bob [options] [commands]
  -tp,--texture-profiles <arg>            DEPRECATED! Use
                                          --texture-compression instead
  -u,--auth <arg>                         User auth token
-    --use-async-build-server             DEPRECATED! Asynchronous build
-                                         is now the default.
+    --use-async-build-server             DEPRECATED! Asynchronous build is
+                                         now the default.
     --use-lua-bytecode-delta             Use byte code delta compression
                                          when building for multiple
                                          architectures

docs/ru/manuals/bob.md

@@ -32,16 +32,16 @@ usage: bob [options] [commands]
                                          binary will be placed. Default is
                                          "<build-output>/<platform>/"
  -bo,--bundle-output <arg>               Bundle output directory
- -br,--build-report <arg>                DEPRECATED in Defold 1.4.6! Use
-                                         --build-report-json instead 
+ -br,--build-report <arg>                DEPRECATED! Use
+                                         --build-report-json instead
  -brhtml,--build-report-html <arg>       Filepath where to save a build
                                          report as HTML
  -brjson,--build-report-json <arg>       Filepath where to save a build
-                                         report as JSON (from Defold 1.4.6)
+                                         report as JSON
     --build-artifacts <arg>              If left out, will default to
                                          build the engine. Choices:
-                                         'engine', 'plugins'. Comma
-                                         separated list.
+                                         'engine', 'plugins', 'library'.
+                                         Comma separated list.
     --build-server <arg>                 The build server (when using
                                          native extensions)
     --build-server-header <arg>          Additional build server header to
@@ -52,6 +52,8 @@ usage: bob [options] [commands]
                                          instead
     --debug-ne-upload                    Outputs the files sent to build
                                          server as upload.zip
+    --debug-output-spirv <arg>           Force build SPIR-V shaders
+    --debug-output-wgsl <arg>            Force build WGSL shaders
     --defoldsdk <arg>                    What version of the defold sdk
                                          (sha1) to use
  -e,--email <arg>                        User email
@@ -60,11 +62,10 @@ usage: bob [options] [commands]
                                          create an empty Defold
                                          application for use as a build
                                          target
-    --exclude-build-folder <arg>         Comma separated list of folders
-                                         to exclude from the build
+    --exclude-build-folder <arg>         DEPRECATED! Use '.defignore' file
+                                         instead
  -h,--help                               This help message
- -i,--input <arg>                        Source directory. Default is
-                                         current directory
+ -i,--input <arg>                        DEPRECATED! Use --root instead
     --identity <arg>                     Sign identity (iOS)
  -kp,--key-pass <arg>                    Password of the deployment key if
                                          different from the keystore
@@ -82,8 +83,13 @@ usage: bob [options] [commands]
     --manifest-public-key <arg>          Public key to use when signing
                                          manifest and archive.
     --max-cpu-threads <arg>              Max count of threads that bob.jar
-                                         can use (from Defold 1.4.6)
+                                         can use
  -mp,--mobileprovisioning <arg>          mobileprovisioning profile (iOS)
+    --ne-build-dir <arg>                 Specify a folder with includes or
+                                         source, to build a specific
+                                         library. More than one occurrance
+                                         is allowed.
+    --ne-output-name <arg>               Specify a library target name
  -o,--output <arg>                       Output directory. Default is
                                          "build/default"
  -p,--platform <arg>                     Platform (when building and
@@ -100,9 +106,9 @@ usage: bob [options] [commands]
     --resource-cache-remote-user <arg>   Username to authenticate access
                                          to the remote resource cache.
     --settings <arg>                     Path to a game project settings
-                                         file. More than one occurrance
-                                         are allowed. The settings files
-                                         are applied left to right.
+                                         file. More than one occurrance is
+                                         allowed. The settings files are
+                                         applied left to right.
     --strip-executable                   Strip the dmengine of debug
                                          symbols (when bundling iOS or
                                          Android)
@@ -111,8 +117,8 @@ usage: bob [options] [commands]
  -tp,--texture-profiles <arg>            DEPRECATED! Use
                                          --texture-compression instead
  -u,--auth <arg>                         User auth token
-    --use-async-build-server             DEPRECATED! Asynchronous build
-                                         is now the default.
+    --use-async-build-server             DEPRECATED! Asynchronous build is
+                                         now the default.
     --use-lua-bytecode-delta             Use byte code delta compression
                                          when building for multiple
                                          architectures

docs/zh/manuals/bob.md

@@ -24,73 +24,124 @@ Bob 运行于命令行界面 `java` (再Windows上是 `java.exe`) 后跟bob的ja
 ```text
 $ java -jar bob.jar --help
 usage: bob [options] [commands]
--a,--archive                            编译数据包
--ar,--architectures <arg>               逗号分割的发布平台包含的架构列表
-    --archive-resource-padding <arg>    游戏包中的资源对齐间隔. 默认值为4.
--bf,--bundle-format <arg>               逗号分割的发布平台格式列表
-                                        (Android: 'apk' 和 'aab')
-    --binary-output <arg>               指定可执行文件存放地址, 默认地址是
-                                        "<build-output>/<platform>/"
--bo,--bundle-output <arg>               打包输出目录
--br,--build-report <arg>                自从 Defold 1.4.6 版本后已弃用! 
-                                        使用 --build-report-json 代替
--brhtml,--build-report-html <arg>       指定编译生成的HTML报告的存放地址
--brjson,--build-report-json <arg>       保存 JSON 编译报告的文件路径位置 (自从 Defold 1.4.6 版本启用)
-    --build-artifacts <arg>             不指定的话默认为编译engine.
-                                        可选项为 'engine', 'plugins'.
-                                        以逗号分隔.
-    --build-server <arg>                编译服务器 (使用原生扩展时需指定)
-    --build-server-header <arg>         设置 build server header
--ce,--certificate <arg>                 已弃用! 使用 --keystore 代替
--d,--debug                              已弃用! 使用 --variant=debug 代替
-    --debug-ne-upload                   把文件打包為upload.zip后上傳到
-                                        編譯服務器
-    --defoldsdk <arg>                   指定 defold sdk (sha1) 使用版本
--e,--email <arg>                        用户电邮
--ea,--exclude-archive                   要从打包中排除的资源档案. 以此创建空应用用作编译目标
-    --exclude-build-folder              自从 Defold 1.5.1 已弃用! 使用
-                                        '.defignore' 文件代替
--h,--help                               该命令的帮助文档
--i,--input <arg>                        指定源目录, 默认是当前目录
-    --identity <arg>                    指定签名 (iOS)
--kp,--key-pass <arg>                    如果开发密钥不同于部署密钥的话
-                                        则在这里指定 (Android)
--ks,--keystore <arg>                    用来签名 APKs (Android) 的部署密钥
--ksa,--keystore-alias <arg>             用来签名 (Android) 的 key+cert 别名
--ksp,--keystore-pass <arg>              用来签名 (Android) 的部署密钥密码
--l,--liveupdate <arg>                   要在发布后使用热更新功能, 该参数填 yes
-
-    --manifest-private-key <arg>        用来签名 manifest 和 archive 的私钥
-
-    --manifest-public-key <arg>         用来签名 manifest 和 archive 的公钥
-    --max-cpu-threads <arg>             设置 bob.jar 使用的最多线程数
-                                        (自从 Defold 1.4.6 版本启用)
--mp,--mobileprovisioning <arg>          指定 mobileprovisioning profile (iOS)
--o,--output <arg>                       输出目录. 默认是 "build/default"
--p,--platform <arg>                     发布平台 (打包时)
--pk,--private-key <arg>                 已弃用! 使用 --keystore 代替
--r,--root <arg>                         指定编译根目录. 默认是当前目录
-    --resource-cache-local <arg>        本地资源缓存地址.
-    --resource-cache-remote <arg>       远程资源缓存URL.
-    --resource-cache-remote-pass <arg>  远程资源存取认证的密码/令牌.
-    --resource-cache-remote-user <arg>  远程资源存取认证的用户名.
-    --settings <arg>                    指定项目配置文件的路径. 可以使用多个
-                                        文件. 配置文件从左到右依次被应用.
-    --strip-executable                  去掉dmengine的debug信息 (编译 iOS 或 Android时)
--tc,--texture-compression <arg>         使用纹理档案中指定的纹理压缩
--tp,--texture-profiles <arg>            已弃用! 使用 --texture-compression 代替
--u,--auth <arg>                         用户认证令牌
-   --use-async-build-server             DEPRECATED! Asynchronous build
-                                         is now the default.
-   --use-lua-bytecode-delta             为多平台编译时使用字节码 delta 压缩
-   --use-uncompressed-lua-source        使用未压缩未加密的明文Lua源代码代替二进制文件
-   --use-vanilla-lua                    已弃用! 使用 --use-uncompressed-lua-source 代替
-
--v,--verbose                            冗余输出
-    --variant <arg>                     指定使用 debug, release 或者 headless
-                                        的dmengine版本 (编译时)
-    --version                           打印输出版本号
-    --with-symbols                      生成标记文件 (如果可用)
+ -a,--archive                            Build archive
+ -ar,--architectures <arg>               Comma separated list of
+                                         architectures to include for the
+                                         platform
+    --archive-resource-padding <arg>     The alignment of the resources in
+                                         the game archive. Default is 4
+ -bf,--bundle-format <arg>               Which formats to create the
+                                         application bundle in. Comma
+                                         separated list. (Android: 'apk'
+                                         and 'aab')
+    --binary-output <arg>                Location where built engine
+                                         binary will be placed. Default is
+                                         "<build-output>/<platform>/"
+ -bo,--bundle-output <arg>               Bundle output directory
+ -br,--build-report <arg>                DEPRECATED! Use
+                                         --build-report-json instead
+ -brhtml,--build-report-html <arg>       Filepath where to save a build
+                                         report as HTML
+ -brjson,--build-report-json <arg>       Filepath where to save a build
+                                         report as JSON
+    --build-artifacts <arg>              If left out, will default to
+                                         build the engine. Choices:
+                                         'engine', 'plugins', 'library'.
+                                         Comma separated list.
+    --build-server <arg>                 The build server (when using
+                                         native extensions)
+    --build-server-header <arg>          Additional build server header to
+                                         set
+ -ce,--certificate <arg>                 DEPRECATED! Use --keystore
+                                         instead
+ -d,--debug                              DEPRECATED! Use --variant=debug
+                                         instead
+    --debug-ne-upload                    Outputs the files sent to build
+                                         server as upload.zip
+    --debug-output-spirv <arg>           Force build SPIR-V shaders
+    --debug-output-wgsl <arg>            Force build WGSL shaders
+    --defoldsdk <arg>                    What version of the defold sdk
+                                         (sha1) to use
+ -e,--email <arg>                        User email
+ -ea,--exclude-archive                   Exclude resource archives from
+                                         application bundle. Use this to
+                                         create an empty Defold
+                                         application for use as a build
+                                         target
+    --exclude-build-folder <arg>         DEPRECATED! Use '.defignore' file
+                                         instead
+ -h,--help                               This help message
+ -i,--input <arg>                        DEPRECATED! Use --root instead
+    --identity <arg>                     Sign identity (iOS)
+ -kp,--key-pass <arg>                    Password of the deployment key if
+                                         different from the keystore
+                                         password (Android)
+ -ks,--keystore <arg>                    Deployment keystore used to sign
+                                         APKs (Android)
+ -ksa,--keystore-alias <arg>             The alias of the signing key+cert
+                                         you want to use (Android)
+ -ksp,--keystore-pass <arg>              Password of the deployment
+                                         keystore (Android)
+ -l,--liveupdate <arg>                   Yes if liveupdate content should
+                                         be published
+    --manifest-private-key <arg>         Private key to use when signing
+                                         manifest and archive.
+    --manifest-public-key <arg>          Public key to use when signing
+                                         manifest and archive.
+    --max-cpu-threads <arg>              Max count of threads that bob.jar
+                                         can use
+ -mp,--mobileprovisioning <arg>          mobileprovisioning profile (iOS)
+    --ne-build-dir <arg>                 Specify a folder with includes or
+                                         source, to build a specific
+                                         library. More than one occurrance
+                                         is allowed.
+    --ne-output-name <arg>               Specify a library target name
+ -o,--output <arg>                       Output directory. Default is
+                                         "build/default"
+ -p,--platform <arg>                     Platform (when building and
+                                         bundling)
+ -pk,--private-key <arg>                 DEPRECATED! Use --keystore
+                                         instead
+ -r,--root <arg>                         Build root directory. Default is
+                                         current directory
+    --resource-cache-local <arg>         Path to local resource cache.
+    --resource-cache-remote <arg>        URL to remote resource cache.
+    --resource-cache-remote-pass <arg>   Password/token to authenticate
+                                         access to the remote resource
+                                         cache.
+    --resource-cache-remote-user <arg>   Username to authenticate access
+                                         to the remote resource cache.
+    --settings <arg>                     Path to a game project settings
+                                         file. More than one occurrance is
+                                         allowed. The settings files are
+                                         applied left to right.
+    --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
+ -tp,--texture-profiles <arg>            DEPRECATED! Use
+                                         --texture-compression instead
+ -u,--auth <arg>                         User auth token
+    --use-async-build-server             DEPRECATED! Asynchronous build is
+                                         now the default.
+    --use-lua-bytecode-delta             Use byte code delta compression
+                                         when building for multiple
+                                         architectures
+    --use-uncompressed-lua-source        Use uncompressed and unencrypted
+                                         Lua source code instead of byte
+                                         code
+    --use-vanilla-lua                    DEPRECATED! Use
+                                         --use-uncompressed-lua-source
+                                         instead.
+ -v,--verbose                            Verbose output
+    --variant <arg>                      Specify debug, release or
+                                         headless version of dmengine
+                                         (when bundling)
+    --version                            Prints the version number to the
+                                         output
+    --with-symbols                       Generate the symbol file (if
+                                         applicable)
 ```
 
 支持的命令: