mirror of
https://github.com/GeWuYou/GFramework.git
synced 2026-05-07 00:39:00 +08:00
074002254e
- 更新 source-generators 侧栏标签并移除 API 参考侧栏中的跨栏目重复入口 - 优化 Core、Ecs.Arch、Game README 的 XML 阅读入口表述，删除覆盖基线式字段 - 补充 documentation-full-coverage-governance 跟踪与验证记录，记录 PR #290 审查收口状态
139 lines
4.5 KiB
Markdown
139 lines
4.5 KiB
Markdown
# GFramework.Ecs.Arch
|
|
|
|
`GFramework.Ecs.Arch` 是 `GFramework` 当前 Arch ECS family 的默认运行时实现包。
|
|
|
|
它负责把 Arch `World`、GFramework 的服务模块生命周期，以及 `ArchSystemAdapter<T>` 系统桥接到同一条采用路径中。
|
|
如果你需要的只是共享契约，请改为依赖 `GFramework.Ecs.Arch.Abstractions`。
|
|
|
|
## 包定位
|
|
|
|
- 这是运行时实现层，不是纯契约层。
|
|
- 适合需要 `UseArch(...)`、`World` 自动注册、默认模块生命周期和系统桥接基类的项目。
|
|
- 常见场景：
|
|
- 在架构实例上显式接入 Arch ECS
|
|
- 让 `World` 由默认模块创建并放入容器
|
|
- 让 ECS 系统复用 `ArchSystemAdapter<float>` 生命周期桥接
|
|
- 通过 `IArchEcsModule.Update(deltaTime)` 统一驱动 ECS 帧更新
|
|
|
|
## 与相邻包的关系
|
|
|
|
- `GFramework.Core`
|
|
- 提供架构、容器、生命周期和系统注册基础设施。
|
|
- `GFramework.Ecs.Arch.Abstractions`
|
|
- 提供 `IArchEcsModule`、`IArchSystemAdapter<T>` 和契约层 `ArchOptions`。
|
|
- `GFramework.Ecs.Arch`
|
|
- 提供 `UseArch(...)`、默认 `ArchEcsModule`、`World` 注册，以及系统适配器基类与示例类型。
|
|
|
|
## 最小接入路径
|
|
|
|
### 1. 安装包
|
|
|
|
```bash
|
|
dotnet add package GeWuYou.GFramework.Ecs.Arch
|
|
```
|
|
|
|
### 2. 在 `Initialize()` 之前显式接入 Arch runtime
|
|
|
|
按当前实现，`UseArch(...)` 会把 `ArchEcsModule` 提前登记到 `ArchitectureModuleRegistry`，因此调用时机应早于
|
|
`Initialize()`。
|
|
|
|
```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. 编写并注册系统
|
|
|
|
```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` 与 ECS 模块
|
|
|
|
```csharp
|
|
using Arch.Core;
|
|
using GFramework.Ecs.Arch.Abstractions;
|
|
|
|
var world = architecture.Context.GetService<World>();
|
|
var ecsModule = architecture.Context.GetService<IArchEcsModule>();
|
|
```
|
|
|
|
### 5. 由宿主循环驱动更新
|
|
|
|
```csharp
|
|
ecsModule.Update(deltaTime);
|
|
```
|
|
|
|
## 运行时职责地图
|
|
|
|
| 文件 | 作用 |
|
|
| --- | --- |
|
|
| `Extensions/ArchExtensions.cs` | 通过 `UseArch(...)` 把默认模块注册到 `ArchitectureModuleRegistry` |
|
|
| `ArchEcsModule.cs` | 创建并注册 `World`，按优先级收集 `ArchSystemAdapter<float>`，负责初始化、销毁和逐帧更新 |
|
|
| `ArchSystemAdapter.cs` | 把 GFramework 系统生命周期桥接到 Arch `ISystem<T>` 生命周期 |
|
|
| `ArchOptions.cs` | 承载 `WorldCapacity`、`EnableStatistics`、`Priority` 这组运行时配置 |
|
|
| `Components/*.cs`、`Systems/*.cs` | 提供最小组件与系统示例，帮助对照查询写法和更新模式 |
|
|
|
|
## XML 阅读入口
|
|
|
|
下表汇总当前模块 README 与源码可对照的类型级 XML 文档入口，方便先抓住 Arch ECS 集成的关键类型。
|
|
|
|
| 类型族 | 代表类型 | 阅读重点 |
|
|
| --- | --- | --- |
|
|
| 装配入口 | `ArchExtensions` | `UseArch(...)` 的接入时机、返回值与默认模块拼装方式 |
|
|
| 运行时模块 | `ArchEcsModule` | `World` 注册、系统排序、销毁顺序与配置对象的消费方式 |
|
|
| 系统桥接层 | `ArchSystemAdapter<T>` | `OnArchInitialize`、`OnUpdate`、`OnArchDispose` 的生命周期桥接 |
|
|
| 示例类型 | `Position`、`Velocity`、`MovementSystem` | 组件布局、查询写法与最小更新循环示例 |
|
|
|
|
## 对应文档入口
|
|
|
|
- ECS 总览：[ECS 文档首页](../docs/zh-CN/ecs/index.md)
|
|
- Arch ECS 集成：[Arch ECS 集成说明](../docs/zh-CN/ecs/arch.md)
|
|
- 抽象契约页：[ECS Arch Abstractions 文档](../docs/zh-CN/abstractions/ecs-arch-abstractions.md)
|
|
- 统一 API / XML 导航：[API 参考首页](../docs/zh-CN/api-reference/index.md)
|