Web Export

Web Export in Godot 4.3+

Ship a Godot 4.x game as HTML5/WebAssembly. This covers what is different from a desktop export: the renderer, threading and server headers, browser interop, persistence, and the input and audio rules browsers enforce. All examples target Godot 4.3+ with no deprecated APIs.

C# projects cannot export to Web in Godot 4 — the .NET editor refuses the export (still true in 4.7.2). The code in this skill is GDScript only for that reason; a C# game that needs a browser build must be ported to GDScript or stay on Godot 3.

Related skills: export-pipeline for presets, CLI export and CI/CD, web-services for HTTP and WebSockets from the browser, rendering-pipeline for what the Compatibility renderer can and cannot do, audio-system for buses and playback, save-load for save formats.

1. What Changes on Web

Design for this from the start if web is a primary target. Porting a Forward+ game late means re-lighting it.

2. The Export Preset

Add a Web preset in Project → Export (export templates must be installed). The options that matter:

The output is an .html page plus .js, .wasm, .pck, and audio worklet files — upload all of them together. The default filename for the page should be index.html for most hosts.

CLI export works as on desktop: godot --headless --export-release "Web" build/web/index.html.

3. Threads or No Threads

Threaded builds use SharedArrayBuffer, which browsers only enable on a cross-origin isolated page. The server must send both headers on every file of the export (the page, its scripts, and the worker scripts):

Copy code
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Default to no threads. Turn them on only when profiling shows a real need (heavy procedural generation, physics on background threads), and you control the server or use a host that sets the headers. Code that must behave differently can check OS.has_feature("threads") — and any Thread-based code (level generation, loaders) must, or it silently does nothing on the default build. WorkerThreadPool is the portable choice.

Godot's own Remote Debug → Run in Browser server sends the headers, so a threaded build can work locally and fail once uploaded. Test on the real host.

4. Hosting

Server config snippets (nginx, Apache, Netlify, Cloudflare Pages), compression, and cache headers: references/hosting.md.

The PWA option also makes the game installable and playable offline. After you publish an update, JavaScriptBridge.pwa_needs_update() turns true (and pwa_update_available is emitted); call JavaScriptBridge.pwa_update() to reload into the new version — it reloads every open tab.

5. Detecting the Platform and Talking to JavaScript

Use feature tags, not OS.get_name() string checks:

gdscriptCopy code
func _ready() -> void:
    if OS.has_feature("web"):
        $QuitButton.hide() # A tab cannot be closed from inside the game.
        if OS.has_feature("web_ios") or OS.has_feature("web_android"):
            _use_touch_controls()

web_android, web_ios, web_macos, web_windows, and web_linuxbsd read the browser's user agent. Use them to pick controls or quality, never as a security check.

JavaScriptBridge calls into the page. It exists on every platform but only does something on Web, so guard calls with OS.has_feature("web").

gdscriptCopy code
var _on_resize_cb: JavaScriptObject # Keep a reference, or the callback is collected and never fires.


func _ready() -> void:
    if not OS.has_feature("web"):
        return
    var window := JavaScriptBridge.get_interface("window")
    _on_resize_cb = JavaScriptBridge.create_callback(_on_browser_resize)
    window.addEventListener("resize", _on_resize_cb)
    var lang: String = JavaScriptBridge.eval("navigator.language", true)
    print("Browser language: ", lang)


func _on_browser_resize(args: Array) -> void:
    print("Browser resized: ", args[0].type)


func export_save_file(data: PackedByteArray) -> void:
    # Call from an input event (button press): browsers may block downloads that aren't.
    JavaScriptBridge.download_buffer(data, "savegame.dat")

Callbacks receive one Array holding the JavaScript arguments. eval() runs arbitrary JavaScript — never pass it strings built from player input or network data.

Uploads, calling functions defined in your HTML shell, and sending events to the embedding page: references/javascript-bridge.md.

6. Audio

• Browsers block audio until the player interacts with the page. Start the game behind a "Click to play" screen (or the default loading page's click) so the first sound isn't swallowed.
• audio/general/default_playback_type.web is Sample: sounds are handed to the Web Audio API for low latency. AudioEffects on buses (reverb, filters, AudioEffectCapture, AudioEffectSpectrumAnalyzer) do not apply in this mode. Forcing Stream restores effects at the cost of latency and crackling — test before choosing it.
• Prefer Ogg Vorbis for music and short WAV for SFX; MP3 also works. See audio-system and assets-pipeline.

7. Saving and Persistence

user:// is backed by IndexedDB and synced when a file is closed. ConfigFile, FileAccess, and ResourceSaver work unchanged.

gdscriptCopy code
func save_settings(cfg: ConfigFile) -> void:
    cfg.save("user://settings.cfg") # Flushed to IndexedDB when the file closes.
    if OS.has_feature("web") and not OS.is_userfs_persistent():
        $SaveWarning.text = "Saves won't survive closing this tab (private browsing or storage blocked)."
        $SaveWarning.show()

• Private browsing, storage-blocking settings, and cleared site data wipe user://. Check OS.is_userfs_persistent() and tell the player.
• Storage is per origin: the same game on another domain (or a new itch.io upload URL) starts with empty saves. Offer export/import of save files (Section 5) for anything players would hate to lose.
• Browsers may evict storage under disk pressure. For accounts and cross-device saves use a backend — see web-services.

8. Input, Window, and Performance Limits

Load-size checklist (export filters, texture formats, custom template builds without unused modules): references/hosting.md.

9. Common Pitfalls

10. Checklist

• Project designed and lit for the Compatibility renderer
• No C# in the project; GDExtension only with variant/extensions_support and web binaries
• Thread support off unless needed and the host sends COOP/COEP (or the PWA service worker handles it)
• vram_texture_compression/for_mobile enabled if phone browsers are a target
• Tested on the actual host, not only the editor's Run in Browser server
• Click-to-play screen before audio starts; game pauses when the tab loses focus
• Fullscreen, mouse capture and downloads triggered from input events
• OS.is_userfs_persistent() checked; players can export important saves
• Quit button hidden on Web; platform checks use OS.has_feature("web")
• JavaScriptBridge callbacks stored in member variables; eval() never fed untrusted strings
• .wasm served as application/wasm; .wasm and .pck compressed on the server
• Download size checked; unused assets excluded from the Web preset