godot-tres-format

Godot .tres 资源文件格式规范

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

---

核心原则

Godot 资源文件是纯文本，AI 可以直接通过 write_to_file 创建材质、形状、环境等资源。

---

一、文件结构

[gd_resource type="ResourceType" format=3 uid="uid://xxx"]

[resource]
property1 = value1
property2 = value2

---

二、材质资源 (StandardMaterial3D)

2.1 基础材质

[gd_resource type="StandardMaterial3D" format=3]

[resource]
albedo_color = Color(0.8, 0.2, 0.2, 1)
roughness = 0.8
metallic = 0.0

2.2 金属材质

[gd_resource type="StandardMaterial3D" format=3]

[resource]
albedo_color = Color(0.9, 0.9, 0.9, 1)
roughness = 0.3
metallic = 0.9
metallic_specular = 0.5

2.3 发光材质

[gd_resource type="StandardMaterial3D" format=3]

[resource]
albedo_color = Color(1, 0.8, 0, 1)
emission_enabled = true
emission = Color(1, 0.8, 0, 1)
emission_energy_multiplier = 3.0

2.4 透明材质

[gd_resource type="StandardMaterial3D" format=3]

[resource]
transparency = 1
albedo_color = Color(0.2, 0.5, 1, 0.5)

2.5 无光照材质

[gd_resource type="StandardMaterial3D" format=3]

[resource]
shading_mode = 0
albedo_color = Color(1, 1, 1, 1)

2.6 带纹理材质

[gd_resource type="StandardMaterial3D" load_steps=2 format=3]

[ext_resource type="Texture2D" path="res://textures/brick.png" id="1_albedo"]

[resource]
albedo_texture = ExtResource("1_albedo")
roughness = 0.9

---

三、常用材质属性参考

属性	类型	说明
albedo_color	Color	基础颜色
albedo_texture	Texture2D	颜色贴图
roughness	float (0-1)	粗糙度，0=光滑，1=粗糙
metallic	float (0-1)	金属度
metallic_specular	float (0-1)	金属高光
emission_enabled	bool	启用发光
emission	Color	发光颜色
emission_energy_multiplier	float	发光强度倍数
transparency	int	0=不透明, 1=Alpha, 2=预乘Alpha
cull_mode	int	0=背面剔除, 1=正面剔除, 2=不剔除
shading_mode	int	0=无光照, 1=逐顶点, 2=逐像素(默认)
normal_enabled	bool	启用法线贴图
normal_texture	Texture2D	法线贴图
normal_scale	float	法线强度

---

四、环境资源 (Environment)

4.1 基础室外环境

[gd_resource type="Environment" format=3]

[resource]
background_mode = 1
background_color = Color(0.4, 0.6, 0.9, 1)
ambient_light_source = 2
ambient_light_color = Color(0.5, 0.5, 0.6, 1)
ambient_light_energy = 0.5
tonemap_mode = 2
tonemap_white = 6.0
ssao_enabled = true
ssil_enabled = true
glow_enabled = true

4.2 室内环境

[gd_resource type="Environment" format=3]

[resource]
background_mode = 1
background_color = Color(0.1, 0.1, 0.15, 1)
ambient_light_source = 1
ambient_light_color = Color(0.3, 0.3, 0.35, 1)
ambient_light_energy = 0.3
ssao_enabled = true
ssao_intensity = 2.0

4.3 带天空盒环境

[gd_resource type="Environment" load_steps=2 format=3]

[sub_resource type="Sky" id="Sky_001"]
sky_material = SubResource("ProceduralSkyMaterial_001")

[sub_resource type="ProceduralSkyMaterial" id="ProceduralSkyMaterial_001"]
sky_top_color = Color(0.3, 0.5, 0.9, 1)
sky_horizon_color = Color(0.7, 0.8, 0.95, 1)
ground_bottom_color = Color(0.2, 0.2, 0.2, 1)
ground_horizon_color = Color(0.5, 0.5, 0.5, 1)
sun_angle_max = 30.0

[resource]
background_mode = 2
sky = SubResource("Sky_001")
ambient_light_source = 3
tonemap_mode = 2

---

五、物理材质 (PhysicsMaterial)

[gd_resource type="PhysicsMaterial" format=3]

[resource]
friction = 0.8
rough = true
bounce = 0.2
absorbent = false

属性	说明
friction	摩擦力 (0-1)
rough	粗糙模式
bounce	弹性 (0-1)
absorbent	吸收模式

---

六、渐变资源 (Gradient)

6.1 线性渐变

[gd_resource type="Gradient" format=3]

[resource]
offsets = PackedFloat32Array(0, 0.5, 1)
colors = PackedColorArray(1, 0, 0, 1, 1, 1, 0, 1, 0, 1, 0, 1)

6.2 用于粒子的渐变

[gd_resource type="Gradient" format=3]

[resource]
offsets = PackedFloat32Array(0, 0.3, 0.7, 1)
colors = PackedColorArray(1, 1, 1, 1, 1, 0.8, 0.2, 1, 1, 0.2, 0, 0.5, 0.5, 0.1, 0, 0)

---

七、曲线资源 (Curve)

7.1 基础曲线

[gd_resource type="Curve" format=3]

[resource]
min_value = 0.0
max_value = 1.0
_data = [Vector2(0, 0), 0.0, 0.0, 0, 0, Vector2(0.5, 1), 0.0, 0.0, 0, 0, Vector2(1, 0), 0.0, 0.0, 0, 0]
point_count = 3

7.2 淡入淡出曲线

[gd_resource type="Curve" format=3]

[resource]
_data = [Vector2(0, 0), 0.0, 2.0, 0, 1, Vector2(0.2, 1), 0.0, 0.0, 0, 0, Vector2(0.8, 1), 0.0, 0.0, 0, 0, Vector2(1, 0), -2.0, 0.0, 1, 0]
point_count = 4

---

八、样式盒资源 (StyleBox)

8.1 扁平样式盒

[gd_resource type="StyleBoxFlat" format=3]

[resource]
bg_color = Color(0.2, 0.2, 0.25, 1)
border_width_left = 2
border_width_top = 2
border_width_right = 2
border_width_bottom = 2
border_color = Color(0.4, 0.4, 0.5, 1)
corner_radius_top_left = 8
corner_radius_top_right = 8
corner_radius_bottom_right = 8
corner_radius_bottom_left = 8

8.2 按钮样式

[gd_resource type="StyleBoxFlat" format=3]

[resource]
bg_color = Color(0.3, 0.5, 0.8, 1)
corner_radius_top_left = 4
corner_radius_top_right = 4
corner_radius_bottom_right = 4
corner_radius_bottom_left = 4
shadow_color = Color(0, 0, 0, 0.3)
shadow_size = 2
shadow_offset = Vector2(0, 2)

---

九、着色器材质 (ShaderMaterial)

9.1 内联着色器

[gd_resource type="ShaderMaterial" load_steps=2 format=3]

[sub_resource type="Shader" id="Shader_001"]
code = "shader_type spatial;

uniform vec4 albedo_color : source_color = vec4(1.0);
uniform float metallic : hint_range(0, 1) = 0.0;

void fragment() {
    ALBEDO = albedo_color.rgb;
    METALLIC = metallic;
}
"

[resource]
shader = SubResource("Shader_001")
shader_parameter/albedo_color = Color(1, 0, 0, 1)
shader_parameter/metallic = 0.5

9.2 引用外部着色器

[gd_resource type="ShaderMaterial" load_steps=2 format=3]

[ext_resource type="Shader" path="res://shaders/custom.gdshader" id="1_shader"]

[resource]
shader = ExtResource("1_shader")
shader_parameter/speed = 2.0
shader_parameter/amplitude = 0.1

---

十、动画资源 (Animation)

10.1 简单位置动画

[gd_resource type="Animation" format=3]

[resource]
resource_name = "move_right"
length = 1.0
loop_mode = 0
tracks/0/type = "value"
tracks/0/imported = false
tracks/0/enabled = true
tracks/0/path = NodePath(".:position")
tracks/0/interp = 1
tracks/0/loop_wrap = true
tracks/0/keys = {
"times": PackedFloat32Array(0, 1),
"transitions": PackedFloat32Array(1, 1),
"update": 0,
"values": [Vector3(0, 0, 0), Vector3(5, 0, 0)]
}

10.2 颜色动画

[gd_resource type="Animation" format=3]

[resource]
resource_name = "flash_red"
length = 0.5
tracks/0/type = "value"
tracks/0/path = NodePath("MeshInstance3D:material_override:albedo_color")
tracks/0/keys = {
"times": PackedFloat32Array(0, 0.1, 0.5),
"values": [Color(1, 1, 1, 1), Color(1, 0, 0, 1), Color(1, 1, 1, 1)]
}

---

十一、字体资源 (FontFile)

字体通常是导入的，但可以创建 FontVariation：

[gd_resource type="FontVariation" load_steps=2 format=3]

[ext_resource type="FontFile" path="res://fonts/main.ttf" id="1_font"]

[resource]
base_font = ExtResource("1_font")
variation_opentype = {
"wght": 700
}
spacing_glyph = 2
spacing_top = -2

---

十二、粒子材质 (ParticleProcessMaterial)

[gd_resource type="ParticleProcessMaterial" format=3]

[resource]
emission_shape = 1
emission_sphere_radius = 0.5
direction = Vector3(0, 1, 0)
spread = 30.0
initial_velocity_min = 5.0
initial_velocity_max = 10.0
gravity = Vector3(0, -9.8, 0)
scale_min = 0.5
scale_max = 1.5
color = Color(1, 0.8, 0, 1)

---

十三、AI 操作指南

13.1 创建材质

write_to_file("res://resources/enemy_mat.tres", """
[gd_resource type="StandardMaterial3D" format=3]

[resource]
albedo_color = Color(0.8, 0.2, 0.2, 1)
roughness = 0.7
emission_enabled = true
emission = Color(0.3, 0, 0, 1)
emission_energy_multiplier = 0.5
""")

13.2 创建环境

write_to_file("res://resources/game_env.tres", """
[gd_resource type="Environment" format=3]

[resource]
background_mode = 1
background_color = Color(0.05, 0.05, 0.1, 1)
ambient_light_color = Color(0.2, 0.2, 0.3, 1)
ambient_light_energy = 0.5
ssao_enabled = true
glow_enabled = true
glow_intensity = 0.5
""")

13.3 创建物理材质

write_to_file("res://resources/bouncy.tres", """
[gd_resource type="PhysicsMaterial" format=3]

[resource]
friction = 0.3
bounce = 0.9
""")

---

十四、资源类型速查表

类型	用途	文件
StandardMaterial3D	3D 材质	*.tres
CanvasItemMaterial	2D 材质	*.tres
ShaderMaterial	自定义着色器材质	*.tres
Environment	环境设置	*.tres
PhysicsMaterial	物理材质	*.tres
Gradient	渐变	*.tres
Curve	曲线	*.tres
StyleBoxFlat	UI 样式盒	*.tres
ParticleProcessMaterial	粒子材质	*.tres
Animation	动画	*.tres 或 *.anim
AudioBusLayout	音频总线布局	*.tres
Theme	UI 主题	*.tres

---

十五、颜色速查表

常用颜色

# 基础色
红色: Color(1, 0, 0, 1)
绿色: Color(0, 1, 0, 1)
蓝色: Color(0, 0, 1, 1)
白色: Color(1, 1, 1, 1)
黑色: Color(0, 0, 0, 1)

# 游戏常用
生命条红: Color(0.9, 0.2, 0.2, 1)
能量条蓝: Color(0.2, 0.5, 0.9, 1)
金币黄: Color(1, 0.85, 0, 1)
毒药绿: Color(0.3, 0.9, 0.2, 1)
暗紫色: Color(0.5, 0.2, 0.7, 1)

# UI 色
暗灰背景: Color(0.15, 0.15, 0.2, 1)
边框灰: Color(0.4, 0.4, 0.5, 1)
高亮蓝: Color(0.3, 0.6, 1, 1)
警告橙: Color(1, 0.6, 0.2, 1)
错误红: Color(0.9, 0.3, 0.3, 1)
成功绿: Color(0.3, 0.8, 0.4, 1)