Exportieren 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

There are significant bugs when running HTML5 projects on iOS (regardless of the browser). We recommend using iOS' native export functionality instead, as it will also result in better performance.

WebGL 2

Bis der OpenGL ES 3 Renderer zugunsten von Vulkan aus Godot entfernt wird, verwendet der HTML5-Export WebGL 2 wenn die Option GLES3 ausgewählt ist.

Warnung

Die Verwendung von WebGL 2 wird nicht empfohlen, da es voraussichtlich aus Godot ersatzlos entfernt wird.

WebGL 2 wird nicht in allen Browsern unterstützt. Firefox und Chromium (Chrome, Opera) sind die beliebtesten unterstützten Browser. Safari und Edge funktionieren nicht. Unter iOS basieren alle Browser auf WebKit (d.H. Safari), sodass sie auch nicht funktionieren.

Der WebGL 2-Renderer von Godot hat Probleme mit 3D und wird nicht länger unterstützt.

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.

You can choose the Export Type to select which features will be available:

  • Regular: is the most compatible across browsers, will not support threads, nor GDNative.

  • Threads: will require the browser to support SharedArrayBuffer

  • GDNative: enables GDNative support but makes the binary bigger and slower to load.

If you plan to use VRAM compression make sure that Vram Texture Compression is enabled for the targeted platforms (enabling both For Desktop and For Mobile will result in a bigger, but more compatible 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

Each project must generate their own HTML file. On export, several text placeholders are replaced in the generated HTML file specifically for the given export options. Any direct modifications to that HTML file will be lost in future exports. To customize the generated file, use the Custom HTML shell option.

Warnung

Export types other then 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 vendors are making more and more functionalities only available in secure contexts, this means that such features are only be available if the web page is served via a secure HTTPS connection (localhost is usually exempt from such requirement).

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.

Threads

As mentioned above multi-threading is only available if the appropriate Export Type is set and support for it across browsers is still limited.

Warnung

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

GDNativ

As mentioned above GDNative is only available if the appropriate Export Type is set.

The export will also copy the required GDNative .wasm files to the output folder (and must be uploaded to your server along with your game).

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

Access to microphone requires a secure context.

Netzwerke

Low level networking is not implemented due to lacking support in browsers.

Currently, only HTTP client, HTTP requests, WebSocket (client) and WebRTC are supported.

The HTTP classes also have several restrictions on the HTML5 platform:

  • 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

Clipboard

Clipboard synchronization between engine and the operating system requires a browser supporting the Clipboard API, additionally, due to the API asynchronous nature might not be reliable when accessed from GDScript.

Warnung

Requires a secure context.

Gamepads

Gamepads will not be detected until one of their button is pressed. Gamepads might have the wrong mapping depending on the browser/OS/gamepad combination, sadly the Gamepad API does not provide a reliable way to detect the gamepad information necessary to remap them based on model/vendor/OS due to privacy considerations.

Warnung

Requires a secure context.

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 that provide on-the-fly compression: GitHub Pages (gzip)

Hosts that don't provide on-the-fly compression: itch.io, GitLab Pages (supports manual gzip precompression)

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-Exportvorlagen können ohne Unterstützung für das Singleton gebuilded sein, um die Sicherheit zu verbessern. Mit solchen Vorlagen und auf anderen Plattformen als HTML5 wird der Aufruf von JavaScript.eval auch null zurückgeben. Die Verfügbarkeit des Singletons kann mit dem JavaScript feature tag geprüft werden:

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)