godot

Godot 开发规范

以 Godot 开发者在编辑器中的工作方式来构建：场景优先。所有可见元素都是场景中的节点，所有可复用元素都各自是一个场景，事件通过信号传递，移动由执行移动的节点负责。优先使用原生基础组件——也就是引擎为相应任务提供的组件——仅在没有合适组件时才编写代码。

采信任何建议前，先确认版本：网上的大多数 Godot 资料都针对 Godot 3。请参考 Godot 4 best practices；从 project.godot 中读取项目指定的版本，并使用该版本对应的文档。

步骤

1. 绘制场景树。 在为任何可见内容编写代码之前，先写出它的节点树：有哪些节点，哪些节点有各自的 .tscn，哪个脚本负责哪项工作，哪些信号向上传递、哪些调用向下发出，以及哪些 Resource 保存数据。完成标准：规格说明或设计稿中的每个元素都对应到草图中的一个节点。设计阶段的草图就是工单中的 Godot structure 部分——模板见 references/ticket-section.md。
2. 为每个基础组件做出选择，参见下表。若某一行指向参考资料，在构建对应部分之前先阅读。
3. 在场景中构建。 在 .tscn 文件中编写节点树；由脚本实例化场景并设置其状态。样式、字体和颜色都放在项目的 Theme 中。
4. 通过观察进行验证。 对游戏代码运行 scripts/smell_check.py（它会读取 .gd 和 .tscn），并解决所有问题：要么改用原生基础组件，要么在该行或其上方标注有意为之的例外：# godot-ok: <reason>（在 .tscn 中使用 ; godot-ok: <reason>）。将其接入验证流程，确保非零退出码会导致构建失败。然后捕获每种状态的画面，并为每种转场录制动态片段（--write-movie out.png --fixed-fps 30 --quit-after N），打开这些画面，并逐一与规格说明或设计稿对比。在汇报工作时附上这些内容。完成标准：检查器发现问题时会使构建失败，且检查结果为绿色；你已查看每种状态和转场的画面，并确认它们都符合预期。仅报告游戏“启动”或“运行”不是验证；实际看过的画面才算。

基元

任务	原生基元	风险信号
游戏对象（场地、单位、拾取物、卡牌）	各自拥有场景并进行实例化；通过类型化方法设置状态	用一个 _draw() 绘制所有对象
点击或悬停世界对象	Area2D + CollisionShape2D、input_pickable、mouse_entered / input_event	使用带字面量尺寸的 Rect2(...).has_point(mouse)
文本	Label / RichTextLabel，由主题设置样式	draw_string、ThemeDB.fallback_font
面板、徽章、按钮外观	主题中的 StyleBox，或主题类型变体	在脚本中使用 StyleBoxFlat.new()
静态 UI 布局	.tscn 中的容器和锚点	在 _ready 中通过 Label.new() / add_child 构建 UI
容器上的叠加元素（徽章、边框、点）	使用普通 Control 作为根节点，将容器和叠加元素作为同级节点	通过容器内的偏移量放置子节点，导致它们被拉伸至填满容器
卡牌或面板上的美术	主题中的 StyleBoxTexture、用于边框的 NinePatchRect、用于图片的 TextureRect — references/art.md	在 UI 树中使用 Sprite2D
世界中的美术	Sprite2D、AnimatedSprite2D、TileMapLayer — references/art.md	用 Polygon2D 占位，代替最终美术
子节点需要动画的布局（卡牌手牌、径向菜单）	自定义 Control 计算目标变换；子节点缓动至目标位置 — references/motion.md	在 BoxContainer 中使用带动画的子节点
响应游戏事件	模型发出信号，由视图连接	每帧轮询并比较数组，以猜测发生了什么变化
会变化的列表（手牌、库存）	每个项目保留一个持久视图，并以项目为键；逐个添加和移除	每次变化时释放所有子节点并重新实例化
一次性动作（弹出、抖动、飞向目标）	在移动节点上通过 create_tween() 创建 Tween	通过刷新调用向下传递倒计时浮点数
编写好的多轨动作	AnimationPlayer	手动按顺序编排计时器
会移动的世界对象	在 _physics_process 中移动，并启用物理插值	在启用了插值的节点上于 _process 中设置变换
UI 缓动和视图刷新	_process	在 _physics_process 中处理视觉效果
世界取景	Camera2D	根据字面量视口尺寸布置世界
工具提示	_make_custom_tooltip() 返回一个场景	对游戏内容使用默认的 tooltip_text
可调数据、卡牌和物品定义	保存为 .tres 的 Resource 子类	在脚本中使用常量字典
每个对象的状态	类型化的 var	set_meta / get_meta
节点引用	@onready var x: Type = %Name；在其他脚本会引用的脚本上使用 class_name	未类型化的 @onready var x = $Path

自定义 _draw() 仅适用于三种原生场景：绘制大量简单的重复形状（网格、棋盘）、绘制没有对应节点的形状（轨迹、圆弧、程序生成的多边形），以及绘制自定义控件中非文本的部分。其他情况都应使用节点。

通信

向下调用，向上发信号。父节点调用子节点的方法；子节点发出信号，绝不访问父节点。场景通过拥有它的场景所调用的 setter 或 bind() 接收所需内容，并且单独打开时也能独立运行。

参考资料

• references/ticket-section.md — 每个 Godot 工单都包含的 Godot 结构部分。
• references/motion.md — 目标缓动布局、Tween、拖动和弹回。
• references/ui.md — 主题、容器、UI 与世界之间的输入路由。
• references/art.md — UI 和世界中的美术放置位置，以及像素美术设置。