---
title: Godot 架构集成
description: 说明 AbstractArchitecture、ArchitectureAnchor 和 Godot 模块挂接的当前生命周期语义，以及推荐的初始化路径。
---

# Godot 架构集成

## 概述

`GFramework.Godot` 当前的架构集成目标很直接：让 `Architecture` 能安全地感知 Godot `SceneTree` 生命周期，并在需要时把
带 `Node` 的扩展模块挂到场景树上。

当前真正参与这条链路的核心类型只有三类：

- `AbstractArchitecture`：在原有 `Architecture` 之上增加 Godot 生命周期绑定
- `ArchitectureAnchor`：挂在 `SceneTree.Root` 下的锚点节点，负责把 `_ExitTree()` 事件转回架构销毁
- `IGodotModule` / `AbstractGodotModule`：当模块本身需要携带 Godot `Node` 时使用

它不是另一套独立的模块系统，也不意味着所有模块都必须改成 `InstallGodotModule(...)`。

## 什么时候该用 `AbstractArchitecture`

当你的架构需要满足下面任一条件时，可以让它继承 `AbstractArchitecture`：

- 需要把架构生命周期绑定到 Godot `SceneTree`
- 需要在架构里安装带 `Node` 的扩展模块
- 需要通过受保护的 `ArchitectureRoot` 访问锚点节点，继续挂接 Godot 子节点

如果你只是做普通的 Model / System / Utility 注册，`AbstractArchitecture` 的主要价值仍然是“让架构知道自己何时跟随
Godot 场景树销毁”，而不是改变注册方式。

## 最小接入路径

### 常规模块仍然用 `InstallModule(...)`

当前更稳的默认做法，是保持普通模块注册方式：

```csharp
using GFramework.Core.Abstractions.Architectures;
using GFramework.Core.Abstractions.Environment;
using GFramework.Godot.Architectures;

namespace MyGame.Scripts.Core;

public sealed class GameArchitecture(
    IArchitectureConfiguration configuration,
    IEnvironment environment)
    : AbstractArchitecture(configuration, environment)
{
    protected override void InstallModules()
    {
        InstallModule(new UtilityModule());
        InstallModule(new ModelModule());
        InstallModule(new GameplayModule());
        InstallModule(new SystemModule());
    }
}
```

这里继承 `AbstractArchitecture` 的意义，是把架构绑定到 Godot 生命周期，而不是把普通模块注册改写成 Godot 风格 API。

### 只有携带 `Node` 的模块才需要 `InstallGodotModule(...)`

如果模块本身暴露一个 Godot `Node`，并且希望由架构锚点统一托管，可以这样写：

```csharp
using GFramework.Core.Abstractions.Architectures;
using GFramework.Godot.Architectures;
using Godot;

namespace MyGame.Scripts.Core;

public sealed class HudModule : AbstractGodotModule
{
    private readonly Control _root = new()
    {
        Name = "HudModule"
    };

    public override Node Node => _root;

    public override void Install(IArchitecture architecture)
    {
    }

    public override void OnAttach(GFramework.Core.Architectures.Architecture architecture)
    {
    }

    public override void OnDetach()
    {
        _root.QueueFree();
    }
}
```

这类模块的关键点不是“注册更多框架能力”，而是“让模块节点跟着架构锚点进出场景树”。
真正调用 `InstallGodotModule(...)` 时，也应该把它放在能够接受异步挂接流程的初始化路径里。

## 当前生命周期

### 初始化阶段

`AbstractArchitecture.OnInitialize()` 目前会按这个顺序工作：

1. 生成唯一的锚点节点名称
2. 调用 `AttachToGodotLifecycle()`
3. 在可用的 `SceneTree` 上创建并绑定 `ArchitectureAnchor`
4. 执行你重写的 `InstallModules()`

也就是说，Godot 生命周期绑定先发生，业务模块注册后发生。

### `InstallGodotModule(...)` 的执行顺序

当前实现里，`InstallGodotModule(...)` 会：

1. 检查模块参数是否为 `null`
2. 检查 `_anchor` 是否已初始化
3. 先执行 `module.Install(this)`
4. 把模块登记进内部 `_extensions`
5. `await anchor.WaitUntilReadyAsync()`
6. 通过 `CallDeferred(AddChild, module.Node)` 把模块节点挂到锚点下
7. 调用 `module.OnAttach(this)`

这条顺序有两个实际意义：

- 模块会在挂接节点前先完成框架侧注册
- 只有等锚点真正 ready 后，才进入需要访问 Godot 节点 API 的附加阶段

### 销毁阶段

`ArchitectureAnchor._ExitTree()` 会触发绑定好的退出回调，随后 `AbstractArchitecture` 会开始观察异步销毁流程：

- 防止重复销毁
- 依次调用已登记 Godot 模块的 `OnDetach()`
- 清空内部扩展列表
- 再进入基类 `DestroyAsync()`

如果异步销毁抛异常，当前实现会把错误写到 Godot 错误输出，而不是静默吞掉。

## 当前边界

### 没有锚点时不会偷偷安装模块

`GFramework.Godot.Tests/Architectures/AbstractArchitectureModuleInstallationTests.cs` 已覆盖一个关键边界：

- 当锚点尚未初始化时，`InstallGodotModule(...)` 会直接抛 `InvalidOperationException("Anchor not initialized")`
- 失败发生在 `module.Install(...)` 之前，因此不会留下半安装副作用

这也是为什么 `InstallGodotModule(...)` 更适合放在异步初始化路径里，而不是同步阻塞地等待挂接结果。

### `AbstractGodotModule` 只是便捷基类，不代表自动阶段广播

当前接口 `IGodotModule` 真正保证的成员只有：

- `Node`
- `Install(IArchitecture architecture)`
- `OnAttach(Architecture architecture)`
- `OnDetach()`

`AbstractGodotModule` 里虽然保留了 `OnPhase(...)` / `OnArchitecturePhase(...)` 虚方法，但它们不在当前接口契约内，也没有在
这条挂接流程里形成稳定的自动广播语义。不要把它写成当前公开保证。

### `ArchitectureRoot` 只在锚点就绪后可用

`ArchitectureRoot` 是受保护属性，底层直接返回 `_anchor`。如果锚点尚未准备好或架构已经失效，它会抛
`InvalidOperationException("Architecture root not ready")`。因此它适合放在明确依赖锚点存在的挂接逻辑里，而不是拿来做
任意时机的全局节点查找。

## 继续阅读

1. [Godot 运行时集成](./index.md)
2. [Godot 集成教程](../tutorials/godot-integration.md)
3. [Godot 场景系统](./scene.md)
4. [Godot UI 系统](./ui.md)