# NovaToolsKit

**Repository Path**: helpking/nova-tools-kit

## Basic Information

- **Project Name**: NovaToolsKit
- **Description**: 一个Unity的通用架构，内容包括，基础数据处理，EditorGUI，资源打包，加载/卸载。工具开发，工具可以兼容Unity编辑器，也可以转Web页面等等。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-24
- **Last Updated**: 2026-01-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Nova Tools Kit

Unity Package Manager (UPM) 移动游戏开发插件。

## 📦 包信息

- **Package ID**: `com.novatools.kit`
- **版本**: 1.0.0
- **Unity 版本**: 2022.3+
- **类型**: 插件
- **支持平台**: Android, iOS
- **仓库地址**: git@gitee.com:helpking/nova-tools-kit.git

## 📚 文档

详细的开发指南、编码规范和架构文档，请参阅 [CLAUDE.md](./CLAUDE.md)。

## 🏗️ 项目结构

```
nova-tools-kit/
├── package.json                           # UPM 包清单
├── CLAUDE.md                              # 开发指南和架构文档
├── README.md                              # 本文件
├── Documents                              # 所有帮助文档，包括Protocol，Runtime，Editor，Test等内容的详细说明
├── Html                                   # 本工程下面所有接口，类等的方法的API接口说明(静态Html页面版本)
│
├── Protocol/                              # 接口定义层（基础层）
│   ├── Runtime/                           # 运行时接口定义
│   │   ├── Data/
│   │   │   └── IData.cs                   # 基础数据接口 (IData, IData<T>)
│   │   ├── Logger/
│   │   │   └── ILogger.cs                 # 日志接口（泛型格式化方法）
│   │   └── NovaToolsKit.Protocol.Runtime.asmdef
│   └── Editor/                            # 编辑器接口定义
│       └── NovaToolsKit.Protocol.Editor.asmdef
│
├── Runtime/                               # 运行时实现
│   ├── Data/
│   │   └── DataBase.cs                    # 基础数据类实现 (DataBase, DataBase<T>)
│   ├── Logger/
│   │   ├── NoGcLogger.cs                  # 零 GC 日志实现
│   │   └── NoGcLogHelper.cs               # 日志帮助类（缓存、扩展方法）
│   ├── Utils/
│   │   ├── UtilsXxHash.cs                 # xxHash32/64/128 实现（Burst 编译）
│   │   └── UtilsMd5.cs                    # MD5 工具（已注释，旧代码）
│   └── NovaToolsKit.Runtime.asmdef
│
├── Editor/                                # 仅编辑器代码
│   └── NovaToolsKit.Editor.asmdef
│
├── Test/                                  # 测试程序集
│   ├── Runtime/
│   │   ├── Logger/
│   │   │   ├── NoGcLoggerPerformanceTest.cs    # 性能基准测试
│   │   │   └── NoGcLoggerComparisonTest.cs     # 对比测试
│   │   └── NovaToolsKit.Test.Runtime.asmdef
│   └── Editor/
│       └── NovaToolsKit.Test.Editor.asmdef
│
└── Plugins/                               # 原生插件
    ├── Android/                           # Android 原生插件 (.aar, .jar)
    └── iOS/                               # iOS 原生插件
```

## 📋 核心功能

### 1. 数据架构模式

分层数据架构，接口定义在 Protocol 层，实现在 Runtime 层：

```csharp
using Data;

// 定义数据类
[System.Serializable]
public sealed class PlayerData : DataBase<PlayerData>
{
    public int health;
    public string playerName;

    public override bool IsValid => health > 0;

    public override void ApplyData(PlayerData data)
    {
        health = data.health;
        playerName = data.playerName;
        Dirty = true;
    }

    public override PlayerData Clone()
    {
        PlayerData clone = new PlayerData();
        clone.ApplyData(this);
        return clone;
    }

    public override void Init()
    {
        base.Init();
        health = 100;
        playerName = "";
    }
}
```

**主要优势：**
- 通过泛型约束实现类型安全
- 脏标记优化（Dirty tracking）
- 支持 Unity 序列化
- 接口与实现清晰分离

### 2. 零 GC 日志系统

为移动游戏优化的高性能、零分配日志系统：

```csharp
using Logger;

public sealed class GameManager
{
    // 将日志实例缓存为静态只读字段
    private static readonly NoGcLogger logger = NoGcLogHelper.GetLogger<GameManager>();

    public void Update()
    {
        // Debug 日志（Release 构建中会被剔除）
        logger.Debug("Frame update");
        logger.DebugFormat("Player position: {0}", playerPos);

        // Info 日志（始终编译）
        logger.Info("Game started");
        logger.InfoFormat("Score: {0}, Lives: {1}", score, lives);

        // Warning 日志
        logger.Warn("Low memory warning");
        logger.WarnFormat("Memory usage: {0} MB", memoryMb);

        // Error 日志
        logger.Error("Failed to load asset");
        logger.ErrorFormat("Asset {0} not found at {1}", assetName, path);
    }
}
```

**性能特性：**
- 预热后零 GC
- 通过线程本地存储实现线程安全
- 针对高频日志优化
- Debug 日志支持条件编译

**日志格式**: `YYYY-MM-DD HH:mm:ss,SSS [LoggerName][LogType] Message`

### 3. 高性能哈希工具

支持 Burst 编译的零分配哈希计算：

```csharp
using Utils;

// xxHash64（推荐用于通用场景）
ulong hash64 = UtilsXxHash.ComputeHash64("Hello World");
ulong hash64FromBytes = UtilsXxHash.ComputeHash64(byteArray);

// xxHash32（32 位哈希）
uint hash32 = UtilsXxHash.ComputeHash32("Hello World");

// xxHash128（Unity.Mathematics）
uint4 hash128 = UtilsXxHash.ComputeHash128("Hello World");
```

**关键特性：**
- Burst 编译实现最高性能
- 栈分配实现零堆开销
- 多种哈希位数（32/64/128 位）
- 支持字符串和字节数组

## 🚀 安装

### 方法 1: 通过 Package Manager UI 添加

1. 打开 Unity Package Manager: `Window → Package Manager`
2. 点击 `+` 按钮 → `Add package from git URL`
3. 输入: `git@gitee.com:helpking/nova-tools-kit.git`

### 方法 2: 通过 manifest.json 添加

在项目的 `Packages/manifest.json` 中添加：

```json
{
  "dependencies": {
    "com.novatools.kit": "git@gitee.com:helpking/nova-tools-kit.git"
  }
}
```

### 方法 3: 本地开发

用于本地开发和实时编辑：

1. 打开 Unity Package Manager: `Window → Package Manager`
2. 点击 `+` 按钮 → `Add package from disk`
3. 选择此仓库文件夹

## 📦 依赖

此包需要以下 Unity 包：

```json
{
  "com.unity.burst": "1.8.25",
  "com.unity.jobs": "0.70.0-preview.7",
  "com.unity.mathematics": "1.3.2"
}
```

**额外依赖：**
- `Cysharp.Text` (ZString) - NoGcLogger 零分配字符串格式化所需（需单独添加）

## 🧪 测试

### 在 Unity 中运行测试

1. 打开 Unity Test Runner: `Window → General → Test Runner`
2. **PlayMode** 标签页: 运行 `Test/Runtime/` 中的测试（运行时测试）
3. **EditMode** 标签页: 运行 `Test/Editor/` 中的测试（编辑器测试）
4. 运行特定测试: 右键测试名称 → `Run Selected`

### 测试结构

- **运行时测试** (`Test/Runtime/Logger/`)
  - 日志性能基准测试（NoGcLoggerPerformanceTest.cs）
  - 日志对比测试（NoGcLoggerComparisonTest.cs）

- **编辑器测试** (`Test/Editor/`)
  - 预留用于编辑器特定测试

## 🏛️ 程序集依赖层级

```
Protocol.Runtime（基础层，无依赖）
├── Protocol.Editor（编辑器，依赖 Protocol.Runtime）
├── Runtime（运行时，依赖 Protocol.Runtime）
│   └── Editor（编辑器，依赖 Protocol.Runtime、Protocol.Editor、Runtime）
├── Test.Runtime（测试，依赖 Protocol.Runtime、Runtime）
│   └── Test.Editor（测试，依赖所有程序集）
```

**关键设计原则：**
- Protocol 层无依赖（纯接口定义）
- Runtime 层仅依赖 Protocol.Runtime
- Editor 层依赖 Protocol 和 Runtime
- 测试程序集依赖其需要测试的内容

## 📝 编码规范

### 命名约定

| 类型 | 约定 | 示例 |
|------|------|------|
| 文件 | PascalCase | FileName.cs |
| 类 | PascalCase | ClassName |
| 接口 | I + PascalCase | IData |
| 枚举 | E + PascalCase | ELogType |
| 常量 | UPPER_SNAKE_CASE | MAX_COUNT |
| 公共字段 | camelCase | health, playerName |
| 方法 | PascalCase | ComputeHash |
| 参数 | camelCase 或 i + camelCase | value, iValue |

### 代码格式化

- **大括号**: 始终使用 Allman 风格（大括号另起一行）
- **缩进**: 4 个空格（不使用制表符）
- **编码**: UTF-8 无 BOM
- **属性**: 优先使用公共字段而非自动属性
- **密封类**: 无继承需求时添加 `sealed` 关键字（IL2CPP 优化）

### 性能要求

**禁止的操作**（特别是在 Update 循环中）：
- ❌ 禁止反射（`SendMessage`、`Invoke` 等）
- ❌ 禁止 LINQ
- ❌ 禁止 `Debug.Log`（使用 `NoGcLogger` 替代）
- ❌ 避免在循环中使用 `gameObject.GetComponent<T>()`（应缓存）
- ❌ 避免在循环中使用字符串拼接（`+` 或 `$""`）（使用 `NoGcLogger.InfoFormat`）

**最佳实践**：
- ✅ 所有日志使用 `NoGcLogger`
- ✅ 将日志实例缓存为 `static readonly` 字段
- ✅ 在高频场景中缓存委托实例
- ✅ 在循环中使用 `Physics.RaycastNonAlloc` 而非 `Physics.Raycast`
- ✅ 游戏逻辑优先使用普通 C# 类而非 `MonoBehaviour`
- ✅ 保持函数在 50 行以内，嵌套深度在 4 层以内

## 🎯 设计理念

Nova Tools Kit 专注于提供高性能、零分配的基础工具，适用于移动游戏开发：

- **性能优先**: 所有核心功能都针对移动平台进行了深度优化
- **零 GC 设计**: 减少垃圾回收压力，提升游戏流畅度
- **分层架构**: 接口与实现分离，易于扩展和维护
- **类型安全**: 充分利用 C# 泛型系统，编译期错误检查

## 📖 版本历史

### v1.0.0（当前版本）
- 初始版本
- 数据架构模式（IData, DataBase）
- NoGcLogger 零 GC 日志系统
- UtilsXxHash 高性能哈希工具
- Unity 2022.3+ 支持

## 📄 许可证

Copyright © 2024 本地插件库. All rights reserved.

## 🤝 贡献

贡献指南请参考 [CLAUDE.md](./CLAUDE.md)。

## 📧 联系方式

如有问题或需要支持，请联系开发团队。

---

**用 ❤️ 为 Unity 游戏开发打造**