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.

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

Achtung

Projects written in C# using Godot 4 currently cannot be exported to the web. See this blog post for more information.

To use C# on web platforms, use Godot 3 instead.

Tipp

Use the browser-integrated developer console, usually opened with F12 or Ctrl + Shift + I (Cmd + Option + I on macOS), to view debug information like JavaScript, engine, and WebGL errors.

If the shortcut doesn't work, it's because Godot actually captures the input. You can still open the developer console by accessing the browser's menu.

Bemerkung

Due to security concerns with SharedArrayBuffer due to various exploits, the use of multiple threads for the Web platform has multiple drawbacks, including requiring specific server-side headers and complete cross-origin isolation (meaning no ads, nor third-party integrations on the website hosting your game).

Since Godot 4.3, Godot supports exporting your game on a single thread, which solves this issue. While it has some drawbacks on its own (it cannot use threads, and is not as performant as the multi-threaded export), it doesn't require as much overhead to install. It is also more compatible overall with stores like itch.io or Web publishers like Poki or CrazyGames. The single-threaded export works very well on macOS and iOS too, where it always had compatibility issues with multiple threads exports.

For these reasons, it is the preferred and now default way to export your games on the Web.

For more information, see this blog post about single-threaded Web export.

Siehe auch

See the list of open issues on GitHub related to the web export for a list of known bugs.

Export file name

We suggest users to export their Web projects with index.html as the file name. index.html is usually the default file loaded by web servers when accessing the parent directory, usually hiding the name of that file.

Achtung

The Godot 4 Web export expects some files to be named the same name as the one set in the initial export. Some issues could occur if some exported files are renamed, including the main HTML file.

WebGL-Version

Godot 4.0 and later can only target WebGL 2.0 (using the Compatibility rendering method). Forward+/Mobile are not supported on the web platform, as these rendering methods are designed around modern low-level graphics APIs. Godot currently does not support WebGPU, which is a prerequisite for allowing Forward+/Mobile to run on the web platform.

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.

Mobile considerations

The Web export can run on mobile platforms with some caveats. While native Android and iOS exports will always perform better by a significant margin, the Web export allows people to run your project without going through app stores.

Remember that CPU and GPU performance is at a premium when running on mobile devices. This is even more the case when running a project exported to Web (as it's WebAssembly instead of native code). See Performance section of the documentation for advice on optimizing your project. If your project runs on platforms other than Web, you can use Feature-Tags to apply low-end-oriented settings when running the project exported to Web.

To speed up loading times on mobile devices, you should also compile an optimized export template with unused features disabled. Depending on the features used by your project, this can reduce the size of the WebAssembly payload significantly, making it faster to download and initialize (even when cached).

Audio playback

Since Godot 4.3, audio playback is done using the Web Audio API on the web platform. This Sample playback mode allows for low latency even when the project is exported without thread support, but it has several limitations:

  • AudioEffects are not supported.

  • Reverberation and doppler effects are not supported.

  • Procedural audio generation is not supported.

  • Positional audio may not always work correctly depending on the node's properties.

To use Godot's own audio playback system on the web platform, you can change the default playback mode using the Audio > General > Default Playback Type.web project setting, or change the Playback Type property to Stream on an AudioStreamPlayer, AudioStreamPlayer2D or AudioStreamPlayer3D node. This leads to increased latency (especially when thread support is disabled), but it allows the full suite of Godot's audio features to work.

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 Ihr Projekt GDExtension verwendet, muss Extension-Unterstützung aktiviert sein.

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

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.

Thread and extension support

If Thread Support is enabled, the exported project will be able to make use of multithreading to improve performance. This also allows for low-latency audio playback when the playback type is set to Stream (instead of the default Sample that is used in web exports). Enabling this feature requires the use of cross-origin isolation headers, which are described in the Dateien bereitstellen section below.

If Extensions Support is enabled, GDExtensions will be able to be loaded. Note that GDExtensions still need to be specifically compiled for the web platform to work. Like thread support, enabling this feature requires the use of cross-origin isolation headers.

Exporting as a Progressive Web App (PWA)

If Progressive Web App > Enable is enabled, it will have several effects:

  • Configure high-resolution icons, a display mode and screen orientation. These are configured at the end of the Progressive Web App section in the export options. These options are used if the user adds the project to their device's homescreen, which is common on mobile platforms. This is also supported on desktop platforms, albeit in a more limited capacity.

  • Allow the project to be loaded without an Internet connection if it has been loaded at least once beforehand. This works thanks to the service worker that is installed when the project is first loaded in the user's browser. This service worker provides a local fallback when no Internet connection is available.

    • Note that web browsers can choose to evict the cached data if the user runs low on disk space, or if the user hasn't opened the project for a while. To ensure data is cached for a longer duration, the user can bookmark the page, or ideally add it to their device's home screen.

    • If the offline data is not available because it was evicted from the cache, you can configure an Offline Page that will be displayed in this case. The page must be in HTML format and will be saved on the client's machine the first time the project is loaded.

  • Ensure cross-origin isolation headers are always present, even if the web server hasn't been configured to send them. This allows exports with threads enabled to work when hosted on any website, even if there is no way for you to control the headers it sends.

    • This behavior can be disabled by unchecking Enable Cross Origin Isolation Headers in the Progressive Web App section.

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 offers additional information about their Web Audio autoplay policies.

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.

Warnung

Since Godot 4.3, by default Web exports will use samples instead of streams to play audio.

This is due to the way browsers prefer to play audio and the lack of processing power available when exporting Web games with the Use Threads export option off.

Please note that audio effects aren't yet implemented for samples.

Netzwerkfunktionen

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

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.

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

Only when exporting with Use Threads, to ensure low audio latency and the ability to use Thread in web exports, Godot 4 web exports use SharedArrayBuffer. This requires a secure context, while also requiring the following CORS headers to be set when serving the files:

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

If you don't control the web server or are unable to add response headers, check Progressive Web App > Enable in the export options. This applies a service worker-based workaround that allows the project to run by simulating the presence of these response headers. A secure context is still required in this case.

If the client doesn't receive the required response headers or the service worker-based workaround is not applied, the project will not run.

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.

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.

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 that don't provide on-the-fly compression: itch.io, GitLab Pages (supports manual gzip precompression)

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.

Interaktion mit dem Browser und JavaScript

Siehe die Seite über die Interaktion mit JavaScript und den Zugang zu einigen einzigartigen Webbrowser-Funktionen.

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

Exportoptionen

You can find a full list of export options available in the EditorExportPlatformWeb class reference.