Unity 2022 里用 JsonUtility 存角色位置和属性，这份避坑指南请收好

Unity 2022中JsonUtility实战角色数据存储的深度解决方案在游戏开发中数据持久化是一个永恒的话题。想象一下玩家花费数小时精心培养的角色因为游戏关闭而消失无踪这种体验无疑是灾难性的。作为Unity开发者我们经常需要在本地保存角色位置、属性和状态等信息而JsonUtility作为Unity官方提供的轻量级JSON序列化工具虽然功能不如第三方库强大但在性能和对Unity原生类型的支持上有着独特优势。1. 设计可序列化的角色数据结构在开始编码之前我们需要精心设计角色的数据结构。一个好的数据结构应该既能完整保存游戏状态又能适应JsonUtility的序列化限制。[Serializable] public class CharacterData { public string characterName; public int level; public float health; public float maxHealth; public Vector3 position; public Quaternion rotation; public ListInventoryItem inventory; public CharacterStats stats; } [Serializable] public class InventoryItem { public string itemId; public int quantity; } [Serializable] public class CharacterStats { public int strength; public int agility; public int intelligence; }关键设计原则所有需要序列化的类必须标记[Serializable]特性使用public字段或标记[SerializeField]的私有字段避免使用属性(property)JsonUtility不支持嵌套类也需要单独标记[Serializable]注意Vector3和Quaternion等Unity特有类型可以直接序列化这是JsonUtility相比通用JSON库的优势之一。2. 处理JsonUtility的特殊限制JsonUtility虽然简单易用但存在一些重要限制需要特别注意2.1 不支持字典的解决方案游戏开发中经常使用字典来存储键值对数据但JsonUtility原生不支持Dictionary类型。以下是几种替代方案方案一使用键值对列表替代[Serializable] public class SerializableDictionaryTKey, TValue { public ListTKey keys new ListTKey(); public ListTValue values new ListTValue(); public void Add(TKey key, TValue value) { keys.Add(key); values.Add(value); } public TValue this[TKey key] { get { int index keys.IndexOf(key); return index 0 ? values[index] : default; } } }方案二序列化前转换为支持的类型public Dictionarystring, int statsDict new Dictionarystring, int(); // 保存时转换为列表 [Serializable] public class StatEntry { public string key; public int value; } public ListStatEntry GetSerializableStats() { return statsDict.Select(kv new StatEntry { key kv.Key, value kv.Value }).ToList(); }2.2 枚举值的处理技巧JsonUtility默认将枚举序列化为数字这在调试和版本兼容性上可能存在问题public enum CharacterClass { Warrior, Mage, Archer } // 默认序列化为数字0, 1, 2 // 解决方案添加字符串表示字段 [Serializable] public class CharacterClassData { public CharacterClass classType; public string classTypeName classType.ToString(); }3. 实现完整的存档/读档系统有了合理的数据结构和应对限制的方案我们可以实现完整的存档系统3.1 保存角色数据public class CharacterSaveSystem : MonoBehaviour { public CharacterData characterData; public void SaveCharacter(string saveFileName) { // 更新角色当前位置和旋转 characterData.position transform.position; characterData.rotation transform.rotation; // 序列化为JSON字符串 string jsonData JsonUtility.ToJson(characterData, true); // 保存到文件 string savePath Path.Combine(Application.persistentDataPath, saveFileName); File.WriteAllText(savePath, jsonData); Debug.Log($角色数据已保存到: {savePath}); } }3.2 加载角色数据public void LoadCharacter(string saveFileName) { string savePath Path.Combine(Application.persistentDataPath, saveFileName); if (File.Exists(savePath)) { string jsonData File.ReadAllText(savePath); characterData JsonUtility.FromJsonCharacterData(jsonData); // 恢复角色位置和旋转 transform.position characterData.position; transform.rotation characterData.rotation; Debug.Log(角色数据加载完成); } else { Debug.LogWarning(存档文件不存在使用默认数据); characterData new CharacterData(); } }3.3 多存档槽位实现实际游戏中通常需要支持多个存档槽位public void SaveToSlot(int slotIndex) { string fileName $save_slot_{slotIndex}.json; SaveCharacter(fileName); } public void LoadFromSlot(int slotIndex) { string fileName $save_slot_{slotIndex}.json; LoadCharacter(fileName); }4. 高级技巧与性能优化4.1 部分数据更新策略频繁保存全部角色数据可能影响性能可以实施部分更新策略public void SavePartialData(string saveFileName, ActionCharacterData updateAction) { // 先加载现有数据 LoadCharacter(saveFileName); // 只更新需要修改的部分 updateAction?.Invoke(characterData); // 重新保存 SaveCharacter(saveFileName); } // 使用示例只更新位置 saveSystem.SavePartialData(autosave.json, data { data.position transform.position; });4.2 二进制加密存储为防止玩家直接修改存档文件可以添加简单加密private string EncryptDecrypt(string data) { // 简单的XOR加密 char[] array data.ToCharArray(); for (int i 0; i array.Length; i) { array[i] (char)(array[i] ^ encryption_key[i % encryption_key.Length]); } return new string(array); } public void SaveWithEncryption(string saveFileName) { string jsonData JsonUtility.ToJson(characterData); string encryptedData EncryptDecrypt(jsonData); File.WriteAllText(saveFileName, encryptedData); }4.3 存档数据版本控制随着游戏更新数据结构可能变化需要版本控制[Serializable] public class SaveMetadata { public int version 1; public DateTime saveTime; public string gameVersion; } [Serializable] public class VersionedCharacterData { public SaveMetadata metadata; public CharacterData characterData; } public void SaveWithVersion(string saveFileName) { var versionedData new VersionedCharacterData { metadata new SaveMetadata { version 2, // 每次数据结构变更递增 saveTime DateTime.Now, gameVersion Application.version }, characterData this.characterData }; string jsonData JsonUtility.ToJson(versionedData); File.WriteAllText(saveFileName, jsonData); }5. 实战中的常见问题与解决方案5.1 MonoBehaviour的直接序列化陷阱试图直接序列化继承自MonoBehaviour的类会导致意外行为// 错误做法直接序列化MonoBehaviour public class PlayerController : MonoBehaviour { public int score; public void Save() { // 这将序列化整个MonoBehaviour包含大量不需要的引擎内部数据 string json JsonUtility.ToJson(this); } } // 正确做法使用专用的可序列化数据类 public void SaveCorrectly() { CharacterData data new CharacterData { score this.score // 只复制需要保存的字段 }; string json JsonUtility.ToJson(data); }5.2 处理Unity特有类型的序列化虽然JsonUtility支持Vector3等Unity类型但需要注意Vector3序列化为{x,y,z}结构Color和Color32需要特殊处理自定义ScriptableObject需要额外考虑[Serializable] public class AdvancedCharacterData { public Vector3 position; public Color hairColor; // Color需要转换为可序列化格式 public float[] hairColorRGB { get new float[] { hairColor.r, hairColor.g, hairColor.b }; set hairColor new Color(value[0], value[1], value[2]); } }5.3 跨平台路径处理不同平台的持久化数据路径不同需要统一处理平台持久化数据路径示例特点WindowsC:\Users\Username\AppData\LocalLow\CompanyName\GameName需要管理员权限macOS~/Library/Application Support/CompanyName/GameName隐藏目录iOS/Android应用沙盒内用户不可直接访问public string GetPlatformSafePath(string fileName) { #if UNITY_EDITOR // 编辑器模式下使用更方便的路径 return Path.Combine(Application.dataPath, Saves, fileName); #else return Path.Combine(Application.persistentDataPath, fileName); #endif }6. 性能对比与最佳实践JsonUtility相比其他JSON解决方案有其独特的性能特点序列化性能对比测试数据单位ms数据大小JsonUtilityNewtonsoft.JsonLitJson小1KB0.51.20.8中100KB3.212.58.7大1MB2810572测试环境Unity 2022.2.5f1i7-9700KRelease模式最佳实践建议对于小型、简单的数据结构优先使用JsonUtility需要复杂功能如字典支持、属性序列化时考虑第三方库频繁保存的数据保持小巧精简大型数据考虑分块保存