用组合模式（Entity-Component）构建可扩展的…

在 Godot 中设计玩家控制器、NPC、敌人、武器或复杂玩法系统时，用「Has-A」组合替代继承来组织节点。

适用场景

解决思路

1. 遵循四条黄金法则：单一职责（一个脚本只做一件事）；封装（组件是「自私的」，只管自身逻辑，不知道谁拥有它）；编排者（根脚本如 player.gd 不做任何逻辑，只管理状态并在组件间传递数据）；解耦（组件通过 Signals 向上通信、通过 Methods 向下调用）。
2. 按决策树选择方案：玩法实体行为（HP、hitbox、移动、交互）用组合（子组件 + 编排者）；跨场景服务（音频总线、存档、网络、经济账本）用 Autoload，不要挂在玩家身上；真正的 is-a 引擎特化（共享生命周期的自定义 Control/Node）才用继承，且极少使用，绝不用于「加一把枪」或「加 HP」。
3. 从 composition_root_init.gd 开始（强制第一步阅读），用带类型的 @export 在 Inspector 或场景中的 %UniqueNames 完成编排者接线；组件查找绝不使用 $ 或 get_node。
4. 按需加载对应组件脚本：生命/死亡用 health_component.gd；伤害区域用 hit_box_component.gd、hurt_box_component.gd；运动用 velocity_component.gd；交互/跟随/视觉同步用 interaction_component.gd、follower_component.gd、visual_sync_component.gd；状态/状态效果用 state_component_vsm.gd、status_effect_component.gd。
5. 连接策略用带类型的导出：不要依赖树顺序，用 @export 加静态类型做显式依赖注入，例如在 player.gd 中声明 @export var health_component: HealthComponent、@export var movement_component: MovementComponent、@export var input_component: InputComponent，并在编辑器中用 % 场景唯一名自动赋值或拖拽赋值。
6. 组件必须定义 class_name 才能被识别为类型；标准模板为 class_name MyComponent extends Node（需要位置时用 Node3D/2D），可持有自己的数据如 @export var stats: Resource，并声明 signal happened_something(value)。
7. 在 _ready() 中调用 _validate_dependencies() 做依赖校验，用 assert(stats != null, "Stats Resource missing on %s" % name) 在开发期尽早失败（注意 assert() 在 release 构建中会被剥离）。
8. 状态-组件模式（FSM）：把复杂行为封装为作为状态的子节点，由父 StateComponent 把生命周期调用委托给当前激活的子节点；强制阅读 state_component_vsm.gd，不要内联粘贴状态机；更深的 VSM/分层 FSM 参考 godot-state-machine-advanced。
9. 组件注册表（O(1) 查找）：在 _ready 中用 Dictionary 按名称或分组编目子节点，避免为兄弟通信做慢速树遍历，例如遍历 get_children() 把 child.name 和 child.get_groups() 写入 _components，再用 get_comp(key) 返回 _components.get(key)。
10. 依赖校验用 @export 加 assert 快速失败，而不是 get_node_or_null 路径（路径在树重排时会失效），例如 assert(health_component != null, "Missing HealthComponent export!")。
11. 性能上不必担心节点数量：Node 很轻量，每个实体加 10-20 个节点没问题，组合带来的组织收益远超 Node 实例的微小内存开销。
12. 绝不使用深继承链（如 Player > Entity > LivingThing > Node），会形成难以重构的脆弱「上帝类」。
13. 绝不用 get_node() 或 $ 查找组件，场景树重排会破坏它，始终用 @export 或 %UniqueNames。
14. 绝不让组件直接引用其父脚本，否则组件无法复用，应使用信号或依赖注入。
15. 绝不把 Input、Physics 和游戏逻辑混在一个脚本里，违反单一职责，应拆分为专门组件。
16. 绝不创建依赖特定 SceneTree 结构的组件，组件应「自私」，只关心自身属性和直接子节点。
17. 绝不用继承来「添加功能」，若想让敌人射击就加 ShootingComponent，而不是让它继承 ShooterEnemy。
18. 绝不硬编码组件依赖，若 CombatComponent 需要 HealthComponent，应在 _ready() 中查找或由父级注入。
19. 绝不把 Godot 节点当作纯数据，节点提供生命周期（_process）和信号；若只需要数据，请用 Resource。
20. 绝不忽略组件中的节点生命周期，对于无论父级状态如何都必须发生的设置/清理，使用 _enter_tree() 和 _exit_tree()。
21. 绝不隐藏组件的访问点，暴露 NodePath 或 Callable 属性，让父级能在 Inspector 中接线组件。

适用边界 · 注意事项

• 跨场景服务（音频总线、存档、网络、经济账本）不适用组合，应使用 Autoload。
• 真正的 is-a 引擎特化（共享生命周期的自定义 Control/Node）属于罕见的继承例外，不适用组合。
• 当 composition_root_init.gd 加一个组件脚本已足够时，不要加载 orchestrator-recipes.md 等更深的编排者配方。