Zstandard for Unity

com.nicoier.zstd.unity 是一个可通过 Unity Package Manager 安装的 Zstandard 原生插件，提供：

• byte[] 与 Stream 的压缩、解压缩 API
• 基于参考文件的差分压缩与补丁应用 API
• Windows、macOS、Linux、Android 和 iOS 原生库
• 不依赖其他 Unity 包的可导入示例

当前内置 Zstandard 版本：1.5.7。C# P/Invoke 绑定由 ClangSharp 生成。

要求

• Unity 2021.3 或更高版本
• 在使用 Git URL 安装时，本机需要可用的 Git

通过 UPM 安装

在 Unity 中打开 Window > Package Manager，点击 +，选择 Install package from git URL...，输入：

https://github.com/NicoIer/zstd-unity.git

也可以直接写入项目的 Packages/manifest.json：

{
  "dependencies": {
    "com.nicoier.zstd.unity": "https://github.com/NicoIer/zstd-unity.git"
  }
}

发布版本后，建议在 URL 末尾添加标签以锁定版本，例如 https://github.com/NicoIer/zstd-unity.git#v1.1.0。

本地开发时，也可以在 Package Manager 中选择 Install package from disk...，并选择本仓库根目录的 package.json。

基础压缩

using System.Text;
using zstd;

byte[] source = Encoding.UTF8.GetBytes("Hello Zstandard");
byte[] compressed = ZStandardAPI.Compress(source);
byte[] restored = ZStandardAPI.Decompress(compressed);

生成并应用差分文件

using System;
using zstd;

class DemoBytes
{
    static void Main()
    {
        // 假设 refData 是参考文件的内容，srcData 是目标文件的内容
        byte[] refData = System.IO.File.ReadAllBytes("ref.bin");
        byte[] srcData = System.IO.File.ReadAllBytes("target.bin");

        // 生成 patch（差分压缩结果）
        byte[] patch = ZStandardDiffAPI.CompressPatch(
            src: srcData,
            refData: refData,
            compressionLevel: 0,                 // 0 使用默认压缩级别
            enableLongDistanceMatching: true,    // 建议启用 LDM
            windowLog: null,                     // 让 API 自动根据 src 大小估算
            chainLog: null,
            targetLength: null
        );

        System.IO.File.WriteAllBytes("target.patch.zst", patch);
        Console.WriteLine($"Patch written: target.patch.zst, size={patch.Length} bytes");

        // 应用 patch（恢复原始目标数据）
        byte[] restored = ZStandardDiffAPI.DecompressPatch(
            patchBytes: patch,
            refData: refData
        );

        System.IO.File.WriteAllBytes("target.restored.bin", restored);
        Console.WriteLine($"Restored written: target.restored.bin, size={restored.Length} bytes");

        // 校验恢复结果是否与原始一致
        bool same = restored.Length == srcData.Length &&
                    System.Linq.Enumerable.SequenceEqual(restored, srcData);
        Console.WriteLine($"Restored equals original: {same}");
    }
}

Samples

安装包后，在 Package Manager 的包详情中导入 Basic Usage。该示例会演示 普通压缩往返和参考文件补丁往返，不需要 TMPro、UniTask 等额外依赖。

支持的平台

平台	架构
Windows	x86_64
macOS	x86_64、ARM64
Linux	x86_64、ARM64
Android	ARMv7、ARM64、x86、x86_64
iOS	ARM64、x86_64 simulator

包结构

Runtime/        C# API、生成的绑定与原生插件
Tests/Editor/   Unity Test Framework 测试
Samples~/       可从 Package Manager 导入的示例
Documentation~/ 离线文档
Tools~/         绑定生成辅助文件，不会被 Unity 导入

License

本项目的托管代码使用 MIT License。Zstandard 原生库使用 BSD-3-Clause License，详情见 Third Party Notices.md。