TSCN file format¶
The TSCN (text scene) file format represents a single scene tree inside Godot. Unlike binary SCN files, TSCN files have the advantage of being mostly human-readable and easy for version control systems to manage.
The ESCN (exported scene) file format is identical to the TSCN file format, but
is used to indicate to Godot that the file has been exported from another
program and should not be edited by the user from within Godot.
Unlike SCN and TSCN files, during import, ESCN files are compiled to binary
SCN files stored inside the .godot/imported/
folder.
This reduces the data size and speeds up loading, as binary formats are faster
to load compared to text-based formats.
To make files more compact, properties equal to the default value are not stored in scene/resource files. It is possible to write them manually, but they will be discarded when saving the file.
For those looking for a complete description, the parsing is handled in the file
resource_format_text.cpp
in the ResourceFormatLoaderText
class.
Note
The scene and resource file formats have changed significantly in Godot 4, with the introduction of string-based UIDs to replace incremental integer IDs.
Mesh, skeleton and animation data is also stored differently compared to Godot 3. You can read about some of the changes in this article: Animation data rework for 4.0
Scenes and resources saved with Godot 4.x contain format=3
in their
header, whereas Godot 3.x uses format=2
instead.
File structure¶
There are five main sections inside the TSCN file:
File descriptor
External resources
Internal resources
Nodes
Connections
The file descriptor looks like [gd_scene load_steps=4 format=3 uid="uid://cecaux1sm7mo0"]
and should be the first entry in the file. The load_steps
parameter is equal to the
total amount of resources (internal and external) plus one (for the file itself).
If the file has no resources, load_steps
is omitted. The engine will
still load the file correctly if load_steps
is incorrect, but this will affect
loading bars and any other piece of code relying on that value.
uid
is an unique string-based identifier representing the scene. This is
used by the engine to track files that are moved around, even while the editor
is closed. Scripts can also load UID-based resources using the uid://
path
prefix to avoid relying on filesystem paths. This makes it possible to move
around a file in the project, but still be able to load it in scripts without
having to modify the script. Godot does not use external files to keep track of
IDs, which means no central metadata storage location is required within the
project. See this pull request
for detailed information.
These sections should appear in order, but it can be hard to distinguish them.
The only difference between them is the first element in the heading for all of
the items in the section. For example, the heading of all external resources
should start with [ext_resource ...]
.
A TSCN file may contain single-line comments starting with a semicolon (;
).
However, comments will be discarded when saving the file using the Godot editor.
Whitespace within a TSCN file is not significant (except within strings), but
extraneous whitespace will be discarded when saving the file.
Entries inside the file¶
A heading looks like
[<resource_type> key1=value1 key2=value2 key3=value3 ...]
where resource_type is one of:
ext_resource
sub_resource
node
connection
Below every heading comes zero or more key = value
pairs. The
values can be complex datatypes such as Arrays, Transforms, Colors, and
so on. For example, a Node3D looks like:
[node name="Cube" type="Node3D"]
transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 1, 2, 3)
The scene tree¶
The scene tree is made up of… nodes! The heading of each node consists of
its name, parent and (most of the time) a type. For example:
[node name="PlayerCamera" type="Camera" parent="Player/Head"]
Other valid keywords include:
instance
instance_placeholder
owner
index
(sets the order of appearance in the tree; if absent, inherited nodes will take precedence over plain ones)
groups
The first node in the file, which is also the scene root, must not have a
parent="Path/To/Node"
entry in its heading. All scene files should have
exactly one scene root. If it doesn't, Godot will fail to import the file.
The parent path of other nodes should be absolute, but shouldn't contain
the scene root's name. If the node is a direct child of the scene root,
the path should be "."
. Here is an example scene tree
(but without any node content):
[node name="Player" type="Node3D"] ; The scene root
[node name="Arm" type="Node3D" parent="."] ; Parented to the scene root
[node name="Hand" type="Node3D" parent="Arm"] ; Child of "Arm"
[node name="Finger" type="Node3D" parent="Arm/Hand"] ; Child of "Hand"
Tip
To make the file structure easier to grasp, you can saving a file with any
given node or resource then inspect it yourself in an external editor. You
can also make incremental changes in the Godot editor, and keep an external
text editor open on the .tscn
or .tres
file with auto-reload enabled
to see what changes.
Here is an example of a scene containing a RigidBody3D-based ball with collision, visuals (mesh + light) and a camera parented to the RigidBody3D:
[gd_scene load_steps=4 format=3 uid="uid://cecaux1sm7mo0"]
[sub_resource type="SphereShape3D" id="SphereShape3D_tj6p1"]
[sub_resource type="SphereMesh" id="SphereMesh_4w3ye"]
[sub_resource type="StandardMaterial3D" id="StandardMaterial3D_k54se"]
albedo_color = Color(1, 0.639216, 0.309804, 1)
[node name="Ball" type="RigidBody3D"]
[node name="CollisionShape3D" type="CollisionShape3D" parent="."]
shape = SubResource("SphereShape3D_tj6p1")
[node name="MeshInstance3D" type="MeshInstance3D" parent="."]
mesh = SubResource("SphereMesh_4w3ye")
surface_material_override/0 = SubResource("StandardMaterial3D_k54se")
[node name="OmniLight3D" type="OmniLight3D" parent="."