godot-fundamentals

Godot 基础知识

遵循项目现有的 Godot 约定，而不是强行套用初始项目布局。

范围

在以下场景中使用此技能：

• 选择和排列 Node、Node2D、Node3D 和 Control 派生节点。
• 创建可复用场景并实例化 PackedScene 资源。
• 定义和分配内置或自定义 Resource 数据。
• 为场景节点添加类型化 GDScript，并正确使用生命周期回调。
• 配置命名输入操作并选择输入回调。
• 使用 Scene、FileSystem、Inspector、Output、Debugger 和 Remote 场景树。
• 诊断基本的项目、导入、节点路径、变换和场景运行问题。

不要使用此技能引入 SOLID 重构、事件架构、命令或对象池；请使用编程模式技能。不要使用此技能决定全局状态的归属、管理器的生命周期、场景路由或存档边界；请使用游戏架构技能。类型专属的游戏玩法和高级渲染不在此范围内。

编辑前检查

1. 定位 project.godot；不要假定当前目录就是项目根目录。
2. 阅读 config/features 和现有工具，确定准确的 Godot 4.x 版本。避免使用该版本之后才引入的 API。
3. 修改项目配置前，检查 [application]、[autoload]、[input]、[display] 和相关的 [rendering] 设置。
4. 检查附近的 .gd、.tscn、.tres 和 .res 文件。遵循其文件夹布局、命名、缩进、静态类型使用程度、节点命名和信号连接风格。
5. 梳理受影响的场景树：根节点类型、父子节点归属、实例化的子场景、可编辑子节点、导出引用、唯一名称节点，以及局部变换与全局变换。
6. 找到项目常用的运行、测试、检查和格式化命令。条件允许时，先运行基线检查。
7. 切勿编辑生成的 .godot/ 导入或缓存内容；应改动源资源或导入设置。

如果没有 project.godot，请先询问是否要初始化项目，再创建 Godot 专用文件。

实施工作流

1. 用一句可观察的描述说明行为。
2. 选择行为符合需求且范围最小的内置节点。
3. 确定该单元应为节点、可复用场景还是资源中的数据。
4. 先构建场景层级，再编写依赖该层级的代码。
5. 使用带类型的 @export 属性公开由设计人员负责的值；使用带类型的 @onready 属性缓存稳定的子节点引用。
6. 使用命名的 Input Map 操作，而不是物理按键常量。
7. 编写能完成行为的最简类型化脚本。
8. 单独测试已编辑的场景，然后运行项目入口场景。

核心决策

节点和场景

• 首先根据行为选择：可见纹理并不意味着根节点必须是 Sprite2D，可点击对象也不一定需要物理主体。
• 使用 Node2D 作为可变换的 2D 分组根节点，使用 Node3D 处理 3D，使用 Control 构建由布局驱动的 UI，并使用普通 Node 处理场景内的非空间协调工作。
• 当节点分支具有独立身份、会被重复使用或适合单独测试时，将其构建为场景。
• 由最近的场景所有者添加和移除运行时子节点。避免将普通游戏节点直接附加到 SceneTree.root。
• 在树中添加实例后，再设置依赖其父节点的世界空间变换。
• 在常规场景树回调中，优先使用 queue_free()。其所有者释放后，所有已存储的节点引用都应视为无效。

extends Node2D

@export var pickup_scene: PackedScene
@onready var pickups: Node2D = %Pickups

func spawn_pickup(at: Vector2) -> void:
	if pickup_scene == null:
		push_error("Assign Pickup Scene before spawning a pickup.")
		return
	var pickup := pickup_scene.instantiate() as Node2D
	if pickup == null:
		push_error("The configured pickup scene must have a Node2D root.")
		return
	pickups.add_child(pickup)
	pickup.global_position = at

资源

• 对于适合通过检查器编辑、复用或序列化，且独立于实时场景节点的数据，请使用资源。
• 如果多个场景需要共享同一定义，请使用外部 .tres。如果数据仅属于一个场景或资源，请将其保留为内置子资源。
• 假设资源是共享引用。不要将每个实例的可变状态放在共享定义资源中。
• 对于脚本解析时已知的固定依赖，请使用 preload()。只有在运行时才选择路径时，才使用 load() 或线程化加载。
• 对于之后可能持久化的数据，请使用稳定标识符；显示名称和文件路径都不适合作为标识。

输入与回调

• 对于物理移动，请在 _physics_process() 中轮询持续按住的操作。
• 如果应让 UI 优先处理离散游戏事件，请在 _unhandled_input() 中处理。
• 对于不依赖物理且由帧驱动的表现逻辑，请使用 _process()。
• 手动计算速率时，请乘以 delta。调用 move_and_slide() 前，不要将 CharacterBody2D.velocity 乘以 delta，因为速度本身已按每秒计量。
• 对于有意不使用的回调参数，请在名称前加 _。

extends CharacterBody2D

@export_range(0.0, 1200.0, 1.0) var speed: float = 240.0

func _physics_process(_delta: float) -> void:
	var direction := Input.get_vector(
		&"move_left", &"move_right", &"move_up", &"move_down"
	)
	velocity = direction * speed
	move_and_slide()

节点引用

• 如果设计人员应负责连接依赖项，请优先使用导出的类型化引用。
• 仅当节点明确标记为场景唯一节点时，才使用 %StableName。
• 对于由同一场景拥有的私有、稳定子节点，请使用简短的 $Child/Path。
• 不要在帧回调中反复搜索整棵树。
• 不要让脆弱的相对路径跨越可复用场景的边界。

验证

使用项目中已确定的可执行文件和命令。如果项目没有现成命令，可使用检测到的 Godot 可执行文件，通过类似以下的命令执行基本的导入和解析检查：

godot --headless --editor --path <project-root> --quit

然后验证所有相关行为：

• 编辑器导入时没有解析器、资源缺失或无效节点警告。
• 受影响的场景能够以等效于 F6 的方式运行，且不会意外依赖主场景。
• 完整项目能够从其配置的主场景运行。
• 每个新增的 Input Map 操作都存在，且每种预期的设备绑定都能正常工作。
• 实例化和重新设定父节点后，局部变换和全局变换仍然正确。
• 每个场景实例都已分配导出的资源和节点引用。
• Output 和 Debugger 面板中没有新增错误。
• Remote 场景树显示的实例位于预期的所有者节点下，并会在预期时离开场景树。
• 现有自动化测试仍然通过。

报告实际运行的检查，以及无法自动化的编辑器专属检查。

故障模式

• **场景只能从主项目运行：**可复用场景访问了其所有权边界之外的内容。请导出依赖项或提供明确的设置方法。
• **Node not found：**路径、唯一名称标记或场景层级发生了变化。检查实际的 .tscn；不要猜测替代路径。
• **操作似乎不起作用：**Input Map 中缺少该操作或名称拼写错误、UI 消耗了该事件，或者节点的处理模式已禁用或暂停。
• **实例互相影响：**可变状态存储在共享资源中。将运行时状态移到实例中，或有意复制该资源。
• **生成后位置错误：**混用了局部坐标和全局坐标，或在设定父节点前设置了变换。
• **子节点访问结果为 null：**访问发生在 _ready() 之前、该子节点是可选的，或脚本附加在不同结构的场景上。
• **物理效果随帧率变化：**移动逻辑使用了 _process()，或对 delta 的处理不一致。
• **编辑器显示过时资源：**绕过了源文件导入设置，或编辑了生成的缓存文件。

参考资料

• 节点、场景和资源
• 类型化 GDScript 和输入
• 编辑器和调试工作流