Unio 项目使用教程

Unio 项目使用教程

1. 项目介绍

Unio（全称为 Unity Native I/O）是一个用于 Unity 的小型 I/O 实用程序集，它使用本机内存区域。Unio 提供了一个 System.IO.File 的替代方案，允许开发者使用 Unity 的 NativeArray 进行文件读写操作。这有助于减少 C# 托管内存的使用，从而提高游戏性能。

主要功能

• NativeFile.ReadAllBytes: 将文件内容一次性读取到 Unity 的 Native 内存区域。
• NativeFile.ReadAllBytesAsync: 异步读取文件内容到 Unity 的 Native 内存区域。
• NativeFile.WriteAllBytes: 将数据写入文件。
• NativeFile.WriteAllBytesAsync: 异步写入数据到文件。
• NativeArray.AsMemory(): 将 NativeArray 转换为 Memory，便于与现代 C# API 互操作。
• NativeArrayBufferWriter: 使用 NativeArray 实现的 IBufferWriter，适用于可变长度缓冲区。

2. 项目快速启动

安装

你可以通过 Unity 的 Package Manager 添加 Git URL 来安装 Unio：

https://github.com/hadashiA/Unio.git#0.2.0

使用示例

读取文件

// 同步读取文件
using var bytes = NativeFile.ReadAllBytes("/path/to/file");

// 异步读取文件
using var bytes = await NativeFile.ReadAllBytesAsync("/path/to/file", cancellationToken: cancellationToken);

写入文件

// 同步写入文件
var bytes = NativeFile.WriteAllBytes("/path/to/file", nativeArray);

// 异步写入文件
var bytes = await NativeFile.WriteAllBytesAsync("/path/to/file", nativeArray);

使用 NativeArrayBufferWriter

using var bufferWriter = new NativeArrayBufferWriter<byte>(InitialBufferSize);

// 使用 Utf8JsonWriter 写入 JSON
var jsonWriter = new Utf8JsonWriter(bufferWriter);
JsonSerializer.Serialize(jsonWriter, data);

// 获取 NativeArray<byte> 并写入文件
var nativeArray = bufferWriter.WrittenBuffer;
NativeFile.WriteAllBytes("/path/to/file", nativeArray);

3. 应用案例和最佳实践

案例1：序列化与反序列化

Unio 可以与现代序列化库（如 System.Text.Json、MessagePack-CSharp、MemoryPack 等）无缝集成。以下是一个使用 Unio 进行序列化和反序列化的示例：

using var bytes = NativeFile.ReadAllBytes("/path/to/file");

// 使用 System.Text.Json 反序列化
var deserializedData = JsonSerializer.Deserialize<MyData>(bytes.AsSpan());

// 使用 MessagePack-CSharp 反序列化
var deserializedData = MessagePackSerializer.Deserialize<MyData>(bytes.AsMemory());

案例2：Unity 资源加载

Unio 可以与 Unity 的资源加载 API 结合使用，例如从 Addressable 加载资源：

var textAsset = await Addressables.LoadAssetAsync<TextAsset>(assetPath);
var bytes = textAsset.GetData<byte>().AsMemory();
YamlSerializer.Deserialize<MyData>(bytes);

4. 典型生态项目

Unity 资源管理

Unio 可以与 Unity 的资源管理工具（如 Addressable）结合使用，提供更高效的资源加载和处理方式。

现代序列化库

Unio 支持与多种现代序列化库（如 System.Text.Json、MessagePack-CSharp、MemoryPack 等）集成，提供高性能的序列化和反序列化功能。

Unity 网络请求

Unio 可以与 Unity 的网络请求 API 结合使用，例如处理 UnityWebRequest 的下载数据：

using var request = UnityWebRequest.Get(url);
while (!request.isDone)
{
    yield return request.SendWebRequest();
}

var bytes = request.downloadHandler.nativeData.AsMemory();
YamlSerializer.Deserialize<MyData>(bytes);

通过这些应用案例和最佳实践，Unio 可以帮助开发者更高效地处理 Unity 中的 I/O 操作，提升游戏性能。