Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Laden und Speichern von Dateien zur Laufzeit

Siehe auch

Siehe Spielestände speichern für Informationen zum Speichern und Laden von Spielverläufen.

Manchmal ist Exportieren von Packs, Patches und Mods nicht ideal, wenn Sie möchten, dass Spieler in der Lage sind, von Benutzern erstellte Inhalte in Ihr Projekt zu laden. Es erfordert, dass Benutzer eine PCK- oder ZIP-Datei über den Godot-Editor erzeugen, die von Godot importierte Ressourcen enthält.

Beispiele für das Laden und Speichern von Dateien zur Laufzeit sind:

  • Laden von für das Spiel entwickelten Texturpaketen.

  • Laden von benutzerdefinierten Audiotracks und deren Wiedergabe in einem spielinternen Radiosender.

  • Laden von benutzerdefinierten Levels oder 3D-Modellen, die mit jedem 3D-DCC entworfen werden können, das nach glTF exportieren kann (einschließlich glTF-Szenen, die von Godot zur Laufzeit gespeichert werden).

  • Verwendung von benutzerdefinierten Schriftarten für Menüs und HUD.

  • Speichern/Laden eines Dateiformats, das mehrere Dateien enthalten kann, aber dennoch leicht von anderen Anwendungen gelesen werden kann (ZIP).

  • Laden von Dateien, die von einem anderen Spiel oder Programm erstellt wurden, oder sogar von Spieldatendateien aus einem anderen, nicht mit Godot erstellten Spiel.

Das Laden von Dateien zur Laufzeit kann mit HTTP-Anfragen kombiniert werden, um Ressourcen direkt aus dem Internet zu laden.

Warnung

Verwenden Sie nicht diesen Ansatz zum Laden von Ressourcen, die Teil des Projekts sind, da er weniger effizient ist und es nicht erlaubt, von Godots Ressourcen-Handling-Funktionen (wie z.B. Übersetzungs-Remaps) zu profitieren. Siehe Import-Prozess für Details.

Siehe auch

Sie können sehen, wie das Speichern und Laden in Aktion funktioniert, indem Sie das Run-time File Saving and Loading (Serialization)-Demoprojekt verwenden.

Klartext- und Binärdateien

Die Klasse FileAccess von Godot bietet Methoden für den Zugriff auf Dateien im Dateisystem zum Lesen und Schreiben:

func save_file(content):
    var file = FileAccess.open("/path/to/file.txt", FileAccess.WRITE)
    file.store_string(content)

func load_file():
    var file = FileAccess.open("/path/to/file.txt", FileAccess.READ)
    var content = file.get_as_text()
    return content

Um benutzerdefinierte Binärformate zu handhaben (wie z.B. das Laden von Dateiformaten, die von Godot nicht unterstützt werden), bietet FileAccess mehrere Methoden zum Lesen/Schreiben von Integers, Floats, Strings und mehr. Diese FileAccess-Methoden haben Namen, die mit get_ und store_ beginnen.

Wenn Sie mehr Kontrolle über das Lesen von Binärdateien benötigen oder Binär-Streams lesen müssen, die nicht Teil einer Datei sind, bietet PackedByteArray mehrere Hilfsmethoden zum Dekodieren/Enkodieren von Bytefolgen in Integern, Floats, Strings und mehr. Diese PackedByteArray-Methoden haben Namen, die mit decode_ und encode_ beginnen. Siehe auch Binäre Serialisierungs-API.

Bilder

Die statische Methode Image.load_from_file von Image übernimmt alles, von der Formaterkennung anhand der Dateierweiterung bis zum Lesen der Datei von der Festplatte.

Wenn Sie eine Fehlerbehandlung oder mehr Kontrolle benötigen (z. B. das Ändern des Maßstabs, mit dem ein SVG geladen wird), verwenden Sie je nach Dateiformat eine der folgenden Methoden:

Verschiedene Bildformate können von Godot auch zur Laufzeit mit den folgenden Methoden gespeichert werden:

Die Methoden mit dem Suffix to_buffer speichern das Bild in einem PackedByteArray anstelle des Dateisystems. Dies ist nützlich, um das Bild über das Netzwerk oder in ein ZIP-Archiv zu senden, ohne es in das Dateisystem schreiben zu müssen. Dies kann die Leistung durch eine geringere I/O-Auslastung erhöhen.

Bemerkung

Wenn Sie das geladene Bild auf einer 3D-Oberfläche anzeigen, stellen Sie sicher, Image.generate_mipmaps aufzurufen, damit die Textur nicht körnig aussieht, wenn sie aus der Ferne betrachtet wird. Dies ist auch in 2D nützlich, wenn man den Anweisungen in Reduzierung von Aliasing beim Downsampling folgt.

Beispiel für das Laden eines Bildes und dessen Anzeige in einem TextureRect-Node (was eine Umwandlung in ImageTexture erfordert):

# Load an image of any format supported by Godot from the filesystem.
var image = Image.load_from_file(path)
# Optionally, generate mipmaps if displaying the texture on a 3D surface
# so that the texture doesn't look grainy when viewed at a distance.
#image.generate_mipmaps()
$TextureRect.texture = ImageTexture.create_from_image(image)

# Save the loaded Image to a PNG image.
image.save_png("/path/to/file.png")

# Save the converted ImageTexture to a PNG image.
$TextureRect.texture.get_image().save_png("/path/to/file.png")

Audio-/Videodateien

Godot unterstützt das Laden von Ogg Vorbis-Audio zur Laufzeit. Beachten Sie dass nicht alle Dateien mit einer .ogg-Dateiendung Ogg Vorbis-Dateien sein können. Einige können Ogg Theora-Videos sein oder Opus-Audio innerhalb eines Ogg Containers. Diese Dateien werden nicht korrekt als Audiodateien in Godot geladen.

Beispiel für das Laden einer Ogg Vorbis-Audiodatei in einen AudioStreamPlayer-Node:

$AudioStreamPlayer.stream = AudioStreamOggVorbis.load_from_file(path)

Beispiel für das Laden einer Ogg Theora-Videodatei in einen VideoStreamPlayer-Node:

var video_stream_theora = VideoStreamTheora.new()
# File extension is ignored, so it is possible to load Ogg Theora videos
# that have an `.ogg` extension this way.
video_stream_theora.file = "/path/to/file.ogv"
$VideoStreamPlayer.stream = video_stream_theora

# VideoStreamPlayer's Autoplay property won't work if the stream is empty
# before this property is set, so call `play()` after setting `stream`.
$VideoStreamPlayer.play()

Bemerkung

Godot unterstützt noch nicht das Laden von MP3- oder WAV-Dateien während der Laufzeit. Bis dies implementiert ist, ist es möglich, das Laden von WAV-Dateien zur Laufzeit mit einem Skript zu implementieren, da die Property data von AudioStreamWAV für Skripte zugänglich ist.

Es ist immer noch möglich, WAV-Dateien mit AudioStreamWAV.save_to_wav zu speichern, was für prozedural generiertes Audio oder Mikrofonaufnahmen nützlich ist.

3D-Szenen

Godot hat erstklassige Unterstützung für glTF 2.0, sowohl im Editor als auch in exportierten Projekten. Mit GLTFDocument und GLTFState zusammen kann Godot glTF-Dateien in exportierten Projekten laden und speichern, sowohl im Text- (.gltf) als auch im Binärformat (.glb). Das binäre Format sollte bevorzugt werden, da es schneller zu schreiben und kleiner ist, aber das Textformat ist einfacher zu debuggen.

Beispiel für das Laden einer glTF-Szene und das Anhängen ihres Root-Nodes an die Szene:

# Load an existing glTF scene.
# GLTFState is used by GLTFDocument to store the loaded scene's state.
# GLTFDocument is the class that handles actually loading glTF data into a Godot node tree,
# which means it supports glTF features such as lights and cameras.
var gltf_document_load = GLTFDocument.new()
var gltf_state_load = GLTFState.new()
var error = gltf_document_load.append_from_file("/path/to/file.gltf", gltf_state_load)
if error == OK:
    var gltf_scene_root_node = gltf_document_load.generate_scene(gltf_state_load)
    add_child(gltf_scene_root_node)
else:
    show_error("Couldn't load glTF scene (error code: %s)." % error_string(error))

# Save a new glTF scene.
var gltf_document_save := GLTFDocument.new()
var gltf_state_save := GLTFState.new()
gltf_document_save.append_from_scene(gltf_scene_root_node, gltf_state_save)
# The file extension in the output `path` (`.gltf` or `.glb`) determines
# whether the output uses text or binary format.
# `GLTFDocument.generate_buffer()` is also available for saving to memory.
gltf_document_save.write_to_filesystem(gltf_state_save, path)

Bemerkung

Beim Laden einer glTF-Szene muss ein Basispfad festgelegt werden, damit externe Ressourcen wie Texturen korrekt geladen werden können. Beim Laden aus einer Datei wird der Basispfad automatisch auf den Ordner gesetzt, der die Datei enthält. Beim Laden aus einem Puffer muss dieser Basispfad manuell gesetzt werden, da es für Godot keine Möglichkeit gibt, diesen Pfad zu ermitteln.

Um den Basispfad zu setzen, setzen Sie GLTFState.base_path auf Ihrer GLTFState-Instanz vor dem Aufruf von GLTFDocument. append_from_buffer oder GLTFDocument.append_from_file.

Schriftarten

FontFile.load_dynamic_font unterstützt die folgenden Schriftdateiformate: TTF, OTF, WOFF, WOFF2, PFB, PFM

Andererseits unterstützt FontFile.load_bitmap_font das Format BMFont (.fnt oder .font).

Zusätzlich ist es möglich, jede Schriftart zu laden, die auf dem System installiert ist, indem man Godots Unterstützung für System-Schriftarten nutzt.

Beispiel für das automatische Laden einer Schriftartdatei anhand ihrer Dateierweiterung und anschließendes Hinzufügen als Theme-Überschreibung zu einem Label Node:

var path = "/path/to/font.ttf"
var path_lower = path.to_lower()
var font_file = FontFile.new()
if (
        path_lower.ends_with(".ttf")
        or path_lower.ends_with(".otf")
        or path_lower.ends_with(".woff")
        or path_lower.ends_with(".woff2")
        or path_lower.ends_with(".pfb")
        or path_lower.ends_with(".pfm")
):
    font_file.load_dynamic_font(path)
elif path_lower.ends_with(".fnt") or path_lower.ends_with(".font"):
    font_file.load_bitmap_font(path)
else:
    push_error("Invalid font file format.")

if not font_file.data.is_empty():
    # If font was loaded successfully, add it as a theme override.
    $Label.add_theme_font_override("font", font_file)

ZIP-Archive

Godot unterstützt das Lesen und Schreiben von ZIP-Archiven unter Verwendung der Klassen ZIPReader und ZIPPacker. Dies unterstützt jede ZIP-Datei, einschließlich Dateien, die von Godots "Export PCK/ZIP"-Funktionalität erzeugt wurden (obwohl diese importierte Godot-Ressourcen und nicht die ursprünglichen Projektdateien enthalten).

Bemerkung

Verwenden Sie ProjectSettings.load_resource_pack, um von Godot exportierte PCK- oder ZIP-Dateien als zusätzliche Datenpakete ermöglicht zu laden. Dieser Ansatz wird für DLCs bevorzugt, da er eine nahtlose Interaktion mit zusätzlichen Datenpaketen ermöglicht (virtuelles Dateisystem).

Diese ZIP-Archiv-Unterstützung kann mit dem Laden von Bildern, 3D-Szenen und Audiodateien zur Laufzeit kombiniert werden, um ein nahtloses Modding-Erlebnis zu ermöglichen, ohne dass die Benutzer den Godot-Editor zur Erstellung von PCK/ZIP-Dateien durchlaufen müssen.

Beispiel, das die Dateien in einem ZIP-Archiv in einem ItemList Node auflistet und dann den daraus gelesenen Inhalt in ein neues ZIP-Archiv schreibt (und damit das Archiv dupliziert):

# Load an existing ZIP archive.
var zip_reader = ZIPReader.new()
zip_reader.open(path)
var files = zip_reader.get_files()
# The list of files isn't sorted by default. Sort it for more consistent processing.
files.sort()
for file in files:
    $ItemList.add_item(file, null)
    # Make folders disabled in the list.
    $ItemList.set_item_disabled(-1, file.ends_with("/"))

# Save a new ZIP archive.
var zip_packer = ZIPPacker.new()
var error = zip_packer.open(path)
if error != OK:
    push_error("Couldn't open path for saving ZIP archive (error code: %s)." % error_string(error))
    return

# Reuse the above ZIPReader instance to read files from an existing ZIP archive.
for file in zip_reader.get_files():
    zip_packer.start_file(file)
    zip_packer.write_file(zip_reader.read_file(file))
    zip_packer.close_file()

zip_packer.close()