HTML5: document host-set Module opt-outs (defold/defold#12396 follow-up) by birdingman0626 · Pull Request #635 · defold/doc

birdingman0626 · 2026-05-18T15:34:20Z

Follow-up documentation for defold/defold#12396, which expands dmloader.js to respect six host-set properties on the global Module object:

Module.isWASMPthreadSupported
Module.isWebGL2Supported
Module.webGLContextAttributes
Module.webGLExtensionFilter
Module.showButtonStrip
Module.autoReloadOnWebGLContextRestore

Each is captured before the loader's own var Module = {...} redefinition and applied in an IIFE that runs at the same site. Default behaviour is byte-identical when nothing is pre-set.

This PR adds a new "Host-set Module properties" subsection to docs/en/manuals/html5.md, placed between the existing "Engine arguments" and "Query arguments in the URL" subsections under "Passing arguments to an HTML5 game". The new content includes:

The example shape (a var Module = { ... }; block before the <script src=\"dmloader.js\"> tag).
A per-property table with the type constraint, the effect, and the concrete failure mode each opt-out addresses.
Two callouts: the let vs var binding gotcha (top-level let Module is invisible to the loader's var Module), and the strict sentinel-value semantics (=== false / === true / function typeof, no coercion).

Should land after defold/defold#12396 merges, since this references behaviour the engine doesn't have yet. Adjustable to whatever the final API surface looks like if the engine PR shrinks during review.

PR checklist

Documentation
- Docs change matches the new engine-side behaviour described in Allow WebView-host opt-outs via pre-set Module.* properties defold#12396.
- New section inserted into the existing manual structure rather than a new file, so navigation / links stay consistent.
- Markdown anchors and code fences validated locally.

dmloader.js now respects six host-set properties on the global Module object when they're declared before <script src="dmloader.js"> loads (defold/defold#12396). Document the full surface — pthread, WebGL2, context attrs, extension filter, button strip, context-loss recovery — in the HTML5 manual under a new "Host-set Module properties" subsection, between Engine arguments and Query arguments. Includes the example shape, the per-property reference table, and the two important notes (let-vs-var binding, strict sentinel checks).

paweljarosz · 2026-06-02T10:37:22Z

 ```


+### Host-set Module properties


Suggested change

### Host-set Module properties

### Advanced HTML5 embedding: Host-set Module properties

paweljarosz · 2026-06-02T10:38:13Z



+### Host-set Module properties
+


Suggested change

These options are intended for advanced HTML5 embedding scenarios, such as WebView wrappers or custom host pages. Most games should not need them.

paweljarosz · 2026-06-02T10:39:08Z

+| `webGLExtensionFilter` | `(name) => boolean` | Strip names from `getSupportedExtensions` / `getExtension`. Returning `true` for a name removes it. Useful when the driver falsely advertises compressed-texture / float-texture / depth-texture extensions then rejects the actual upload. |
+| `showButtonStrip` | `=== false` | Hide the engine_template footer (`.buttons-background`). [project setting]`html5.show_fullscreen_button = 0` + `html5.show_made_with_defold = 0` suppresses the inner anchors but leaves a 42 px white bar behind; this opt-out finishes the job for hosts that want a true-fullscreen canvas. |
+| `autoReloadOnWebGLContextRestore` | `=== true` | Attach `webglcontextlost` / `webglcontextrestored` listeners to the canvas. `preventDefault()` on lost asks the browser to restore; on restored, `location.reload()` so the engine boots cleanly. The player lands on the title screen and resumes from autosave. |
+


Suggested change

::: important

Some of these options patch browser prototypes and may affect other WebGL canvases on the same page. Use them only on controlled host pages dedicated to the Defold game.

:::

paweljarosz · 2026-06-02T10:40:57Z

+| `webGLContextAttributes` | `Object` | Merged (`Object.assign`) into the attrs argument of the WebGL context creation. Notably useful for forcing `preserveDrawingBuffer:true` when the host compositor is flaky and `eglSwapBuffers` may fail between renders. |
+| `webGLExtensionFilter` | `(name) => boolean` | Strip names from `getSupportedExtensions` / `getExtension`. Returning `true` for a name removes it. Useful when the driver falsely advertises compressed-texture / float-texture / depth-texture extensions then rejects the actual upload. |
+| `showButtonStrip` | `=== false` | Hide the engine_template footer (`.buttons-background`). [project setting]`html5.show_fullscreen_button = 0` + `html5.show_made_with_defold = 0` suppresses the inner anchors but leaves a 42 px white bar behind; this opt-out finishes the job for hosts that want a true-fullscreen canvas. |
+| `autoReloadOnWebGLContextRestore` | `=== true` | Attach `webglcontextlost` / `webglcontextrestored` listeners to the canvas. `preventDefault()` on lost asks the browser to restore; on restored, `location.reload()` so the engine boots cleanly. The player lands on the title screen and resumes from autosave. |


Suggested change

| `autoReloadOnWebGLContextRestore` | `=== true` | Attach `webglcontextlost` / `webglcontextrestored` listeners to the canvas. `preventDefault()` on lost asks the browser to restore; on restored, `location.reload()` so the engine boots cleanly. The player lands on the title screen and resumes from autosave. |

| `autoReloadOnWebGLContextRestore` | `=== true` | Attach `webglcontextlost` / `webglcontextrestored` listeners to the canvas. `preventDefault()` on lost asks the browser to restore; on restored, `location.reload()` so the engine boots cleanly. On restore, the page is reloaded so the engine can initialise a fresh WebGL context. Any game state that should survive the reload must be persisted by the game.|

paweljarosz · 2026-06-02T10:43:15Z

+:::
+
+::: important
+The checks are strict — only the literal sentinel triggers the opt-out (`=== false` for the booleans, `=== true` for `autoReloadOnWebGLContextRestore`, a `function` typeof for the filter, a truthy object for the attrs). Truthy/falsy values like `0`, `null`, `""`, or `undefined` are ignored.


Suggested change

The checks are strict — only the literal sentinel triggers the opt-out (`=== false` for the booleans, `=== true` for `autoReloadOnWebGLContextRestore`, a `function` typeof for the filter, a truthy object for the attrs). Truthy/falsy values like `0`, `null`, `""`, or `undefined` are ignored.

The checks are strict — only the literal sentinel triggers the opt-out (`=== false` for the booleans, `=== true` for `autoReloadOnWebGLContextRestore`, a `function` typeof for the filter, a truthy object for the attrs). Must be a plain object. Other truthy/falsy values like `0`, `null`, `""`, or `undefined` are unsupported, ignored, and should not be used.

paweljarosz · 2026-06-02T10:44:12Z

+    isWebGL2Supported: false,
+    webGLContextAttributes: { preserveDrawingBuffer: true },
+    webGLExtensionFilter: function (name) {
+        return name.toLowerCase().includes("compressed_texture");


Suggested change

return name.toLowerCase().includes("compressed_texture");

return typeof name === "string" && name.toLowerCase().includes("compressed_texture");

paweljarosz · 2026-06-02T10:45:23Z

+| `isWebGL2Supported` | `=== false` | Downgrade `getContext('webgl2')` to `'webgl'`. Useful when the embedded GLES driver advertises WebGL2 but trips inside the engine's VAO / instancing init. |
+| `webGLContextAttributes` | `Object` | Merged (`Object.assign`) into the attrs argument of the WebGL context creation. Notably useful for forcing `preserveDrawingBuffer:true` when the host compositor is flaky and `eglSwapBuffers` may fail between renders. |
+| `webGLExtensionFilter` | `(name) => boolean` | Strip names from `getSupportedExtensions` / `getExtension`. Returning `true` for a name removes it. Useful when the driver falsely advertises compressed-texture / float-texture / depth-texture extensions then rejects the actual upload. |
+| `showButtonStrip` | `=== false` | Hide the engine_template footer (`.buttons-background`). [project setting]`html5.show_fullscreen_button = 0` + `html5.show_made_with_defold = 0` suppresses the inner anchors but leaves a 42 px white bar behind; this opt-out finishes the job for hosts that want a true-fullscreen canvas. |


Suggested change

| `showButtonStrip` | `=== false` | Hide the engine_template footer (`.buttons-background`). [project setting]`html5.show_fullscreen_button = 0` + `html5.show_made_with_defold = 0` suppresses the inner anchors but leaves a 42 px white bar behind; this opt-out finishes the job for hosts that want a true-fullscreen canvas. |

| `showButtonStrip` | `=== false` | Hide the engine_template footer (`.buttons-background`). This can be used in addition to the existing html5.show_fullscreen_button and html5.show_made_with_defold project settings - `html5.show_fullscreen_button = 0` + `html5.show_made_with_defold = 0` suppresses the inner anchors but leaves a 42 px white bar behind; this opt-out finishes the job for hosts that want a true-fullscreen canvas. |

birdingman0626 mentioned this pull request May 18, 2026

Allow WebView-host opt-outs via pre-set Module.* properties defold/defold#12396

Open

14 tasks

britzl requested review from AGulev and paweljarosz May 20, 2026 07:45

paweljarosz reviewed Jun 2, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

HTML5: document host-set Module opt-outs (defold/defold#12396 follow-up)#635

HTML5: document host-set Module opt-outs (defold/defold#12396 follow-up)#635
birdingman0626 wants to merge 1 commit into
defold:masterfrom
birdingman0626:dmloader-host-module-opt-outs

birdingman0626 commented May 18, 2026

Uh oh!

paweljarosz Jun 2, 2026

Uh oh!

paweljarosz Jun 2, 2026

Uh oh!

paweljarosz Jun 2, 2026

Uh oh!

paweljarosz Jun 2, 2026

Uh oh!

paweljarosz Jun 2, 2026

Uh oh!

paweljarosz Jun 2, 2026

Uh oh!

paweljarosz Jun 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	### Host-set Module properties
	### Advanced HTML5 embedding: Host-set Module properties


	These options are intended for advanced HTML5 embedding scenarios, such as WebView wrappers or custom host pages. Most games should not need them.

	The checks are strict — only the literal sentinel triggers the opt-out (`=== false` for the booleans, `=== true` for `autoReloadOnWebGLContextRestore`, a `function` typeof for the filter, a truthy object for the attrs). Truthy/falsy values like `0`, `null`, `""`, or `undefined` are ignored.
	The checks are strict — only the literal sentinel triggers the opt-out (`=== false` for the booleans, `=== true` for `autoReloadOnWebGLContextRestore`, a `function` typeof for the filter, a truthy object for the attrs). Must be a plain object. Other truthy/falsy values like `0`, `null`, `""`, or `undefined` are unsupported, ignored, and should not be used.

	return name.toLowerCase().includes("compressed_texture");
	return typeof name === "string" && name.toLowerCase().includes("compressed_texture");

Conversation

birdingman0626 commented May 18, 2026

PR checklist

Uh oh!

paweljarosz Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

paweljarosz Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

paweljarosz Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

paweljarosz Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

paweljarosz Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

paweljarosz Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

paweljarosz Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants