Work in progress

The content of this page was not yet updated for Godot 4.4 and may be outdated. If you know how to improve this page or you can confirm that it's up to date, feel free to open a pull request.

HTML5 Shell-Klassenreferenz

Projekte, die für das Web exportiert werden, stellen der JavaScript-Umgebung die Klasse Engine() zur Verfügung, die eine genaue Kontrolle über den Startvorgang der Engine ermöglicht.

Diese API ist asynchron aufgebaut und erfordert ein grundlegendes Verständnis von Promises.

Die Engine

Die Klasse Engine bietet Methoden zum Laden und Starten exportierter Projekte im Web. Bei den Default-Export-Einstellungen ist dies bereits Teil der exportierten HTML-Seite. Um die praktische Verwendung der Klasse Engine zu verstehen, siehe Benutzerdefinierte HTML-Seite für Web-Export.

Statische Methoden

Promise	`load` ( string basePath )
void	`unload` ( )
boolean	`isWebGLAvailable` ( [ number majorVersion=1 ] )

Instanzmethoden

Promise	`init` ( [ string basePath ] )
Promise	`preloadFile` ( string\|ArrayBuffer file [, string path ] )
Promise	`start` ( EngineConfig override )
Promise	`startGame` ( EngineConfig override )
void	`copyToFS` ( string path, ArrayBuffer buffer )
void	`requestQuit` ( )

class Engine(initConfig)

Erzeugt eine neue Engine-Instanz mit der angegebenen Konfiguration.

Parameter:

initConfig (EngineConfig()) -- Die initiale Konfiguration für diese Instanz.

Statische Methoden

Engine.load(basePath)

Lädt die Engine aus dem angegebenen Basispfad.

Parameter:

basePath (string()) -- Basispfad der zu ladenden Engine.

Rückgabe:

Ein Promise, das sich einlöst, sobald die Engine geladen ist.

Rückgabetyp:

Promise

Engine.unload()

Entlädt die Engine, um Speicher freizugeben.

Diese Methode wird je nach Konfiguration automatisch aufgerufen. Siehe unloadAfterInit.

Engine.isWebGLAvailable([majorVersion=1])

Prüfen Sie, ob WebGL verfügbar ist. Geben Sie optional eine bestimmte Version von WebGL an, auf die geprüft werden soll.

Parameter:

majorVersion (number()) -- Die Haupt-WebGL-Version, auf die geprüft werden soll.

Rückgabe:

Wenn die angegebene Hauptversion von WebGL verfügbar ist.

Rückgabetyp:

boolean

Instanzmethoden

Engine.prototype.init([basePath])

Initialisierung der Engine-Instanz. Optional kann der Basispfad zur Engine übergeben werden, um sie zu laden, falls sie noch nicht geladen wurde. Siehe Engine.load().

Parameter:

basePath (string()) -- Basispfad der zu ladenden Engine.

Rückgabe:

Ein Promise, das sich einlöst, sobald die Engine geladen und initialisiert ist.

Rückgabetyp:

Promise

Engine.prototype.preloadFile(file[, path])

Lädt eine Datei, damit sie im Dateisystem der Instanz verfügbar ist, sobald diese läuft. Muss vor dem Start der Instanz aufgerufen werden.

Wenn nicht angegeben, wird der Pfad von der URL der geladenen Datei abgeleitet.

Parameter:

file (string|ArrayBuffer()) -- Die Datei, die vorgeladen werden soll. Wenn es ein String ist, wird die Datei von diesem Pfad geladen. Wenn es ein ArrayBuffer oder ein View auf einen solchen ist, wird der Buffer als Inhalt der Datei verwendet.
path (string()) -- Pfad, unter dem die Datei zugänglich sein wird. Erforderlich, wenn file kein String ist.

Rückgabe:

Ein Promise, das aufgelöst wird, sobald die Datei geladen ist.

Rückgabetyp:

Promise

Engine.prototype.start(override)

Startet die Engine-Instanz unter Verwendung der angegebenen Override-Konfiguration (falls vorhanden). startGame kann in typischen Fällen stattdessen verwendet werden.

Dadurch wird die Instanz initialisiert, wenn sie nicht bereits initialisiert ist. Für die manuelle Initialisierung siehe init. Die Engine muss vorher geladen werden.

Schlägt fehl, wenn ein Canvas auf der Seite nicht gefunden werden kann oder nicht in der Konfiguration angegeben ist.

Parameter:

override (EngineConfig()) -- Eine optionale Konfigurations-Override.

Rückgabe:

Ein Promise, das nach dem Starten der Engine aufgelöst wird.

Rückgabetyp:

Promise

Engine.prototype.startGame(override)

Startet die Spielinstanz mit dem angegebenen Konfigurations-Override (falls vorhanden).

Dadurch wird die Instanz initialisiert, wenn sie nicht initialisiert ist. Für die manuelle Initialisierung, siehe init.

Dadurch wird die Engine geladen, falls sie noch nicht geladen ist, und das Hauptpaket wird vorgeladen.

Diese Methode erwartet, dass die initiale Konfiguration (oder das Override) sowohl die executable als auch die mainPack-Property gesetzt hat (normalerweise geschieht dies durch den Editor während des Exports).

Parameter:

override (EngineConfig()) -- Eine optionale Konfigurations-Override.

Rückgabe:

Ein Promise, das sich auflöst, sobald das Spiel begonnen hat.

Rückgabetyp:

Promise

Engine.prototype.copyToFS(path, buffer)

Erzeugt eine Datei im angegebenen path mit dem als buffer übergebenen Inhalt im Dateisystem der Instanz.

Parameter:

path (string()) -- Der Ort, an dem die Datei erstellt werden soll.
buffer (ArrayBuffer()) -- Der Inhalt der Datei.

Engine.prototype.requestQuit()

Anforderung, dass die aktuelle Instanz beendet wird.

Dies ist vergleichbar mit dem Drücken des "Schließen"-Buttons im Fenstermanager und hat keine Auswirkungen, wenn die Engine abgestürzt ist oder in einer Schleife feststeckt.

Engine-Konfiguration

Ein Objekt, das dazu dient, die Engine-Instanz auf der Grundlage der Godot-Exportoptionen zu konfigurieren und diese bei Bedarf in benutzerdefinierten HTML-Vorlagen außer Kraft zu setzen.

Propertys

Typ	Name
boolean	`unloadAfterInit`
HTMLCanvasElement	`canvas`
String	`executable`
String	`mainPack`
String	`locale`
Zahl	`canvasResizePolicy`
Array.<String>	`args`
Funktion	`onExecute`
Funktion	`onExit`
Funktion	`onProgress`
Funktion	`onPrint`
Funktion	`onPrintError`

EngineConfig

Das Konfigurationsobjekt der Engine. Dies ist nur ein Typedef, erstellen Sie es wie ein normales Objekt, z.B.:

const MyConfig = { executable: 'godot', unloadAfterInit: false }

Property-Beschreibungen

unloadAfterInit

Ob die Engine automatisch entladen werden soll, nachdem die Instanz initialisiert wurde.

Typ:: boolean
Wert:: true

canvas

Das zu verwendende HTML DOM Canvas-Objekt.

Standardmäßig wird das erste Canvas-Element im Dokument verwendet, wenn keines angegeben ist.

Typ:: HTMLCanvasElement
Wert:: null

executable

Der Name der WASM-Datei ohne Erweiterung. (Wird durch den Exportvorgang des Godot-Editors festgelegt).

Typ:: String
Wert:: ""

mainPack

Ein alternativer Name für das zu ladende Spiel-pck. Ansonsten wird der Name der ausführbaren Datei verwendet.

Typ:: String
Wert:: null

locale

Geben Sie einen Sprachcode an, um die richtige Lokalisierung für das Spiel auszuwählen.

Die Browser-Sprachumgebung wird verwendet, wenn keine angegeben ist. Siehe vollständige Liste der unterstützten Gebietsschemata.

Typ:: String
Wert:: null

canvasResizePolicy

Die Richtlinie zur Größenänderung des Canvas legt fest, wie die Größe des Canvas durch Godot geändert werden soll.

0 bedeutet, dass Godot keine Größenänderung vornimmt. Dies ist nützlich, wenn Sie die Größe des Canvas über Javascript-Code in Ihrer Vorlage steuern möchten.

1 bedeutet, dass Godot die Größe des Canvas beim Start und beim Ändern der Fenstergröße über Engine-Funktionen ändert.

2 bedeutet, dass Godot die Größe des Canvas an die Größe des gesamten Browserfensters anpasst.

Typ:: Zahl
Wert:: 2

args

Die Argumente, die beim Starten als Befehlszeilenargumente übergeben werden.

Siehe Kommandzeilen-Tutorial.

Hinweis: startGame fügt immer das --main-pack-Argument hinzu.

Typ:: Array.<String>
Wert:: []

onExecute(path, args)

Eine Callback-Funktion für die Behandlung von Godots OS.execute-Aufrufen.

Dies wird zum Beispiel in der Web-Editor-Vorlage verwendet, um zwischen Projektmanager und Editor zu wechseln und um das Spiel zu starten.

Parameter:

path (string()) -- Der Pfad, den Godot ausführen möchte.
args (Array.) -- Die Argumente des auszuführenden "Befehls".

onExit(status_code)

Eine Callback-Funktion, um benachrichtigt zu werden, wenn die Godot-Instanz beendet wird.

Hinweis: Diese Funktion wird nicht aufgerufen, wenn die Engine abstürzt oder nicht mehr reagiert.

Parameter:

status_code (number()) -- Der von Godot beim Beenden zurückgegebene Statuscode.

onProgress(current, total)

Eine Callback-Funktion zur Anzeige des Download-Fortschritts.

Die Funktion wird einmal pro Frame beim Herunterladen von Dateien aufgerufen, so dass die Verwendung von requestAnimationFrame() nicht notwendig ist.

Wenn die Callback-Funktion eine Gesamtanzahl von Bytes als 0 erhält, bedeutet dies, dass sie nicht berechnet werden kann. Mögliche Gründe sind:

Dateien werden mit serverseitiger Blockkomprimierung geliefert
Dateien werden mit serverseitiger Komprimierung auf Chromium geliefert
Es wurden noch nicht alle Dateidownloads gestartet (normalerweise auf Servern ohne Multithreading)

Parameter:

current (number()) -- Die aktuelle Anzahl der bisher heruntergeladenen Bytes.
total (number()) -- Die Gesamtmenge der herunterzuladenden Bytes.

onPrint([...var_args])

Eine Callback-Funktion für die Behandlung des Default-Ausgabestroms. Diese Methode sollte normalerweise nur in Debug-Seiten verwendet werden.

Standardmäßig wird console.log() verwendet.

Parameter:

var_args (*()) -- Eine variadische Menge von Argumenten, die ausgegeben werden sollen.

onPrintError([...var_args])

Eine Callback-Funktion für die Behandlung des Default-Fehlerstroms. Diese Methode sollte normalerweise nur in Debug-Seiten verwendet werden.

Standardmäßig wird console.error() verwendet.

Parameter:

var_args (*()) -- Eine variable Menge von Argumenten, die als Fehler ausgegeben werden.