Unity 使用 Protobuf（Pb2）二进制数据全流程工具详解
前言
在Unity游戏开发中，高效、快速、安全地读取配置数据是一项重要需求。本文介绍一种完整的解决方案——使用Protobuf二进制格式（Pb2）存储和读取游戏数据，并详细分享实现全流程的Unity工具。
一、技术流程概览
实现Unity读取Pb2二进制数据的流程如下：
- Excel设计数据表
- Excel转Proto文件
- Proto文件转C#类
- Excel数据序列化为Pb2二进制文件
- Unity中加载Pb2数据文件
二、具体实现步骤
1. Excel设计数据表
数据表应遵循特定的格式规范：
- 第一行：字段注释
- 第二行：字段名（英文变量名）
- 第三行：字段数据类型（例如int32、string）
- 第四行及以下：数据内容
2. Excel转Proto文件
使用自定义编辑器工具自动将Excel表转换为.proto文件。
关键代码：ProtoGenerator.cs
private void GenerateProtoFile()
{
FileInfo fileInfo = new FileInfo(excelFilePath);
if (!fileInfo.Exists)
{
Debug.LogError("Excel 文件不存在: " + excelFilePath);
return;
}
// 确保输出目录存在
if (!Directory.Exists(outputFolder))
{
Directory.CreateDirectory(outputFolder);
}
// 定义 .proto 文件头部信息
string protoContent = "syntax = \"proto3\";\n";
protoContent += "package GameDataProto;\n\n";
using (ExcelPackage package = new ExcelPackage(fileInfo))
{
// 遍历所有工作表，每个工作表生成一个 message
foreach (ExcelWorksheet worksheet in package.Workbook.Worksheets)
{
string messageName = worksheet.Name;
protoContent += $"message {messageName} {{\n";
// 假定第一行为注释，第二行为变量名，第三行为类型
int colCount = worksheet.Dimension.Columns;
int fieldIndex = 1;
for (int col = 1; col <= colCount; col++)
{
object commentObj = worksheet.Cells[1, col].Value;
object variableNameObj = worksheet.Cells[2, col].Value;
object typeObj = worksheet.Cells[3, col].Value;
if (variableNameObj == null || typeObj == null)
continue;
string comment = commentObj != null ? commentObj.ToString().Trim() : "";
string variableName = variableNameObj.ToString().Trim();
string type = typeObj.ToString().Trim();
if (!string.IsNullOrEmpty(comment))
{
protoContent += $" // {comment}\n";
}
protoContent += $" {type} {variableName} = {fieldIndex};\n";
fieldIndex++;
}
protoContent += "}\n\n";
}
}
string protoFilePath = Path.Combine(outputFolder, "GameDataProto.proto");
Editor.EditorHelper.WriteAllText(protoFilePath, protoContent);
Debug.Log($"生成 .proto 文件: {protoFilePath}");
}- 通过Unity Editor菜单打开窗口，选择Excel文件与输出目录，自动生成.proto文件。
3. Proto文件转C#类
根据生成的.proto文件，自动生成对应的C#数据类。
关键代码：ProtoToCSharpGenerator.cs
- 自动解析proto协议，生成继承自
DataInfo的数据类与继承自BaseGameData的容器类GameData。
[ProtoBuf.ProtoContract]
public class DataInfo
{
[ProtoBuf.ProtoIgnore]
public int id;
}
public class BaseGameData
{
/// <summary>
/// 使用反射将加载到的表格数据存储到当前 GameData 实例中。
/// 例如，加载到的 List<CharacterInfo> 会赋值给属性名为 CharacterInfo 的属性，
/// 要求属性类型必须为 List<T>，T 与传入数据类型一致。
/// </summary>
/// <typeparam name="T">表格数据的元素类型</typeparam>
/// <param name="tableData">加载到的表格数据列表</param>
public void SetTableData<T>(List<T> tableData)
{
// 查找当前实例中类型为 List<T> 的公共属性
var property = this.GetType().GetProperties(BindingFlags.Public | BindingFlags.Instance)
.FirstOrDefault(p => p.PropertyType == typeof(List<T>));
if (property != null)
{
property.SetValue(this, tableData);
Debug.Log($"成功将 {typeof(T).Name} 数据加载到 {this.GetType().Name} 中。");
}
else
{
Debug.LogError($"在 {this.GetType().Name} 中未找到类型为 List<{typeof(T).Name}> 的属性。");
}
}
public T GetDataByID<T>(int id) where T : DataInfo
{
var containerType = GetType();
// 改为搜索公共字段，而非属性
var field = containerType.GetFields(BindingFlags.Public | BindingFlags.Instance)
.FirstOrDefault(f => f.FieldType == typeof(List<T>));
if (field != null)
{
var list = field.GetValue(this) as List<T>;
if (list != null)
{
return list.FirstOrDefault(item => item.id == id);
}
}
return default(T);
}
} // 固定使用的命名空间
string packageName = "Reacool.Core.DataTable";
List<string> messageNames = new List<string>();
string[] lines = Reacool.Editor.EditorHelper.ReadAllLines(protoFilePath);
bool isMessage = false;
bool isEnum = false;
StringBuilder sb = new StringBuilder();
// 文件头注释和 using 声明
sb.AppendLine("// 通过 .proto 文件自动生成的 C# 文件，请勿手动修改");
sb.AppendLine("using System.Collections.Generic;");
sb.AppendLine();
// 开始生成代码，强制命名空间为 Reacool.Core.DataTable
sb.AppendLine($"namespace {packageName}");
sb.AppendLine("{");
// 解析 .proto 文件内容
for (int i = 0; i < lines.Length; i++)
{
string line = lines[i].Trim();
// 忽略 package 声明（固定命名空间）
if (line.StartsWith("package"))
{
continue;
}
else if (line.StartsWith("//"))
{
sb.AppendLine(" " + line);
}
else if (line.StartsWith("message"))
{
isMessage = true;
var match = Regex.Match(line, @"message\s+(\w+)");
if (match.Success)
{
string messageName = match.Groups[1].Value;
if (!messageNames.Contains(messageName))
messageNames.Add(messageName);
// 表格类继承 DataInfo
sb.AppendLine(" [ProtoBuf.ProtoContract]");
sb.AppendLine($" public class {messageName} : DataInfo");
sb.AppendLine(" {");
// 在每个 message 里，自动插入 idProxy 属性，替代基类 id 做序列化
sb.AppendLine(" [ProtoBuf.ProtoMember(1)]");
sb.AppendLine(" public int idProxy");
sb.AppendLine(" {");
sb.AppendLine(" get => base.id;");
sb.AppendLine(" set => base.id = value;");
sb.AppendLine(" }");
}
}
else if (line.StartsWith("enum"))
{
isEnum = true;
var match = Regex.Match(line, @"enum\s+(\w+)");
if (match.Success)
{
string enumName = match.Groups[1].Value;
sb.AppendLine(" public enum " + enumName);
sb.AppendLine(" {");
}
}
else if (line.StartsWith("}"))
{
if (isMessage || isEnum)
{
sb.AppendLine(" }");
isMessage = false;
isEnum = false;
}
}
else if (string.IsNullOrEmpty(line))
{
sb.AppendLine();
}
else if (isMessage)
{
// 解析 message 内字段，如 "repeated type name = id;"
var fieldMatch = Regex.Match(line, @"(repeated\s+)?(\w+)\s+(\w+)\s*=\s*(\d+);");
if (fieldMatch.Success)
{
bool isArray = !string.IsNullOrEmpty(fieldMatch.Groups[1].Value);
string fieldType = fieldMatch.Groups[2].Value;
string fieldName = fieldMatch.Groups[3].Value;
int fieldId = int.Parse(fieldMatch.Groups[4].Value);
// 跳过 id 属性，因为我们已经用 idProxy 代替
if (fieldName.Equals("id", System.StringComparison.OrdinalIgnoreCase))
{
continue;
}
// 简单转换 Protobuf 基本类型为 C# 类型
if (fieldType == "int32") fieldType = "int";
else if (fieldType == "int64") fieldType = "long";
sb.AppendLine($" [ProtoBuf.ProtoMember({fieldId})]");
sb.AppendLine($" public {fieldType}{(isArray ? "[]" : "")} {fieldName};");
}
}
else if (isEnum)
{
sb.AppendLine(" " + line.Replace(';', ','));
}4. Excel数据序列化为Pb2二进制文件
使用工具将Excel表中数据自动序列化为Protobuf二进制格式。
关键代码：ProtobufBytesGenerator.cs
- 自动读取Excel文件，解析工作表，并序列化为Pb2格式，存储成.bytes文件。
FileInfo excelFile = new FileInfo(excelFilePath);
using (ExcelPackage package = new ExcelPackage(excelFile))
{
// 通过反射获取 GameData 类型的所有公共实例字段
Type gameDataType = typeof(T);
FieldInfo[] fields = gameDataType.GetFields(BindingFlags.Public | BindingFlags.Instance);
foreach (FieldInfo field in fields)
{
// 仅处理 List<T> 类型的字段
if (field.FieldType.IsGenericType &&
field.FieldType.GetGenericTypeDefinition() == typeof(List<>))
{
Type elementType = field.FieldType.GetGenericArguments()[0];
// 约定工作表名称与元素类型名称相同（如 CharacterInfo、AudioInfo 等）
string sheetName = elementType.Name;
var worksheet = package.Workbook.Worksheets[sheetName];
if (worksheet == null)
{
Debug.LogWarning("未找到工作表：" + sheetName + "，跳过。");
continue;
}
// 调用通用解析方法 ParseSheet<T> 将工作表数据转为 List<T>
MethodInfo method = typeof(BinaryGenerator)
.GetMethod("ParseSheet", BindingFlags.NonPublic | BindingFlags.Static);
MethodInfo genericMethod = method.MakeGenericMethod(elementType);
object listObj = genericMethod.Invoke(null, new object[] { worksheet });
// 输出文件路径：以工作表名称命名的二进制文件（例如 CharacterInfo.bytes）
string outputFilePath = Path.Combine(outputFolder, sheetName + ".bytes");
using (FileStream fs = new FileStream(outputFilePath, FileMode.Create))
{
Serializer.Serialize(fs, listObj);
}
Debug.Log("生成二进制文件成功：" + outputFilePath);
}
}
}5. Unity中加载Pb2数据文件
通过DataTableManager读取Pb2二进制文件并反序列化。
关键代码：DataTableManager.cs、BaseGameData.cs
- 使用泛型反射动态加载二进制数据，存入
BaseGameData对象中，统一管理。
/// <summary>
/// 保存二进制数据
/// </summary>
/// <param name="fileData"></param>
/// <typeparam name="T"></typeparam>
public void ProcessByteData<T,T2>(byte[] fileData)where T : DataInfo where T2 : BaseGameData
{
if (fileData == null || fileData.Length == 0)
{
Debug.LogError("传入的数据为空！");
return;
}
// 根据类型名称生成对应的字段名：例如 "CharacterInfo" -> "characterInfos"
string typeName = typeof(T).Name;
string fieldName = char.ToLowerInvariant(typeName[0]) + typeName.Substring(1) + "s";
// 利用反射获取全局 GameData 实例中对应的公共字段
var field = typeof(T2).GetField(fieldName, System.Reflection.BindingFlags.Public | System.Reflection.BindingFlags.Instance);
if (field == null)
{
Debug.LogWarning($"GameData 中未找到对应字段：{fieldName}");
return;
}
// 检查该字段是否已经有数据加载，若有数据，则跳过加载
var existingData = field.GetValue(this.GameData) as System.Collections.IList;
if (existingData != null && existingData.Count > 0)
{
Debug.Log($"{typeName} 数据已加载，跳过加载。");
return;
}
// 反序列化传入的 bytes 数据
List<T> listObj = null;
try
{
using (var ms = new System.IO.MemoryStream(fileData))
{
listObj = ProtoBuf.Serializer.Deserialize<List<T>>(ms);
}
}
catch (System.Exception ex)
{
Debug.LogError($"解析 {typeName} 数据失败：{ex.Message}");
return;
}
// 将解析后的数据存入 GameData 中对应的字段
field.SetValue(this.GameData, listObj);
Debug.Log($"成功加载 {typeName} 数据到 GameData.{fieldName}");
}三、关键代码解析
- Excel转二进制数据：使用EPPlus解析Excel文件，序列化数据为二进制格式。
- 数据反序列化：利用Protobuf库，将二进制数据反序列化为C#对象。
- 反射自动加载：利用C#反射特性，自动匹配数据字段和数据类型，简化数据加载过程。
四、总结
本文提供了一整套基于Unity引擎的Protobuf（Pb2）数据管理流程，从Excel设计、数据转换、代码生成到数据加载，自动化程度高且扩展性强。通过本文分享的工具与方法，开发者可以高效地实现Unity项目的数据管理。