---
description: Godot 项目的分层、依赖方向、信号解耦与工程完整性约定
alwaysApply: true
---

# Godot 分层架构

先识别项目已有目录、autoload 和通信方式，再沿用其边界；不要仅为套用规则而创建新框架。

## 依赖方向

- 领域逻辑负责规则、状态与数据，尽量保持可在 headless 环境运行。
- 表现层负责场景、UI、输入、动画、音频和特效，不在回调中复制领域规则。
- 逻辑层不得加载 UI 场景、抓取表现节点或等待表现动画完成。
- UI 将用户意图转为逻辑层公开命令；状态变化通过返回值、可观察状态或信号反馈。
- 跨系统优先用明确接口或信号解耦。若项目已有事件总线，复用其契约；没有时不要强制新建全局总线。

```gdscript
# 表现层只转发意图
func _on_confirm_pressed() -> void:
	entity_service.confirm(entity_id)

# 逻辑层发布状态变化，不直接操作 UI
func confirm(id: StringName) -> void:
	# 更新领域状态
	entity_confirmed.emit(id)
```

## 边界约束

- 信号参数和公开方法是跨层契约；修改时同步调用方、测试与相关文档。
- 避免双向依赖和跨层节点路径。依赖应显式注入或通过稳定接口获取。
- autoload 只承载确需全局生命周期的服务或状态，不把普通功能默认做成单例。
- 新系统先明确所有权、生命周期、可测试边界和失败处理，再决定放置位置。

## 工程完整性

- Godot 版本遵循项目声明；升级引擎或兼容特征前必须说明影响并取得确认。
- 修改 `project.godot`、导出预设、autoload 或输入映射前，先说明运行与构建影响。
- Godot 生成的 UID 与对应资源保持一致，不手工伪造；移动或删除资源时检查引用。
- 外部插件和第三方资源遵守 `dependency-governance`。