Godot 场景摆放

内容定义在哪：有位置、有外观的东西摆进 .tscn，代码只管规则和运行时才出现的东西。

验收标准：不运行游戏，在编辑器里拖动灯、NPC、血条，存盘后游戏里同样改变。

范围

先查内置

• 默认直接导出 Texture2D，拖进 Inspector
• 有资源表或 MOD 覆盖时导出 ID 字符串，@tool 里解析成贴图

做法

自查

动手前先确认项目现在的做法，细节和脚本见 references/audit.md：

1. 读几个现有 .tscn，看节点数和游戏画面对不对得上
2. 搜脚本里的 .new() 加 add_child、给 Control 设 position size、load 贴图
3. 搜配表里的坐标、贴图路径、颜色字段
4. 无头跑审计脚本，数 _ready 后多出的、owner 为空的节点

• 程序生成的地图、按数据数量建的列表行属于运行时内容，不算问题

内容归属

• 同一项只有一个来源，外观不在场景和配表里各写一份

新做场景

关卡的树，每一项都是存盘的节点，重复的东西是预制场景实例：

Level            Node2D  level.gd
├ Background     Parallax2D / Sprite2D
├ Ground         TileMapLayer
├ Props          Node2D / crate.tscn 实例若干
├ Npcs           Node2D / npc.tscn 实例 覆盖朝向和对话 ID
├ SpawnPoints    Node2D / Marker2D 若干
└ Hud            hud.tscn 实例

不开编辑器时用一次性脚本生成，godot --headless -s make_level.gd，跑完删掉脚本：

extends SceneTree

func _initialize() -> void:
	var level := Node2D.new()
	level.name = "Level"
	var points := Node2D.new()
	points.name = "SpawnPoints"
	level.add_child(points)
	points.owner = level
	for i in 3:
		var marker := Marker2D.new()
		marker.name = "Spawn%d" % i
		marker.position = Vector2(200.0 * i, 0.0)
		points.add_child(marker)
		marker.owner = level
	var packed := PackedScene.new()
	packed.pack(level)
	ResourceSaver.save(packed, "res://level.tscn")
	level.free()
	quit()

• 每个后代都设 owner 为场景根，只设直接子节点不够
• 实例化的子场景只给它的根设 owner
• 编辑器里的场景根是 EditorInterface.get_edited_scene_root()
• 小场景可直接写 tscn 文本，注意事项见 godot-scene-architecture

脚本只取场景里摆好的节点，运行时内容从预制场景实例化：

extends Node2D

@export var enemy_scene: PackedScene
@onready var spawn_points: Node2D = $SpawnPoints

func spawn_wave() -> void:
	for point: Node in spawn_points.get_children():
		var enemy := enemy_scene.instantiate() as Node2D
		enemy.position = (point as Node2D).position
		add_child(enemy)

自绘节点

Sprite2D 能表达的用 Sprite2D。需要自己语义的节点，如按米算高度，同样按导出属性在编辑器里画出来：

@tool
class_name GroundProp
extends Node2D

@export var texture: Texture2D:
	set(value):
		texture = value
		queue_redraw()
@export var height: float = 64.0:
	set(value):
		height = value
		queue_redraw()

func _draw() -> void:
	if texture == null:
		return
	var size := texture.get_size() * (height / texture.get_height())
	draw_texture_rect(texture, Rect2(Vector2(-size.x / 2.0, -size.y), size), false)

• 存盘的是节点和导出属性，画法跟着脚本走
• setter 里只 queue_redraw() 或改自身状态
• setter 在进树前就会调用，用到树的操作先判断 is_inside_tree()

派生属性

_ready 或 setter 里按环境算出的属性，如按视口选的 material、按深度算的 z_index，存盘时照样写进 tscn。用 _validate_property 去掉存盘位：

@tool
extends Node2D

@export var depth: float = 0.0:
	set(value):
		depth = value
		z_index = -10 if depth > 0.0 else 10

func _validate_property(property: Dictionary) -> void:
	if property.name == "z_index":
		property.usage &= ~PROPERTY_USAGE_STORAGE

• 对继承来的引擎属性也生效，脚本须是 @tool
• 去掉后场景里手设的值也不存，该属性只能由代码决定

节点自己生成、不属于内容的子节点，如地面条、阴影，用 internal 子节点，不设 owner：

@tool
extends Node2D

var _shadow: Sprite2D

func _ready() -> void:
	_shadow = Sprite2D.new()
	_shadow.modulate = Color(0.0, 0.0, 0.0, 0.4)
	add_child(_shadow, false, Node.INTERNAL_MODE_BACK)

• 只不设 owner 时，复制节点会连生成的子节点一起复制，新节点 _ready 再建一份
• 设了 owner 的 internal 子节点照样存盘，读回来变成普通子节点

存盘导出

确定性模拟、回滚联机、服务器不依赖场景树时，位置照样摆在场景里，存盘时导出成数据文件一起提交：

@tool
extends Node2D

@export_file("*.json") var export_path: String = "res://room_points.json"

func _notification(what: int) -> void:
	if what == NOTIFICATION_EDITOR_PRE_SAVE:
		export_points()

func export_points() -> void:
	var points: Array[Dictionary] = []
	for child: Node in get_children():
		var marker := child as Marker2D
		if marker != null:
			points.append({"name": String(marker.name), "x": marker.position.x, "y": marker.position.y})
	var file := FileAccess.open(export_path, FileAccess.WRITE)
	file.store_string(JSON.stringify({"points": points}, "\t"))

• 只在编辑器里、打包场景前发给被存场景的每个节点
• 这时节点被锁，add_child remove_child 报错，只能读写属性和文件
• 统一导出放在插件里时连 EditorPlugin.scene_saved，文件写盘后调用

编辑器视口

• 材质按 get_viewport() 在进树后选
• _process 里每帧 queue_redraw() 会让编辑器一直刷新
• _exit_tree 里释放的东西在 _enter_tree 里补回
• 改了全局着色器参数、静态缓存的节点，在 _exit_tree 里还原
• 换场景时先 remove_child() 再 queue_free()，否则旧节点帧末出树会还原掉新设的值
• 只在当前编辑场景里做的事，判断 is_part_of_edited_scene()，_ready 里可用

陷阱

参考

• references/csharp.md：C# 项目先读，本文各节示例的 C# 写法、[Tool] 热重载
• references/audit.md：自查清单、搜索命令、无头审计脚本、报告格式
• references/migration.md：迁移顺序、坐标换算、无头编辑器验证插件、常见报错
• https://docs.godotengine.org/en/stable/tutorials/best_practices/scenes_versus_scripts.html
• https://docs.godotengine.org/en/stable/tutorials/best_practices/scene_organization.html
• https://docs.godotengine.org/en/stable/tutorials/plugins/running_code_in_the_editor.html