From d75c1b2c414eaa3e7b4923b885061c9a6a7db3d8 Mon Sep 17 00:00:00 2001 From: Hesperus Date: Thu, 27 Aug 2026 00:01:09 -0700 Subject: [PATCH] Web: document dlink_enabled as the GDExtension tradeoff it is, not a requirement MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README's single build command and the FAQ presented dlink_enabled=yes as required for the WebGPU export template. It is the engine's GDExtension switch (default off), and the WebGPU template builds and runs without it — verified end to end: compile, desktop rendering, and immersive-vr session entry on a non-dlink build. The cost of leaving it on for projects that ship no GDExtensions is real and user-visible: a split main+side module is larger than the monolithic build (50MB vs 43.5MB here), and the side module's link/relocation runs on the main thread AFTER the download bar completes — measured as ~10s of silent post-bar stall vs 2-3s for the monolithic build, whose compilation overlaps the download via streaming compile. Same total work, much worse distribution: the visible progress ends before the expensive step begins. Present both commands, defaults-first, with a per-flag tradeoff table (also covering opengl3/threads), matching upstream's model of shipping both template variants and selecting per-project via the export preset. --- README.md | 13 ++++++++++++- webgpu_site/FAQ.md | 2 +- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a0a93089600b..aa2e4b088941 100644 --- a/README.md +++ b/README.md @@ -210,10 +210,21 @@ Pre-built macOS editor with WebGPU export support. ## Building from Source ```bash -# WebGPU-only release template: +# WebGPU release template (no GDExtension support — smaller, faster boot): +scons platform=web target=template_release webgpu=yes opengl3=no threads=no + +# WebGPU release template WITH GDExtension support (dynamic linking): scons platform=web target=template_release dlink_enabled=yes webgpu=yes opengl3=no threads=no ``` +Build-flag decisions (each is a per-project tradeoff, not a requirement): + +| Flag | Engine default | Effect of deviating | +|---|---|---| +| `dlink_enabled=yes` | off | Enables GDExtension plugins on web. Costs a larger download (split main+side module) and a multi-second main-thread link/relocation step after the download bar completes — measured ~10s of silent post-bar stall on a mid-size template vs ~2-3s without. Only needed if the project uses GDExtensions (upstream Godot ships both template variants and selects per-project via the export preset's "Extensions Support" checkbox). | +| `opengl3=no` | on | Strips the GL driver: smaller template, but no `gl_compatibility` fallback for browsers without WebGPU. Keep GL in (like the debug recipe above does) if you want graceful fallback. | +| `threads=no` | on | Single-threaded build: avoids the COOP/COEP cross-origin-isolation hosting requirement. Currently required by this backend's single-threaded design assumptions. | + Requirements: - Emscripten 4.0.10+ (for the emdawnwebgpu port) - No Rust toolchain needed (Tint C++ translator is compiled directly into the engine) diff --git a/webgpu_site/FAQ.md b/webgpu_site/FAQ.md index 24cc09476a34..c9007b78415d 100644 --- a/webgpu_site/FAQ.md +++ b/webgpu_site/FAQ.md @@ -24,7 +24,7 @@ All major desktop browsers with WebGPU enabled. Mobile browser support is emergi scons platform=web target=template_release dlink_enabled=yes webgpu=yes opengl3=no threads=no ``` -The `dlink_enabled=yes` flag enables Emscripten dynamic linking, which produces a main module (`godot.wasm`) and a side module (`godot.side.wasm`). This is required for the WebGPU export template. +The `dlink_enabled=yes` flag enables Emscripten dynamic linking, which produces a main module (`godot.wasm`) and a side module (`godot.side.wasm`). It is required only for GDExtension support on web — the WebGPU template builds and runs without it (verified: compile, desktop rendering, and immersive-vr entry all work on a non-dlink build), and the monolithic build is smaller and avoids a multi-second main-thread linking step after download. Use `dlink_enabled=yes` when the project ships GDExtensions; omit it otherwise. Requirements: - Emscripten 4.0.10+ (for the emdawnwebgpu port)