From 359698f4774852e9b5afa9aece6f82ddbb286721 Mon Sep 17 00:00:00 2001 From: AGulev Date: Fri, 11 Sep 2026 15:26:40 +0200 Subject: [PATCH] big 1.13.2 fixes --- .wordlist.txt | 2 + docs/en/manuals/android.md | 35 ++++++++++++++++ docs/en/manuals/app-manifest.md | 20 +++++++++ docs/en/manuals/editor-preferences.md | 3 ++ docs/en/manuals/editor-scripts-ui.md | 28 ++++++++++++- docs/en/manuals/editor-scripts.md | 6 ++- docs/en/manuals/extensions.md | 46 ++++++++++++++++++++- docs/en/manuals/file-access.md | 2 + docs/en/manuals/font.md | 2 + docs/en/manuals/gui-text.md | 3 +- docs/en/manuals/html5.md | 22 ++++++++++ docs/en/manuals/optimization-size.md | 2 + docs/en/manuals/project-settings.md | 18 ++++++-- docs/en/manuals/render.md | 59 +++++++++++++++++++++++++++ docs/en/manuals/scene-editing.md | 12 +++++- docs/en/manuals/script-properties.md | 14 ++++++- docs/en/manuals/writing-code.md | 10 +++++ 17 files changed, 274 insertions(+), 10 deletions(-) diff --git a/.wordlist.txt b/.wordlist.txt index 9c8da37b5..8b3f97d4c 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -233,6 +233,7 @@ jamesramsay javafx JIT jitter +JNI jobfolder jpg js @@ -304,6 +305,7 @@ MonoBehaviour MonoBehaviours Monteiro movieclip +MSAA mutex Nakama namespace diff --git a/docs/en/manuals/android.md b/docs/en/manuals/android.md index d270b9a1f..32c265839 100644 --- a/docs/en/manuals/android.md +++ b/docs/en/manuals/android.md @@ -85,6 +85,41 @@ For this feature to work, you will need *ADB* installed and *USB debugging* enab An *.aab* file can be uploaded to Google Play via the [Google Play developer console](https://play.google.com/apps/publish/). It is also possible to generate an *`.apk`* file from an *.aab* file to install it locally using the [Android bundletool](https://developer.android.com/studio/command-line/bundletool). +## Shrinking Java code with R8 + +R8 reduces the size of Java code through shrinking, optimization and obfuscation. + +### Enabling R8 + +Select `/builtins/manifests/android/dmengine.keep` in **Android ▸ R8 Keep Rules** in *game.project*. This uses Defold's default rules directly: + +```ini +[android] +r8_keep_rules = /builtins/manifests/android/dmengine.keep +``` + +Make sure every extension with Java code provides a `.keep` file for the classes it needs at runtime. Extension rules are combined with the selected project rules when building. Test a release build on a device after enabling R8. + +Leaving **R8 Keep Rules** empty uses D8 without shrinking. Enabling R8 uses the native extension build service, even for a project without native extensions. + +### Adding rules to an extension + +Keep rules for an extension belong in its `manifests/android` directory, next to `build.gradle`. See [R8 keep rules for Android extensions](/manuals/extensions/#r8-keep-rules-for-android) for how to add a file and preserve the extension's Java classes. + +### Keeping the obfuscation mapping + +Enable **Generate debug symbols** in the Android bundle dialog, or pass `--with-symbols` to Bob, to retain R8's `mapping.txt` when the build produces one. For example, from the project directory: + +```sh +java -jar bob.jar --platform arm64-android --variant release \ + --archive --with-symbols --bundle-output build/android \ + resolve build bundle +``` + +The mapping is saved as `.apk.symbols/mapping.txt` beside the generated APK or AAB. For example, with the project title `My Game`, the command above produces `build/android/MyGame/MyGame.apk.symbols/mapping.txt`. + +Keep the mapping file with the exact release it came from. It maps obfuscated Java names back to the original names for interpreting stack traces; a mapping from a different build may give incorrect results. + ## Permissions The Defold engine requires a number of different permissions for all engine features to work. The permissions are defined in the `AndroidManifest.xml`, specified in the *game.project* [project settings file](/manuals/project-settings/#android). You can read more about Android permissions in [the official docs](https://developer.android.com/guide/topics/permissions/overview). The following permissions are requested in the default manifest: diff --git a/docs/en/manuals/app-manifest.md b/docs/en/manuals/app-manifest.md index 29462c14d..9df02baf1 100644 --- a/docs/en/manuals/app-manifest.md +++ b/docs/en/manuals/app-manifest.md @@ -76,6 +76,21 @@ Include support for Ogg Opus sound resources. The Opus decoder is excluded by de Exclude all input handling from the engine. +## Exclude GUI + +Remove GUI resources, components and Lua support from the engine. Enable this only if the project does not use GUI scenes or GUI scripts. Label components remain available. This option is disabled by default. + + +## Exclude Particle FX + +Remove particle effect resources, components and the `particlefx` Lua module. This also removes support for particle nodes in GUI scenes; GUI scenes without particle nodes remain supported. Remove references to particle effects and calls to their APIs before enabling this option. It is disabled by default. + + +## Exclude Tilemaps + +Remove tilemap resources, components and the `tilemap` Lua module. Enable this only if the project does not use tilemap components or their APIs. Tile sources used by other components remain available. This option is disabled by default. + + ## Exclude Live Update Exclude the [Live Update functionality](/manuals/live-update) from the engine. @@ -120,6 +135,11 @@ On Linux ARM64, the **OpenGL** choice uses the OpenGL ES backend. The Android co If enabled (`true`), this includes the full text layout system for shaping text, including right-to-left languages. Enable this option together with `font.runtime_generation` in *game.project* to use runtime generation for SDF fonts from TrueType (`.ttf`) or OpenType (`.otf`) resources. Runtime generation from `.otf` resources is supported since Defold 1.13.2. Read more in the [Font Manual](/manuals/font/#enabling-runtime-fonts). +## Use Rich Text + +Include rich text parsing and style effects for labels and GUI text. This option is enabled by default. Disable it to reduce engine size when the project only needs plain text. Labels and GUI text remain supported, but markup renders as plain text instead of applying formatting or effects. + + ## Minimum browser versions The YAML fields **`minSafariVersion`**, **`minFirefoxVersion`**, and **`minChromeVersion`** specify the minimum browser versions targeted by Emscripten. The current defaults and minimum supported versions differ between the non-threaded and threaded targets: diff --git a/docs/en/manuals/editor-preferences.md b/docs/en/manuals/editor-preferences.md index 89d713cdc..08614def9 100644 --- a/docs/en/manuals/editor-preferences.md +++ b/docs/en/manuals/editor-preferences.md @@ -61,6 +61,9 @@ Zoom on Scroll Auto-insert closing parens : Automatically inserts matching closing characters while editing code. This option is enabled by default. +Format on save +: Runs the language server formatter on modified open code files when saving. Disabled by default. The language server must support formatting; see [formatting code](/manuals/writing-code/#formatting-code) for formatting a document or selection manually. + ### Open script files in Visual Studio Code diff --git a/docs/en/manuals/editor-scripts-ui.md b/docs/en/manuals/editor-scripts-ui.md index f50a38145..55b58a969 100644 --- a/docs/en/manuals/editor-scripts-ui.md +++ b/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). You can find the full editor API reference [here](/ref/stable/editor-lua/). 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 dialogs and open resources 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](/ref/stable/editor-lua/). ## Hello world @@ -53,6 +53,32 @@ Finally, after pressing Enter (or clicking on the `Perform` button), Perform action: true ``` +## Opening resources + +Call `editor.ui.open_resource()` from a command's `run` function to open a project resource. The path starts with `/`. Omitting the view selects the resource's primary view: + +```lua +editor.ui.open_resource("/main/main.script") +``` + +The `code` and `text` views accept a cursor position or a selection as a third argument. Line and column numbers start at `1`; a missing column defaults to `1`. Specify the view when passing these arguments: + +```lua +editor.ui.open_resource("/main/main.script", "code", { line = 10 }) +editor.ui.open_resource("/main/main.script", "code", { line = 10, column = 5 }) +``` + +To select a range, provide `from` and `to` cursor positions instead: + +```lua +editor.ui.open_resource("/main/main.script", "code", { + from = { line = 10, column = 1 }, + to = { line = 12, column = 1 } +}) +``` + +The configured resource view may open in the editor or an external application. The built-in Code and Text views support the cursor and selection arguments. See [`editor.ui.open_resource()`](/ref/beta/editor/#editor.ui.open_resource:resource_path-view-args) for supported view names. + ## Basic concepts ### Components diff --git a/docs/en/manuals/editor-scripts.md b/docs/en/manuals/editor-scripts.md index 60f114c42..9bf57da21 100644 --- a/docs/en/manuals/editor-scripts.md +++ b/docs/en/manuals/editor-scripts.md @@ -576,9 +576,11 @@ Please note that lifecycle hooks currently are an editor-only feature, and they ## Language servers -The editor supports a subset of the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/): diagnostics (lints), completions, hover information, document symbols in the Structure pane, go to definition, find references, and symbol rename. Hover over a symbol to see information from the language server. With the cursor on a symbol, use F2 to rename it, F12 to go to its definition, or Shift+F12 to find references. These actions are also available from the Edit menu. +The editor supports a subset of the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/): diagnostics (lints), completions, hover information, document symbols in the Structure pane, go to definition, find references, symbol rename, and document/range formatting. Hover over a symbol to see information from the language server. With the cursor on a symbol, use F2 to rename it, F12 to go to its definition, or Shift+F12 to find references. These actions are also available from the Edit menu. See [formatting code](/manuals/writing-code/#formatting-code) for the formatting command and format-on-save preference. -To define the language server, you need to edit your editor script's `get_language_servers` function like so: +The bundled Lua language server includes Defold type annotations for the runtime and editor scripting APIs. In `.editor_script` files, completion and diagnostics recognize `editor.*` functions and their argument and return types. See [code completion](/manuals/writing-code/#code-completion). + +To register an additional language server, define your editor script's `get_language_servers` function like so: ```lua function M.get_language_servers() diff --git a/docs/en/manuals/extensions.md b/docs/en/manuals/extensions.md index 992d25800..971a4bbfe 100644 --- a/docs/en/manuals/extensions.md +++ b/docs/en/manuals/extensions.md @@ -72,13 +72,57 @@ The optional *manifests* folder of an extension contains additional files used i * `android` - This folder accepts a manifest stub file to be merged into the main application ([as described here](/manuals/extensions-manifest-merge-tool)). * The folder can also contain a `build.gradle` file with dependencies to be [resolved by Gradle](/manuals/extensions-gradle). - * The folder can also contain R8 keep-rule files (`.keep`) for Java code that needs to be preserved when shrinking is enabled. See the [R8 Keep Rules project setting](/manuals/project-settings/#r8-keep-rules) for setup and migration from the former ProGuard configuration. + * Extensions with Java code should include an [R8 keep-rule file](#r8-keep-rules-for-android) (`.keep`) for the classes they need at runtime. * `ios` - This folder accepts a manifest stub file to be merged into the main application ([as described here](/manuals/extensions-manifest-merge-tool)). * The folder can also contain a `Podfile` file with dependencies to be [resolved by Cocoapods](/manuals/extensions-cocoapods). * `osx` - This folder accepts a manifest stub file to be merged into the main application ([as described here](/manuals/extensions-manifest-merge-tool)). * `web` - This folder accepts a manifest stub file to be merged into the main application ([as described here](/manuals/extensions-manifest-merge-tool)). +### R8 keep rules for Android + +Add a `.keep` file to the extension's `manifests/android` directory, next to `build.gradle`. For example, `/myextension/manifests/android/myextension.keep` can preserve the extension's Java classes with: + +```proguard +-keep,allowoptimization class com.example.myextension.** { *; } +``` + +Replace `com.example.myextension` with the package containing your extension's Java classes. This rule preserves the classes and their members while allowing R8 to optimize their code. Add rules for other classes accessed through the Java Native Interface (JNI) or reflection, since R8 may not discover those uses automatically. + +If the extension relies on annotations at runtime, also include: + +```proguard +-keepattributes *Annotation* +``` + +These rules are combined with the project's selected keep file when [R8 is enabled](/manuals/android/#enabling-r8). + + +## Custom resources + +An extension can include data in the game archive by declaring custom resources in an `ext.properties` file next to its `ext.manifest`: + +```ini +[project] +custom_resources.default = /myextension/data +``` + +For example, place a JSON file at `/myextension/data/settings.json`. The path is relative to the project root, including the extension folder. When sharing the extension as a library, include `myextension` in the library's [Include Dirs](/manuals/libraries/#setting-up-library-sharing) so consuming projects receive the extension and its data. + +These paths are combined with `project.custom_resources` from *game.project* and contributions from other extensions. Setting custom resources in the project does not replace the extension contributions. Both editor builds and Bob archives include the files, which can be loaded at runtime: + +```lua +local data, err = sys.load_resource("/myextension/data/settings.json") +if data then + local settings = json.decode(data) + pprint(settings) +else + print(err) +end +``` + +See [file access](/manuals/file-access/#custom-resources) for how custom resources differ from bundle resources. + ## Sharing an extension Extensions are treated just like any other assets in your project and they can be shared in the same way. If a native extension folder is added as a Library folder it can be shared and used by others as a project dependency. Refer to the [Library project manual](/manuals/libraries/) for more information. diff --git a/docs/en/manuals/file-access.md b/docs/en/manuals/file-access.md index 46209d8ef..34bbb11fc 100644 --- a/docs/en/manuals/file-access.md +++ b/docs/en/manuals/file-access.md @@ -90,6 +90,8 @@ You can include files with your application using bundle resources and custom re #### Custom Resources :[Custom Resources](../shared/custom-resources.md) +Extensions can also contribute these files through `ext.properties`. Their paths are combined with the project's custom resources in both editor builds and Bob archives. See [extension custom resources](/manuals/extensions/#custom-resources). + ```lua -- Load level data into a string local data, error = sys.load_resource("/assets/level_data.json") diff --git a/docs/en/manuals/font.md b/docs/en/manuals/font.md index 591d98639..91ead3801 100644 --- a/docs/en/manuals/font.md +++ b/docs/en/manuals/font.md @@ -33,6 +33,8 @@ We currently use the libraries [HarfBuzz](https://github.com/harfbuzz/harfbuzz), See [Enabling Runtime Fonts](/manuals/font#enabling-runtime-fonts) +The editor uses the engine's font renderer for font and scene text previews. Text shaping and right-to-left layout require [runtime fonts](#enabling-runtime-fonts) and the **Use full text layout system** option in the App Manifest. For offline fonts, the preview respects the font's **Characters** and **All Chars** settings. + ## Font collection The `.fontc` file format is also known as a font collection. In offline mode, only one font is associated with it. diff --git a/docs/en/manuals/gui-text.md b/docs/en/manuals/gui-text.md index 77cc8dbc8..17c4441e6 100644 --- a/docs/en/manuals/gui-text.md +++ b/docs/en/manuals/gui-text.md @@ -7,6 +7,8 @@ brief: This manual describes how to add text to GUI scenes. Defold supports a specific type of GUI node that allows text to be rendered in a GUI scene. Any font resource added to a project can be used for text node rendering. +The editor preview supports text shaping and right-to-left layout using the engine's font renderer. See [text layout support](/manuals/font/#text-layout-support-eg-right-to-left) for the required font and App Manifest settings. + ## Adding text nodes The fonts that you wish to use in GUI text nodes must be added to the GUI component. Either right-click the *Fonts* folder, use the GUI top menu or press the corresponding keyboard shortcut. @@ -55,4 +57,3 @@ function on_message(self, message_id, message, sender) end end ``` - diff --git a/docs/en/manuals/html5.md b/docs/en/manuals/html5.md index 85f32effc..41ea374c2 100644 --- a/docs/en/manuals/html5.md +++ b/docs/en/manuals/html5.md @@ -79,6 +79,28 @@ Defold HTML5 bundles require a modern browser with WebAssembly support. Internet When you click on the Create bundle button you will be prompted to select a folder in which to create your application. After the export process completes, you will find all of the files needed to run the application. +## WebGL context version + +Select the requested graphics context through [`graphics.webgl_version_hint`](/manuals/project-settings/#webgl-version-hint). Its default is WebGL 2; request WebGL 1 to test or target that context on browsers that support both versions. + +## Download verification + +The HTML5 loader checks the sizes of downloaded engine and archive files by default. Failed checks cause downloads to be retried before the loader reports an error: + +* Network errors, failed HTTP statuses and size mismatches in the engine's JavaScript or WebAssembly download use the retry limit in `html5.retry_count`. +* Archive-file verification has its own retry limit for size or SHA-1 mismatches. Each verification retry downloads the file's pieces again, with the normal network retries available for each download. + +The `html5.retry_time` setting controls the delay between retries in both cases. + +If your server, proxy or CDN intentionally rewrites served files and changes their sizes, disable size verification in *game.project*: + +```ini +[html5] +verify_downloaded_file_size = 0 +``` + +Disabling **Verify Downloaded File Size** leaves any SHA-1 verification included in the bundle enabled. See the [HTML5 project settings](/manuals/project-settings/#verify-downloaded-file-size). + ## Known issues and limitations * Hot Reload - Hot Reload doesn't work in HTML5 builds. Defold applications must run their own miniature web server in order to receive updates from the editor, which isn't possible in a HTML5 build. diff --git a/docs/en/manuals/optimization-size.md b/docs/en/manuals/optimization-size.md index 5fc724299..ba01463b0 100644 --- a/docs/en/manuals/optimization-size.md +++ b/docs/en/manuals/optimization-size.md @@ -34,6 +34,8 @@ Defold will create a dependency tree when building and bundling your application A quick way to reduce the engine size is to remove functionality in the engine that you do not use. This is done [application manifest file](https://defold.com/manuals/app-manifest/) where it is possible to remove engine components that you do not need. Examples: * Physics - If your game does not make use of Box2D or Bullet3D physics then it is strongly advised to remove the physics engines +* GUI, particle effects and tilemaps - These components can be excluded separately with the [App Manifest component switches](/manuals/app-manifest/#exclude-gui). Remove component references and API calls for any feature you exclude. Excluding particle effects also removes support for particle nodes in GUI scenes. +* Rich text - Disable [Use Rich Text](/manuals/app-manifest/#use-rich-text) if labels and GUI text only need plain text. This removes rich text parsing and style effects while retaining ordinary text rendering. * LiveUpdate - If your game does not use LiveUpdate it can be removed * Image loaded - If your game does not manually load and decode images using `image.load()` * BasisU - If your game has few textures, compare the build size without BasisU (removed via app manifest) and without texture compression versus a build with BasisU and compressed textures. For games with limited textures, it might be more beneficial to reduce the binary size and skip texture compression. Additionally, not using the transcoder can lower the amount of memory required to run your game. diff --git a/docs/en/manuals/project-settings.md b/docs/en/manuals/project-settings.md index 3c7951b50..206ee0aff 100644 --- a/docs/en/manuals/project-settings.md +++ b/docs/en/manuals/project-settings.md @@ -102,6 +102,8 @@ A list of URLs to the project *Library URL*s. Refer to the [Libraries manual](/m Loading custom resources is covered in more detail in the [File Access manual](/manuals/file-access/#how-to-access-files-bundled-with-the-application). +Paths contributed by extensions through `custom_resources.default` in `ext.properties` are combined with this setting. See [extension custom resources](/manuals/extensions/#custom-resources) for an example. + #### Bundle Resources `bundle_resources` :[Bundle Resources](../shared/bundle-resources.md) @@ -165,6 +167,8 @@ Creates a high dpi back buffer on displays that support it. Typically the game w #### Samples How many samples to use for super sampling anti-aliasing. It sets the `GLFW_FSAA_SAMPLES` window hint. A value of `0` means that anti-aliasing is turned off. +This setting controls the window. Offscreen [multisampled render targets](/manuals/render/#multisampled-render-targets) have their own sample count. + #### Fullscreen Check if the application should start full screen. If unchecked, the application runs windowed. @@ -301,6 +305,9 @@ The texture profiles file to use for this project, `/builtins/graphics/default.t #### Verify Graphics Calls Verify the return value after each graphics call and report any errors in the log. +#### WebGL Version Hint +`graphics.webgl_version_hint` selects the WebGL context version to request for HTML5. Valid values are `1` (WebGL 1) and `2` (WebGL 2, the default). Set it to `1` to target or test WebGL 1 even on a browser that supports WebGL 2. Keep [Exclude GLES 2.0](#exclude-gles-20) disabled when targeting WebGL 1 so the required shaders are included. + #### OpenGL Version Hint OpenGL context version hint. If a specific version is selected, this will be used as the minimum version required (does not apply to OpenGL ES). @@ -641,9 +648,11 @@ Whether or not the application can be debugged using tools such as [GAPID](https #### R8 Keep Rules `android.r8_keep_rules` selects a `.keep` file to enable R8 shrinking, optimization and obfuscation of Java code in Android builds. Leave the setting empty to use D8 without shrinking. -Select `/builtins/manifests/android/dmengine.keep` to use the built-in rules. To customize them, copy this file into your project and select the copy. The selected file is the complete project rule set; it replaces the built-in rules rather than adding to them. Extensions can also provide [R8 keep rules](/manuals/extensions/#manifest-files). +Select `/builtins/manifests/android/dmengine.keep` to use Defold's default rules directly. Extensions supply their own [keep rules](/manuals/extensions/#r8-keep-rules-for-android), which are combined with this file. -Since Defold 1.13.2, this setting replaces `android.proguard`, and the built-in `dmengine.pro` file has been removed. Migrate existing project and extension rules to `.keep` files and select the project rules through **R8 Keep Rules**. +Only copy the built-in file into your project if you need to add project-specific rules. Preserve the built-in rules in the copy: selecting a custom file replaces the complete project rule set. + +See the [Android manual](/manuals/android/#shrinking-java-code-with-r8) for enabling R8 and retaining its obfuscation mapping with a release bundle. #### Extract Native Libraries Specifies whether the package installer extracts native libraries from the APK to the file system. If set to `false`, your native libraries are stored uncompressed in the APK. Although your APK might be larger, your application loads faster because the libraries load directly from the APK at runtime. This will set the `android:extractNativeLibs` flag in the Android Manifest ([official documentation](https://developer.android.com/guide/topics/manifest/application-element#extractNativeLibs)). @@ -720,11 +729,14 @@ When enabled this option will print information about the engine and engine vers Specifies which method to use to scale the game canvas. #### Retry Count -The number of attempts to download a file when the engine starts (see `Retry Time`). +The number of retries after a failed download during startup, including network errors, failed HTTP statuses and size mismatches in the engine's JavaScript or WebAssembly file. The initial request is separate. Archive-file verification has its own retry limit; see [download verification](/manuals/html5/#download-verification) and `Retry Time`. #### Retry Time The number of seconds to wait between attempts to download a file when the download failed (see `Retry Count`). +#### Verify Downloaded File Size +`html5.verify_downloaded_file_size` checks downloaded engine and archive files against their expected sizes. Enabled by default (`true`). Set it to `false` only if a server, proxy or CDN intentionally rewrites files and changes their sizes. Failed verification causes download retries before startup fails. The retry limits differ for engine downloads and archive-file verification; see [download verification](/manuals/html5/#download-verification). + #### Transparent Graphics Context Check if you want the graphics context to have a transparent backdrop. diff --git a/docs/en/manuals/render.md b/docs/en/manuals/render.md index 6c1cef464..d7d1de217 100644 --- a/docs/en/manuals/render.md +++ b/docs/en/manuals/render.md @@ -348,6 +348,65 @@ render.draw(self.my_tile_predicate) Defold currently only supports `Materials` and `Render Targets` as referenced render resources, but over time more resource types will be supported by this system. ::: +### Multisampled render targets + +Render targets support multisample anti-aliasing (MSAA). This smooths geometry edges in an offscreen render pass. The target's sample count is independent of [Display ▸ Samples](/manuals/project-settings/#samples), which controls anti-aliasing for the window. + +For a `.render_target` resource, set **Sample Count** in the editor to `1`, `2`, `4`, `8` or `16`. A value of `1` disables multisampling. Add the resource to your `.render` file's **Render Resources** table and use its assigned name with `render.set_render_target()`, as in the example above. + +Alternatively, create a target in your render script's `init()`. Put `sample_count` in the outer parameter table, alongside the attachments: + +```lua +self.offscreen = render.render_target({ + sample_count = 4, + [graphics.BUFFER_TYPE_COLOR0_BIT] = { + format = graphics.TEXTURE_FORMAT_RGBA, + width = 1024, + height = 1024, + min_filter = graphics.TEXTURE_FILTER_LINEAR, + mag_filter = graphics.TEXTURE_FILTER_LINEAR, + u_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, + v_wrap = graphics.TEXTURE_WRAP_CLAMP_TO_EDGE, + }, +}) +self.scene_predicate = render.predicate({"scene"}) +self.present_predicate = render.predicate({"present"}) +``` + +This example uses a color-only target. All color, depth and stencil attachments in a target share its sample count. Add a depth attachment and the usual depth-test state if the pass requires depth testing. + +For the following `update()` fragment, give the scene materials the `scene` tag and a full-screen quad's material the `present` tag. The quad's material must sample texture unit `0`. Set the appropriate view and projection for each pass: + +```lua +render.set_render_target(self.offscreen) +render.set_viewport(0, 0, 1024, 1024) +render.clear({[graphics.BUFFER_TYPE_COLOR0_BIT] = vmath.vector4(0, 0, 0, 1)}) +-- Set the scene view and projection here. +render.draw(self.scene_predicate) + +render.set_render_target(render.RENDER_TARGET_DEFAULT) +render.set_viewport(0, 0, render.get_window_width(), render.get_window_height()) +-- Set the full-screen quad view and projection here. +render.enable_texture(0, self.offscreen, graphics.BUFFER_TYPE_COLOR0_BIT) +render.draw(self.present_predicate) +render.disable_texture(0) +``` + +Switching away from the target finishes the pass and resolves its multisampled color attachments automatically. `render.enable_texture()` binds the resolved color texture, so the quad uses an ordinary texture sampler. No separate resolve command is required. + +The requested sample count defaults to `1` and must be a positive integer. Graphics backends reduce unsupported requests to a supported power-of-two count, falling back to `1` if necessary, and log a warning when the count changes. Higher sample counts increase the memory needed for the attachments. + +When using a render target resource, inspect its effective count from a game object `.script` with `resource.get_render_target_info()`. For example, after adding `/render/offscreen.render_target` to **Render Resources**: + +```lua +function init(self) + local info = resource.get_render_target_info("/render/offscreen.render_targetc") + print("Render target sample count:", info.sample_count) +end +``` + +Use this effective count when checking device support instead of assuming that the requested count was available. See [`render.render_target()`](/ref/beta/render/#render.render_target:parameters) and [`resource.get_render_target_info()`](/ref/beta/resource/#resource.get_render_target_info:path) for the full parameter and result tables. + ## Texture handles Textures in Defold are represented internally as a handle, which essentially equates to a number that should uniquely identify a texture object anywhere in the engine. This means that you can bridge the gameobject world with the rendering world by passing these handles between the render system and a gameobject script. For example, a script can create a dynamic texture in a script attached to a gameobject and send this to the renderer to be used as a global texture in a draw command. diff --git a/docs/en/manuals/scene-editing.md b/docs/en/manuals/scene-editing.md index bf1aea4be..7ab1bd064 100644 --- a/docs/en/manuals/scene-editing.md +++ b/docs/en/manuals/scene-editing.md @@ -7,7 +7,7 @@ brief: The Scene Editor is where you edit collections, game objects, GUIs, parti The **Scene Editor** is the visual editor used to build and edit scenes such as collections, game objects, and other visual assets. -By default, many visual scenes open with a **2D orthographic** view. For 3D work you can switch to a 3D-oriented layout, enable a 3D grid plane, and use a **perspective** camera. +The initial camera view depends on the resource. 3D resources such as models and glTF scenes default to **perspective**, while 2D resources such as sprites, tilemaps and GUI scenes default to **orthographic**. You can change the camera orientation, projection and grid through the scene toolbar. ## Opening the Scene Editor @@ -20,6 +20,14 @@ Open the Scene Editor by double-clicking a visual resource in the *Assets* pane, - **Effects** — particle effects (`.particlefx`) - And others +## Remembered scene views + +The editor remembers the camera state for each scene resource when its tab is closed or the editor exits. Reopening the same resource restores its view, so different collections or models can retain different camera positions, orientations and projections. + +Visibility filters are also remembered per scene. Hiding models or component guides in one scene does not require using the same filters in another. These are editor view settings and do not change the game's camera or runtime visibility. + +For resources without a saved camera state, model, mesh and glTF resources start in perspective. Collision objects choose their view from the project's 2D/3D physics setting; collections and game objects choose an initial view based on their scene geometry. + ## Scene view navigation (camera controls) The Scene Editor camera can be controlled with mouse and keyboard. The available controls depend on whether you are using the standard camera navigation or **Free Camera Mode**. @@ -128,6 +136,8 @@ Click on the **Visibility Eye Icon** (`👁`) in the Toolbar to toggle visibilit The grid can be customized to match your workflow (especially useful in 3D). Click the **Grid Settings** button (`▦`) to open the grid settings popup. +The editor keeps separate grid settings for 2D and 3D views. Set the size, plane and appearance while the desired mode is active; switching modes restores that mode's grid settings. **Reset to Defaults** resets the active mode's settings. + ![Grid Settings](images/editor/grid_popup.png) Settings include: diff --git a/docs/en/manuals/script-properties.md b/docs/en/manuals/script-properties.md index 920d82cda..08b896e87 100644 --- a/docs/en/manuals/script-properties.md +++ b/docs/en/manuals/script-properties.md @@ -67,7 +67,7 @@ Script properties are parsed when building the project. Value expressions are no Since Defold 1.13.2, a string default defines a text property. Text properties support UTF-8 and newline characters and are edited in a multiline field in the editor: ```lua -go.property("greeting", "Hello!\nWelcome to the game.") +go.property("greeting", "Hello!\nWelcome, José!") function init(self) go.set("#label", "text", self.greeting) @@ -76,6 +76,18 @@ end Select a script component in a game object or collection to override its text properties, just like other script properties. Embedded NUL characters are not allowed in defaults or overrides. +Other scripts can read and write a text property through the script component's URL. For example, put the script above and a label on a game object named `speaker` in the collection, with component ids `script` and `label`. Update them from another script's `init()`: + +```lua +function init(self) + local greeting = go.get("/speaker#script", "greeting") + go.set("/speaker#script", "greeting", greeting .. "\nEnjoy the game!") + go.set("/speaker#label", "text", go.get("/speaker#script", "greeting")) +end +``` + +Changing the script property does not automatically update the label; the last line explicitly copies the new value to the label's `text` property. + ## Accessing script properties Any defined script property is available as a stored member in `self`, the script instance reference: diff --git a/docs/en/manuals/writing-code.md b/docs/en/manuals/writing-code.md index 95a416188..cacd606b4 100644 --- a/docs/en/manuals/writing-code.md +++ b/docs/en/manuals/writing-code.md @@ -35,6 +35,16 @@ Pressing CTRL + Space will show additional information abo ![](/images/editor/apireference.png) +The bundled Lua language server includes type annotations for Defold APIs. Completion, hover information and diagnostics understand Defold types such as hashes, URLs, vectors and quaternions, as well as function arguments and return values. The editor provides annotations for game scripts and for the `editor.*` APIs used in `.editor_script` files. No separate annotation library is needed for the built-in APIs when using the Defold code editor. + +Third-party extension APIs may need their own annotations. + +### Formatting code + +Select Edit ▸ Format Document/Selection or press Alt + Shift + F to run the language server's formatter. With a selection, the editor formats the selected lines; without one, it formats the document. Formatting requires a language server that supports the corresponding formatting operation. + +To format modified open files when saving, enable **Format on save** in Preferences ▸ Code. This preference is disabled by default and requires a language server that supports document formatting. See [Code preferences](/manuals/editor-preferences/#code). + ### Jump to symbol The built-in code editor can show a searchable list of symbols in the current code file, such as functions, objects, and variables. Select View ▸ Jump to Symbol…, or press Ctrl + Shift + O on Windows and Linux, or ⌘ Cmd + Shift + O on macOS.