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...

Configurazione di importazione

Godot provides several ways to customize the imported data, such as the import dock, the advanced import setting dialog, and inherited scenes. This can be used to make further changes to the imported scene, such as adjusting meshes, adding physics information, and adding new nodes. You can also write a script that runs code at the end of the import process to perform arbitrary customization.

Note that, when applicable, modifying the original data should be preferred to configuring the scene after import. This helps minimize the differences between the 3D modeling application and the imported scene. See the Considerazioni sull'esportazione di modelli and Node type customization using name suffixes articles for more information.

Procedure di importazione

Since Godot can only save its own scene format (.tscn/.scn), Godot cannot save over the original 3D scene file (which uses a different format). This is also a safer approach as it avoids making accidental changes to the source file.

To allow customizing the scene and its materials, Godot's scene importer allows for different workflows regarding how data is imported.

Import dock after selecting a 3D scene in the FileSystem dock

This import process is customizable using 3 separate interfaces, depending on your needs:

• The Import dock, after selecting the 3D scene by clicking it once in the FileSystem dock.

• La finestra Impostazioni di importazione avanzate, accessibile facendo doppio clic sulla scena 3D nel pannello Filesystem o cliccando sul pulsante Avanzato… nel pannello Importazione, consente di personalizzare le opzioni per singolo oggetto in Godot e di visualizzare in anteprima modelli e animazioni. Consultare la pagina Impostazioni avanzate del progetto per ulteriori informazioni.

• Import hints, which are special suffixes added to object names in the 3D modeling software. This allows you to customize per-object options in the 3D modeling software.

Per le personalizzazioni base, basta utilizzare il pannello Importazione. Tuttavia, per operazioni più complesse, come la definizione di materiali sostitutivi per ciascun materiale, sarà necessario utilizzare la finestra Impostazioni di importazione avanzate, le indicazioni di importazione o possibilmente entrambi.

Utilizzo del pannello di Importazione

The following options can be adjusted in the Import dock after selecting a 3D scene in the FileSystem dock:

• Tipo di radice: il tipo di nodo da utilizzare come nodo radice. Si consiglia di utilizzare tipi di nodo che ereditano da Node3D. Se no, si perderà l'abilità di posizionare il nodo direttamente nell'editor 3D.

• Nome di radice: il nome del nodo radice nella scena importata. Questo non è generalmente evidente quando si crea un'istanza della scena nell'editor (o trascinandola dal pannello Filesystem), poiché in questo caso il nodo radice viene rinominato così da corrispondere al nome del file.

• Applica scala da radice: se abilitata, Scala di radice verrà applicata direttamente alle mesh e alle animazioni, mantenendo la scala del nodo radice al valore predefinito di (1, 1, 1). Significa che se in seguito aggiungi un nodo figlio all'interno della scena importata, questo non verrà scalato. Se disabilitata, Scala radice moltiplicherà invece la scala del nodo radice.

Mesh

• Garantisci tangenti: se selezionata, genera le tangenti dei vertici tramite Mikktspace se le mesh di input non contengono dati di tangenti. Quando possibile, si consiglia di lasciare che il software di modellazione 3D generi le tangenti durante l'esportazione anziché affidarsi a questa opzione. Le tangenti sono necessarie per visualizzare correttamente le mappe di normali e di altezza, nonché qualsiasi funzionalità di materiale/shader che le richieda. Se non servono funzionalità di materiali che richiedono tangenti, disabilitando questa opzione è possibile ridurre le dimensioni del file risultante e velocizzare l'importazione se il file 3D sorgente non contiene tangenti.

• Genera LOD: Se selezionata, genera varianti a basso livello di dettaglio della mesh che saranno visualizzate in lontananza per migliorare le prestazioni di rendering. Non tutte le mesh traggono vantaggio dai LOD, soprattutto se non sono mai renderizzate da lontano. Disabilitando questa opzione è possibile ridurre le dimensioni del file risultante e velocizzare l'importazione. Consultare Mesh level of detail (LOD) per ulteriori informazioni.

• Crea mesh d'ombra: se selezionata, abilita la generazione di mesh d'ombra durante l'importazione. Questo ottimizza il rendering delle ombre senza ridurre la qualità, unendo i vertici quando possibile. Ciò a sua volta riduce la larghezza di banda necessaria per renderizzare le ombre. La generazione di mesh d'ombra attualmente non supporta l'utilizzo di un livello di dettaglio più basso della mesh sorgente (ma il rendering delle ombre utilizzerà i LOD quando necessario).

• Precalcolo della luce: configura la modalità di illuminazione globale delle mesh nella scena 3D. Se impostato su Static Lightmaps, imposta la modalità GI delle mesh su Static e genera le UV2 durante l'importazione per il precalcolo delle lightmap.

• Dimensione dei texel della lightmap: visibile solo se Light Baking è impostato su Static Lightmap. Controlla la dimensione di ciascun texel sulla lightmap generata. Un valore inferiore produce lightmap più precise, a scapito di dimensioni maggiori e tempi precalcolo più lunghi.

Skin

• Usa skin con nome: se selezionata, utilizza Skin con nomi per le animazioni. Il nodo MeshInstance3D contiene 3 proprietà rilevanti in questo caso: un NodePath dello scheletro che punta al nodo Skeleton3D (di solito ..), una mesh e una skin:

  • Il nodo Skeleton3D contiene un elenco di ossa con i relativi nomi, la loro posa e riposo, un nome e un osso genitore.

  • La mesh è costituita da tutti i dati grezzi dei vertici necessari per visualizzare una mesh. In termini di mesh, essa conosce i pesi dei vertici e utilizza una numerazione interna spesso importata dai software di modellazione 3D.

  • La skin contiene le informazioni necessarie per associare questa mesh a questo Skeleton3D. Per ogni ID osso interno scelto dal software di modellazione 3D, contiene due cose. Primo, una matrice nota come Bind Pose Matrix, Inverse Bind Matrix o IBM in breve. secondo, la Skin contiene il nome di ciascun osso (se Usa skin con nome è abilitato) oppure l'indice dell'osso nell'elenco di Skeleton3D (se Usa skin con nome è disabilitato).

Assieme, queste informazioni sono sufficienti per indicare a Godot come utilizzare le pose delle ossa nel nodo Skeleton3D per renderizzare la mesh di ogni MeshInstance3D. Si noti che ogni MeshInstance3D può condividere le associazioni, come accade comunemente nei modelli esportati da Blender, oppure può utilizzare un oggetto Skin separato, come avviene comunemente nei modelli esportati da altri strumenti come Maya.

Animation

• Importa: se selezionata, importa le animazioni dalla scena 3D.

• FPS: Il numero di fotogrammi al secondo da utilizzare per precalcolare le curve di animazione su una serie di punti con interpolazione lineare. Si consiglia di configurare questo valore in modo che corrisponda al valore utilizzato come base nel software di modellazione 3D. Valori più elevati producono animazioni più precise con rapidi cambi di movimento, a scapito di dimensioni dei file e utilizzo della memoria maggiori. Grazie all'interpolazione, solitamente non è particolarmente vantaggioso andare oltre gli 30 FPS (poiché l'animazione apparirà comunque fluida anche a frame rate di rendering più elevati).

• Ritaglio: taglia l'inizio e la fine delle animazioni se non ci sono modifiche ai fotogrammi chiave. Questo può ridurre le dimensioni dei file risultanti e l'utilizzo della memoria con determinate scene 3D, a seconda del contenuto delle loro tracce di animazione.

• Rimuovi tracce immutabili: rimuove le tracce di animazione che contengono solo valori predefiniti. Questo può ridurre le dimensioni dei file risultanti e l'utilizzo della memoria con determinate scene 3D, a seconda del contenuto delle loro tracce di animazione.

Script di importazione

• Percorso: percorso a uno script di importazione, che può eseguire codice dopo aver completato il processo di importazione per un'elaborazione personalizzata. Consulta Using import scripts for automation per ulteriori informazioni.

glTF

• Gestione delle texture incorporate: controlla come gestire le texture incorporate nelle scene glTF. Discard All Textures non importa alcuna texture, il che è utile se si desidera configurare manualmente i materiali in Godot. Extract Textures estrae le texture in immagini esterne, ottenendo file di dimensioni inferiori e maggiore controllo sulle opzioni di importazione. Embed as Basis Universal e Embed as Uncompressed mantengono le texture incorporate nella scena importata, rispettivamente con e senza compressione VRAM.

FBX

• Importer Quale metodo di importazione è utilizzato. ubfx gestisce i file fbx come file fbx. FBX2glTF converte i file FBX in glTF durante l'importazione e richiede una configurazione in più. FBX2glTF non è consigliato a meno che non si abbia un motivo specifico per usarlo al posto di ufbx o si stia lavorando con un formato di file diverso.

• Consenti nodi ausiliari di geometria abilita o disabilita i nodi ausiliari per la geometria

• Gestione delle texture incorporate: controlla come gestire le texture incorporate nelle scene fbx. Discard All Textures non importa alcuna texture, il che è utile se si desidera configurare manualmente i materiali in Godot. Extract Textures estrae le texture in immagini esterne, ottenendo file di dimensioni inferiori e maggiore controllo sulle opzioni di importazione. Embed as Basis Universal e Embed as Uncompressed mantengono le texture incorporate nella scena importata, rispettivamente con e senza compressione VRAM.

Opzioni specifiche di Blender

Visibile solo per i file .blend.

Nodi

• Visible: All imports everything, even invisible objects. Visible Only only imports visible objects. Renderable only imports objects that are marked as renderable in Blender, regardless of whether they are actually visible. In Blender, renderability is toggled by clicking the camera icon next to each object in the Outliner, while visibility is toggled by the eye icon.

• Active Collection Only: se selezionata, sono importati solo i nodi presenti nella collezione attiva in Blender.

• Punctual Lights: If checked, imports lights (directional, omni, and spot) from Blender. "Punctual" is not to be confused with "positional", which is why directional lights are also included.

• Cameras: If checked, imports cameras from Blender.

• Custom Properties: If checked, imports custom properties from Blender as glTF extras. This data can then be used from an editor plugin that uses GLTFDocument.register_gltf_document_extension(), which can set node metadata on import (among other use cases).

• Modifiers: If set to No Modifiers, object modifiers are ignored on import. If set to All Modifiers, applies modifiers to objects on import.

Mesh

• Colors: If checked, imports vertex colors from Blender.

• UVs: If checked, imports vertex UV1 and UV2 from Blender.

• Normals: se selezionato, importa le normali dei vertici da Blender.

• Export Geometry Nodes Instances: se selezionato, importa le istanze del nodo geometrico da Blender.

• GPU Instances If checked, imports instances and particle systems as GLTF's buffer/accessor data instead of numerous singular Mesh3D object. This does not include Geometry Nodes instancing.

• Tangents: se selezionato, importa le tangenti dei vertici da Blender.

• Skins: None salta l'importazione dei dati delle skin di scheletro da Blender. 4 Influences (Compatible) importa i dati delle skin per renderli compatibili con tutti i renderer, a scapito di una precisione inferiore per alcuni rig. All Influences importa i dati delle skin con tutte le influenze (fino a 8 in Godot), che è più preciso ma potrebbe non essere compatibile con tutti i renderer.

• Export Bones Deforming Mesh Only: se selezionato, importa solo le ossa che deformano la mesh da Blender.

Materiali

• Unpack Enabled: se selezionata, decomprime le immagini originali nel file system Godot e le utilizza. Questo consente di modificare le impostazioni di importazione delle immagini, come la compressione VRAM. Se deselezionata, consente a Blender di convertire le immagini originali, ad esempio rimpacchettando la texture di rugosità e di metallico in una singola texture con entrambi. Nella maggior parte dei casi, questa opzione si dovrebbe lasciare selezionata, ma se le immagini del file .blend non sono nel formato corretto, questa opzione si deve disabilitare per un funzionamento corretto.

• Export Materials: If set to Placeholder, does not import materials, but keeps surface slots so that separate materials can be assigned to different surfaces. If set to Export, imports materials as-is (note that procedural Blender materials may not work correctly). If set to Named Placeholder, imports materials, but doesn't import images that are packed into the .blend file. Textures will have to be reassigned manually in the imported materials.

Animation

• Limit Playback: If checked, limits animation import to the playback range defined in Blender (the Start and End options at the right of the animation timeline in Blender). This can avoid including unused animation data, making the imported scene smaller and faster to load. However, this can also result in missing animation data if the playback range is not set correctly in Blender.

• Always Sample: If checked, forces animation sampling on import to ensure consistency between how Blender and glTF perform animation interpolation, at the cost of larger file sizes. If unchecked, there may be differences in how animations are interpolated between what you see in Blender and the imported scene in Godot, due to different interpolation semantics between both.

• Group Tracks: If checked, imports animations (actives and on NLA tracks) as separate tracks. If unchecked, all the currently assigned actions become one glTF animation.

Using import scripts for automation

A special script to process the whole scene after import can be provided. This is great for post-processing, changing materials, doing funny stuff with the geometry, and more.

Create a script that is not attached to any node by right-clicking in the FileSystem dock and choosing New > Script…. In the script editor, write the following:

@tool # Needed so it runs in editor.
extends EditorScenePostImport

# This sample changes all node names.
# Called right after the scene is imported and gets the root node.
func _post_import(scene):
    # Change all node names to "modified_[oldnodename]"
    iterate(scene)
    return scene # Remember to return the imported scene

# Recursive function that is called on every node
# (for demonstration purposes; EditorScenePostImport only requires a `_post_import(scene)` function).
func iterate(node):
    if node != null:
        print_rich("Post-import: [b]%s[/b] -> [b]%s[/b]" % [node.name, "modified_" + node.name])
        node.name = "modified_" + node.name
        for child in node.get_children():
            iterate(child)

The _post_import(scene: Node) function takes the imported scene as argument (the parameter is actually the root node of the scene). The scene that will finally be used must be returned (even if the scene can be entirely different).

To use your script, locate the script in the import tab's "Path" option under the "Import Script" category.

Utilizzo di librerie di animazione

È anche possibile scegliere di importare solo le animazioni da un file glTF e nient'altro. Questa opzione è usata in alcune pipeline di risorse per distribuire le animazioni separatamente dai modelli. Ad esempio, ciò consente di utilizzare un insieme di animazioni per diversi personaggi, senza dover duplicare i dati di animazione per ogni personaggio.

To do so, select the glTF file in the FileSystem dock, then change the import mode to Animation Library in the Import dock:

Changing the import type to Animation Library in the Import dock

Click Reimport and restart the editor when prompted. After restarting, the glTF file will be imported as an AnimationLibrary instead of a PackedScene. This animation library can then be referenced in an AnimationPlayer node.

The import options that are visible after changing the import mode to Animation Library act the same as when using the Scene import mode. See Utilizzo del pannello di Importazione for more information.

Filtra script

È possibile specificare uno script di filtraggio con una sintassi speciale per decidere quali tracce di quali animazioni bisogna mantenere.

Lo script di filtraggio viene eseguito su ogni animazione importata. La sintassi è composta da due tipi di istruzioni: la prima per scegliere quali animazioni filtrare e la seconda per filtrare le singole tracce dentro l'animazione corrispondente. Tutti gli schemi di nomi vengono elaborati attraverso una corrispondenza di espressioni, senza distinzione tra maiuscole e minuscole, con supporto per i caratteri jolly ? e * (utilizzando String.matchn() internamente).

Lo script deve iniziare con un'istruzione di filtro animazione (indicata dalla riga che inizia con @). Ad esempio, se volessimo applicare filtri a tutte le animazioni importate il cui nome termina con "_Loop":

@+*_Loop

Similmente, è possibile aggiungere ulteriori schemi alla stessa riga, separati da virgole. Ecco un esempio modificato per includere anche tutte le animazioni con nomi che iniziano con "Arm_Left", ma anche escludere tutte le animazioni i cui nomi terminano con "Attack":

@+*_Loop, +Arm_Left*, -*Attack

Dopo l'istruzione di filtro per selezionare le animazioni, aggiungiamo gli schemi di filtro traccia per indicare quali tracce di animazione bisogna mantenere o scartare. Se non viene specificati schemi di filtro traccia, tutte le tracce dentro le animazioni corrispondenti verranno scartate!

È importante notare che le istruzioni di filtro traccia vengono applicate in sequenza, per ciascuna traccia dentro l'animazione. Significa che una riga può includere una traccia, ma una regola successiva può comunque escluderla. Similmente, una traccia esclusa da una regola iniziale può essere reintrodotta da una regola di filtro più avanti nello script di filtraggio.

Ad esempio: includi tutte le tracce nelle animazioni con nomi che terminano con "_Loop", ma scarta tutte le tracce che influenzano uno "Skeleton" che terminano con "Control", a meno che non abbiano "Arm" nel loro nome:

@+*_Loop
+*
-Skeleton:*Control
+*Arm*

Nell'esempio precedente, tracce come "Skeleton:Leg_Control" verrebbero scartate, mentre tracce come "Skeleton:Head" o "Skeleton:Arm_Left_Control" verrebbero mantenute.

Tutte le righe del filtro traccia che non iniziano con + o - sono ignorate.

Ereditarietà di scene

In molti casi, potrebbe essere necessario apportare modifiche manuali alla scena importata. Normalmente, questo non è possibile perché, se la risorsa 3D sorgente cambia, Godot reimporterà l'intera scena.

Tuttavia, è possibile apportare modifiche locali attraverso l'ereditarietà di scene. Se si tenta di aprire la scena importata tramite Scena > Apri scena… o Scena > Apri scena rapida…, verrà visualizzata la seguente finestra di dialogo:

Finestra di dialogo all'apertura di una scena 3D importata nell'editor

Nelle scene ereditate, le uniche restrizioni per la modifica sono:

• I nodi della scena base non possono essere rimossi, ma è possibile aggiungerne altri ovunque.

• Le sotto-risorse non possono essere modificate. È necessario salvarle esternamente come descritto in precedenza.

A parte questo, tutto è permesso.