godot-composition-apps

Godot 组合与架构（应用与 UI）

决策门槛 — 应用还是游戏实体

根节点 / 任务	路径
Control、EditorPlugin、工具窗口、设置停靠栏、表单 UI	留在此处 — 编排器 + 组件
Player、Enemy、Weapon、Hitbox、游戏玩法 CharacterBody	godot-composition — 不适用此技能

仅限应用的门槛： 如果节点是游戏玩法角色（Player/Enemy/Weapon/Hitbox），请使用 godot-composition。此技能负责 Control / EditorPlugin / 工具 组合。

核心理念

判断标准（石头测试）

编写脚本前，请先问：“如果把这个脚本附加到一块真正的石头上，它还能正常工作吗？”

• 通过： 石头上的 AuthComponent 能让石头登录。（与上下文无关）
• 未通过： 石头上的 LoginForm 脚本试图获取石头并不存在的文本字段。（存在耦合）

必须执行： 使用 comp_rock_test_boilerplate.gd 验证新组件。

背包模型（有 > 是）

将根节点视为空的背包。

• 错误： SubmitButton 继承自 AnimatedButton，后者继承自 BaseButton。
• 正确： 根节点拥有 AnimationComponent，并且拥有 NetworkRequestComponent。

权力层级（通信规则）

方向	来源 → 目标	方法	原因
向下	编排器 → 组件	函数调用	管理器负责管理工作者。
向上	组件 → 编排器	信号	工作者不了解外部情况。
横向	组件 A ↔ 组件 B	禁止	同级组件不得直接通信。

横向通信的解决方法： 组件 A 向编排器发送信号；编排器调用组件 B。

可用脚本

必须执行：实现相应模式前，请先阅读匹配的脚本。不要在代码中内联重造编排器连线逻辑。

comp_rock_test_boilerplate.gd

必须首先阅读 — 将候选脚本附加到真正石头上的测试框架，可及早发现强耦合组件。

comp_orchestrator_base.gd

创建任何应用 / UI 根节点时必须使用 — 信号向上 / 调用向下的连线骨架（业务计算为 0%）。

comp_logic_visual_syncer.gd

VLS 必须使用 — 逻辑发出 state_changed；视觉效果 / 动画作出响应，而逻辑无需了解 AnimationPlayer / Theme。

comp_base_component.gd

用于应用工作者的共享组件生命周期管理与依赖项验证。

comp_dependency_injector.gd

通过带类型的导出 / 注册表注入，避免编排器依赖脆弱的 $ 路径。

clipboard_copier.gd

与上下文无关的剪贴板工作者 — 搭配编排器 Toast 模式使用（参见参考资料）。

comp_data_driven_config.gd

为工具设置和表单默认值提供由 Resource 支持的配置。

comp_persistence_component.gd

可保存的 UI / 工具状态必须使用 — 注册 Saveable 组和 get_save_data()，无需在视觉层中处理 I/O。

comp_ability_sequencer.gd

将有序的多步骤工具工作流（向导页面、导出流水线）作为子步骤处理。

comp_health_component.gd / comp_hitbox_component.gd

仅当应用 / 工具需要模拟实体时使用；真实游戏优先使用 godot-composition。

编排器模式

根脚本（LoginScreen.gd、UserProfile.gd、EditorPlugin 停靠面板根节点）是编排器：

• 数学／逻辑：0% · 状态连接：100%
• 职责：监听组件信号 → 调用其他组件方法

强制要求： 扩展 comp_orchestrator_base.gd 中的模式。

概念	应用／UI 示例
编排器	UserProfile.gd / Editor 停靠面板根节点
逻辑组件	AuthValidator
VLS	通过 comp_logic_visual_syncer.gd 实现的 AuthVisualSyncer
主题所有权	使用独立的主题组件——绝不在表单逻辑中修改主题
焦点所有权	编排器分配／释放 Control 焦点；组件绝不抢占同级节点的焦点

实现标准

1. 类型安全 — 组件使用 class_name；核心架构中不得使用无类型声明。
2. 依赖注入 — @export var auth: AuthComponent（Inspector / %UniqueNames）。绝不使用 get_node("Path/To/Child") 获取组件。
3. 无状态工作组件 — 编排器将数据传入函数；组件不得从同级 Control 中抓取数据。

绝不做（专家架构规则）

层级与依赖

• 绝不使用 get_parent() 获取数据 — 通过 @export 或函数参数注入。
• 绝不横向通信 — 信号向上发送；编排器向下调用。
• 绝不使用脆弱的节点路径 — 优先使用 @export / %。

逻辑与状态

• 绝不在编排器中编写业务逻辑 — 只允许作为委托器的 _on_signal。
• 绝不在单个组件中存储全局状态 — 使用共享 Context Resource 或 Autoload。
• 绝不假定组件的父节点是特定类型 — 这会导致摇滚测试失败。

润色与编排

• 绝不跳过信号清理 — 退出时断开连接／在适当情况下使用 CONNECT_ONE_SHOT。
• 绝不让逻辑层了解视觉层 — 发出信号；由 VLS／编排器播放动画并应用 Theme。

脆弱的应用工作流：可保存性 + 主题所有权

不要在表单 Control 中执行保存 I/O 或修改 Theme。应通过组件处理：

1. 编排器（或专用的 Saveable 子节点）上必须有 comp_persistence_component.gd — add_to_group("Saveable") + get_save_data()。
2. Theme／StyleBox 的更改应由主题组件 (theme_manager.gd) 处理；逻辑发出成功／失败信号后，由编排器向下调用该组件。
3. 焦点：验证失败后由编排器负责调用 grab_focus()，使逻辑保持与 Control 无关。

# settings_dock_orchestrator.gd (pattern — wire via @export, not $)
extends Control
@export var persistence: CompPersistenceComponent
@export var theme_mgr: Node  # theme_manager.gd API
@export var form_logic: Node

func _ready() -> void:
    form_logic.settings_valid.connect(_on_settings_valid)
    form_logic.settings_invalid.connect(_on_settings_invalid)

func _on_settings_valid(payload: Dictionary) -> void:
    theme_mgr.apply_user_theme(payload.get("theme_id"))
    # Save systems collect via Saveable group — persistence component stays dumb

func _on_settings_invalid(field: StringName) -> void:
    # Orchestrator owns focus; logic never touches sibling LineEdits
    var target := get_node_or_null("%" + String(field))
    if target is Control:
        target.grab_focus()

专家组合模式（应用）

1. 应用级服务定位器

对于轻量级非 Node 服务（Auth、Config），优先使用 Engine.register_singleton()，而不是创建数十个 Autoload Node [6]。

2. 视觉-逻辑同步器（VLS）

强制要求使用 comp_logic_visual_syncer.gd — 逻辑绝不调用 AnimationPlayer.play()。

3. O(1) 组件注册表

编排器使用 Dictionary 注册表管理仪表板模块——仍然禁止横向调用；注册表是编排器私有的查找结构。

强制要求： 剪贴板／分享编排器示例和服务定位器的详细内容请参阅 app-orchestrator-examples.md。如果 comp_orchestrator_base.gd 已涵盖你的屏幕，则不要加载此文件。

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接；在需要转向相关领域时加载相关技能——不要预加载整个技能体系。

官方文档

• 场景组织 — 规范的信号向上、调用向下所有权模式，让 Orchestrator 能够连接组件，而不让兄弟节点相互耦合。
• 何时以及如何避免所有内容都使用节点 — 纯数据和逻辑服务优先使用 Resources/RefCounted，让组件保持精简且易于彻底测试。
• Godot 接口 — 鸭子类型方法契约（has_method），让组合无需依赖深层继承树即可运作。
• Godot 类是什么？ — 说明 Godot 为何更倾向于场景组合（Has-A），而非用于可复用行为的经典 Is-A 层次结构。
• 使用信号 — 组件向上发送至 Orchestrator 的事件，让工作组件无需了解父节点和兄弟节点。
• GDScript 导出变量 — 类型化的 @export 依赖注入，可取代脆弱的 Inspector get_node 路径。
• 场景唯一节点 — 使用 %UniqueName 在 Orchestrator 内连接 Control/Button，避免字符串路径脆弱易变。
• 资源 — 使用数据驱动的 .tres 配置，让数值与逻辑组件分离。
• 分组 — 批量注册（例如 Saveable/Components），让 Orchestrator 注册表无需硬编码兄弟节点引用。
• Autoload 与常规节点 — 了解在应用/UI 组合中，何时场景内的 Orchestrator 比全局 Autoload 更合适。
• 单例（Autoload） — 在确有必要使用真正的应用级定位器时，安全注册跨场景服务。
• 保存游戏 — 可自然适配模块化可保存组件的持久化模式。

相关技能

前置条件

• godot-project-foundations — 项目布局、Autoload 注册和场景所有权，为 Orchestrator 和组件提供接入基础。
• godot-gdscript-mastery — 依赖注入和易于彻底测试的组件所需的类型化导出变量、信号和 class_name 熟练度。
• godot-composition — 核心 Has-A 组件模型（面向游戏的同类技能）；本技能针对 Apps/Tools/UI 专门应用相同规则。

补充

• godot-signal-architecture — 连接标志、幽灵清理以及 Orchestrator 用于向上连线的 EventBus 模式。
• godot-autoload-architecture — 当组合需要使用精简的全局服务，而非场景本地状态时，了解启动顺序和所有权。
• godot-resource-data-patterns — 为数据驱动组件提供自定义资源和可热切换的 .tres 配置。
• godot-ui-containers — Control 树应向上发出意图信号，而 Orchestrator 则向下调用布局。
• godot-ui-theming — 在 VLS 模式下，主题／视觉同步器与身份验证／表单逻辑保持分离。
• godot-scene-management — 场景切换必须重新注入导出项并重新连接 Orchestrator 连线，不使用横向的同级节点链接。
• godot-testing-patterns — 使用 Rock 测试和信号间谍，验证组件始终与上下文无关。

下游／使用方

• godot-save-load-systems — 使用 Saveable 组持久化组件，实现模块化应用状态。
• godot-ability-system — 将能力节点作为子组件，由 Orchestrator 排序调用，避免继承树。
• godot-state-machine-advanced — 状态节点与逻辑／视觉同步器并列组合；FSM 负责管理转换，而非同级节点之间的相互调用。

主入口

• godot-master — 库路由器和镜像模块入口；发现哪个领域技能负责处理跨领域架构问题时，请打开此项。