Exportieren für das Web

Siehe auch

This page describes how to export a Godot project to HTML5. If you're looking to compile editor or export template binaries from source instead, read Kompilieren für das Web.

Der HTML5-Export ermöglicht die Veröffentlichung von in Godot Engine erstellten Spielen im Browser. Dies erfordert die Unterstützung von WebAssembly und WebGL im Browser des Benutzers.

Wichtig

Verwenden Sie die in den Browser integrierte Entwicklerkonsole, die normalerweise mit F12 geöffnet wird, um Debug-Informationen wie JavaScript-, Engine- und WebGL-Fehler anzuzeigen.

Achtung

Es gibt erhebliche Fehler beim Ausführen von HTML5-Projekten auf iOS (unabhängig vom Browser). Wir empfehlen stattdessen die Verwendung der iOS nativen Exportfunktionalität, da dies ebenfalls zu einer besseren Performance führt.

WebGL version

Je nach Wahl des Renderers kann Godot WebGL 1.0 (GLES2) oder WebGL 2.0 (GLES3) verwenden.

WebGL 1.0 ist die empfohlene Option, wenn man möchte, dass ein Projekt auf allen Browsern mit der besten Leistung unterstützt wird.

Der GLES3-Renderer von Godot zielt auf High-End-Geräte ab, und die Leistung mit WebGL 2.0 kann unterdurchschnittlich sein. Einige Funktionen werden auch nicht speziell in WebGL 2.0 unterstützt.

Während die meisten Browser WebGL 2.0 unterstützen, ist dies bei Safari noch nicht der Fall. WebGL 2.0-Unterstützung wird in Safari 15 für macOS kommen und ist noch für keinen iOS-Browser verfügbar (alle WebKit-basiert wie Safari). Siehe Can I use WebGL 2.0 für Details.

Exportoptionen

Wenn eine ausführbare Web-Exportvorlage verfügbar ist, wird im Editor eine Schaltfläche zwischen den Schaltflächen Szene stoppen und Bearbeitete Szene abspielen angezeigt, um das Spiel schnell im Standardbrowser zum Testen zu öffnen.

Sie können den Exporttyp wählen, um auszuwählen, welche Funktionen verfügbar sein sollen:

  • Regulär: ist am kompatibelsten mit allen Browsern, unterstützt keine Threads und kein GDNative.

  • Threads: setzt voraus, dass der Browser SharedArrayBuffer unterstützt. Für Einzelheiten sehen Sie sich Can I use SharedArrayBuffer <https://caniuse.com/sharedarraybuffer> an.

  • GDNative: Aktiviert die GDNative-Unterstützung, sorgt jedoch für eine größere Binärdatei und längere Ladezeiten.

Wenn Sie VRAM-Komprimierung verwenden möchten, stellen Sie sicher, dass Vram Texture Compression für die Zielplattformen aktiviert ist (wenn Sie sowohl Für Desktop als auch Für Mobile aktivieren, ergibt sich ein größerer, aber kompatiblerer Export).

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.

Warnung

Export types other than Regular are not yet supported by the C# version.

Limitierungen

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).

Tipp

Überprüfen Sie die Liste der offenen HTML5-Probleme auf GitHub, um zu sehen, ob die Funktionalität, an der Sie interessiert sind, schon ein Problem hat. Falls nicht, öffnen Sie eines, um Ihr Interesse mitzuteilen.

Verwenden von Cookies für die Datenbeständigkeit

Benutzer müssen Cookies zulassen (insbesondere IndexedDB) wenn das Dateisystems user: // gewünscht wird. Wenn Sie ein Spiel spielen, das in einem iframe präsentiert wird, müssen Cookies von Drittanbietern ebenfalls aktiviert sein. Der Inkognito bzw. Privat-Modus verhindert auch diese Datennutzung.

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

Background processing

The project will be paused by the browser when the tab is no longer the active tab in the user's browser. This means functions such as _process() and _physics_process() will no longer run until the tab is made active again by the user (by switching back to the tab). This can cause networked games to disconnect if the user switches tabs for a long duration.

This limitation does not apply to unfocused browser windows. Therefore, on the user's side, this can be worked around by running the project in a separate window instead of a separate tab.

Threads

Wie bereits erwähnt oben ist Multi-Threading nur verfügbar, wenn der entsprechende Export-Typ eingestellt ist, jedoch ist die Unterstützung dafür in manchen Browsern noch begrenzt.

Warnung

Requires a secure context. Browsers also require that the web page is served with specific cross-origin isolation headers.

GDNativ

Wie bereits :ref:`oben <doc_javascript_export_options>`erwähnt, ist GDNative nur verfügbar, wenn der entsprechende Exporttyp gesetzt ist.

Der Export kopiert auch die benötigten GDNative .wasm-Dateien in den Ausgabeordner (und muss zusammen mit dem Spiel auf Ihren Server hochgeladen werden).

Aufnahme des gesamten Bildschirms und der Maus

Browser erlauben keinen willkürlichen Vollbildmodus. 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 Eingabeereignishandler gestartet wird. Dies erfordert eine Anpassung der HTML-Seite.

Audio

Chrome schränkt die Wiedergabe von Audio auf Websites ein. Möglicherweise benötigt der Player einen Tastendruck oder Aktivierung um Audio zu aktivieren.

Siehe auch

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

Warnung

Der Zugriff auf das Mikrofon erfordert einen sicheren Kontext.

Netzwerke

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 die Abfrage in einer Schleife einfriert

  • Keine zerstückelten Antworten

  • 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.

Game pads

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 Standard-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.

Einschränkungen der Shader-Sprache

Beim Exportieren eines GLES2-Projekts nach HTML5 wird WebGL 1.0 verwendet. WebGL 1.0 unterstützt keine dynamischen Schleifen, daher funktionieren dort keine Shader, die diese verwenden.

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.

Die generierte .html Datei kann als Verzeichnisindex in Apache-Servern verwendet werden und kann jederzeit in z.B. index.html umbenannt werden, ihr Name ist standardmäßig nie davon abhängig.

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 Webspiel-Hosting-Sites üblich ist.

Die anderen exportierten Dateien werden so, wie sie sind, neben der .html Datei serviert, Namen unverändert. 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-Image. 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.

Vorsicht

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

Die Lieferung der Dateien mit serverseitiger Kompression wird besonders für die .pck und .wasm Dateien empfohlen, die normalerweise groß sind. Das WebAssembly-Modul komprimiert besonders gut, mit gzip-Kompression auf etwa ein Viertel seiner ursprünglichen Größe.

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)

Aufruf von JavaScript aus dem Skript

In Webbuilds ist der JavaScript-Singleton implementiert. Es bietet eine einzige Methode namens "eval", die ähnlich wie die gleichnamige JavaScript-Funktion funktioniert. Es nimmt eine Zeichenfolge als Argument und führt sie als JavaScript-Code aus. Dies ermöglicht die Interaktion mit dem Browser auf eine Weise, die mit in Godot integrierten Skriptsprachen nicht möglich ist.

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

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

  • JavaScript Nummer wird in GDScript zurückgegeben als :ref: class_float

  • JavaScript boolean wird in GDScript zurückgegeben als bool

  • JavaScript string wird in GDScript zurückgegeben als String

  • JavaScript ArrayBuffer, TypedArray und DataView werden in GDScript zurückgegeben als PoolByteArray

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

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

HTML5 export templates may be built without support for the singleton to improve security. With such templates, and on platforms other than HTML5, calling JavaScript.eval will also return null. The availability of the singleton can be checked with the JavaScript feature tag:

func my_func3():
    if OS.has_feature('JavaScript'):
        JavaScript.eval("""
            console.log('The JavaScript singleton is available')
        """)
    else:
        print("The JavaScript 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 eval Methode akzeptiert auch ein zweites, optionales boolesches Argument, das angibt, ob der Code im globalen Ausführungskontext ausgeführt werden soll, wobei die Voreinstellung auf false steht, um eine Verschmutzung des globalen Namensraums zu verhindern:

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