mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-07 00:39:00 +08:00
094e29ed8b
- 更新 docs 站点中 abstractions、source-generators、api-reference 的导航文案，使其与 landing page 入口一致 - 补充遗漏的源码生成器 sidebar 条目，并本地化抽象层与 API 参考的侧边栏标签 - 修复 ECS、Game、Godot 文档中的路径式可见链接标签，改为读者可理解的语义化名称
145 lines
4.9 KiB
Markdown
145 lines
4.9 KiB
Markdown
---
|
||
title: Arch ECS 集成
|
||
description: GFramework.Ecs.Arch 的默认运行时装配路径、系统桥接方式与源码阅读入口。
|
||
---
|
||
|
||
# Arch ECS 集成
|
||
|
||
`GFramework.Ecs.Arch` 是当前仓库里负责 Arch ECS 默认接入路径的运行时包。它把 Arch `World`、GFramework 的
|
||
`IServiceModule` 生命周期，以及 `AbstractSystem` / `ISystem` 体系桥接到同一条初始化与更新链路中。
|
||
|
||
## 什么时候依赖它
|
||
|
||
当你需要下面任一能力时，应直接依赖 `GeWuYou.GFramework.Ecs.Arch`：
|
||
|
||
- 在架构实例上调用 `UseArch(...)`
|
||
- 让 `World` 在服务模块注册阶段自动创建并注入容器
|
||
- 让 ECS 系统继承 `ArchSystemAdapter<T>`
|
||
- 使用仓库自带的 `Position`、`Velocity`、`MovementSystem` 最小示例
|
||
|
||
如果你只想保留共享边界，而不依赖默认实现，请改看
|
||
[ECS 抽象层说明](../abstractions/ecs-arch-abstractions.md)。
|
||
|
||
## 最小接入路径
|
||
|
||
### 1. 安装包
|
||
|
||
```bash
|
||
dotnet add package GeWuYou.GFramework.Ecs.Arch
|
||
```
|
||
|
||
### 2. 在 `Initialize()` 之前调用 `UseArch(...)`
|
||
|
||
当前实现通过 `ArchitectureModuleRegistry.Register(...)` 提前登记 `ArchEcsModule`。这意味着调用时机应位于
|
||
`Initialize()` 之前，而不是放进 `OnInitialize()` 里。
|
||
|
||
```csharp
|
||
using GFramework.Core.Architectures;
|
||
using GFramework.Ecs.Arch.Extensions;
|
||
|
||
public sealed class GameArchitecture : Architecture
|
||
{
|
||
public GameArchitecture() : base(new ArchitectureConfiguration())
|
||
{
|
||
}
|
||
|
||
protected override void OnInitialize()
|
||
{
|
||
RegisterSystem<MovementSystem>();
|
||
}
|
||
}
|
||
|
||
var architecture = new GameArchitecture()
|
||
.UseArch(options =>
|
||
{
|
||
options.WorldCapacity = 2048;
|
||
options.Priority = 50;
|
||
});
|
||
|
||
architecture.Initialize();
|
||
```
|
||
|
||
### 3. 用 `ArchSystemAdapter<float>` 编写系统
|
||
|
||
`ArchSystemAdapter<T>` 在 `OnInit()` 中从当前上下文解析 `World`，再把 Arch 的 `Initialize / BeforeUpdate /
|
||
AfterUpdate / Dispose` 钩子桥接到可重写方法。
|
||
|
||
```csharp
|
||
using Arch.Core;
|
||
using GFramework.Ecs.Arch;
|
||
using GFramework.Ecs.Arch.Components;
|
||
|
||
public sealed class MovementSystem : ArchSystemAdapter<float>
|
||
{
|
||
private QueryDescription _query;
|
||
|
||
protected override void OnArchInitialize()
|
||
{
|
||
_query = new QueryDescription()
|
||
.WithAll<Position, Velocity>();
|
||
}
|
||
|
||
protected override void OnUpdate(in float deltaTime)
|
||
{
|
||
var frameDelta = deltaTime;
|
||
|
||
World.Query(in _query, (ref Position position, ref Velocity velocity) =>
|
||
{
|
||
position.X += velocity.X * frameDelta;
|
||
position.Y += velocity.Y * frameDelta;
|
||
});
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 初始化后解析 `World` 与模块服务
|
||
|
||
```csharp
|
||
using Arch.Core;
|
||
using GFramework.Ecs.Arch.Abstractions;
|
||
|
||
var world = architecture.Context.GetService<World>();
|
||
var ecsModule = architecture.Context.GetService<IArchEcsModule>();
|
||
```
|
||
|
||
### 5. 由宿主循环显式调用 `Update`
|
||
|
||
```csharp
|
||
ecsModule.Update(deltaTime);
|
||
```
|
||
|
||
这一步在 `GFramework.Ecs.Arch.Tests/Ecs/*.cs` 中也采用同样的驱动方式。
|
||
|
||
## 运行时职责
|
||
|
||
| 类型 | 责任 | 证据文件 |
|
||
| --- | --- | --- |
|
||
| `ArchExtensions` | 把 `ArchEcsModule` 注册到 `ArchitectureModuleRegistry` | `GFramework.Ecs.Arch/Extensions/ArchExtensions.cs` |
|
||
| `ArchEcsModule` | 创建并注册 `World`，按优先级收集 `ArchSystemAdapter<float>`，负责初始化、销毁和逐帧更新 | `GFramework.Ecs.Arch/ArchEcsModule.cs` |
|
||
| `ArchSystemAdapter<T>` | 从 GFramework 系统生命周期桥接到 Arch `ISystem<T>` 生命周期 | `GFramework.Ecs.Arch/ArchSystemAdapter.cs` |
|
||
| `ArchOptions` | 暴露 `WorldCapacity`、`EnableStatistics`、`Priority` 这组运行时配置对象 | `GFramework.Ecs.Arch/ArchOptions.cs` |
|
||
|
||
## 配置对象阅读提示
|
||
|
||
当前公开配置对象是 `GFramework.Ecs.Arch.ArchOptions`。从源码可直接确认：
|
||
|
||
- `WorldCapacity` 用于 `World.Create(...)` 的容量参数
|
||
- `Priority` 影响 `ArchEcsModule` 作为服务模块的排序
|
||
- `EnableStatistics` 目前保留在公开配置面上；采用时应以源码 XML 注释和实现行为为准，而不是依赖旧文档推断
|
||
|
||
## 源码阅读入口
|
||
|
||
| 类型族 | 代表类型 | 建议先确认什么 |
|
||
| --- | --- | --- |
|
||
| 装配入口 | `ArchExtensions` | `UseArch(...)` 的时机、链式调用返回值 |
|
||
| 服务模块 | `ArchEcsModule` | `World` 注册、系统收集、模块销毁顺序 |
|
||
| 系统桥接层 | `ArchSystemAdapter<T>` | `OnArchInitialize` / `OnUpdate` / `OnArchDispose` |
|
||
| 示例类型 | `Position`、`Velocity`、`MovementSystem` | 组件布局、查询写法和最小集成样例 |
|
||
|
||
## 相关入口
|
||
|
||
- ECS 模块总览：[ECS 模块总览](./index.md)
|
||
- 抽象契约页：[ECS 抽象层说明](../abstractions/ecs-arch-abstractions.md)
|
||
- 仓库模块说明：[Ecs.Arch 运行时说明](https://github.com/GeWuYou/GFramework/blob/main/GFramework.Ecs.Arch/README.md)
|
||
- 统一 API / XML 导航：[API 参考](../api-reference/index.md)
|