Work in progress
Godot documentation is being updated to reflect the latest changes in version
4.0. Some documentation pages may
still state outdated information. This banner will tell you if you're reading one of such pages.
The contents of this page can 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.
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
This reduces the data size and speeds up loading, as binary formats are faster
to load compared to text-based formats.
For those looking for a complete description, the parsing is handled in the file
There are five main sections inside the TSCN file:
The file descriptor looks like
[gd_scene load_steps=3 format=2] 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.
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
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.
Entries inside the file¶
A heading looks like
[<resource_type> key=value key=value key=value ...]
where resource_type is one of:
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" parent="."] transform=Transform( 1.0, 0.0, 0.0 ,0.0, 1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0 )
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 type="Camera" name="PlayerCamera" parent="Player/Head"]
Other valid keywords include:
index(sets the order of appearance in the tree. If absent, inherited nodes will take precedence over plain ones)
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" parent="." type="Node3D"] ; Parented to the scene root [node name="Hand" parent="Arm" type="Node3D"] [node name="Finger" parent="Arm/Hand" type="Node3D"]
Similar to the internal resource, the document for each node is currently incomplete. Fortunately, it is easy to find out because you can simply save a file with that node in it. Some example nodes are:
[node type="CollisionShape" name="SphereCollision" parent="SpherePhysics"] shape = SubResource(8) transform = Transform( 1.0 , 0.0 , -0.0 , 0.0 , -4.371138828673793e-08 , 1.0 , -0.0 , -1.0 , -4.371138828673793e-08 ,0.0 ,0.0 ,-0.0 ) [node type="MeshInstance3D" name="Sphere" parent="SpherePhysics"] mesh = SubResource(9) transform = Transform( 1.0 , 0.0 , -0.0 , 0.0 , 1.0 , -0.0 , -0.0 , -0.0 , 1.0 ,0.0 ,0.0 ,-0.0