# MCore

**Repository Path**: zhangjunming/mcore

## Basic Information

- **Project Name**: MCore
- **Description**: 我的游戏框架
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-03-12
- **Last Updated**: 2026-03-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCore 游戏开发框架

[![Unity 版本](https://img.shields.io/badge/Unity-2022.3-blue.svg)](https://unity.com/)
[![版本](https://img.shields.io/badge/Version-1.0.2-green.svg)](https://gitee.com/zhangjunming/mcore.git)
[![许可证](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## 📖 框架概述

**MCore** 是一个基于 Unity 2022.3 平台开发的综合性游戏开发框架，旨在为游戏开发者提供便捷的开发工具和功能模块。该框架支持快速构建用户界面、网络通信、资源管理等核心游戏功能，大幅提升开发效率。

### 核心特性

- 🎮 **模块化架构** - 各模块独立，按需使用
- ⚡ **异步优先** - 全面集成 UniTask 实现异步操作
- 🎨 **UI 系统** - 强大的 UI 管理系统，支持分层管理
- 🌐 **网络模块** - 基于 PurrNet 的多人游戏支持
- 🔧 **对象池系统** - 高性能对象池管理
- ⏱️ **计时器系统** - 灵活的计时器，支持冷却和倒计时
- 💾 **资源管理** - 基于 Addressables 的异步资源加载
- 🗄️ **本地数据库** - 基于 SQLite 的数据持久化
- 🔥 **热更新支持** - 集成 HybridCLR 实现代码热更新

## 🏗️ 架构设计

```
MCore 框架
├── 核心模块              - 框架核心和系统
│   ├── 事件系统          - 事件驱动架构
│   ├── UI 核心           - UI 管理系统
│   ├── 计时器           - 计时器系统
│   ├── 对象池           - 对象池管理
│   ├── 音频             - 音频管理
│   ├── 数据系统          - 数据系统
│   ├── 动作系统          - 动作/序列系统
│   └── 单元系统          - 单元系统
├── 网络模块             - 多人联机网络 (PurrNet)
├── 资源模块             - 资源管理
└── 本地数据库           - 本地数据库 (SQLite)
```

## 🚀 快速开始

### 环境要求

- Unity 2022.3 LTS 或更高版本
- 必需的 Unity 包：
  - com.unity.addressables（资源管理）
  - com.unity.logging（日志系统）
  - MemoryPack.Unity（高性能序列化）
  - Luban（配置表工具）
  - HybridCLR（热更新支持）
  - UniTask（异步任务）
  - DOTween（补间动画）
  - Odin Inspector（编辑器增强）

### 安装步骤

1. 克隆此仓库或下载包文件
2. 导入到 Unity 项目中
3. 确保所有必需的 Unity 包已安装
4. 配置框架设置

### 客户端初始化

**1. 创建 MCoreLauncher**：
- 在层级视图中右键 → MCore → MCoreLauncher

**2. 创建 MUIRoot**：
- 在层级视图中右键 → UI → MCore → MUIRoot

**3. 添加程序集收集类**：
- 创建一个继承自 `MComponent` 的类来收集程序集

**4. 运行场景**：
- 查找 `MCoreInit` 日志，确认初始化成功

### 配置文件设置

```
项目根目录/
├── Settings/                    # 配置文件夹
│   ├── MCore/                   # MCore 特定配置
│   │   ├── MCoreSetting.asset   # 核心框架配置
│   └── MUISetting.asset         # UI 系统配置
```

**重要提示**：使用 URP（通用渲染管线）时，需要添加宏定义 `MCORE_URP` 并重新编译项目，以确保 UI 相机正确融合。

## 📚 模块文档

### 1. 核心模块

#### MCoreComponent
框架入口点，初始化所有核心系统。

```csharp
public class MCoreComponent : MUnit
{
    public static MCoreComponent MRoot { get; private set; }
    public ResLoadType LoadType = ResLoadType.ResourceLoader;
}
```

#### 事件系统
基于特性的事件驱动架构。

```csharp
[MEvent]
public class OnClientStart : MEvent<OnMCoreInitArgs>
{
    public override async UniTask Run(OnMCoreInitArgs arg)
    {
        // 你的初始化逻辑
    }
}

// 触发事件
EventComponent.Instance.Invoke(new OnMCoreInitArgs());
```

### 2. UI 系统

#### UIComponent
强大的 UI 管理系统，支持生命周期控制和分层管理。

**UI 层级定义**：
```csharp
public enum UILayer
{
    Bottom,  // 背景层
    Mid,     // 主层
    Top,     // 弹窗层
    System   // 系统层
}
```

**使用示例**：
```csharp
// 定义 UI
[UI(typeof(MainMenu), UILayer.Mid, "MainMenu", true)]
public class MainMenu : UIUnit
{
    public override async UniTask Init()
    {
        // UI 初始化
    }
}

// 打开 UI
await UIComponent.Instance.OpenUI<MainMenu>();

// 关闭 UI
UIComponent.Instance.CloseUI<MainMenu>();

// 检查 UI 是否打开
bool isOpen = UIComponent.Instance.ISUIOpen(typeof(MainMenu));

// 获取 UI 实例
var menu = UIComponent.Instance.GetUIComponent<MainMenu>();
```

**功能特性**：
- 基于 UI 层级的组织管理
- 背景/遮罩管理
- 世界坐标到 UI 坐标转换
- UI 碰撞检测
- 泛型初始化接口支持

### 3. 网络模块

#### PurrnetComponent
基于 PurrNet 框架的多人联机网络系统。

**网络模式**：
- **客户端** - 连接到服务器
- **服务器** - 托管游戏会话
- **主机** - 同时作为客户端和服务器

**使用示例**：
```csharp
// 启动网络
PurrnetComponent.Instance.StartClient();  // 客户端模式
PurrnetComponent.Instance.StartServer();  // 服务器模式
PurrnetComponent.Instance.StartHost();    // 主机模式

// 发送消息
TestMessage message = new TestMessage { data = "你好" };
PurrnetComponent.Instance.Send(playerId, message);

// 异步 RPC 调用
var response = await PurrnetComponent.Instance.CallAsync(playerId, request);

// 订阅消息
InstanceHandler.NetworkManager.Subscribe<TestMessage>(OnTestMessage);
```

**支持的传输方式**：
- UDP 传输
- Web 传输

**功能特性**：
- 会话管理 (`MSession`)
- 带响应处理的 RPC
- 玩家加入/离开事件
- 连接状态监控
- MemoryPack 消息序列化

### 4. 计时器系统

#### MTimerComponent
灵活的计时器系统，用于冷却时间、倒计时和周期性任务。

```csharp
// 创建并启动计时器
MTimer skillTimer = new MTimer(10f);  // 10 秒
MTimerComponent.Instance.AddTimer("SkillCD", skillTimer);

// 停止计时器
MTimerComponent.Instance.StopTimer("SkillCD");

// 每日计时器
MDayTimer dailyTimer = new MDayTimer(8, 0, 0);  // 每天 8:00
```

**功能特性**：
- 并发计时器管理
- 技能冷却跟踪
- 倒计时计时器
- 每日/周期性计时器

### 5. 对象池系统

#### PoolComponent
高性能对象池，用于内存优化。

```csharp
// 初始化对象池
PoolComponent.Instance.InitObjectPool<MyObject>(initialSize: 100, growSize: 50);

// 获取对象
var obj = PoolComponent.Instance.GetObject<MyObject>();

// 返回对象
PoolComponent.Instance.ReturnObject(obj);
```

**功能特性**：
- GameObject 对象池
- 普通对象池
- 自动扩容
- 内存高效

### 6. 资源管理 (MCore.Addressable)

基于 Unity Addressables 的异步资源加载。

```csharp
// 加载并实例化 UI
var handle = await ResourceLoadComponent.Instance.ResLoader
    .InstaniateComponentAsync<UIUnit>("UI/MainMenu", parent);

// 加载资源
var prefab = await ResourceLoadComponent.Instance.ResLoader
    .LoadAssetAsync<GameObject>("Prefabs/Player");
```

### 7. 本地数据库 (MCore.LocalDB)

基于 SQLite 的本地数据持久化。

```csharp
// 查询数据
var players = await LocalDBManager.Instance.QueryAsync<Player>("SELECT * FROM players");

// 执行命令
await LocalDBManager.Instance.ExecuteAsync("INSERT INTO players VALUES (@name)", parameters);
```

## 🔧 配置文件

### MCoreSetting.asset
核心框架配置，包括：
- 资源加载类型（Resource/Addressable）
- 系统初始化顺序
- 调试设置

### MUISetting.asset
UI 系统配置，包括：
- UI 层设置
- 相机配置
- 背景设置
- 默认路径

## 🌐 服务器部署

### 服务器场景
- 使用 `serverscene` 进行服务器部署
- 包含网络监听和玩家连接处理

### 构建要求
- 可打包为 Linux 或 Windows 服务器版本
- 确保在构建设置中包含 `serverscene`
- 验证网络配置
- 包含所有必需的依赖项

### 服务器配置

```csharp
// 配置服务器端点
IPEndPoint serverEndpoint = new IPEndPoint(IPAddress.Parse("127.0.0.1"), 7777);
PurrnetComponent.Instance.SetIp(serverEndpoint);

// 启动服务器
PurrnetComponent.Instance.StartServer();
```

## 📦 依赖包

| 包名 | 用途 |
|------|------|
| UniTask | 异步/await 支持 |
| DOTween | 动画/补间动画 |
| MemoryPack | 高性能序列化 |
| Odin Inspector | 增强编辑器工具 |
| HybridCLR | 热更新能力 |
| Luban | 配置管理 |
| PurrNet | 多人联机网络 |

## 🎯 常见使用场景

### 1. 创建自定义 UI

```csharp
[UI(typeof(SettingsUI), UILayer.Top, "SettingsUI", true)]
public class SettingsUI : UIUnit, IInit
{
    public override async UniTask Init()
    {
        // 初始化 UI 元素
        // 设置事件监听器
        // 加载设置
    }

    private void OnSaveClicked()
    {
        // 保存设置逻辑
        UIComponent.Instance.CloseUI<SettingsUI>();
    }
}
```

### 2. 处理网络事件

```csharp
[MEvent]
public class OnPlayerConnected : MEvent<PlayerConnectedArgs>
{
    public override async UniTask Run(PlayerConnectedArgs args)
    {
        await UIComponent.Instance.OpenUI<PlayerUI>();
        // 使用玩家数据更新 UI
    }
}
```

### 3. 使用计时器进行技能冷却

```csharp
public class PlayerSkill : MonoBehaviour
{
    private const float COOLDOWN_TIME = 5f;

    public async UniTask UseSkill()
    {
        if (MTimerComponent.Instance.Timers.TryGetValue("SkillCD", out var timer))
        {
            if (timer.IsRunning)
            {
                MLog.Warning("技能正在冷却中");
                return;
            }
        }

        // 执行技能
        ExecuteSkillLogic();

        // 开始冷却
        var cooldownTimer = new MTimer(COOLDOWN_TIME);
        MTimerComponent.Instance.AddTimer("SkillCD", cooldownTimer);
    }
}
```

## 🔍 调试和日志

### MLog 系统

```csharp
MLog.Debug("调试信息");
MLog.Info("普通信息");
MLog.Warning("警告信息");
MLog.Error("错误信息");
```

## ⚠️ 重要注意事项

1. **Unity 版本**：确保使用 Unity 2022.3 LTS 或更高版本
2. **URP 支持**：使用 URP 时添加 `MCORE_URP` 宏定义
3. **相机集成**：在 URP 模式下正确配置 UI 相机堆栈
4. **服务器环境**：确保 Linux/Windows 服务器的网络配置正确
5. **热更新**：HybridCLR 需要正确的项目配置

## 📖 版本历史

### v1.0.2 (当前版本)
- ✨ 新增计时器系统
- 🔧 性能优化
- 🐛 Bug 修复和改进

### v1.0.1
- 初始版本发布

## 🤝 贡献指南

1. Fork 本仓库
2. 创建你的特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交你的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📝 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。

## 📞 技术支持

- **问题反馈**：[Gitee Issues](https://gitee.com/zhangjunming/mcore/issues)
- **文档**：[Gitee Wiki](https://gitee.com/zhangjunming/mcore/wikis)
- **项目地址**：https://gitee.com/zhangjunming/mcore.git

## 🙏 致谢

- Unity Technologies 提供 Unity 引擎
- PurrNet 提供网络框架
- Cysharp 提供 UniTask
- Sirenix 提供 Odin Inspector

---

**用 ❤️ 为 Unity 游戏开发者构建**