mcpField
U
unity-data-persistence

unity-data-persistence

github.com/muharremtozan开发1758 次安装22 周前更新
代码仓库

关于 unity-data-persistence

unity-data-persistence 是一套以 DTO 数据绑定为核心的 Unity 存档与加载系统，面向需要将游戏实体状态关联到存档数据的开发者，并支持替换序列化器和存储服务。

主要功能

  1. 01将实体直接绑定到 DTO
  2. 02保存和加载 GameData
  3. 03使用稳定的 SerializableGuid 标识
  4. 04替换存储后端与序列化器
  5. 05绑定多实体列表

适用场景

  1. 01保存玩家和物品栏状态
  2. 02从存档恢复场景实体
  3. 03从扁平 GameData 字段起步
  4. 04将本地 JSON 存储切换为其他后端

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/muharremtozan/unity-agent-skills --skill unity-data-persistence

安装后在 Claude Code 中输入/unity-data-persistence确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

assets/code/
FileDataService.cs.txt
PersistenceCore.cs.txt
SaveLoadManager.cs.txt
SaveLoadSystem.cs.txt
references/
guide.md

详细介绍

Unity 数据持久化

构建专业的保存/加载系统，以数据绑定为核心：可保存对象持有对 DTO 的实时引用，并始终保持最新状态，使序列化几乎瞬时完成，且不依赖后端。

灵感来源：adammyhre/Unity-Inventory-System。

核心架构

SaveLoadSystem
    ├── IDataService  (FileDataService by default)
    │       └── ISerializer  (JsonSerializer by default)
    └── GameData  (your root DTO)
            ├── PlayerData   (ISaveable) ←─ Hero.Bind()
            └── InventoryData (ISaveable) ←─ Inventory.Bind()

核心功能

  1. 数据绑定模式：MonoBehaviour 持有对自身 DTO 的引用，因此保存只需序列化 GameData——无需轮询，也无需遍历属性。
  2. IBind<T> / ISaveable：两个接口，可在场景加载时将场景实体与其保存数据关联起来。
  3. SerializableGuid：稳定、快速的 GUID 标识（基于 int 的比较），用于将已保存的数据与生成的实体匹配。
  4. 可替换后端：IDataService + ISerializer 让你只需改一行代码，就能从本地 JSON 切换到云端/二进制。
  5. 多实体绑定：基于列表的 Bind<T, TData>(List<TData>) 可处理多实体场景（敌人、生成器）。

核心文件（最多 3 个）

  • PersistenceCore.cs.txt — ISerializer、JsonSerializer、IDataService、ISaveable、IBind<T>、SerializableGuid
  • FileDataService.cs.txt — 本地磁盘实现：Save、Load、Delete、DeleteAll、ListSaves
  • SaveLoadSystem.cs.txt — 持久化 MonoBehaviour 协调器，提供 Bind<T,TData>() 以及公开的 Save/Load/New API

用法

快速入门（轻量路径——无需绑定）
// 1. Extend GameData with your fields
[Serializable] public class GameData {
    public string Name;
    public int Score;
}

// 2. Save / Load
SaveLoadSystem.Instance.gameData.Score = 100;
SaveLoadSystem.Instance.SaveGame();
SaveLoadSystem.Instance.LoadGame("MySave");
完整系统（专业路径——数据绑定）
// 1. Create a DTO
[Serializable] public class PlayerData : ISaveable {
    [field: SerializeField] public SerializableGuid Id { get; set; }
    public Vector3 position;
}

// 2. Implement IBind on your MonoBehaviour
public class PlayerEntity : MonoBehaviour, IBind<PlayerData> {
    [SerializeField] SerializableGuid id;
    PlayerData data;
    public SerializableGuid Id { get => id; set => id = value; }
    public void Bind (PlayerData d) { data = d; data.Id = id; transform.position = d.position; }
    void Update () { data.position = transform.position; } // write-through
}

// 3. Register in SaveLoadSystem.OnSceneLoaded
Bind<PlayerEntity, PlayerData>(gameData.playerData);

完整示例请参阅 references/guide.md，包括多实体绑定和后端切换。

核心原则

先设计数据模型。DTO 结构就是你的保存格式。从简单开始（包含扁平字段的 GameData）——只有当实体需要独立、可恢复的状态时，才添加绑定。

评论

支持 Markdown