Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Caricamento e salvataggio dei file in fase di esecuzione

Vedi anche

Consulta Salvataggio di giochi per informazioni su come salvare e caricare i progressi di gioco.

A volte, esportare pacchetti, patch e mod non è ideale quando si desidera che i giocatori possano caricare contenuti generati dagli utenti nel progetto. Richiede agli utenti di generare un file PCK o ZIP tramite l'editor Godot, che contiene le risorse importate da Godot.

Esempi di casi d'uso per caricare e salvare file in fase di esecuzione includono:

  • Caricare pacchetti di texture progettati per il gioco.

  • Caricare tracce audio fornite dall'utente e riprodurle in una stazione radio nel gioco.

  • Caricare livelli personalizzati o modelli 3D che si possono progettare con qualsiasi DCC 3D in grado di esportare in glTF o FBX (incluse le scene glTF salvate da Godot in fase di esecuzione).

  • Utilizzare font forniti dall'utente per i menu e l'HUD.

  • Salvare/caricare un formato di file che può contenere più file ma che può comunque essere letto facilmente da altre applicazioni (ZIP).

  • Caricare file creati da un altro gioco o programma, o anche dati di gioco provenienti da un altro gioco non realizzato con Godot.

Il caricamento dei file in fase di esecuzione si può combinare con le richieste HTTP per caricare risorse direttamente da Internet.

Avvertimento

Non utilizzare questo approccio di caricamento in fase di esecuzione per caricare risorse che fanno parte del progetto, poiché è meno efficiente e non consente di sfruttare le funzionalità di gestione delle risorse in Godot (come le rimappature delle traduzioni). Consultare Processo d'importazione per i dettagli.

Vedi anche

È possibile osservare come funzionano il salvataggio e il caricamento in azione attraverso il progetto demo Salvataggio e caricamento (serializzazione).

File di testo semplice e binari

La classe FileAccess di Godot fornisce metodi per accedere ai file sul file system per la lettura e la scrittura:

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

Per gestire formati binari personalizzati (ad esempio, caricare formati di file non supportati da Godot), FileAccess fornisce diversi metodi per leggere/scrivere interi, numeri in virgola mobile, stringhe e altro ancora. Questi metodi di FileAccess hanno nomi che iniziano con get_ e store_.

Se c'è bisogno di controllare meglio la lettura dei file binari o di leggere i flussi binari che non fanno parte di un file, PackedByteArray fornisce diversi metodi ausiliari per decodificare/codificare serie di byte in interi, float, stringhe e altro ancora. Questi metodi di PackedByteArray hanno nomi che iniziano con decode_ e encode_. Consultare anche API di serializzazione binaria.

Immagini

Il metodo statico Image.load_from_file di Image gestisce tutto, dal rilevamento del formato in base all'estensione del file, alla lettura del file dal disco.

Se c'è bisogno di gestire gli errori o di avere più controllo (ad esempio, modificare la scala in cui viene caricato un SVG), usare uno dei seguenti metodi a seconda del formato del file:

Godot può salvare diversi formati di immagine in fase di esecuzione attraverso i seguenti metodi:

I metodi con il suffisso to_buffer salvano l'immagine in un PackedByteArray anziché nel file system. Questo è utile per inviare l'immagine in rete o in un archivio ZIP senza doverla scrivere sul file system. Ciò può aumentare le prestazioni riducendo l'utilizzo di I/O.

Nota

Se si visualizza l'immagine caricata su una superficie 3D, assicurarsi di chiamare Image.generate_mipmaps in modo che la texture non appaia granulosa se visualizzata da lontano. Questo è utile anche in 2D quando si seguono le istruzioni su come ridurre l'aliasing durante il downsampling.

Esempio di caricamento di un'immagine e della sua visualizzazione in un nodo TextureRect (che richiede una conversione in ImageTexture):

# 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")

File audio/video

Godot supporta il caricamento di audio Ogg Vorbis, MP3 e WAV in fase di esecuzione. Si noti che non tutti i file con estensione .ogg sono file Ogg Vorbis. Alcuni potrebbero essere video Ogg Theora o contenere audio Opus in un contenitore Ogg. Questi file non verranno caricati correttamente come file audio in Godot.

Esempio di caricamento di un file audio Ogg Vorbis in un nodo AudioStreamPlayer:

$AudioStreamPlayer.stream = AudioStreamOggVorbis.load_from_file(path)

Esempio di caricamento di un file video Ogg Theora in un nodo VideoStreamPlayer:

var video_stream_theora = VideoStreamTheora.new()
# File extension is ignored, so it is possible to load Ogg Theora videos
# that have a `.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()

Scene 3D

Godot offre un supporto di prima classe per glTF 2.0, sia nell'editor sia nei progetti esportati. Utilizzando GLTFDocument e GLTFState insieme, Godot può caricare e salvare file glTF nei progetti esportati, sia in formato testo (.gltf) sia binario (.glb). Il formato binario è preferibile perché è più veloce da scrivere e più piccolo, ma il formato testuale è più facile da debuggare.

A partire da Godot 4.3, è possibile anche caricare (ma non salvare) le scene FBX in fase di esecuzione attraverso le classi FBXDocument e FBXState. Il codice per farlo è lo stesso di glTF, ma sarà necessario sostituire tutte le istanze di GLTFDocument e GLTFState con FBXDocument e FBXState negli esempi di codice seguenti.

Esempio di caricamento di una scena glTF e aggiunta del suo nodo radice alla scena:

# 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)

Nota

Quando si carica una scena glTF, è necessario impostare un percorso base affinché le risorse esterne, come le texture, si possano caricare correttamente. Quando si carica da un file, il percorso base viene automaticamente impostato sulla cartella che contiene il file. Quando si carica da un buffer, questo percorso base si deve impostare manualmente, poiché Godot non ha modo di dedurlo.

Per impostare il percorso base, impostare GLTFState.base_path sulla propria istanza di GLTFState prima di chiamare GLTFDocument.append_from_buffer o GLTFDocument.append_from_file.

Font

FontFile.load_dynamic_font supporta i seguenti formati di file di font: TTF, OTF, WOFF, WOFF2, PFB, PFM

D'altro parte, FontFile.load_bitmap_font supporta il formato BMFont (.fnt o .font).

Inoltre, è possibile caricare qualsiasi font installato sul sistema attraverso il supporto di Godot per Font di sistema.

Esempio di caricamento automatico di un file di font in base alla sua estensione, quindi aggiunta come sostituzione del tema a un nodo Label:

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)

Archivi ZIP

Godot supporta la lettura e la scrittura di archivi ZIP attraverso le classi ZIPReader e ZIPPacker. Queste supportano qualsiasi file ZIP, inclusi i file generati dalla funzionalità "Esporta PCK/ZIP" di Godot (anche se questi conterranno risorse Godot importate anziché i file originali di progetto).

Nota

Utilizzare ProjectSettings.load_resource_pack per caricare file PCK o ZIP esportati da Godot come pacchetti di dati aggiuntivi. Questo approccio è preferibile per i DLC, poiché rende uniforme l'interazione con i pacchetti di dati aggiuntivi (file system virtuale).

Questo supporto per gli archivi ZIP si può combinare con il caricamento in fase di esecuzione di immagini, scene 3D e audio per offrire un'esperienza di modding uniforme, senza richiedere agli utenti di passare attraverso l'editor Godot per generare file PCK/ZIP.

Esempio che elenca i file in un archivio ZIP in un nodo ItemList, quindi scrive il contenuto letto da esso in un nuovo archivio ZIP (essenzialmente duplicando l'archivio):

# 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()