Godot-4-Spiel fürs Web exportieren (HTML5 und itch.io)

Godot exportiert Spiele als HTML5 und WebAssembly fürs Web. Dein Spiel läuft also in einem Browser-Tab, ohne Download und ohne Plugin. Das ist der schnellste Weg, jemandem einen spielbaren Build zu zeigen. Du teilst einen Link, die Person klickt und spielt.

„Fürs Web exportieren“ sind zwei Aufgaben, nicht eine. Die Dateien zu erzeugen dauert etwa eine Minute. Diese Dateien im Browser zum Laufen zu bringen ist der Punkt, an dem viele vor einem schwarzen Bildschirm stehen, meist wegen der Art, wie die Dateien ausgeliefert werden, oder weil eine Export-Option still und leise eine Anforderung eingeschaltet hat, die das Hosting nicht erfüllen kann. Diese Anleitung behandelt beide Hälften, die genauen Einstellungen und die Fehler hinter den meisten gescheiterten Exports.

Sie gilt für Godot 4.3 und neuer. Ältere 4.x-Versionen haben immer einen Build mit Threads verwendet. Wenn du also noch auf 4.0, 4.1 oder 4.2 bist, lies den Abschnitt über die Header genau oder aktualisiere den Editor.

{/* IMAGE: The Godot Export dialog open with a Web preset selected, the Export Project button highlighted. 1200x675 editor screenshot. */}

Was ein „Web-Export“ wirklich erzeugt

Beim Export erstellt Godot keine einzelne Datei. Es schreibt einen kleinen Ordner mit statischen Dateien.

• index.html ist die Seite, die alles lädt. Diese Datei öffnet der Browser.
• Eine .wasm-Datei ist die Godot-Engine selbst, kompiliert zu WebAssembly. Das ist das größte Stück.
• Eine .pck-Datei enthält deine Spieldaten, also Szenen, Skripte und Assets, zusammengepackt.
• Eine .js-Datei ist der Loader, der die Engine mit der Seite verbindet.
• Manchmal eine .audio.worklet.js und bei Builds mit Threads zusätzliche Worker-Dateien.

Alle diese Dateien müssen zusammen liegen und über HTTP ausgeliefert werden. Du kannst nicht auf die index.html doppelklicken und erwarten, dass sie läuft, und genau daran scheitern viele als Erstes.

Schritt 1. Export-Templates installieren

Godot liefert den Editor und die Export-Templates getrennt aus. Die Templates sind die vorkompilierten Engine-Binärdateien für jede Plattform, einschließlich des WebAssembly-Builds für den Browser. Eine frische Installation hat sie nicht.

Geh zu Editor und dann Manage Export Templates (Export-Templates verwalten) und klicke auf Download and Install. Damit lädst du die Templates für deine genaue Engine-Version.

Die Templates müssen exakt zu deiner Editor-Version passen. Ein 4.4-Editor kann nicht mit 4.3-Templates exportieren, und umgekehrt genauso wenig. So ein Versionskonflikt ist eine der häufigsten Ursachen für einen kaputten Web-Build. Installiere die Templates nach jedem Editor-Update neu.

Schritt 2. Ein Web-Export-Preset hinzufügen

Öffne Project und dann Export. Klicke auf Add und wähle Web.

Die Standardwerte sind vernünftig. Drei Gruppen von Optionen sind fürs Web wichtig.

• Variant, Thread Support. Seit Godot 4.3 standardmäßig aus. Lass es aus, solange du keinen echten Bedarf an Threads gemessen hast. Ein Single-Thread-Build läuft auf jedem statischen Host und in iframes auf Spieleportalen. Wenn du die Option einschaltest, brauchst du die beiden Cross-Origin-Header aus Schritt 4.
• Variant, Extensions Support. Nur nötig, wenn dein Projekt GDExtension verwendet. Auch diese Option braucht die Cross-Origin-Header, und jede native Extension braucht einen eigenen Web-Build.
• VRAM Texture Compression. „For Desktop“ ist standardmäßig an und „For Mobile“ aus. Wenn du beides aktivierst, wird der Export größer, aber kompatibler. Das ist wichtig, wenn du Spieler auf dem Handy erwartest, weil Handys die Desktop-Texturformate in der Regel nicht unterstützen.

Lass Head Include und die eigene HTML-Shell leer, außer du hast einen Grund, sie zu ändern. Die Standard-Shell kümmert sich um das Laden und den Fortschrittsbalken.

Schritt 3. Das Projekt exportieren

Wähle einen Zielordner. Lege einen leeren Ordner mit einem Namen wie web-build an, damit sich die Ausgabedateien nicht mit anderen Dateien vermischen.

Nenne die Hauptdatei index.html, nicht wie dein Spiel. Die meisten Hosts, auch itch.io, suchen nach einer index.html als Einstiegspunkt. Wenn du sie mygame.html nennst, findet der Host sie nicht.

Klicke auf Export Project. Nach wenigen Sekunden liegen die oben genannten Dateien im Ordner.

{/* IMAGE: A file explorer showing the exported web-build folder contents: index.html, .wasm, .pck, .js files. 1000x500. */}

Schritt 4. Wann du die Cross-Origin-Header brauchst

Die meisten älteren Tutorials sagen, dass jeder Godot 4 Web-Build spezielle Header braucht. Das stimmte vor 4.3. Heute hängt es von zwei Checkboxen ab.

Ein Build mit aktiviertem Thread Support oder Extensions Support verwendet SharedArrayBuffer, und Browser erlauben das nur, wenn die Seite mit diesen beiden Response-Headern ausgeliefert wird.

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

Ohne sie kann die Engine nicht starten, und die Konsole zeigt einen Fehler, der SharedArrayBuffer oder crossOriginIsolated erwähnt. Diese Header setzt du nicht in Godot. Du setzt sie dort, wo die Dateien ausgeliefert werden.

Ein Build mit beiden Optionen aus, also der Standard, braucht keinen der beiden Header. Deshalb ist der Single-Thread-Export die richtige Wahl für itch.io, Spieleportale und einfaches statisches Hosting. Threads können die Performance in aufwendigen Spielen verbessern, kosten dich aber Flexibilität beim Hosting und Kompatibilität beim Einbetten.

Schritt 5. Vor dem Hochladen lokal testen

Debugge einen Web-Export nie, indem du hochlädst und neu lädst. Teste zuerst auf deinem eigenen Rechner.

Am schnellsten geht das mit dem One-Click-Deploy des Editors. Sobald ein Web-Preset existiert, erscheint oben rechts im Editor ein Browser-Symbol. Ein Klick darauf startet einen lokalen Webserver, exportiert das Projekt und öffnet es in deinem Standardbrowser. Dieser Server sendet die Cross-Origin-Header, also laufen dort auch Builds mit Threads.

Für einen Build, den du schon exportiert hast, funktioniert jeder lokale Server, solange Thread Support und Extensions Support aus sind. Wenn Python installiert ist, führe im Ordner web-build den Befehl python -m http.server 8000 aus und öffne http://localhost:8000.

Einen Build mit Threads lieferst du mit beiden Headern aus. Speichere Folgendes als serve.py im Ordner.

import http.server, socketserver

class Handler(http.server.SimpleHTTPRequestHandler):
    def end_headers(self):
        self.send_header("Cross-Origin-Opener-Policy", "same-origin")
        self.send_header("Cross-Origin-Embedder-Policy", "require-corp")
        super().end_headers()

with socketserver.TCPServer(("", 8000), Handler) as httpd:
    print("Serving on http://localhost:8000")
    httpd.serve_forever()

Führe python serve.py aus und öffne http://localhost:8000. Wenn das Spiel hier lädt, ist der Export korrekt, und jedes verbleibende Problem liegt an der Konfiguration des Hosts.

Schritt 6. Das Spiel hosten

itch.io (am einfachsten, kostenlos)

Das ist der empfohlene Weg zum Teilen und für Game Jams.

1. Packe den Inhalt des Ordners web-build als ZIP, nicht den übergeordneten Ordner, damit die index.html auf der obersten Ebene der ZIP-Datei liegt.
2. Erstelle auf itch.io ein neues Projekt und setze Kind of project (Art des Projekts) auf HTML.
3. Lade die ZIP-Datei hoch und aktiviere This file will be played in the browser (diese Datei wird im Browser gespielt).
4. Stelle in den Einbettungsoptionen eine Viewport-Größe ein, die zur Auflösung deines Spiels passt.

itch.io akzeptiert bis zu 500 MB entpackten Inhalt, 200 MB für eine einzelne Datei und 1.000 Dateien. Ein Single-Thread-Build braucht sonst nichts. Für einen Build mit Threads bietet itch.io in den Optionen des Einbettungsrahmens die Checkbox SharedArrayBuffer support an. Sie ist als experimentelle Funktion angekündigt, die Teile der Seite kaputt machen kann, also teste die veröffentlichte Seite in mehr als einem Browser.

Netlify, Vercel, GitHub Pages oder dein eigener Server

Ein Single-Thread-Build läuft unverändert auf jedem statischen Host, auch auf einfachem GitHub Pages. Achte darauf, dass der Server .wasm-Dateien mit dem Content-Type application/wasm ausliefert und komprimiert, denn WebAssembly schrumpft mit gzip auf etwa ein Viertel seiner Größe.

Für einen Build mit Threads muss der Host die beiden Header senden. Lege bei Netlify eine Datei _headers im Deploy-Stammverzeichnis an.

/*
  Cross-Origin-Opener-Policy: same-origin
  Cross-Origin-Embedder-Policy: require-corp

Bei Vercel setzt du dieselben beiden Header in vercel.json unter einer headers-Regel. Bei nginx oder Apache fügst du sie dem location-Block hinzu. GitHub Pages kann keine eigenen Header senden, deshalb brauchen Builds mit Threads dort einen Service Worker als Workaround, etwa coi-serviceworker, den nicht jeder Browser respektiert. Wenn du keine Threads brauchst, ist die einfachere Lösung, Thread Support auszuschalten.

Schwarzer Bildschirm, die Checkliste

Wenn du eine schwarze Canvas siehst, öffne die Entwicklerkonsole des Browsers (drücke F12, dann den Tab Console) und lies den ersten roten Fehler. Geh diese Punkte der Reihe nach durch.

1. Hast du die Datei direkt geöffnet? Wenn die URL mit file:// beginnt, liefere das Spiel stattdessen über HTTP aus.
2. Steht SharedArrayBuffer oder crossOriginIsolated im Fehler? Thread Support oder Extensions Support ist aktiviert, und der Host sendet die Header nicht. Schalte beide Optionen aus und exportiere neu, oder ergänze die Header beim Host.
3. Erwähnt der Fehler eine Version oder ein Template, das nicht geladen werden konnte? Deine Export-Templates passen nicht zu deiner Editor-Version. Installiere sie in Manage Export Templates neu.
4. Ist es ein C#-Projekt? Godot 4 kann C#-Projekte nicht fürs Web exportieren. Der Web-Build braucht ein GDScript-Projekt.
5. Wird die .wasm-Datei mit dem falschen Typ ausgeliefert? Manche Hosts senden sie als generischen Download. Setze den Content-Type application/wasm.

Die meisten gescheiterten Web-Exports sind einer dieser fünf Fälle.

Was im Browser anders ist

Ein Web-Build ist keine Desktop-Version mit URL. Einige Dinge verhalten sich anders.

• Spielstände landen in der IndexedDB des Browsers, nicht in einem Ordner auf der Festplatte, und Spieler müssen den Website-Speicher erlauben, damit sie erhalten bleiben. In einem iframe auf einem Portal kann das Drittanbieter-Speicher erfordern, also teste das Speichern auf dem Host, den du verwenden willst.
• Audio startet erst, nachdem der Spieler klickt, tippt oder eine Taste drückt, weil Browser Autoplay blockieren. Ein „Klicken zum Starten“-Bildschirm löst das.
• Native Plugins (für den Desktop kompilierte GDExtension-Bibliotheken) laden nicht, außer sie bringen einen Web-Build mit und Extensions Support ist aktiviert.
• C# lässt sich in Godot 4 nicht fürs Web exportieren.
• Rendering läuft im Web über den Compatibility-Renderer (WebGL 2). Ein Projekt, das mit Forward+ oder Mobile erstellt wurde, sieht deshalb anders aus. Effekte wie SDFGI, volumetrischer Nebel und Screen-Space-Reflexionen werden nicht gerendert. Baue Spiele, die fürs Web gedacht sind, von Anfang an im Compatibility-Renderer, damit du im Editor siehst, was am Ende ausgeliefert wird. Summers eigenes Web-Template ist anders, denn es nutzt WebGPU mit Forward+ oder Mobile.
• Die Ladegröße zählt mehr als überall sonst. Der Spieler lädt die Engine, das Datenpaket und jedes Asset herunter, bevor das Spiel startet. Laut dem Entwicklerleitfaden von Poki springen Spieler meist ab, wenn das Laden länger als zehn Sekunden dauert, also halte den ersten Download klein.

Summer Engine und Web-Export

Summer Engine ist eine Desktop-Engine für macOS und Windows, die die Workflows von Godot 4 beibehält, mit einer KI, die Szenen, Skripte und Assets aus normaler Sprache erstellt. Sie erstellt Desktop-Versionen deines Spiels, die du auf Steam verkaufen oder als Download auf itch.io hochladen kannst, und exportiert auch Web-Builds.

Seit Engine 0.7 liefert der Editor Summers eigenes Web-Export-Template mit, das WebGPU mit dem Forward+- oder Mobile-Renderer nutzt. Der Web-Export funktioniert für GDScript-Projekte. Projekte mit C# können nicht fürs Web exportiert werden, dieselbe Einschränkung wie in Godot 4. Der Web-Build ist eine normale statische .zip-Datei mit index.html im Hauptverzeichnis. Du veröffentlichst ihn auf Summer Games, wo man ihn im Browser spielt. Summer Games nimmt auch den oben beschriebenen Standard-Web-Export von Godot mit dem Compatibility-Renderer an. Agents erledigen beide Schritte mit den MCP-Tools summer_export_game (Ziel web) und danach summer_publish_build.

Wenn du heute ein Spiel in Summer anfangen willst, starte mit einem Template, in dem Bewegung und Kamera schon eingerichtet sind, beschreibe die Mechaniken, die du darauf aufbauen willst, und exportiere einen Build, sobald es sich gut spielt.