??? TSCN 文件格式

• https://docs.godotengine.org/en/stable/development/file_formats/tscn.html

• https://github.com/godotengine/godot/blob/master/scene/resources/resource_format_text.cpp

• https://github.com/godotengine/godot/blob/master/core/variant_parser.cpp

• godot-docs\development\file_formats\tscn.rst

• godot\scene\resources\resource_format_text.cpp

• godot\core\variant_parser.cpp

TSCN (text scene) 字符串格式場景文件，Godot 加載后會編譯成二進制文件保存在 `.import/` 或工作目錄，Godot 4.x 則保存在 `.godot/imported/`。

TSCN 文件有 5 個區(qū)段，分別開頭表示注解：

• 0. File Descriptor? ? - ``[gd_scene]``

• 1. External resources - ``[ext_resource]``

• 2. Internal resources - ``[sub_resource]``

• 3. Nodes? ? ? ? ? ? ? - ``[node]``

• 4. Signal Connections - ``[connection]``

所有區(qū)段中使用的實體使用方括號包括，實體可以添加任意的 key="value" 鍵值對，實體后可以緊跟屬性設(shè)置，使用 property=value 這樣的格式書寫。

Godot 4.x 使用的格式版本為 Version 3，使用字符串作為資源 ID、UID，與前一個版本不兼容：

• - Version 2: changed names for Basis, AABB, Vectors, PoolVectors, etc.

• - Version 3: new string ID for ext/subresources, and uid, breaks forward compat.

需要將 Godot 4.x 工程降級為低版本的 Godot 3.x 工程，則需要考慮類型名稱變化、資源文件格式問題，還有新版本中 GDScript 關(guān)鍵字、注解功能的差別。手動降級 Godot 工程的操作步驟：

• - 修改 project.godot 中的版本號，將新版本 config_version=5，舊版本 Godot 3.x 版本為 4；

• - 修改場景文件中的版本號，改為 format=2；

• - 刪除場景中的 uid 屬性，并重新設(shè)置實體的 id 屬性，去掉雙引號及字符串，直接使用一個唯一的數(shù)值；

• - 相應(yīng)地修改資源引用 SubResource(id) 或 ExtResource(id)；

• - 根據(jù)節(jié)點及數(shù)據(jù)類型修改 type 屬性，更新相應(yīng)的名稱，以及結(jié)構(gòu)；

• - 更新 GDScript 腳本中關(guān)鍵字、注解的使用，同時修改類型名稱；

例如，Godot 4.x 中的 RPC 標注與 Godt 3.5 中的關(guān)鍵字等價關(guān)系：

文件描述符號是場景文件的開頭區(qū)段，定義場景文件的格式版本和加載步驟數(shù)：外部資源數(shù)量+場景文件本身。即使 load_steps 數(shù)值不正確，引擎還是會加載場景文件，但會影響使用這個值的代碼。

除了外部資源，場景文件還可以內(nèi)嵌資源，比如節(jié)點內(nèi)嵌的腳本，分別使用 `ExtResource` 和 `SubResource` 引用 ID 指定的外部資源和內(nèi)嵌資源。內(nèi)嵌資源包括 meshes, materials, GDScript 等等數(shù)據(jù)。

比如以下場景文件，根節(jié)點引用了內(nèi)嵌腳本資源，內(nèi)嵌資源使用 [sub_resource] 實體定義，并通過資源屬性 `script/source` 指定腳本源代碼，代碼按原樣直接緊接資源屬性的 = 后面，并使用雙引號包括，源代碼中的雙引號和 \ 會被轉(zhuǎn)義為 \" 和 \\：

節(jié)點和外部資源是場景樹層次結(jié)構(gòu)組織的基本方式，[ext_resource] 實體定義外部資源，[node] 定義節(jié)點。場景文件中第一個定義節(jié)點即為場景的根節(jié)點，子節(jié)點通過 parent 屬性指定父級節(jié)點。

場景樹中一些節(jié)點需要引用其它節(jié)點，場景文件中需要使用``NodePath(Path/To/Node)``來指定節(jié)點路徑，比如，MeshInstance3D 中的骨架屬性，需要使用``NodePath()``引用指定骨架節(jié)點。動畫節(jié)點 Animation 也類似地使用``NodePath()``引用指定節(jié)點的屬性：

此外，場景文件中還有其它許多不同的節(jié)點類型，及數(shù)據(jù)格式，參考 TSCN 文件格式文檔。

源代碼中定義了文本資源加載器，使用 is_scene 指示加載的是 TSCN 場景資源文件，即等同 [gd_scene]。

ResourceLoaderText::open() 負責打開文本資源文件，并通過 VariantParser::parse_tag() 解析資源文件中的實體定義。VariantParser::parse_value() 中定義了支持使用的數(shù)據(jù)類型：