Exportieren für das Web

HTML5 export allows publishing games made in Godot Engine to the browser. This requires support for WebAssembly and WebGL in the user's browser.

Wichtig

Use the browser-integrated developer console, usually opened with F12, to view debug information like JavaScript, engine, and WebGL errors.

Achtung

Many browsers, including Firefox and Chromium-based browsers, will not load exported projects when opened locally per file:// protocol. To get around this, use a local server.

Tipp

Python offers an easy method to start a local server. Use python -m http.server 8000 --bind 127.0.0.1 with Python 3 to serve the current working directory at http://localhost:8000. Refer to MDN for additional information.

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.

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.

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.

Aufnahme des gesamten Bildschirms und der Maus

Browsers do not allow arbitrarily entering full screen. The same goes for capturing the cursor. Instead, these actions have to occur as a response to a JavaScript input event. In Godot, this means entering full screen from within a pressed input event callback such as _input or _unhandled_input. Querying the Input singleton is not sufficient, the relevant input event must currently be active.

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 Autoplay

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.

HTTPClient und HTTPRequest

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

Exportierte .html Datei darf nicht wiederverwendet werden

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 the generated HTML file will be lost in future exports. To customize the generated file, see Eigene HTML Seiten für Web Export.

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.

Nicht implementierte Funktionalität

Die folgenden Funktionen sind derzeit auf der HTML5-Plattform nicht verfügbar:

  • Threads
  • GDNative
  • C#
  • Zwischenablagesynchronisation zwischen Engine und Betriebssystem
  • andere Netzwerke als HTTPClient and WebSocketClient

Tipp

Check the list of open HTML5 issues on GitHub to see if the functionality you're interested in has an issue yet. If not, open one to communicate your interest.

Dateien bereitstellen

Exporting for the web generates several files to be served from a web server, including a default HTML page for presentation. A custom HTML file can be used, see Eigene HTML Seiten für Web Export.

The generated .html file can be used as DirectoryIndex in Apache servers and can be renamed to e.g. index.html at any time, its name is never depended on by default.

The HTML page draws the game at maximum size within the browser window. This way it can be inserted into an <iframe> with the game's size, as is common on most web game hosting sites.

The other exported files are served as they are, next to the .html file, names unchanged. The .wasm file is a binary WebAssembly module implementing the engine. The .pck file is the Godot main pack containing your game. The .js file contains start-up code and is used by the .html file to access the engine. The .png file contains the boot splash image. It is not used in the default HTML page, but is included for custom HTML pages.

The .pck file is binary, usually delivered with the MIME-type application/octet-stream. The .wasm file is delivered as application/wasm.

Vorsicht

Delivering the WebAssembly module (.wasm) with a MIME-type other than application/wasm can prevent some start-up optimizations.

Delivering the files with server-side compression is recommended especially for the .pck and .wasm files, which are usually large in size. The WebAssembly module compresses particularly well, down to around a quarter of its original size with gzip compression.

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.

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.

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

GDScript's multi-line strings, surrounded by 3 quotes """ as in my_func3() above, are useful to keep JavaScript code readable.

The eval method also accepts a second, optional Boolean argument, which specifies whether to execute the code in the global execution context, defaulting to false to prevent polluting the global namespace:

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