Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Exportieren für das Web¶

Siehe auch

Diese Seite beschreibt, wie man ein Godot-Projekt nach HTML5 exportiert. Wenn Sie stattdessen Editor- oder Exportvorlagen-Binärdateien aus dem Quellcode kompilieren möchten, lesen Sie Kompilieren für das Web.

Der HTML5-Export ermöglicht die Veröffentlichung von Spielen im Browser, die in der Godot Engine erstellt wurden. Dies erfordert Unterstützung für WebAssembly, WebGL und SharedArrayBuffer im Browser des Benutzers.

Achtung

Projekte, die in C# mit Godot 4 geschrieben wurden, können derzeit nicht ins Web exportiert werden. Für die Verwendung von C# auf Web-Plattformen sollten Sie stattdessen Godot 3 verwenden.

Tipp

Verwenden Sie die in den Browser integrierte Entwicklerkonsole, die normalerweise mit F12 (Cmd + Option + I unter macOS) geöffnet wird, um Debug-Informationen wie JavaScript-, Engine- und WebGL-Fehler anzuzeigen.

Achtung

Die HTML5-Exporte von Godot 4 können derzeit aufgrund von Upstream-Fehlern mit SharedArrayBuffer und WebGL 2.0 nicht auf macOS und iOS ausgeführt werden. Wir empfehlen, stattdessen die nativen Exportfunktionen macOS und iOS zu verwenden, da diese auch eine bessere Performance bieten.

Die HTML5-Exporte von Godot 3 sind im Allgemeinen besser mit verschiedenen Browsern kompatibel, insbesondere bei Verwendung des GLES2-Rendering-Backends (das nur WebGL 1.0 erfordert).

WebGL-Version¶

Godot 4.0 und spätere Versionen können nur WebGL 2.0 (unter Verwendung der Kompatibilitäts-Rendering-Methode) ansteuern. Es gibt noch keine stabile Möglichkeit, Vulkan-Anwendungen im Web auszuführen.

Eine Liste der Browser-Versionen, die WebGL 2.0 unterstützen, finden Sie unter Kann ich WebGL 2.0 verwenden. Beachten Sie, dass Safari einige Probleme mit der Unterstützung von WebGL 2.0 hat, die andere Browser nicht haben. Wir empfehlen daher, wenn möglich einen Chromium-basierten Browser oder Firefox zu verwenden.

Exportoptionen¶

Wenn eine ausführbare Web-Exportvorlage verfügbar ist, wird im Editor ein Button zwischen den Buttons Szene stoppen und Bearbeitete Szene abspielen angezeigt, um das Spiel schnell im Default-Browser zum Testen zu öffnen.

Wenn Sie VRAM-Komprimierung verwenden wollen, stellen Sie sicher, dass Vram-Texturkompression für die Target-Plattformen aktiviert ist (wenn Sie sowohl Für Desktop als auch Für Mobile aktivieren, wird der Export größer, aber kompatibler).

Wenn man einen Pfad zu einer benutzerdefinierten HTML-Shell-Datei angibt, wird dieser anstelle der Standard-HTML-Seite verwendet. Siehe Eigene HTML Seiten für Web Export.

Head Include wird an das Element <head> der generierten HTML-Seite angehängt. Auf diese Weise können Sie beispielsweise Webfonts und JavaScript-APIs von Drittanbietern laden, CSS hinzufügen oder JavaScript-Code ausführen.

Wichtig

Jedes Projekt muss seine eigene HTML-Datei generieren. Beim Export werden einige Textplatzhalter in der generierten HTML-Datei speziell für die gegebenen Exportoptionen ersetzt. Alle direkten Änderungen an dieser HTML-Datei gehen bei zukünftigen Exporten verloren. Um die generierte Datei anzupassen, verwenden Sie die Option Custom HTML shell.

Einschränkungen¶

Aus Sicherheits- und Datenschutzgründen sind viele Funktionen, die auf nativen Plattformen mühelos funktionieren, auf der Webplattform komplizierter. Im Folgenden finden Sie eine Liste der Einschränkungen, die Sie beim Portieren eines Godot-Spiels ins Web beachten sollten.

Wichtig

Browser-Hersteller stellen immer mehr Funktionen nur in sicheren Kontexten zur Verfügung, d.h. solche Funktionen sind nur verfügbar, wenn die Webseite über eine sichere HTTPS-Verbindung bedient wird (localhost ist in der Regel von dieser Anforderung ausgenommen).

Verwenden von Cookies für die Datenbeständigkeit¶

Benutzer müssen Cookies (insbesondere IndexedDB) zulassen, wenn die Beständigkeit des user://-Dateisystems gewünscht ist. Beim Spielen eines Spiels, das in einem iframe präsentiert wird, müssen Cookies von Drittanbietern ebenfalls zugelassen werden. Der Inkognito/Private-Browsing-Modus verhindert ebenfalls die Beständigkeit.

Die Methode OS.is_userfs_persistent() kann verwendet werden um zu überprüfen, ob das user: //-Dateisystem nutzbar ist, kann aber in einigen Fällen Falsch-Positive liefern.

Hintergrundverarbeitung¶

Das Projekt wird vom Browser pausiert, wenn der Tab nicht mehr der aktive Tab im Browser des Benutzers ist. Das bedeutet, daß Funktionen wie _process() und _physics_process() nicht mehr ausgeführt werden, bis der Tab vom Benutzer wieder aktiv gemacht wird (durch Zurückschalten auf den Tab). Dies kann dazu führen, daß Netzwerkspiele die Verbindung unterbrechen, wenn der Benutzer für längere Zeit die Tabs wechselt.

Diese Einschränkung gilt nicht für nicht fokussierte Browser-Fenster. Auf der Benutzerseite kann dies daher umgangen werden, indem das Projekt in einem separaten Fenster statt in einem separaten Tab ausgeführt wird.

Aufnahme des gesamten Bildschirms und der Maus¶

Die Browser erlauben es nicht, willkürlich den Vollbildmodus zu aktivieren. Dasselbe gilt für das Erfassen des Cursors. Stattdessen müssen diese Aktionen als Antwort auf ein JavaScript-Eingabeereignis erfolgen. In Godot bedeutet dies, den Vollbildmodus aus einem gedrückten Eingabe-Ereignis-Callback wie _input oder _unhandled_input. Die Abfrage des Input-Singletons reicht nicht aus, das entsprechende Eingabeereignis muss aktuell aktiv sein.

Aus dem gleichen Grund funktioniert die Vollbild-Projekteinstellung nur, wenn die Engine in einem gültigen Eingabe-Event-Handler gestartet wird. Dies erfordert eine Anpassung der HTML-Seite.

Audio¶

Einige Browser schränken die automatische Wiedergabe von Audio auf Websites ein. Die einfachste Möglichkeit, diese Einschränkung zu umgehen, besteht darin, den Spieler aufzufordern, einen Button anzuklicken, zu berühren oder eine Taste zu drücken, um den Ton zu aktivieren, z.B. wenn ein Startbildschirm zu Beginn des Spiels angezeigt wird.

Siehe auch

Google bietet zusätzliche Informationen zu den Richtlinien für die automatische Wiedergabe von Web-Audio.

Das Safari-Team von Apple hat außerdem zusätzliche Informationen über die Änderungen der Auto-Play-Richtlinie für macOS veröffentlicht.

Warnung

Der Zugriff auf das Mikrofon erfordert einen sicheren Kontext.

Netzwerkfunktionen¶

Low-Level-Networking ist aufgrund mangelnder Unterstützung in Browsern nicht implementiert.

Derzeit werden nur HTTP-Client, HTTP-Anfragen, WebSocket (Client) und WebRTC unterstützt.

Die HTTP-Klassen haben verschiedene Einschränkungen für die HTML5-Plattform:

Der Zugriff auf den StreamPeer ist nicht möglich

Threaded/Blocking-Modus ist nicht verfügbar

Der Fortschritt kann nicht mehr als einmal pro Frame ausgeführt werden, sodass Polling in einer Schleife zum Einfrieren führt

Keine Chunked Responses

Die Host-Verifizierung kann nicht deaktiviert werden

Vorbehaltlich der same-origin policy

Zwischenablage¶

Die Synchronisierung der Zwischenablage zwischen der Engine und dem Betriebssystem erfordert einen Browser, der die Clipboard-API unterstützt, außerdem kann es aufgrund der asynchronen Natur der API sein, dass der Zugriff von GDScript aus nicht zuverlässig ist.

Warnung

Erfordert einen sicheren Kontext.

Gamepads¶

Gamepads werden nicht erkannt, bis eine ihrer Tasten gedrückt wird. Gamepads können je nach Browser/OS/Gamepad-Kombination eine falsche Zuordnung haben. Leider bietet die Gamepad-API aus Datenschutzgründen keine zuverlässige Möglichkeit, die Gamepad-Informationen zu erkennen, die für eine Neuzuordnung auf Basis von Modell/Hersteller/OS erforderlich sind.

Warnung

Erfordert einen sicheren Kontext.

Boot-Splash wird nicht angezeigt¶

Auf der Default-HTML-Seite wird beim Laden kein Boot Splash angezeigt. Das Bild wird jedoch als PNG-Datei exportiert, sodass benutzerdefinierte HTML-Seiten es anzeigen können.

Dateien bereitstellen¶

Beim Exportieren für das Web werden mehrere Dateien erzeugt, die von einem Webserver bereitgestellt werden, einschließlich einer Standard-HTML-Seite für die Präsentation. Eine benutzerdefinierte HTML-Datei kann verwendet werden, siehe Eigene HTML Seiten für Web Export.

Warnung

Um eine niedrige Audio-Latenz und die Fähigkeit zur Verwendung von Thread in Web-Exporten zu gewährleisten, verwenden Godot 4-Web-Exporte immer SharedArrayBuffer. Dies erfordert einen sicheren Kontext, wobei auch die folgenden CORS-Header beim Servieren der Dateien gesetzt werden müssen:

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

Wenn Sie keine Kontrolle über den Webserver haben oder nicht in der Lage sind, Response-Header hinzuzufügen, verwenden Sie coi-serviceworker als Workaround.

Wenn der Client die erforderlichen Antwort-Header nicht erhält, wird das Projekt nicht ausgeführt.

Die erzeugte .html-Datei kann als DirectoryIndex in Apache-Servern verwendet werden und kann jederzeit in z.B. index.html umbenannt werden. Auf ihren Namen wird standardmäßig nie zurückgegriffen.

Die HTML-Seite zeichnet das Spiel in maximaler Größe innerhalb des Browserfensters. Auf diese Weise kann sie in einen <iframe> mit der Größe des Spiels eingefügt werden, wie es auf den meisten Web-Spiele-Hosting-Seiten üblich ist.

Die anderen exportierten Dateien werden so, wie sie sind, neben der .html-Datei, mit unveränderten Namen, bereitgestellt. Die .wasm-Datei ist ein binäres WebAssembly-Modul, das die Engine implementiert. Die .pck Datei ist das Godot-Hauptpaket, das Ihr Spiel enthält. Die .js Datei enthält den Startcode und wird von der .html-Datei benutzt, um auf die Engine zuzugreifen. Die .png-Datei enthält das Boot-Splash-Bild. Es wird nicht in der Standard-HTML-Seite verwendet, ist aber für eigene HTML Seiten enthalten.

Die .pck-Datei ist binär und wird normalerweise mit dem MIME-Typ application/octet-stream geliefert. Die Datei .wasm wird als application/wasm geliefert.

Warnung

Die Auslieferung des WebAssembly-Moduls (.wasm) mit einem anderen MIME-Typ als application/wasm kann einige Start-Optimierungen verhindern.

Die Auslieferung der Dateien mit serverseitiger Komprimierung wird insbesondere für die Dateien .pck und .wasm empfohlen, die in der Regel sehr groß sind. Das WebAssembly-Modul lässt sich besonders gut komprimieren, mit gzip-Komprimierung auf etwa ein Viertel der ursprünglichen Größe. Ziehen Sie die Verwendung der Brotli-Vorkomprimierung in Erwägung, falls Ihr Webserver diese unterstützt, um die Dateigröße weiter zu verringern.

Hosts, die on-the-fly Komprimierung anbieten: GitHub Pages (gzip)

Hosts, die keine on-the-fly-Komprimierung anbieten: itch.io, GitLab Pages (unterstützt manuelle gzip-Vorkomprimierung)

Tipp

Das Godot-Repository enthält ein Python-Skript zum Hosten eines lokalen Webservers. Dieses Skript ist für den Test des Webeditors gedacht, kann aber auch zum Testen exportierter Projekte verwendet werden.

Speichern Sie das verlinkte Skript in eine Datei mit dem Namen serve.py, verschieben Sie diese Datei in den Ordner, der die index.html des exportierten Projekts enthält, und führen Sie dann den folgenden Befehl in einer Eingabeaufforderung im selben Ordner aus:

# You may need to replace `python` with `python3` on some platforms.
python serve.py --root .

Unter Windows können Sie eine Eingabeaufforderung im aktuellen Ordner öffnen, indem Sie bei gedrückter Umschalt-Taste mit der rechten Maustaste auf einen leeren Bereich im Windows Explorer klicken und dann PowerShell-Fenster hier öffnen wählen.

Dadurch wird der Inhalt des aktuellen Ordners angezeigt und der Default-Webbrowser automatisch geöffnet.

Beachten Sie, dass dieser auf Python basierende Webserver nicht für Produktionszwecke verwendet werden sollte. Stattdessen sollten Sie einen etablierten Webserver wie Apache oder nginx verwenden.

Aufruf von JavaScript aus dem Skript¶

In Web-Builds ist das Singleton JavaScriptBridge implementiert. Es bietet eine einzige Methode namens eval, die ähnlich wie die gleichnamige JavaScript-Funktion funktioniert. Sie nimmt einen String als Argument und führt ihn als JavaScript-Code aus. Dies ermöglicht die Interaktion mit dem Browser auf eine Art und Weise, die mit in Godot integrierten Skriptsprachen nicht möglich ist.

func my_func():
    JavaScriptBridge.eval("alert('Calling JavaScript per GDScript!');")

private void MyFunc()
{
    JavaScriptBridge.Eval("alert('Calling JavaScript per C#!');")
}

Der Wert der letzten JavaScript-Anweisung wird in einen GDScript-Wert konvertiert und unter bestimmten Umständen von eval() zurückgegeben:

JavaScript number wird als float zurückgegeben

JavaScript boolean wird als bool zurückgegeben

JavaScript string wird als String zurückgegeben

JavaScript ArrayBuffer, TypedArray und DataView werden als PackedByteArray zurückgegeben

func my_func2():
    var js_return = JavaScriptBridge.eval("var myNumber = 1; myNumber + 2;")
    print(js_return) # prints '3.0'

private void MyFunc2()
{
    var jsReturn = JavaScriptBridge.Eval("var myNumber = 1; myNumber + 2;");
    GD.Print(jsReturn); // prints '3.0'
}

Jeder andere JavaScript-Wert wird zurückgegeben als null.

HTML5-Exportvorlagen können gebaut werden ohne Unterstützung für das Singleton, um die Sicherheit zu verbessern. Mit solchen Vorlagen und auf anderen Plattformen als HTML5 wird der Aufruf von JavaScriptBridge.eval ebenfalls null zurückgeben. Die Verfügbarkeit des Singletons kann mit dem web feature tag überprüft werden:

func my_func3():
    if OS.has_feature('web'):
        JavaScriptBridge.eval("""
            console.log('The JavaScriptBridge singleton is available')
        """)
    else:
        print("The JavaScriptBridge singleton is NOT available")

private void MyFunc3()
{
    if (OS.HasFeature("web"))
    {
        JavaScriptBridge.Eval("console.log('The JavaScriptBridge singleton is available')");
    }
    else
    {
        GD.Print("The JavaScriptBridge singleton is NOT available");
    }
}

Tipp

Die mehrzeiligen Strings von GDScript, umgeben von 3 Anführungszeichen """ wie in my_func3() oben, sind nützlich, um JavaScript-Code lesbar zu halten.

Die Methode eval akzeptiert auch ein zweites, optionales boolesches Argument, das angibt, ob der Code im globalen Ausführungskontext ausgeführt werden soll. Die Voreinstellung ist false, um den globalen Namespace nicht zu vermüllen:

func my_func4():
    # execute in global execution context,
    # thus adding a new JavaScript global variable `SomeGlobal`
    JavaScriptBridge.eval("var SomeGlobal = {};", true)

private void MyFunc4()
{
    // execute in global execution context,
    // thus adding a new JavaScript global variable `SomeGlobal`
    JavaScriptBridge.Eval("var SomeGlobal = {};", true);
}

Umgebungsvariablen¶

Sie können die folgenden Umgebungsvariablen verwenden, um Exportoptionen außerhalb des Editors festzulegen. Während des Exportvorgangs überschreiben diese die Werte, die Sie im Exportmenü festgelegt haben.

HTML5-Export-Umgebungsvariablen¶
Export-Option	Umgebungsvariable
Verschlüsselung / Verschlüsselungsschlüssel	`GODOT_SCRIPT_ENCRYPTION_KEY`