How to Ship Godot 4 HTML5 Demos Without a Blank Screen - MIME Types, Paths, and First Interactive Frame

You exported a Godot 4 project for the Web, uploaded the folder, opened the link, and stared at an empty rectangle. The editor preview worked. Locally opening index.html might have looked fine. On a real host, the canvas stays blank, the console fills with red, or the loader hangs at the first progress tick.

This tutorial gives you a fix order that matches how the Web export actually loads files so you can ship browser demos for jams, Steam Next Fest companion pages, or press builds without losing a day to hosting guesswork.

If you already went through our Godot 4.4+ Web export checklist, treat this article as the narrative companion with emphasis on blank-screen causes and first interactive frame verification.

What the browser is really waiting for

Godot’s Web build is a small shell (index.html plus JavaScript glue) that fetches WASM, optional worker scripts, and your PCK (or embedded data). If any request returns the wrong MIME type, gets blocked by cross-origin isolation, 404s because of path case, or dies on Caching, the runtime never reaches your first _ready() frame. The canvas can stay white forever even though nothing “looks” wrong in the Godot export log.

Your job is to line up four layers in order:

1. Correct files in the folder you upload
2. Correct URLs the HTML actually requests
3. Correct response headers and MIME types from the server
4. Host features that match your export options (threads on/off, GDExtension limits, etc.)

Fix 1 - Serve WASM and related files with the right MIME types

Static hosts usually get application/javascript right for .js. The usual blank-screen culprit is application/wasm for .wasm or a missing type for .pck or .godot sidecars, depending on version and packaging.

What to do

• After upload, open DevTools → Network, reload once with cache disabled, and inspect the row for your .wasm file. The response must not be text/html or application/octet-stream on strict browsers if your setup expects explicit WASM MIME handling.
• If you control the server (Apache, nginx, Cloudflare Workers, Netlify _headers, etc.), set types per your host docs. Community-run Godot games on GitHub Pages or small VPS often need one explicit rule added once, then everything works for every future upload.
• For shared hosts where you cannot set MIME types, consider moving to a platform that lets you set headers (or front your files with a CDN that does).

Verification

• WASM loads with status 200 and a non-HTML content type.
• The main .pck (or data package) also loads with 200, not 404.

Fix 2 - Paths, base href, and case sensitivity

Your index.html references scripts with paths relative to the URL you opened. If you deploy to https://example.com/games/demo/ but only upload files as if the site root were /, every relative path can 404.

What to do

• Mirror the same folder layout Godot exported. Do not rename index.html, the .wasm, or the .pck unless you know exactly what you are changing in the HTML and loader options.
• Remember Linux servers are case-sensitive. MyGame.pck and mygame.pck are different files. macOS and Windows exporters often hide that problem until deploy.
• If you use a router (SPA hosting) that sends unknown paths to index.html, exclude .wasm, .pck, .js, and worker scripts from that rewrite rule.

Verification

• Open Network tab and confirm every asset request is 200 with the expected filename spelling.
• No unexpected redirects from asset URLs back to HTML.

Fix 3 - Threads, SharedArrayBuffer, and the dreaded COOP or COEP errors

When threads are enabled in the Godot Web export, browsers require cross-origin isolation. If your host does not send compatible COOP and COEP headers, the runtime can fail early. Sometimes you see console errors mentioning SharedArrayBuffer. Sometimes you see nothing helpful and only a blank canvas.

What to do

• Decide deliberately whether you need threads for your demo. Vertical slices that do not benefit from them can ship without threads to cut hosting friction and simplify compatibility with cheap static hosts and older Safari versions.
• If you need threads, apply the header pattern your stack documents (often Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp or credentialless, depending on policy updates). Re-test after every CDN or caching layer change because edge configs often strip custom headers silently.
• Audit third-party scripts (analytics, chat widgets) that fight isolation. Sometimes a single injected script is enough to prevent a threaded build from booting.

This overlaps tightly with our Web export checklist after the 4.3 lessons—keep both tabs open while you iterate.

Verification

• With threads on, crossOriginIsolated should read true in the page context where Godot attaches (check in DevTools console).
• With threads off, you should not see SharedArrayBuffer requirement errors at all.

Fix 4 - First interactive frame and input focus

Some “blank screen” reports are really a running game with a black first frame or audio or input blocked until a user gesture. Other cases are the splash or boot sitting behind a fullscreen or pointer-lock policy.

What to do

• Give players something visible in frame one (even a slapped-on “Click to start” label drawn in your boot scene) so you can separate loading failures from rendering or input issues.
• Test audio unlocking on Chrome mobile and Safari. A silent first frame plus blocked audio callbacks can look like a freeze if your logic waits on audio before continuing.
• Avoid blocking the main thread during _ready() with synchronous downloads or huge parse loops. The Web run loop is less forgiving than desktop; move heavy init behind one frame or use async patterns Godot supports in your version.

Verification

• With DevTools performance recording, you see repaints after load completes.
• A tap or click produces expected input logs or HUD updates.

Fix 5 - Platform-specific notes (itch.io, GitHub Pages, Netlify)

itch.io is a common jam target. Project HTML5 can work beautifully, but you still need correct packaging and MIME behavior on the underlying CDN. If something fails only on itch, download the uploaded zip and compare hashes against your local export to ensure the upload did not strip files.

If you are comparing engines for the same jam brief, our Godot vs Unity mobile reality check is not Web-specific but helps set expectations when you also ship desktop builds from the same repo.

For GitHub Pages or Netlify, plan your branch and folder the static generator expects. Double pipelines that run a build step twice sometimes publish an empty dist.

Pro tips that save hours

• Always test from a clean hard refresh after the first successful load. Service workers, aggressive CDNs, and browser cache can hide the fact your latest PCK never shipped.
• Compare remote logs to local Project → Export → Run in Browser only after you understand that local preview may not enforce the same headers as production.
• Keep a one-page runbook for your team with exact upload steps. Jams love runbooks when Wi-Fi dies.
• When you move from demo to product, pair this with our Godot 4.4 HTML5 blank or huge export troubleshooting for template and compression issues that also show up as empty canvases.

FAQ

Why does my game work when I upload as ZIP to one host but not another?
Different default MIME maps, header injection, and rewrite rules. Trust the Network tab before you trust the UI.

Should I use threads for a tiny jam demo?
Only if you measured a need. Threads expand your hosting checklist and shrink the list of forgiving CDNs.

Can I fix everything only from Godot export settings?
You can fix paths, compression, and thread toggles. MIME and isolation require server or CDN cooperation.

Does a smaller PCK always help?
It improves download time but does not replace correct types and headers. Big PCK on a fast line still boots; small PCK with bad WASM type still fails.

Closing

Shipping Godot 4 HTML5 demos is less about “one magic checkbox” and more about proving each asset request succeeded before you argue with game code. Work top-down from MIME and paths, then isolation, then first-frame UX. Bookmark this flow for your next festival deadline, and share it with teammates who insist “it works on my machine” while the canvas stays white for players.

If you want a deeper Web stack angle beyond Godot, our JavaScript and HTML5 game tech overview pairs well when you are mixing engines or tools in the same repository.