GFramework/docs/zh-CN/ecs/index.md

title, description

title	description
ECS 系统集成	GFramework 的 ECS（Entity Component System）集成方案，支持多种 ECS 框架。

ECS 系统集成

概述

GFramework 提供了灵活的 ECS（Entity Component System）集成方案，允许你根据项目需求选择合适的 ECS 框架。ECS 是一种数据驱动的架构模式，特别适合处理大量相似实体的场景。

什么是 ECS？

ECS（Entity Component System）是一种架构模式，将游戏对象分解为三个核心概念：

• Entity（实体）：游戏世界中的基本对象，本质上是一个唯一标识符
• Component（组件）：纯数据结构，存储实体的状态
• System（系统）：包含游戏逻辑，处理具有特定组件组合的实体

ECS 的优势

• 高性能：数据局部性好，缓存友好
• 可扩展：通过组合组件轻松创建新实体类型
• 并行处理：系统之间相互独立，易于并行化
• 数据驱动：逻辑与数据分离，便于序列化和网络同步

何时使用 ECS？

适合使用 ECS 的场景：

• 大量相似实体（敌人、子弹、粒子）
• 需要高性能批量处理
• 复杂的实体组合和变化
• 需要并行处理的系统

不适合使用 ECS 的场景：

• 全局状态管理
• 单例服务
• UI 逻辑
• 游戏流程控制

支持的 ECS 框架

GFramework 采用可选集成的设计，你可以根据需求选择合适的 ECS 框架：

Arch ECS（推荐）

Arch 是一个高性能的 C# ECS 框架，具有以下特点：

• ✅ 极致性能：基于 Archetype 的内存布局，零 GC 分配
• ✅ 简单易用：清晰的 API，易于上手
• ✅ 功能完整：支持查询、过滤、并行处理等高级特性
• ✅ 活跃维护：社区活跃，持续更新

安装方式：

dotnet add package GeWuYou.GFramework.Ecs.Arch

文档链接：Arch ECS 集成指南

其他 ECS 框架

GFramework 的设计允许集成其他 ECS 框架，未来可能支持：

• DefaultEcs：轻量级 ECS 框架
• Entitas：成熟的 ECS 框架，Unity 生态常用
• 自定义 ECS：你可以基于 GFramework 的模块系统实现自己的 ECS 集成

快速开始

1. 选择 ECS 框架

根据项目需求选择合适的 ECS 框架。对于大多数项目，我们推荐使用 Arch ECS。

2. 安装集成包

# 安装 Arch ECS 集成包
dotnet add package GeWuYou.GFramework.Ecs.Arch

3. 注册 ECS 模块

using GFramework.Core.architecture;
using GFramework.Ecs.Arc;

public class GameArchitecture : Architecture
{
    public GameArchitecture() : base(new ArchitectureConfiguration())
    {
    }

    protected override void OnInitialize()
    {
        // 显式注册 Arch ECS 模块
        this.UseArch(options =>
        {
            options.WorldCapacity = 2000;
            options.EnableStatistics = true;
        });
    }
}

4. 定义组件

using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential)]
public struct Position(float x, float y)
{
    public float X { get; set; } = x;
    public float Y { get; set; } = y;
}

[StructLayout(LayoutKind.Sequential)]
public struct Velocity(float x, float y)
{
    public float X { get; set; } = x;
    public float Y { get; set; } = y;
}

5. 创建系统

using Arch.Core;
using GFramework.Ecs.Arch;

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)
    {
        World.Query(in _query, (ref Position pos, ref Velocity vel) =>
        {
            pos.X += vel.X * deltaTime;
            pos.Y += vel.Y * deltaTime;
        });
    }
}

6. 注册系统

public class GameArchitecture : Architecture
{
    protected override void OnInitialize()
    {
        this.UseArch();

        // 注册 ECS 系统
        RegisterSystem<MovementSystem>();
    }
}

设计理念

显式集成

GFramework 采用显式集成的设计，而不是自动注册：

// ✅ 显式注册 - 清晰、可控
public class GameArchitecture : Architecture
{
    protected override void OnInitialize()
    {
        this.UseArch(); // 明确表示使用 Arch ECS
    }
}

// ❌ 自动注册 - 隐式、难以控制
// 只需引入包，自动注册（不推荐）

优势：

• 清晰的依赖关系
• 更好的 IDE 支持
• 易于测试和调试
• 符合 .NET 生态习惯

零依赖原则

如果你不使用 ECS，GFramework.Core 包不会引入任何 ECS 相关的依赖：

<!-- GFramework.Core.csproj -->
<ItemGroup>
  <!-- 无 Arch 依赖 -->
</ItemGroup>

<!-- GFramework.Ecs.Arch.csproj -->
<ItemGroup>
  <PackageReference Include="Arch" Version="2.1.0" />
  <PackageReference Include="Arch.System" Version="1.1.0" />
</ItemGroup>

模块化设计

ECS 集成基于 GFramework 的模块系统：

// ECS 模块实现 IServiceModule 接口
public sealed class ArchEcsModule : IArchEcsModule
{
    public string ModuleName => nameof(ArchEcsModule);
    public int Priority => 50;
    public bool IsEnabled { get; }

    public void Register(IIocContainer container) { }
    public void Initialize() { }
    public ValueTask DestroyAsync() { }
    public void Update(float deltaTime) { }
}

与传统架构结合

ECS 可以与 GFramework 的传统架构（Model、System、Utility）无缝结合：

// Model 存储全局状态
public class GameStateModel : AbstractModel
{
    public int Score { get; set; }
    public int Level { get; set; }
}

// ECS System 处理实体逻辑
public class EnemySpawnSystem : ArchSystemAdapter<float>
{
    protected override void OnUpdate(in float deltaTime)
    {
        // 访问 Model
        var gameState = this.GetModel<GameStateModel>();

        // 根据关卡生成敌人
        for (int i = 0; i < gameState.Level; i++)
        {
            World.Create(
                new Position(Random.Shared.Next(0, 100), 0),
                new Velocity(0, -1),
                new Health(50, 50)
            );
        }
    }
}

// 传统 System 处理游戏逻辑
public class ScoreSystem : AbstractSystem
{
    protected override void OnInit()
    {
        this.RegisterEvent<EnemyDestroyedEvent>(OnEnemyDestroyed);
    }

    private void OnEnemyDestroyed(EnemyDestroyedEvent e)
    {
        var gameState = this.GetModel<GameStateModel>();
        gameState.Score += 100;
    }
}

下一步

• Arch ECS 集成指南 - 详细的 Arch ECS 使用文档

相关资源

• Architecture 架构系统
• System 系统
• 事件系统