Web Export¶
The client is pure GDScript on top of WebSocketPeer. Browser exports run
it with no native code and no extra build steps.
Scheme rules¶
- Use
wss://in production. - Dialing
ws://from a secure page fails loudly withERR_INVALID_PARAMETERbefore any dial, and browsers themselves block insecurews://dials to non-loopback hosts from HTTPS pages. The client never silently downgrades. The staticinsecure_scheme_error(url, is_web_platform, secure_page)predial check produces this error.
Authentication¶
Browsers cannot set WebSocket handshake headers, so authentication happens
after the socket opens. connect_to_server() auto-sends Authenticate on
open. No Authorization header is involved anywhere in the flow.
Polling¶
The client is single-threaded and non-blocking. poll() drains the socket
from _process (or from your own loop) and never blocks, which fits the
browser's single-threaded runtime.
Sends during close¶
A send can return FAILED while the browser starts closing and Godot still
reports an open socket. Stop sending after a refusal and keep polling. The
transport waits up to one second for the browser close callback, drains queued
packets, and reports disconnected(code, reason). If no close arrives, it
reports the original send failure once. Further sends return ERR_UNCONFIGURED
during this wait. Check every send result; a refused frame was not queued.
Authentication and reconnect handshake refusals preserve this wait and use
the client's close watchdog.
The Web engine also has a finite receive queue. A delayed Godot 4.7.2 relay control dropped reliable packets after restart when this queue filled (#488). The SDK cannot recover packets discarded inside the engine. See the delayed relay controls for the retained failure and separate local credit comparison.
Origin¶
Origin is a server-side policy. The browser sets it; the client cannot.
Allow-list your hosting origins on the server.
Storage¶
Treat browser localStorage and query strings as user-visible. Keep
reconnection tokens in memory. Persist them only with an explicit,
documented decision, and never log them.
Checklist automation¶
The browser checklist runs automatically in the weekly Web Export Smoke
workflow: the exported demo boots in headless Chromium over local HTTPS,
dials a local wss:// server (the browser-set Origin is asserted server
side), round-trips Authenticate/Ping, and dials ws:// from the secure
page, which the client refuses before any network traffic (the predial
check; loopback hosts are exempt from browser mixed-content blocking, so
that browser-level block only applies to production hosts). No manual
steps remain for the standard build.
Before shipping to production, still verify the host-specific items:
- Your HTTPS certificate is trusted by players' browsers.
- Your server accepts your page's
Origin.
Export preset and CI¶
The demo project ships a "Web" export preset that builds the demo straight
to a browser build. The preset exports all project resources (dev trees
excluded): scene-only exports do not follow preload() chains in scripts,
which left addon scripts out of the pack and broke the page at boot.
CI runs the scheduled web-export smoke: it imports the project, exports the
preset, asserts that the build produces index.html and index.wasm, and
runs the automated browser checklist above.