Unity 存档方式配 TaoToken：settings.json 与 config.toml 骨架一次讲清

1. Unity 存档方式到底怎么选PlayerPrefs、JsonUtility、二进制序列化Unity 存档方式这件事说简单也简单说坑也多。你搜「unity 存档方式」大概率会看到三种主流方案PlayerPrefs、JsonUtility、二进制序列化。它们不是互相替代的关系而是各自适合不同量级的数据。PlayerPrefs 适合存音量、画质档位、是否看过新手引导这种零散小数据JsonUtility 适合存一个结构清晰的 Save 类字段可读、方便调试二进制序列化适合字段多、不想让玩家直接改存档的场景。但真正让新手卡住的往往不是「怎么写存档」而是「存档写完了怎么和外部 AI 工具链的配置衔接起来」。比如你想让 AI 帮你生成存档结构、检查字段命名、甚至跑一次配置校验就需要一个统一的 Key/API 通道。这篇就把两件事拆成可验证的两步先讲清 Unity 三种存档方式的骨架再给出 settings.json 与 config.toml 的可复制配置最后用统一通道跑通一次校验。适合谁看正在做 Unity 小项目、需要存档系统同时想接入 AI 辅助编码或配置校验的开发者。下面所有代码都可以直接复制进项目改。2. 前置准备TaoToken 统一 Key 与 API 通道在动手写存档之前先把外部工具链的通道准备好。TaoToken 的作用是给你一个统一的 Key 和 API 入口让模型对话、编码辅助、配置校验都走同一条通道不用每个工具单独配一遍。你需要先拿到一个 API Key。进入控制台创建即可控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite拿到 Key 之后记住两个地址官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。注意 API 地址后面不加任何 UTM 参数配置里写干净地址就行。提示Key 只显示一次创建后立刻复制到安全的地方。不要把它硬编码进 Unity 的 C# 脚本里提交到仓库后面配置章节会讲怎么放。这一步的目标不是「注册」而是让你手里有一个可用的 Key 和两个明确的地址下一步的 settings.json 和 config.toml 都要用到它们。3. 可复制配置settings.json 与 config.toml 骨架外部 AI 工具通常读两种配置文件JSON 格式的 settings.json和 TOML 格式的 config.toml。下面两份骨架你可以直接复制把 Key 换成自己的。3.1 settings.json 骨架这份配置适合大多数读 JSON 的工具字段名保持通用{ provider: taotoken, api_base: https://taotoken.net/api, api_key: sk-你的Key粘贴在这里, model: claude-sonnet-4-20250514, timeout_seconds: 60, max_retries: 2, unity: { save_root: Assets/StreamFile, default_format: json, pretty_print: true } }几个字段说明api_base固定写 https://taotoken.net/api 不要加斜杠结尾unity.save_root对应你 Unity 项目里存档目录和后面 C# 里的Application.dataPath拼接路径保持一致default_format决定默认用哪种存档方式调试阶段建议先用 json。3.2 config.toml 骨架有些工具更偏好 TOML等价配置如下provider taotoken api_base https://taotoken.net/api api_key sk-你的Key粘贴在这里 model claude-sonnet-4-20250514 timeout_seconds 60 max_retries 2 [unity] save_root Assets/StreamFile default_format json pretty_print trueTOML 的层级用[unity]表示和 JSON 里的嵌套对象是一回事。两份配置的字段名我特意保持一致这样你在不同工具之间切换时不用重新记。注意api_key这一行在正式项目里建议改成读环境变量比如api_key ${TAOTOKEN_API_KEY}避免明文进版本库。4. Unity 三种存档方式的完整代码与配置校验配置准备好之后回到 Unity 本体。下面三种方式我都给出保存和读取的完整方法并说明各自和配置文件的衔接点。4.1 Save 类与 PlayerPrefs 轻量存档先定义可序列化的 Save 类这是三种方式共用的数据结构using System.Collections.Generic; using UnityEngine; [System.Serializable] public class Save { public Listint livingTargetPosition new Listint(); public Listint livingMonsterPosition new Listint(); public int shootNum 0; public int score 0; }PlayerPrefs 不适合存复杂结构但适合存「当前用哪种存档格式」这种开关。比如// 记录玩家选择的存档格式供工具链读取 PlayerPrefs.SetString(save_format, json); PlayerPrefs.SetInt(save_slot, 1); PlayerPrefs.Save();这样你的外部工具读 settings.json 里的default_formatUnity 运行时读 PlayerPrefs 的save_format两边能对上。4.2 JsonUtility 存档可读性最好Unity 自带的 JsonUtility 不需要第三方库直接可用using System.IO; using UnityEngine; public void SaveByJson(Save save) { string dir Path.Combine(Application.dataPath, StreamFile); if (!Directory.Exists(dir)) Directory.CreateDirectory(dir); string filePath Path.Combine(dir, save.json); string json JsonUtility.ToJson(save, true); File.WriteAllText(filePath, json); Debug.Log(JSON 存档写入: filePath); } public Save LoadByJson() { string filePath Path.Combine(Application.dataPath, StreamFile, save.json); if (!File.Exists(filePath)) return new Save(); string json File.ReadAllText(filePath); return JsonUtility.FromJsonSave(json); }JsonUtility.ToJson第二个参数传true会格式化输出和 settings.json 里的pretty_print对应。存档文件长这样肉眼可读调试时直接打开看字段对不对{ livingTargetPosition: [1, 2, 3], livingMonsterPosition: [4, 5], shootNum: 10, score: 250 }4.3 二进制序列化字段多时更紧凑字段一多JSON 文件会变大二进制更紧凑using System.IO; using System.Runtime.Serialization.Formatters.Binary; using UnityEngine; public void SaveByBinary(Save save) { string dir Path.Combine(Application.dataPath, StreamFile); if (!Directory.Exists(dir)) Directory.CreateDirectory(dir); string filePath Path.Combine(dir, save.bin); BinaryFormatter formatter new BinaryFormatter(); using (FileStream fs File.Create(filePath)) { formatter.Serialize(fs, save); } Debug.Log(二进制存档写入: filePath); } public Save LoadByBinary() { string filePath Path.Combine(Application.dataPath, StreamFile, save.bin); if (!File.Exists(filePath)) return new Save(); BinaryFormatter formatter new BinaryFormatter(); using (FileStream fs File.Open(filePath, FileMode.Open)) { return (Save)formatter.Deserialize(fs); } }注意BinaryFormatter在新版 .NET 里被标记为不安全Unity 项目里仍可用但如果你要跨平台或长期维护建议换成JsonUtility或自己写字节流。这也是为什么我在配置里把default_format默认设成 json。4.4 用统一通道跑一次配置校验三种存档代码写完后怎么确认你的 settings.json 和 config.toml 没写错用统一通道发一次请求校验即可。下面用 curl 演示把 Key 换成你自己的curl https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 256, messages: [ {role: user, content: 检查这段 Unity 存档配置是否合法api_basehttps://taotoken.net/api, default_formatjson, save_rootAssets/StreamFile} ] }如果返回里有正常的文本内容说明 Key、地址、模型名三者都对上了。这一步的意义在于把「存档读写」和「工具链配置」彻底拆开验证存档出问题查 C#配置出问题查这份请求。5. 本篇常见错排查5.1 存档路径不存在导致写入失败Application.dataPath在编辑器里指向 Assets 目录但StreamFile子目录不会自动创建。上面代码里我加了Directory.CreateDirectory如果你抄的是老教程没这句就会报DirectoryNotFoundException。排查方法在保存前打印dir看路径对不对。5.2 JsonUtility 字段为空的三个原因第一Save 类没加[System.Serializable]第二字段是属性property而不是字段fieldJsonUtility 只认 public 字段第三字段名和 JSON 里的键不一致。对照 settings.json 里的unity节点确保命名风格统一。5.3 配置校验返回 401 或 404401 通常是 Key 没带对检查x-api-key头有没有多余空格404 多半是api_base写错确认是 https://taotoken.net/api 而不是带 UTM 的官网地址。这两个错误在排障时优先查接入文档里有完整说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite5.4 二进制存档换版本后读不出来BinaryFormatter对类结构变化很敏感你给 Save 加一个字段旧存档就可能反序列化失败。解决办法是给 Save 加版本号字段读取时判断版本再决定怎么解析。这也是长期项目更推荐 JSON 的原因。6. 把存档与工具链接起来下一步怎么走存档代码和配置文件都跑通之后你可以把两者真正串起来让 AI 工具读你的 Save 类定义自动生成对应的 settings.json 字段校验规则或者反过来根据配置生成 C# 骨架。这一步用模型对话就能做模型对话入口https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite如果你是要长期做 Unity 项目、频繁让 AI 参与编码和配置生成建议直接上 Coding Plan省得每次单独配 KeyCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite我自己的习惯是PlayerPrefs 只存开关JsonUtility 做主力存档二进制留给字段爆炸的场景配置文件里default_format跟着改。这样存档出问题查 C#配置出问题查那份 curl 请求两边互不干扰。