# HCore

**Repository Path**: heyu.520/hcore

## Basic Information

- **Project Name**: HCore
- **Description**: HCore Unity 自己弄着玩的框架
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-09-22
- **Last Updated**: 2026-03-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HCore

[![Unity Version](https://img.shields.io/badge/Unity-6000.2.0f1-blue.svg)](https://unity.com/releases/editor/archive)
[![Package Min Unity](https://img.shields.io/badge/UPM%20min%20Unity-2023.1-green.svg)](./Packages/top.rainhy.hcore/package.json)
[![License](https://img.shields.io/badge/License-MIT-brightgreen.svg)](./LICENSE.md)

HCore 是一个面向 Unity 项目的分层运行时基础库，核心能力包括 IOC 容器、事件系统、生命周期集成、任务队列、调度器、对象池，以及一组可直接复用的 Gameplay 模块。

## 这是什么

- 面向 Unity 的基础设施包，重点解决依赖注入、模块解耦与运行时组织问题。
- 仓库同时包含 `Packages/top.rainhy.hcore/` 包源码、测试、示例和规范文档。
- 当前仓库以 Unity `6000.2.0f1` 作为主要开发/验证环境；`package.json` 中声明的 UPM 最低版本为 Unity `2023.1`。

## 五层架构

HCore 采用固定的单向依赖：

```text
Gameplay
  -> Engine
    -> Support
      -> IOC
        -> Core
```

| 层级 | 命名空间 | 职责 | 约束 |
|------|----------|------|------|
| Core | `HCore.Core.*` | 纯 C# 算法、数据结构、工具 | 禁止依赖 Unity API |
| IOC | `HCore.IOC.*` | Bean 定义、容器、生命周期、事件上下文 | 负责注入与容器编排 |
| Support | `HCore.Support.*` | Unity API 绑定、扩展与工具 | 向上层屏蔽 Unity 细节 |
| Engine | `HCore.Engine.*` | 生命周期集成、队列、调度、对象池、加载 | 面向运行时基础设施 |
| Gameplay | `HCore.Gameplay.*` | 音频、输入、场景、UI、资源等模块 | 面向业务功能 |

## 仓库结构

```text
HCore/
├── Packages/top.rainhy.hcore/   # 可发布的 Unity 包
│   ├── Runtime/                 # 五层运行时代码
│   ├── LICENSE.md
│   ├── README.md
│   └── package.json
├── Assets/Tests/                # Unity Test Runner 测试
├── Assets/Examples/             # 示例与演示
├── docs/                        # 长文规范
├── tasks/                       # 任务记录
├── TASKS.md                     # 任务索引
└── AGENTS.md                    # 项目级规则入口
```

## 安装

### 方式一：作为本地包引用

将本仓库置于 Unity 项目旁侧或任意本地路径，然后在目标项目的 `Packages/manifest.json` 中添加：

```json
{
  "dependencies": {
    "top.rainhy.hcore": "file:../HCore/Packages/top.rainhy.hcore"
  }
}
```

### 方式二：通过 Git URL

在 Unity Package Manager 中选择 `Add package from git URL`，或直接在 `manifest.json` 中添加仓库地址。

> 如果通过 Git 分发，请以 `Packages/top.rainhy.hcore/` 作为包根目录。

## 快速开始

### 1. 启动容器

```csharp
using HCore;
using UnityEngine;

public sealed class GameBootstrap : MonoBehaviour
{
    private void Awake()
    {
        HCore.Instance.Start(this);
    }
}
```

### 2. 注册 Bean 并注入依赖

```csharp
using HCore.Engine.Behaviour;
using HCore.IOC.Core.Beans.Factory.Attribute.Attr;
using HCore.IOC.Core.Context.Stereotype;

public interface IScoreService
{
    int CurrentScore { get; }
    void Add(int value);
}

[Component]
public sealed class ScoreService : IScoreService
{
    public int CurrentScore { get; private set; }

    public void Add(int value)
    {
        CurrentScore += value;
    }
}

public sealed class ScorePresenter : HCoreMonoBehaviour
{
    [Autowired] private IScoreService scoreService = null!;

    private void Start()
    {
        scoreService.Add(10);
    }
}
```

> `HCoreMonoBehaviour` 不要再标注 `[Component]`。它会在 `Awake()` 中自行启动/接入容器并完成后续注入。

### 3. 发布与监听事件

```csharp
using HCore.Engine.Behaviour;
using HCore.IOC.Core.Context.Event;
using HCore.IOC.Core.Context.Event.Attr;
using HCore.IOC.Core.Context.Stereotype;

public sealed class ScoreChangedEvent : ApplicationEvent
{
    public ScoreChangedEvent(int score) : base(score)
    {
        Score = score;
    }

    public int Score { get; }
}

public sealed class ScorePublisher : HCoreMonoBehaviour
{
    public void Raise(int score)
    {
        PublishEvent(new ScoreChangedEvent(score));
    }
}

[Component]
public sealed class ScoreLogger
{
    [EventListener]
    private void OnScoreChanged(ScoreChangedEvent evt)
    {
        UnityEngine.Debug.Log($"Score => {evt.Score}");
    }
}
```

## 文档入口

### 先看这里

| 文档 | 用途 |
|------|------|
| [AGENTS.md](./AGENTS.md) | 项目级约束入口 |
| [Packages/top.rainhy.hcore/README.md](./Packages/top.rainhy.hcore/README.md) | 包使用说明与模块导航 |
| [Packages/top.rainhy.hcore/Runtime/README.md](./Packages/top.rainhy.hcore/Runtime/README.md) | 运行时代码总览 |
| [docs/CODE_GUIDE.md](./docs/CODE_GUIDE.md) | C# 代码规范长文 |
| [docs/NULLABLE_GUIDE.md](./docs/NULLABLE_GUIDE.md) | Nullable 规范长文 |
| [docs/UNITY_GUIDE.md](./docs/UNITY_GUIDE.md) | Unity 开发指南 |

### 测试与示例

| 文档 | 用途 |
|------|------|
| [Assets/Tests/Editor/README.md](./Assets/Tests/Editor/README.md) | Edit Mode 测试导航 |
| [Assets/Tests/PlayMode/README.md](./Assets/Tests/PlayMode/README.md) | PlayMode 测试导航 |
| [Assets/Tests/MANUAL_TESTING.md](./Assets/Tests/MANUAL_TESTING.md) | 命令行手动测试 |
| [Assets/Examples/Demos/README.md](./Assets/Examples/Demos/README.md) | 功能演示导航 |
| [Assets/Examples/Games/README.md](./Assets/Examples/Games/README.md) | 完整示例导航 |

### 任务与历史材料

| 文档 | 用途 |
|------|------|
| [TASKS.md](./TASKS.md) | 当前任务索引 |
| [tasks/](./tasks/) | 任务详情 |
| [.opencode/archived-docs/README.md](./.opencode/archived-docs/README.md) | OpenCode 历史归档说明 |
| [.opencode/project-rules-backup/2026-03-11-codex-migration/RESTORE.md](./.opencode/project-rules-backup/2026-03-11-codex-migration/RESTORE.md) | 迁移前快照恢复说明 |

## 测试策略

- 纯 C# 与容器逻辑优先放在 Edit Mode。
- 生命周期、协程、场景、资源、Unity API 交互放在 PlayMode。
- 依赖容器的 PlayMode 测试优先复用 `Assets/Tests/TestUtils/PlayModeTestBase.cs`。
- 运行命令行测试时，优先参考 [Assets/Tests/MANUAL_TESTING.md](./Assets/Tests/MANUAL_TESTING.md)。

## 历史边界

- `.opencode/archived-docs/` 与 `.opencode/project-rules-backup/` 仅用于历史追溯与恢复，不再是当前规范入口。
- 当前生效的仓库规则、编码规范与开发流程以 `AGENTS.md` 和 `docs/` 为准。

**最后更新时间**：2026-03-12