# GameCore 游戏框架设计文档

## 概述

通用 Unity 游戏框架，以 Unity Package 形式分发，基于自研轻量 DI 容器，采用核心扩展式架构。目标：跨项目可复用 + 开箱即用的常用系统。

- **目标平台：** Unity 2022 LTS
- **架构模式：** 依赖注入 (DI)
- **分发形式：** Unity Package
- **DI 容器：** 自研轻量实现（反射，预留 Source Generator 优化接口）

---

## 架构：核心扩展式

```
GameCore (核心 asmdef)
  ├── DI 容器
  ├── 所有模块接口定义
  └── 核心模块：事件系统、对象池、游戏流程控制、计时器

扩展包 (各自独立 asmdef，只依赖核心)
  ├── GameCore.UI
  ├── GameCore.Audio
  ├── GameCore.Resource
  ├── GameCore.Data
  ├── GameCore.Save
  └── GameCore.Network

可替换实现 (各自独立 asmdef)
  ├── GameCore.Defaults        — 默认 EventBus + Timer
  ├── GameCore.R3              — R3 实现（可选替换 Defaults）
  ├── GameCore.Resource.Resources
  ├── GameCore.Resource.Addressables
  ├── GameCore.Save.FileStorage
  └── GameCore.Save.PlayerPrefsStorage
```

**设计原则：**
- 核心包定义接口，不包含具体实现（DI、Pool、Lifecycle 除外）
- 扩展包只依赖核心，互不依赖
- 可替换实现通过 DI Installer 注册，换实现不改上层代码

---

## DI 容器

### 能力

- 接口→实现绑定 (`Bind<IAudioManager>().To<AudioManager>()`)
- 实例绑定 (`ToValue(instance)`)
- 生命周期：`AsSingleton()` / `AsTransient()`
- 子容器（场景级作用域，子容器销毁时自动释放其单例）
- 构造函数注入（普通 C# 类）
- 属性注入 `[Inject]`（MonoBehaviour）
- 方法注入 `[Inject]`（初始化/PostConstruct）
- 自动递归解析依赖链
- 反射实现，预留 Source Generator 优化接口

### 子容器

```csharp
// 全局容器（跨场景）
var root = new GameContainer();

// 场景容器（继承全局，场景销毁时一起释放）
var sceneContainer = root.CreateChild();

// 子容器可访问父容器绑定
sceneContainer.Resolve<IAudioManager>(); // 从父容器拿

// 子容器同名绑定覆盖父容器
sceneContainer.Bind<IGameManager>().To<GameManager>().AsSingleton();
```

### 注入方式

```csharp
// 构造函数注入 — 普通 C# 类
public class AudioManager : IAudioManager
{
    private readonly IEventBus _eventBus;
    public AudioManager(IEventBus eventBus) { _eventBus = eventBus; }
}

// 属性注入 — MonoBehaviour
public class GameCoreEntry : MonoBehaviour
{
    [Inject] private IEventBus _eventBus;
}

// 方法注入 — 初始化/PostConstruct
public class GameManager : IGameManager
{
    [Inject]
    public void Init(IEventBus eventBus, IDataManager data)
    {
        // 所有依赖就绪后执行
    }
}
```

---

## 核心模块

### 事件总线 (IEventBus)

接口定义在核心包，实现可替换。

```csharp
public interface IEventBus
{
    void Subscribe<T>(Action<T> handler) where T : IEvent;
    void Unsubscribe<T>(Action<T> handler) where T : IEvent;
    void Publish<T>(T evt) where T : IEvent;
}
```

- 事件用 `struct`，避免 GC 压力
- 泛型事件分发，每个事件类型独立维护订阅者列表

默认实现：`GameCore.Defaults.DefaultEventBus`
R3 实现：`GameCore.R3.R3EventBus`

### 计时器/调度器 (ITimerManager)

接口定义在核心包，实现可替换。

```csharp
public interface ITimerManager
{
    ITimerHandle Delay(float seconds, Action callback);
    ITimerHandle Repeat(float interval, Action callback);
    void Tick(float deltaTime);
}

public interface ITimerHandle
{
    void Cancel();
    bool IsDone { get; }
}
```

- 不依赖 MonoBehaviour Coroutine，纯 Tick 驱动
- 内部用对象池管理 Timer 对象

默认实现：`GameCore.Defaults.DefaultTimerManager`
R3 实现：`GameCore.R3.R3TimerManager`

### 对象池 (IPoolManager)

```csharp
public interface IPoolManager
{
    IPool<T> CreatePool<T>(Func<T> factory, int prewarm = 0);
    IGameObjectPool CreateGameObjectPool(string prefabPath, int prewarm = 0);
}

public interface IPool<T>
{
    T Get();
    void Release(T item);
}
```

- 泛型对象池，支持任意类型
- 预加载容量，支持预热
- GameObject 池的创建/销毁由 Resource 扩展包实现，核心只定义接口

### 游戏流程控制 (GameLifecycle)

```csharp
public static class GameCore
{
    public static void Launch(StartupConfig config);
    public static void Tick();
    public static void Shutdown();
}

public class StartupConfig
{
    public IInstaller[] Installers;
    public IStartupTask[] StartupTasks;
}

public interface IInstaller
{
    void Install(IGameContainer container);
}

public interface IStartupTask
{
    Task Execute();
}
```

生命周期阶段：
```
Launch → Installers 注册绑定 → ResolveAll 创建单例 → StartupTasks 按序执行 → Running
                                                                          ↓
                                                                    场景切换时
                                                                     子容器销毁
                                                                          ↓
                                                                       Shutdown
```

- `IInstaller` 统一模块注册入口
- `IStartupTask` 控制启动顺序（支持异步）
- 场景切换时自动销毁场景级子容器
- Shutdown 时按反序释放所有模块

---

## 扩展包

### GameCore.Resource — 资源加载

```csharp
public interface IResourceLoader
{
    T Load<T>(string path) where T : Object;
    Task<T> LoadAsync<T>(string address) where T : Object;
    void Release<T>(T asset);
    void ReleaseAll();
}
```

- 统一封装，支持引用计数，同一资源多次加载不重复
- 存储实现可替换：Resources / Addressables / AssetBundle / 自定义

### GameCore.UI — UI 管理

```csharp
public interface IUIManager
{
    T Open<T>(string layer = null) where T : UIPanelBase;
    void Close<T>() where T : UIPanelBase;
    void CloseAll();
    void CloseLayer(string layer);
    void RegisterLayer(string name, Canvas canvas, int sortOrder);
}

public abstract class UIPanelBase : MonoBehaviour
{
    [Inject] protected IEventBus _eventBus;
    [Inject] protected IResourceLoader _loader;
    public virtual void OnOpen() { }
    public virtual void OnClose() { }
}
```

- 层级由用户自定义注册，不预设固定层级
- 面板栈管理，支持返回上一级
- 面板复用（配合对象池）

### GameCore.Audio — 音频管理

```csharp
public interface IAudioManager
{
    IAudioHandle PlayBGM(string name, bool loop = true, float fadeIn = 0f);
    void StopBGM(float fadeOut = 0f);
    IAudioHandle PlaySFX(string name);
    void Stop(IAudioHandle handle);
    void Pause(IAudioHandle handle);
    void Resume(IAudioHandle handle);
    void SetBGMVolume(float volume);
    void SetSFXVolume(float volume);
    void MuteAll();
    void UnmuteAll();
}

public interface IAudioHandle
{
    float Volume { get; set; }
    bool IsPlaying { get; }
    void Stop(float fadeOut = 0f);
}
```

- fadeIn/fadeOut 处理音频过渡，具体曲线在实现层
- IAudioHandle 可停止单个音频
- SFX 用对象池管理 AudioSource

### GameCore.Data — 数据/配置管理

```csharp
public interface IDataManager
{
    void RegisterParser<TParser>(string format) where TParser : IDataParser;
    void LoadModule(string moduleName);
    void UnloadModule(string moduleName);
    bool IsModuleLoaded(string moduleName);
    T GetConfig<T>(string key) where T : IConfig;
    IReadOnlyList<T> GetConfigs<T>() where T : IConfig;
}

public interface IDataParser
{
    IEnumerable<IConfig> Parse(string content);
}
```

- 格式自定义：注册 IDataParser 实现（JSON/CSV/ScriptableObject/自定义）
- 分模块按需加载和卸载

### GameCore.Save — 存档系统

```csharp
public interface ISaveManager
{
    Task Save(string slotName, object data);
    Task<T> Load<T>(string slotName);
    void Delete(string slotName);
    bool Exists(string slotName);
    string[] ListSaves();
}

public interface ISaveStorage
{
    Task Write(string key, byte[] data);
    Task<byte[]> Read(string key);
    void Delete(string key);
    bool Exists(string key);
}
```

- ISaveManager 负责序列化和业务逻辑
- ISaveStorage 负责底层读写，可替换：File / PlayerPrefs / 云存档 / 自定义
- 支持多存档位

### GameCore.Network — 网络层

```csharp
public interface INetworkService
{
    Task<T> Request<T>(string url, object body);
    Task Connect(string url);
    void Disconnect();
    void Send<T>(T message);
    void OnReceive<T>(Action<T> handler);
}
```

- HTTP 请求封装（GET/POST）
- WebSocket 长连接
- 断线重连、超时处理、心跳机制

---

## 包结构

```
com.yourname.gamecore/
├── package.json
├── README.md
├── CHANGELOG.md
├── LICENSE
├── Runtime/
│   ├── GameCore/                          # 核心 asmdef
│   │   ├── DI/
│   │   ├── Events/IEventBus.cs
│   │   ├── Timer/ITimerManager.cs
│   │   ├── Pool/
│   │   ├── Lifecycle/
│   │   └── Interfaces/
│   │
│   ├── GameCore.Defaults/                 # 默认 EventBus + Timer
│   ├── GameCore.R3/                       # R3 实现（可选）
│   │
│   ├── GameCore.UI/
│   ├── GameCore.Audio/
│   │
│   ├── GameCore.Resource/                 # 接口
│   ├── GameCore.Resource.Resources/       # Resources 实现
│   ├── GameCore.Resource.Addressables/    # Addressables 实现
│   │
│   ├── GameCore.Data/
│   │
│   ├── GameCore.Save/                     # 接口 + 序列化
│   ├── GameCore.Save.FileStorage/
│   ├── GameCore.Save.PlayerPrefsStorage/
│   │
│   └── GameCore.Network/
│
├── Editor/
│   └── GameCore.Editor/
└── Samples~/
```

---

## 完整使用示例

```csharp
// 入口
public class GameBootstrap : MonoBehaviour
{
    void Awake()
    {
        GameCore.Launch(new StartupConfig
        {
            Installers = new IInstaller[]
            {
                new CoreInstaller(),
                new TimerInstaller(),
                new ResourceInstaller<AddressablesResourceLoader>(),
                new AudioInstaller(),
                new UIInstaller(),
                new DataInstaller(),
                new SaveInstaller<FileSaveStorage>(),
            },
            StartupTasks = new IStartupTask[]
            {
                new LoadConfigTask(),
                new ShowMainMenuTask(),
            }
        });
    }

    void Update() => GameCore.Tick();
    void OnDestroy() => GameCore.Shutdown();
}

// 使用模块
public class MainMenuPanel : UIPanelBase
{
    [Inject] private IAudioManager _audio;
    [Inject] private IEventBus _eventBus;
    [Inject] private IDataManager _data;

    public override void OnOpen()
    {
        _audio.PlayBGM("main_menu", fadeIn: 1f);
        var weapons = _data.GetConfigs<WeaponConfig>();
        RenderWeaponList(weapons);
    }

    public void OnStartGameClick()
    {
        _audio.PlaySFX("click");
        _eventBus.Publish(new StartGameEvent { Level = 1 });
    }
}

// 事件定义
public struct StartGameEvent : IEvent
{
    public int Level;
}
```