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

Author: britzl

.wordlist.txt

@@ -71,6 +71,7 @@ cmd
 CocoaPods
 CodeAndWeb
 codebase
+CJK
 codesign
 collada
 collectionfactory
@@ -94,6 +95,7 @@ customizable
 customizations
 cutscene
 cutscenes
+dt
 dae
 deadzone
 debuggable
@@ -128,6 +130,7 @@ esc
 excitemike
 exe
 ffmpeg
+FCM
 Fi
 filesystem
 filetype
@@ -160,6 +163,7 @@ Git's
 github
 gitlab
 GL
+GLES
 glb
 GLFW
 globals
@@ -186,6 +190,7 @@ hxdefold
 IAM
 IAP
 ico
+icns
 ICOConvert
 iconified
 idfa
@@ -366,6 +371,7 @@ scroller
 SD
 SDK
 SDKs
+SDF
 Sergey
 sha
 shader

docs/en/manuals/camera.md

@@ -229,12 +229,6 @@ function M.screen_to_world(camera, screen_x, screen_y, z)
     local projection = go.get(camera, "projection")
     local view = go.get(camera, "view")
     local w, h = window.get_size()
-    -- The window.get_size() function will return the scaled window size,
-    -- ie taking into account display scaling (Retina screens on macOS for
-    -- instance). We need to adjust for display scaling in our calculation.
-    local scale = window.get_display_scale()
-    w = w / scale
-    h = h / scale
 
     -- https://defold.com/manuals/camera/#converting-mouse-to-world-coordinates
     local inv = vmath.inv(projection * view)
@@ -246,7 +240,7 @@ function M.screen_to_world(camera, screen_x, screen_y, z)
 end
 ```
 
-Visit the [Examples page](https://defold.com/examples/render/screen_to_world/) to see screen to world coordinate conversion in action. There is also a [sample project](https://github.com/defold/sample-screen-to-world-coordinates/) showing how to do screen to world coordinate conversion.
+Keep in mind that the values `action.screen_x` and `action.screen_y` from `on_input()` should be used as arguments for this function. Visit the [Examples page](https://defold.com/examples/render/screen_to_world/) to see screen to world coordinate conversion in action. There is also a [sample project](https://github.com/defold/sample-screen-to-world-coordinates/) showing how to do screen to world coordinate conversion.
 
 ::: sidenote
 The [third-party camera solutions mentioned in this manual](/manuals/camera/#third-party-camera-solutions) provides functions for converting to and from screen coordinates.

docs/en/manuals/editor-scripts.md

@@ -71,6 +71,7 @@ You can interact with the editor using `editor` package that defines this API:
 - `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.
 - `editor.create_directory(resource_path)` — create a directory if it does not exist, and all non-existent parent directories.
+- `editor.create_resources(resources)` — create 1 or more resources, either from templates or with custom content
 - `editor.delete_directory(resource_path)` — delete a directory if it exists, and all existent child directories and files.
 - `editor.execute(cmd, [...args], [options])` — run a shell command, optionally capturing its output.
 - `editor.save()` — persist all unsaved changed to disk.
@@ -692,7 +693,7 @@ The editor script runtime uses 2 execution modes that are mostly transparent to
 Some of the functions that the editor scripts can use may take a lot of time to run. For example, `editor.execute("git", "status", {reload_resources=false, out="capture"})` can take up to a second on sufficiently large projects. To maintain editor responsiveness and performance, functions that may be time-consuming are not allowed in contexts where the editor needs an immediate response. Attempting to use such a function in an immediate context will result in an error: `Cannot use long-running editor function in immediate context`. To resolve this error, avoid using such functions in immediate contexts.
 
 The following functions are considered long-running and cannot be used in immediate mode:
-- `editor.create_directory()`, `editor.delete_directory()`, `editor.save()`, `os.remove()` and `file:write()`: these functions modify the files on disc, causing the editor to synchronize its in-memory resource tree with the disc state, which can take seconds in large projects.
+- `editor.create_directory()`, `editor.create_resources()`, `editor.delete_directory()`, `editor.save()`, `os.remove()` and `file:write()`: these functions modify the files on disc, causing the editor to synchronize its in-memory resource tree with the disc state, which can take seconds in large projects.
 - `editor.execute()`: execution of shell commands can take an unpredictable amount of time.
 - `editor.transact()`: large transactions on widely-referenced nodes may take hundreds of milliseconds, which is too slow for UI responsiveness.
 

docs/en/manuals/editor.md

@@ -175,6 +175,21 @@ You can also get access to editor logs while the editor is running if it is star
 $ > ./path/to/Defold.app/Contents/MacOS/Defold
 ```
 
+## Editor server
+
+When the editor opens a project, it will start a web server on a random port. The server may be used to interact with the editor from other applications. Since 1.11.0, the port is written to the `.internal/editor.port` file.
+
+Additionally, since 1.11.0 the editor executable has a command line option `--port` (or `-p`), which allows specifying the port during launch, e.g.::
+```shell
+# on Windows
+.\Defold.exe --port 8181
+
+# on Linux:
+./Defold --port 8181
+
+# on macOS:
+./Defold.app/Contents/MacOS/Defold --port 8181
+```
 
 ## FAQ
 :[Editor FAQ](../shared/editor-faq.md)

docs/en/manuals/font.md

@@ -16,11 +16,6 @@ Fonts added to your project are automatically converted into a texture format th
 - Bitmap
 - Distance field
 
-::: sidenote
-It is possible to [generate font glyphs at runtime](/extension-fontgen) from a bundled TrueType font instead of generating and including a font texture in the application bundle. This approach can greatly reduce the download size and runtime memory consumption of a Defold game.
-:::
-
-
 ## Creating a font
 
 To create a font for use in Defold, create a new Font file by selecting <kbd>File ▸ New...</kbd> from the menu, then select <kbd>Font</kbd>. You can also <kbd>right click</kbd> a location in the *Assets* browser and select <kbd>New... ▸ Font</kbd>.
@@ -97,7 +92,7 @@ space ! " # $ % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @ A B C D E
 *Cache Width/Height*
 : Constrains the size of the glyph cache bitmap. When the engine renders text, it looks up the glyph from the cache bitmap. If it does not exist there, it will be added to the cache before rendering. If the cache bitmap is too small to contain all the glyphs the engine is asked to render, an error is signalled (`ERROR:RENDER: Out of available cache cells! Consider increasing cache_width or cache_height for the font.`).
 
-  If set to 0 the cache size is set automatically.
+  If set to 0 the cache size is set automatically, and will grow to 2048x4096 max.
 
 ## Distance field fonts
 
@@ -167,3 +162,79 @@ 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).
+
+## Runtime generation
+
+It is possible to use runtime generation for SDF type fonts, when using TrueType (.ttf) fonts.
+This approach can greatly reduce the download size and runtime memory consumption of a Defold game.
+The small downside is a very small delay for each glyph generated at runtime.
+
+Enable the feature by setting `font.runtime_generation` in game.project.
+
+::: sidenote
+This feature is currently experimental, but with the intention to be used as the default workflow in the future.
+:::
+
+::: important
+This setting affects all .ttf fonts in the project.
+:::
+
+### Prewarming glyph cache
+
+In order to make the runtime fonts easier to use, they support prewarming of the glyph cache.
+This means the font will generate the glyphs listed in *Characters* in the font.
+
+::: sidenote
+If `All Chars` is selected, there will be no prewarming as it defeats the purpose of not having to generate all glyphs at the same time.
+:::
+
+### Font Scripting
+
+For runtime fonts, it's possible to add or removed sub fonts.
+This is useful when a large font has been split up into multiple files for different character sets (e.g. CJK)
+
+::: important
+Adding a subfont doesn't automatically load or render all the glyphs.
+:::
+
+```lua
+-- Add the range A-Z to the .fontc
+local font_hash = hash("/assets/fonts/roboto.fontc")
+local ttf_hash = hash("/assets/fonts/Roboto/Roboto-Bold.ttf")
+local codepoint_min = 0x00000041 -- A
+local codepoint_max = 0x0000005A -- Z
+font.add_source(font_hash, ttf_hash, codepoint_min, codepoint_max)
+```
+
+```lua
+-- Remove the associated ttf resource
+local font_hash = hash("/assets/fonts/roboto.fontc")
+local ttf_hash = hash("/assets/fonts/Roboto/Roboto-Bold.ttf")
+font.remove_source(font_hash, ttf_hash)
+```
+
+To load the glyphs to the font, you will need to call the `font.add_glyphs()`.
+It is an asynchronous operation, and once it's done, it's safe to progress to show any message containing the glyphs.
+
+```lua
+local function add_glyph_callback(self, id, result, errmsg)
+  if not result then
+    print("Request " .. id .." finished with error:", errmsg)
+  else
+    msg.post(some_url, "show_dialog")
+  end
+end
+
+-- Load glyphs into the font
+local font_hash = hash("/assets/fonts/roboto.fontc")
+local glyphs = "Some text to be shown!" -- for optimal performance, make this a list of unique glyphs
+local request_id = font.add_glyphs(font_hash, ttf_hash, add_glyph_callback)
+```
+
+And, once the characters aren't needed anymore, you can discard that memory:
+```lua
+-- Remove the associated ttf resource
+local font_hash = hash("/assets/fonts/roboto.fontc")
+font.remove_glyphs(font_hash, "All the characters in the set")
+```
+

docs/en/manuals/images/live-update/05-liveupdate-settings-zip.png

@@ -48,6 +48,9 @@ There are currently two ways that Defold can store the resources. Choose the met
 `Zip`
 : This option tells Defold to create a Zip archive file with any excluded resources. The archive is saved at the location specified in the *Export path* setting.
 
+`Folder`  
+: This option tells Defold to create a folder with all the excluded resources. It works exactly the same way as Zip, but uses a directory instead of an archive. This may be useful in cases where you need to post-process files before uploading and plan to pack them into an archive yourself.
+
 `Amazon`
 : This option tells Defold to automatically upload excluded resources to an Amazon Web Service (AWS) S3 bucket. Fill in your AWS *Credential profile* name, select the appropriate *Bucket* and provide a *Prefix* name.  You can read more on how to setup an AWS account in this [aws guide](/manuals/live-update-aws)