web-export
/web-export
Use when shipping a Godot game to the browser — Web export preset options, threads vs no-threads and COOP/COEP headers, hosting on itch.io or your own server, PWA, JavaScriptBridge, user:// persistence, audio and input limits, and load size
- Author
- jame581 ↗
- Repository
- godotprompter ↗
- Licence
- MIT
- Last repository change
- 24.10.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 0
- HTML comments
- 2
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.
What it does and when to use it
Use when shipping a Godot game to the browser — Web export preset options, threads vs no-threads and COOP/COEP headers, hosting on itch.io or your own server, PWA, JavaScriptBridge, user:// persistence, audio and input limits, and load size
Original author description
Use when shipping a Godot game to the browser — Web export preset options, threads vs no-threads and COOP/COEP headers, hosting on itch.io or your own server, PWA, JavaScriptBridge, user:// persistence, audio and input limits, and load size
How it works
- 1. What Changes on Web
- 2. The Export Preset
- 3. Threads or No Threads
- 4. Hosting
- 5. Detecting the Platform and Talking to JavaScript
- 6. Audio
- 7. Saving and Persistence
- 8. Input, Window, and Performance Limits
- 9. Common Pitfalls
- 10. Checklist
SKILL.md preview
---
name: web-export
description: Use when shipping a Godot game to the browser — Web export preset options, threads vs no-threads and COOP/COEP headers, hosting on itch.io or your own server, PWA, JavaScriptBridge, user:// persistence, audio and input limits, and load size
---
# 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
| Area | On Web |
|---|---|
| Renderer | Always **Compatibility** (WebGL 2) — `rendering/renderer/rendering_method.web` defaults to `gl_compatibility`. No SDFGI, VoxelGI, volumetric fog, SSR, FSR, or screen-space AA |
| Scripting | GDScript and GDExtension only. No C# |
| Threads | Optional. Off by default; turning them on needs special server headers (Section 3) |
| Audio | Sample playback through the Web Audio API by default — `AudioEffect`s on buses do not apply (Section 6) |
| Files | `user://` lives in the browser's IndexedDB; there is no access to the player's disk except downloads and file-picker uploads |
| Networking | HTTP via the browser's `fetch` (CORS applies), WebSockets and WebRTC only — no raw TCP/UDP, so no ENet |
| Processes | No `OS.execute()`, `OS.create_process()`, or quitting the tab |
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:
| Option | Default | Set it when |
|---|---|---|
| `variant/thread_support` | `false` | You need threads and can serve COOP/COEP headers (Section 3) |
| `variant/extensions_support` | `false` | The project uses GDExtension (needs the extension's web build) |
| `vram_texture_compression/for_desktop` | `true` | S3TC/BPTC textures for desktop browsers |
| `vram_texture_compression/for_mobile` | `false` | Turn on for phone browsers (ETC2/ASTC); costs a second texture set in the PCK |
| `html/canvas_resize_policy` | Adaptive | `None` / `Project` when embedding in a fixed-size page element |
| `html/focus_canvas_on_start` | `true` | Keep on so keyboard input works without a first click |
| `html/experimental_virtual_keyboard` | `false` | Mobile browsers need an on-screen keyboard for `LineEdit` |
| `html/head_include` | empty | Extra `<head>` tags — analytics, meta tags, fonts |
| `html/custom_html_shell` | empty | Replace the whole loading page with your own template |
| `progressive_web_app/enabled` | `false` | Installable, offline-capable build (Section 4) |
| `threads/emscripten_pool_size`, `threads/godot_pool_size` (Godot 4.5+) | 8, 4 | Only shown with thread support; lower them to reduce memory |
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):
```
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
```
| | No threads (default, Godot 4.3+) | Threads |
|---|---|---|
| Hosting | Any static host | Needs the two headers above, or the PWA workaround |
| Audio | Sample playback, low latency | Sample playback by default; stream mode crackles more |
| Embeds, ads, third-party iframes | Work | Break unless they also send CORP/CORS headers (`require-corp` blocks them) |
| `WorkerThreadPool` | Tasks run inline on the main thread, so heavy work stalls frames | Real background threads |
| `Thread` | **`start()` returns `OK` but the function never runs** | Real background threads |
| Feature tag | `nothreads` | `threads` |
**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
| Host | What to do |
|---|---|
| **itch.io** | Upload a ZIP with `index.html` at its root, set the project kind to HTML. For threaded builds tick **SharedArrayBuffer support** in the embed options |
| **GitHub Pages, plain static hosts** | No custom headers: ship the no-threads build, or enable PWA with `progressive_web_app/ensure_cross_origin_isolation_headers` (default `true`) so a service worker adds the headers after the first load |
| **Your own server / CDN** | Send COOP/COEP for threads, serve `.wasm` as `application/wasm`, and precompress `.wasm` and `.pck` with Brotli or gzip |
Server config snippets (nginx, Apache, Netlify, Cloudflare Pages), compression, and cache headers: [references/hosting.md](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
<!-- csharp-parity: n/a — C# projects cannot export to Web in Godot 4, so web-only code paths are GDScript only -->
Use feature tags, not `OS.get_name()` string checks:
```gdscript
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")`.
```gdscript
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](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. `AudioEffect`s 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.
<!-- csharp-parity: n/a — C# projects cannot export to Web in Godot 4, so web-only code paths are GDScript only -->
```gdscript
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
| Behavior | Rule |
|---|---|
| Fullscreen, mouse capture, pointer lock, clipboard writes | Only work from inside an input event handler (a click or key press), not from `_ready()` or a timer |
| Keyboard focus | Lost when the player clicks outside the canvas; keep `html/focus_canvas_on_start` on and show a "click to focus" hint |
| Browser shortcuts | `Ctrl+W`, `Ctrl+T`, `F11` and similar may be handled by the browser, not the game — don't bind core actions to them |
| Frame rate | The browser drives frames with `requestAnimationFrame`; background tabs are throttled or paused, so pause the game on `NOTIFICATION_WM_WINDOW_FOCUS_OUT` |
| Memory | WebAssembly memory is limited; large levels and uncompressed textures crash low-end and mobile browsers first |
| Load size | Every megabyte of `.pck` and `.wasm` is downloaded before play — trim unused assets and compress on the server |
Load-size checklist (export filters, texture formats, custom template builds without unused modules): [references/hosting.md](references/hosting.md#reducing-download-size).
---
## 9. Common Pitfalls
| Symptom | Cause | Fix |
|---|---|---|
| Blank page, console says `SharedArrayBuffer is not defined` | Threaded build on a server without COOP/COEP | Export with thread support off, or add the headers |
| Works locally, fails after upload | The editor's test server sends headers your host doesn't | Test on the real host; ship no-threads |
| Opening `index.html` from disk fails | Browsers block WebAssembly from `file://` | Serve over HTTP, even locally |
| Game looks flat or dark compared to desktop | Compatibility renderer drops advanced lighting | Bake lightmaps; design for Compatibility (see **rendering-pipeline**) |
| No sound until the second click | Autoplay policy | Click-to-play screen before the first sound |
| Reverb/filters missing | Sample playback ignores bus effects | Accept it, or use Stream playback for that project |
| Saves gone next visit | Private window or new origin | Warn via `is_userfs_persistent()`; offer save export |
| HTTP requests fail only in the browser | CORS or mixed content | Fix server headers; HTTPS/WSS only (see **web-services**) |
| `request_fullscreen` / mouse capture ignored | Not called from an input event | Trigger it from a button press |
| Web export fails with "not supported in Godot 4 when using C#/.NET" | .NET editor builds cannot target Web | Port to GDScript, or export a GDScript-only project from the standard editor |
---
## 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
Files in this package (3)
- SKILL.md 13 KB
- references/hosting.md 4 KB
- references/javascript-bridge.md 5 KB
Versions
The database has no other skills named web-export.
Database snapshot: 13.11.2026 · package version f61dc5ecf841 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100godot-export
Export and build a Godot 4.7 project for distribution: install export templates, define export presets (Windows/macOS/Linux/Web/Android), run headless command-line exports for CI, and handle web (HTML5) COOP/COEP and dedicated-server/headless builds. Use when exporting a Godot… - 100game-web-publish
Ships a browser game: hardens the build (size budgets, compression, COOP/COEP headers) and publishes to itch.io, Poki, CrazyGames, YouTube Playables, Discord Activities, PWA or desktop wrappers, with per-platform AI disclosure. Use for "publish my web game", "upload to itch",… - 100scenario-godot-performance-export
Use when a Godot game stutters, drops frames, hitches when entering new areas, overheats a phone, or must ship: profiling and Performance monitors, CPU or GPU bound, draw calls, MultiMesh, occlusion culling, LOD, shader compilation hitches, export to macOS, Windows, Linux,… - 100godot-platform-web
Expert blueprint for web/browser platforms (HTML5 export) covering WebGL/WebGPU rendering, custom loading screens, JavaScriptBridge integration, LocalStorage saves, and size optimization. Use when exporting to web or implementing browser-specific features. Keywords web, HTML5,… - 90godot-web
Build and export Godot 4 web games on this VM. Use when the user asks for a Godot game, GDScript logic, or a playable web export. Owns the headless export workflow, project layout, and preview handoff. - 90scenario-unity-web
Use when a Unity 6.3 game must run in a browser: 'export to WebGL', Web build settings or Build Profiles, gzip or Brotli, Decompression Fallback, server headers, 'Unable to parse .framework.js.br', build too big or slow to load, itch.io, CrazyGames or Poki limits, Addressables…