今日速览

  • setAchievement() 只改内存，不发网络。不发 storeStats()，玩家永远看不到那个弹窗——这是 90% 的「成就没弹」根因。
  • storeStats() 是异步推送、有节流的调用。别在 _process 里调，也别每帧解锁就推一次；按「关卡结束 / 退出游戏 / 每 30 秒最多一次」的节奏推。
  • SDK 1.60 之前必须先 requestCurrentStats() 并等回调成功再操作成就；在 _ready() 里立刻 set，等于把成就扔进黑洞。
  • 成就的 API Name 必须先在 Steamworks 后台建好并发布，否则 setAchievement 静默返回 false。编辑器里跑不出成就，多半是没发布、或没跑在 Steam 客户端里。
  • Steam 默认上限 100 个成就；成就名与图标须全年龄合规，靠「凑数成就」刷数量会被玩家和算法一起惩罚。

核心学习内容

一、成就的三段时序：define → set → store

Steamworks 官方把成就接入拆成三步，官方文档说「10 分钟、10 行代码」——确实，但前提是你理解它是三段式而不是一个函数：

  1. 定义（后台）：在 App Admin → Stats & Achievements 里建成就，拿到 API Name（如 ACH_KILL_100）。这个名字是代码与 Steam 之间唯一的契约。
  2. 解锁（本地内存）：Steam.setAchievement("ACH_KILL_100")。文档原话是 “This call only modifies Steam’s in-memory state so it is quite cheap” —— 便宜，因为它什么都没提交。
  3. 提交（网络 + 弹窗）：Steam.storeStats()。这一步才会把状态推到 Steam 服务器，并触发右下角那个 Toast 弹窗。

所以正确的写法是「批量攒、集中推」：一局游戏里可能解锁 3 个成就，内存里 set 三次，关卡结束时 store 一次。这同时解决了性能问题和节流问题。

配套读回用 getAchievement(name)，全局稀有度用 getAchievementAchievedPercent(name)——后者能告诉你「这个成就只有 2.3% 玩家拿到」，是做难度调优的免费数据。

二、5 个「成就没弹」的真实原因

按踩坑频率排序：

  1. 漏了 storeStats。set 完就完事，内存里是 true，Steam 上还是灰的。
  2. API Name 拼错或没发布。后台建了但没点 Publish，或代码里写成 ach_kill_100（大小写敏感）。返回值是 false，但很多人没检查。
  3. 在 Steam 没初始化成功时调用。从编辑器直接 F5 跑、没有 steam_appid.txt、或 Steam 客户端没开，Steam.steamInitEx() 失败。正确姿势是全程用一个 steam_ready 标志守护，未就绪时降级为本地成就（先写本地存档，下次启动补推），而不是让游戏崩。
  4. 时序错：老版本 SDK 需 requestCurrentStats 回调完成后再 set；新版本虽放宽，但初始化当帧就 set 仍然危险。统一放到「初始化成功后的下一帧或进入主菜单时」。
  5. 测试方式不对。已解锁的成就不会重复弹。测试要 clearAchievement() + storeStats() 重置，且成就必须在后台发布过才能测。

另外提醒一句：indicateAchievementProgress(name, cur, max) 只负责显示进度条（比如 37/100），它不存档、不解锁。真正的解锁仍要靠你自己在达到条件时 setAchievement。

三、成就该当成设计工具，不是奖杯货架

把成就分成四类，各占约 1/4，是性价比最高的结构：

  • 进度型（通关、到达第 5 关）：给绝大多数玩家的确定回报，完成率应 >60%。
  • 探索型（找到隐藏房间、用三种武器各赢一次）：教会玩家「这游戏还有别的玩法」，是低成本的内容放大器。
  • 挑战型（无伤、速通、极限难度）：给硬核玩家炫耀资本，完成率 1-5% 正好。
  • 彩蛋型（对着雕像跳 10 次）：社交传播素材，也是玩家写评测时会提的梗。

24 个成就的预算：进度 8 + 探索 7 + 挑战 6 + 彩蛋 3。这个数量对独立游戏刚好——足够撑起「有内容」，又不至于让完成度百分比变成噪音。

🎯 DeepSeek 提示词

提示词 1：生成 GodotSteam 成就管理器（含离线补推）

适用场景：第一次接 Steamworks 成就，想要一个能直接用的 autoload。

你是一位 Godot 4.3 + GodotSteam 的资深开发者。请为我写一个成就管理器 Autoload 脚本（GDScript），文件路径 res://autoload/achieve.gd。

【功能要求】
1. 启动时调用 Steam.steamInitEx()，用返回值与 Steam.isSteamRunning() 判断是否就绪，结果存为 steam_ready: bool。
2. 提供 unlock(api_name: String) 方法：
   - 若成就已解锁（getAchievement 返回 true），直接 return，不重复 set。
   - 若 steam_ready 为 false，仅写入本地存档 user://pending_achievements.json 排队，并打印 warning。
   - 若 steam_ready 为 true，调用 setAchievement，检查其 bool 返回值，失败时打印 error 并把 api_name 记入 pending 队列。
3. 提供 flush() 方法：调用 storeStats，成功后清空 pending 队列。
4. flush 必须节流：内部记录上次 flush 时间，30 秒内重复调用直接忽略（用 Time.get_ticks_msec 实现）。
5. 在 _notification 收到 NOTIFICATION_WM_CLOSE_REQUEST 时强制 flush 一次，并在 _exit_tree 再兜底一次。
6. 提供 get_progress(api_name) 返回 Dictionary {unlocked: bool, percent: float}，percent 来自 getAchievementAchievedPercent。

【约束】
- 所有 Steam.* 调用都必须包在 if steam_ready 里，禁止在未就绪时调用任何 Steam API。
- 只输出一个完整的 .gd 文件，不要解释，不要省略代码，不要用 ... 占位。
- 注释用中文，每个公开方法上方写一行用途说明。
- 不要引入任何第三方插件。

【输出格式】
先输出代码块，再在代码块之后用 5 行以内的列表说明「需要在 project.godot 里注册 autoload 的名字」和「需要在后台配置的成就 API Name 占位」。

提示词 2：设计 24 个成就并输出可批量导入的 CSV

适用场景：成就配置前的方案设计。Steamworks 后台支持 CSV 批量导入导出，先用 AI 出稿再微调最省事。

你是一位做过 3 款 Steam 独立游戏的设计师。我的游戏是：{一句话类型，如「2D 像素 roguelike 地牢探险，单局 20 分钟」}。核心循环是 {一句话}。

请为它设计 24 个成就，输出为 Markdown 表格，列为：
API Name | 显示名（中文，≤12 字）| 描述（≤60 字，不剧透）| 类型（进度/探索/挑战/彩蛋）| 触发点（具体到什么事件、什么阈值）| 预估完成率（%）| 是否隐藏（是/否）

【硬性约束】
- 类型配额：进度 8 个、探索 7 个、挑战 6 个、彩蛋 3 个，总数必须正好 24。
- API Name 全大写、下划线分隔、以 ACH_ 开头，且能看出含义（如 ACH_CLEAR_FLOOR_5）。
- 进度型预估完成率 >60%，挑战型 1-5%，探索型 10-40%，彩蛋型 <8%。
- 6 个隐藏成就（is_hidden=是），从挑战型和彩蛋型里选。
- 每个成就的触发点必须是**程序能唯一判定的事件**，禁止写「玩得开心」这类无法实现的描述。
- 成就描述里不得出现具体数值谜底（如「击杀 100 只」应写成「击杀大量敌人」）。

表格之后，再单独输出一段纯 CSV（无表格线、UTF-8、逗号分隔，字段用英文双引号包裹），表头为：
"API Name","Name","Description","Hidden","Icon"
Icon 列统一填 "placeholder" 占位。这段 CSV 我要直接粘贴到 Steamworks 批量导入页。

最后用 3 条要点说明：这 24 个成就如何引导玩家尝试我可能被忽略的玩法。

提示词 3：成就失效的定向排错

适用场景：代码写完了，Steam 上就是不弹。把现象喂给 DeepSeek 做定点诊断，比乱改快得多。

你是 Steamworks 接入的排错专家。我的环境：Godot {版本} + GodotSteam {版本}，操作系统 {Windows/Linux}。

现象：{例如「游戏内达成条件后控制台打印 setAchievement 返回 true，但 Steam 客户端没有弹窗，成就页面仍是灰色」}

我的相关代码：
```gdscript
{粘贴你的 unlock 与初始化代码，20 行以内}
```

请按以下结构输出诊断，不要泛泛而谈：

1. 【最可能原因】按概率从高到低列 3 条，每条用一句话说明「为什么这个现象符合它」。
2. 【30 秒验证法】针对每条原因，给一个能在 1 分钟内做完的验证动作（例如「在后台 Achievement 页面确认该成就是 Published 而非 Draft」）。
3. 【修复代码】给出修正后的 GDScript 片段，只改必要部分，用注释标出改了哪里。
4. 【防回归】给一条可以写进代码的断言或日志，让这个 bug 不再复发。

约束：不要建议我重装 SDK 或重装 Steam 客户端这类破坏性操作；不确定的地方明确说「需确认」，不要猜 API 签名。

学习心得

到第 76 天，我越来越确信一件事：Steam 的坑几乎都不在「功能怎么写」，而在「什么时候调」。成就系统 10 行代码就能接完，但 setAchievement 与 storeStats 之间的那一步，把「内存里的 true」变成「服务器上的 true 加一个弹窗」，正是新手最容易漏的一步。

这对「用 DeepSeek 做一款 Steam 游戏」的意义很直接：DeepSeek 非常擅长写 API 调用本身，但时序与状态生命周期必须由我给足上下文（SDK 版本、初始化时机、离线场景），否则它会给你一段看起来完美、实际永不弹窗的代码。所以提示词 1 里我把「离线补推」「节流」「退出兜底」写成了硬约束——这些不是锦上添花，是能不能上架的区别。

另外，成就设计这件事特别适合交给 AI 出初稿：24 个成就的结构化配额、完成率预估、API Name 命名规范，都是可以被规则约束的。我只需要做最后一步判断——哪个成就真的会让玩家想去试试另一种玩法。

明日关注

  • 在 Steamworks 后台跑一遍 CSV 批量导入，确认 API Name 大小写与代码完全一致，并点 Publish
  • 用 clearAchievement + storeStats 写一个仅调试版可用的「重置全部成就」按钮，验证重弹窗流程
  • 统计自己游戏里所有「可判定事件」，逐一映射到成就触发点，补齐缺失的埋点

本文由自动化学习流水线每日生成，坚持即学即记。