/godot-tscn-format

name: godot-tscn-format
description: >-
  Godot 4.x .tscn 场景文件纯文本格式规范与 AI 操作指南 — 文件结构、资源引用、
  Transform 变换、属性值格式、信号连接，以及 AI 直接读写 .tscn 文件的操作方法。
version: 1.0.0

Godot .tscn 场景文件格式规范

> **用途**：让 AI 能够直接读写 Godot 场景文件 > **版本**：v1.0 · 2026-04-24 > **适用引擎**：Godot 4.x

---

核心原则

**Godot 场景文件是纯文本**，AI 可以直接通过 `write_to_file` 和 `replace_in_file` 操作，无需任何中间层。

---

一、文件结构总览

[gd_scene load_steps=N format=3 uid="uid://xxx"]    ← 头部（必需）

[ext_resource type="Type" path="res://..." id="ID"]  ← 外部资源引用（可选）
[ext_resource ...]

[sub_resource type="Type" id="ID"]                   ← 内嵌资源定义（可选）
property = value
[sub_resource ...]

[node name="Name" type="Type"]                       ← 根节点（必需）
property = value

[node name="Child" type="Type" parent="."]           ← 子节点
property = value

[connection signal="sig" from="Node" to="Target" method="func"]  ← 信号连接（可选）

---

二、头部声明

2.1 基本格式

[gd_scene load_steps=4 format=3]

| 字段 | 说明 | |------|------| | `load_steps` | 资源加载步数 = ext_resource 数 + sub_resource 数 + 1（场景本身） | | `format` | 固定为 `3`（Godot 4.x） | | `uid` | 可选，Godot 自动生成的唯一 ID，创建时可省略 |

2.2 计算 load_steps

load_steps = len(ext_resources) + len(sub_resources) + 1

示例：2 个外部资源 + 3 个内嵌资源 → `load_steps=6`

---

三、外部资源引用 (ext_resource)

3.1 格式

[ext_resource type="Type" path="res://path/to/file" id="ID"]

3.2 常见类型

| type | 文件类型 | 示例 | |------|----------|------| | `Script` | GDScript | `path="res://scripts/player.gd"` | | `PackedScene` | 场景 | `path="res://scenes/enemy.tscn"` | | `Material` | 材质资源 | `path="res://materials/floor.tres"` | | `Texture2D` | 2D 纹理 | `path="res://textures/icon.png"` | | `AudioStream` | 音频 | `path="res://audio/shoot.wav"` | | `Shader` | 着色器 | `path="res://shaders/outline.gdshader"` |

3.3 ID 命名规范

AI 生成时使用有意义的 ID：

[ext_resource type="Script" path="res://scripts/player.gd" id="1_player_script"]
[ext_resource type="Material" path="res://resources/floor_mat.tres" id="2_floor_mat"]
[ext_resource type="PackedScene" path="res://scenes/bullet.tscn" id="3_bullet_scene"]

---

四、内嵌资源定义 (sub_resource)

4.1 格式

[sub_resource type="Type" id="ID"]
property1 = value1
property2 = value2

4.2 常用碰撞形状

# 胶囊体（角色常用）
[sub_resource type="CapsuleShape3D" id="CapsuleShape3D_player"]
radius = 0.35
height = 1.8

# 球体
[sub_resource type="SphereShape3D" id="SphereShape3D_001"]
radius = 0.5

# 盒子
[sub_resource type="BoxShape3D" id="BoxShape3D_floor"]
size = Vector3(10, 0.2, 10)

# 圆柱体
[sub_resource type="CylinderShape3D" id="CylinderShape3D_001"]
height = 2.0
radius = 0.5

# 2D 形状
[sub_resource type="RectangleShape2D" id="RectangleShape2D_001"]
size = Vector2(32, 32)

[sub_resource type="CircleShape2D" id="CircleShape2D_001"]
radius = 16.0

4.3 常用网格

# 盒子网格
[sub_resource type="BoxMesh" id="BoxMesh_001"]
size = Vector3(1, 1, 1)

# 球体网格
[sub_resource type="SphereMesh" id="SphereMesh_001"]
radius = 0.5
height = 1.0

# 胶囊网格
[sub_resource type="CapsuleMesh" id="CapsuleMesh_001"]
radius = 0.5
height = 2.0

# 圆柱网格
[sub_resource type="CylinderMesh" id="CylinderMesh_001"]
top_radius = 0.5
bottom_radius = 0.5
height = 2.0

# 平面网格
[sub_resource type="PlaneMesh" id="PlaneMesh_001"]
size = Vector2(10, 10)

4.4 材质（内嵌）

[sub_resource type="StandardMaterial3D" id="Material_red"]
albedo_color = Color(1, 0, 0, 1)
roughness = 0.8
metallic = 0.2

# 发光材质
[sub_resource type="StandardMaterial3D" id="Material_glow"]
emission_enabled = true
emission = Color(1, 0.8, 0, 1)
emission_energy_multiplier = 2.0

---

五、节点声明 (node)

5.1 根节点

[node name="Player" type="CharacterBody3D"]
script = ExtResource("1_player_script")

5.2 子节点

[node name="ChildName" type="NodeType" parent="."]
property = value

| parent 值 | 含义 | |-----------|------| | `.` | 直接子节点（父节点是根） | | `ParentName` | 指定父节点名 | | `Parent/Child` | 嵌套路径 |

5.3 引用资源

# 引用外部资源
script = ExtResource("1_player_script")
mesh = ExtResource("2_mesh")

# 引用内嵌资源
shape = SubResource("CapsuleShape3D_player")
mesh = SubResource("BoxMesh_001")

5.4 实例化场景

[node name="Enemy1" parent="Enemies" instance=ExtResource("4_enemy_scene")]
transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 5, 0, -10)

---

六、Transform 变换

6.1 Transform3D 格式

transform = Transform3D(bx.x, bx.y, bx.z, by.x, by.y, by.z, bz.x, bz.y, bz.z, ox, oy, oz)

| 参数 | 含义 | |------|------| | bx (1-3) | X 轴基向量 | | by (4-6) | Y 轴基向量 | | bz (7-9) | Z 轴基向量 | | o (10-12) | 位置 (origin) |

6.2 常用变换

# 单位变换（默认位置）
transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)

# 仅位置
transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 5, 2, -10)

# 位置 + 缩放 0.5
transform = Transform3D(0.5, 0, 0, 0, 0.5, 0, 0, 0, 0.5, 5, 2, -10)

# 绕 Y 轴旋转 90°（sin90=1, cos90=0）
transform = Transform3D(0, 0, 1, 0, 1, 0, -1, 0, 0, 0, 0, 0)

6.3 Transform2D 格式

transform = Transform2D(cos, sin, -sin, cos, x, y)

# 单位变换
transform = Transform2D(1, 0, 0, 1, 100, 200)

# 旋转 45° 位于 (100, 200)
transform = Transform2D(0.707, 0.707, -0.707, 0.707, 100, 200)

---

七、常用属性值格式

7.1 基础类型

# 布尔
visible = true
enabled = false

# 整数
health = 100

# 浮点
speed = 10.5

# 字符串
name = "Player"

7.2 向量

# Vector2
position = Vector2(100, 200)
size = Vector2(32, 32)

# Vector3
position = Vector3(0, 1.5, 0)
target_position = Vector3(0, 0, -100)

# Vector4
custom_data = Vector4(1, 2, 3, 4)

7.3 颜色

# Color(R, G, B, A) 范围 0.0-1.0
light_color = Color(1, 0.85, 0.3, 1)
albedo_color = Color(0.25, 0.25, 0.3, 1)

# 半透明
modulate = Color(1, 1, 1, 0.5)

7.4 数组

# PackedStringArray
config/features = PackedStringArray("4.6", "Forward Plus")

# PackedVector2Array
polygon = PackedVector2Array(0, 0, 100, 0, 100, 100, 0, 100)

# 普通数组
groups = ["enemy", "damageable"]

---

八、信号连接 (connection)

8.1 格式

[connection signal="signal_name" from="NodePath" to="TargetPath" method="method_name"]

8.2 示例

# 同级节点连接
[connection signal="time