games-development-ai/.agents/skills/puzzle-game-design.md

name, description

name	description
puzzle-game-design	当为解谜/找茬/消除/记忆类 brief 产设计阶段玩法方案或评审时使用:顿悟引擎、可达谜题范式、关卡阶梯与计分锚、「解须在取证面上」「盘面必可解」等品类特有红线、通用+品类自检、金标锚点。

skill: puzzle-game-design —— 解谜小游戏「玩法设计」作业手册(给生成 agent 的设计阶段)

定位:这是 生成 agent 设计阶段造"好玩的解谜玩法设计"的唯一作业手册。它回答 "设计什么才好玩"(谜题机制/关卡进度/数值/美术/音/UI 范式),与 littlejs-game-dev.md(回答"代码怎么写")配对:设计阶段产玩法概念 → 代码生成阶段照 littlejs-game-dev 产代码。经营/养成类的对应手册是 sim-business-game-design.md;两份体例相同、品类不同。

铁律(创始人 2026-06-21):"好玩 = 上游设计层职责",不在 runtime/插件。插件只让设计能被 juice 出手感;这份 skill 负责让设计本身好玩。

可达性边界:产出必须落得到 A-model 轻量运行时——LittleJS 2D 手机竖屏(390×844)、单/少场景、便宜模型可生成的多文件代码、11 注入插件能力域。解谜品类还有一条品类特有的可达红线:谜题的"解"必须在屏上肉眼可辨(§9,设计再妙、玩家看不出哪里可点就是卡死)。

上位标准:分层质量与验收口径 = docs/architecture/架构/生成引擎/游戏质量与爆火能力.md(L1 机制可玩/L2 内容丰富/L3 留存结构/L4 传播钩子;品类 rubric 计分制见其 §4)。本品类 rubric 机器版(喂 LLM 验证 agent)= cheap-worker/fixtures/genre-rubrics/puzzle.json,与本文 §10 品类条目同源——改任一处必须同改另一处并做金标复验。

证据基:范式蒸馏自近年微信/抖音「找茬/脑洞益智/消除/记忆翻牌」品类的成熟模式(训练知识,非实时榜单);范式稳定可用,具体举例供参照。

---

0. 为什么这一品类爆(底层动机 —— 设计要击中这些)

解谜小游戏的"爽"来自 6 个心理引擎,好玩 = 同时点燃尽量多个;无趣 = 一个都没点燃:

1. 顿悟时刻(啊哈!):看一眼没头绪 → 观察两秒 → "我懂了!"——线索与解之间必须有一段想一下的距离,这是解谜区别于反应点击的命脉。
2. 胜任感(我变聪明了):解开=智力被确认;连续解开=滚雪球的自信。反面:靠乱点也能过 = 顿悟感全无。
3. 清屏快感:把盘面上的目标一个个点掉、清空、整理归位的强迫症满足(消除/配对/归类共用这条)。
4. 递进挑战与"差一点":关卡一关比一关难一点点;卡住时"就差一个没找到"的张力,引向提示/重试,别卡死。
5. 炫耀智商:成绩(用时/步数/星级/关数)天然可比较、可截图——解谜是传播钩子最顺手的品类。
6. 低门槛零阅读:规则靠第一关"点一下就懂"示范,不靠文字说明书;3 秒上手,谜题深度靠后续关卡展开。

反"无趣"总纲:解谜无趣几乎总是因为——谜面一眼看穿(无顿悟)/ 关卡重复同一规则(无递进)/ 乱点也能过(无胜任感)/ 卡死无提示(挫败流失)/ 无音效无庆祝(解开了没反馈)。§10 是落地清单。

---

1. 核心玩法范式(可达子集 —— design 优先从这里选)

范式	一句话	我们运行时怎么落(插件)
规则匹配谜盘(主流首选)	每关给一条线索(如"找出所有【红宝石】"),盘面若干格,点中所有符合的即过关;规则随关卡换维度(颜色→形状→数量→组合)	core 纯逻辑产盘面+判定 + hud-ui 线索横幅/格子 + session-score 计分 + particles-juice 点中爆点
找不同 / 找目标	一堆干扰项里藏 N 个目标(不同色/缺一角/多一笔),全找到过关	core 产干扰+目标 + render 细微差异绘制 + juice 找到闪光
顺序推理	按推理出的次序点(从小到大/按亮灯顺序/按字序),点错断连击	core 产序列+当前该点项 + hud-ui 高亮 + timer-scheduler 节奏
记忆翻牌配对	短暂展示后盖住,凭记忆点出成对目标	core 记牌面 + timer-scheduler 展示倒计时;两步操作须守 §9 的下一步指引纪律
归类整理	把混在一起的东西按规则归拢(点出所有"属于厨房的")	同规则匹配谜盘,规则换成类别归属
消除变体(点选式)	点走相邻同色/凑三消除,清空过关	core 盘面+消除判定;只用点选、不做拖拽滑动(§9)
星级 / 收集图鉴	每关按用时/步数评 1–3 星,攒星解锁新章节/新主题	session-score(best 接 save)+ save-progress 存星 + hud-ui 图鉴格
数值成长曲线	每关基分 + 连击倍率 + 剩时奖励,制造"这把更高分"的重开欲	balance 数值表 + session-score

组合配方(经验):一款轻量解谜 = 1 个谜题主范式 + 关卡阶梯(规则随关递进)+ 连击/星级一个成长点缀 + 收集/称号一个第二动机。别堆超过 2 个主机制(便宜模型 + 单屏扛不住,也稀释顿悟感)。

---

2. 关卡 / 进度 / 留存设计(解谜的进度结构 = 关卡阶梯本身)

解谜品类里,「解锁阶梯」的品类形态 = 关卡链:每过一关解锁下一关,且新关引入新规则/新维度/更大盘面——这就是质量模型底线四件里"解锁阶梯 ≥3 级"的解谜映射(纯换汤不换药的重复关不算阶梯)。

• 首 3 分钟(决定生死):① 0–10 秒:第一关零阅读、一眼能解(示范规则,点一下就有反馈);② 10–60 秒:连过 2–3 关,第一次出现"要想一下"的关 + 第一次连击/星级奖励(给到"我变聪明了"的爽);③ 1–3 分钟:露出后续内容预告(下一章图鉴 / "第 8 关解锁新玩法"的锁),建立"还有很多"预期。
• 难度曲线:难度 = 盘面大小 × 规则维度 × 干扰强度,三个旋钮一次只拧一个。节奏 = 2–3 关舒适 → 1 关"要想一下" → 过关大庆祝 → 回舒适;顿悟关是爽点、不是墙。
• 卡点设计:玩家 ≥8–12 秒无正确操作 = 卡壳信号 → 给软提示(候选高亮/线索重播/排除一个干扰项),卡壳不出局;提示是"诱惑"(将来可接看广告解锁),不是"惩罚"。
• 留存钩子:每日谜题(当日专属一关)· 章节图鉴(攒星点亮)· 连胜纪录 · 称号阶梯("见习侦探→推理大师")。便宜档至少给一种。
• 长线:章节主题轮换(水果→宝石→古文字)· 图鉴凑齐 · 无尽模式冲纪录。

---

3. 数值与节奏(给具体区间锚 —— 别让 code agent 拍脑袋)

• 盘面与解数:起步 3×3 格、每关 3–5 个正确目标;上限 4×4(竖屏手指友好,格子 ≥72px);目标太少无清屏感、太多变体力活。
• 观察窗口:出题后留 0.8–1.5s 让玩家扫一眼盘面再判定(别一出题就算超时);记忆类展示 1.5–2.5s 再盖住。
• 一关时长:8–20s/关为舒适区;整局限时 60–90s 或 8–12 关到终局,两种收口都可。
• 计分骨架:每个正确目标基分(如 +10)+ 连击倍率(2s 内连续正确 ×1.5/×2,断连归 1)+ 过关奖励(+30 起、随关数上浮 ×1.15/关)+ 剩时奖励。让"聪明又快"肉眼变成大分差。
• 错点惩罚(轻):点错 = 抖屏 + 断连击 + 短锁定 0.3–0.5s;绝不倒扣到看不见涨分(分数总体must上升,挫败=流失)。
• 双货币(变现预留):星星(过关挣,解锁章节)+ 提示券(稀缺,卡壳消耗,经看广告或攒)。看广告点位:卡壳要提示 · 失败续 10 秒 · 结算翻倍。包装成"福利",不打断顿悟爽点。

标准 Match-3 的动作可读性

相邻交换三消的核心反馈不是“分数涨了、盘面变了”，而是玩家能连续看懂本手因果：交换 → 匹配停留 → 消失 → 下落/补位 → 连锁间隔 → 稳定。无效交换必须前移后回退。缺任一主体阶段、直接跳终盘、只用粒子或闪屏代替棋子运动，都属于玩法体验不完整，不得在设计稿中写成“已有消除反馈”。

• 交换约 180–240ms；匹配停留约 80–140ms；消失约 160–220ms；下落/补位约 180–360ms；连锁间隔约 80–120ms。
• 第二击接受后锁棋盘输入，稳定后恢复；锁定期额外点击不能改盘面、分数、步数或再次启动结算。
• 每一轮连锁独立播放消失与下落，不能只画第一轮匹配或最后一轮终盘。
• 终局结果可以同步确定，但结算页必须等最后一轮稳定后出现，不能抢走最后一次消除。
• 标准局部消除效果由固定 host 自动合成：亮色核心、扩散环与八向碎片使用 L1 注入的主题 palette，Writer 不自制匹配消失粒子，也不调用 match3VisualTimeline.renderEffects()。
• 设计输出必须明确主题棋子如何做位移、缩放/透明消失、顶部补位入场、无效回滚、连锁强化和终局转场；音效和震动只作辅助，不能重复覆盖 host 已提供的标准消除效果。

---

4. 美术风格范式(可达 + mmx 可产 + 程序化兜底)

风格	调性	配色	适合
明快益智扁平(主流首选)	干净聪明	高对比糖果色 + 深底	绝大多数谜盘/找茬
夜空霓虹	专注冷静	深蓝底 + 霓虹高亮	逻辑/序列/记忆
纸面手绘	轻松幽默	米纸底 + 铅笔线	脑洞/找不同
国风雅致	沉静	宣纸 + 黛青/朱砂	古文字/七巧板主题

• 谜面可读性 > 一切装饰:格子间距 ≥12px、目标属性(颜色/形状/数量)一眼可辨——看不清的谜面 = 假难度,是解谜品类头号美术错误。
• 高亮语言要统一:可点/选中/正确/错误四态各一种视觉语言(描边/发光/抖动/变灰),全程一致。
• 美术一致性之根:全程共用一组"风格词",mmx 每次生成都带它;程序化兜底——纯几何图形(圆/方/星/菱)+ 统一色板就能做出体面的谜盘,别因美术阻塞可玩性。

---

5. UI 范式(hud-ui 全可达)

• 线索横幅:盘面上方一条醒目横幅写本关线索("找出所有【红色宝石】");换关时横幅刷新 + 轻动画;
• 顶部 HUD:关卡数(第 3/8 关)/ 分数 / 剩余时间条(drawBar);
• 连击提示:连续正确时"连击 ×2!"飘字放大;
• 过关庆祝:整盘清空瞬间全屏小庆祝(闪白 + 粒子 + 音效 + "第 N 关完成!");
• 卡壳软提示:候选格轻微脉动/发光(hud-ui 变色重绘即可);
• 结算面板:大分数 + 通过关数 + 最佳纪录 + 星级/称号 + 再来一局按钮——结算就是炫耀时刻,别打完黑屏。

---

6. 音乐 / 音效范式

• 普通 puzzle：BGM 轻快专注循环；正确、错误、过关等即时反馈可经 audioMusic 提供，无声卡时静默降级不崩。
• 标准 Match-3：主题 BGM、交换、无效回滚、每轮 clear 复合音、fall 落定音和 terminal 音全部由 host-protected match3AudioDirector 自动跟随视觉时间线播放。设计只需给出主题听感，不向 Writer 下发音频实现清单；Writer 不得使用 audioMusic/playSfx、自建 Web Audio 或另造连锁 cue。
• 红线:宁可程序化音效,也别没有反馈音(解开无声 = 顿悟感直接减半)。

---

7. 首屏 / 留存视觉钩子(通用,MVP 也用)

• 首屏 3 秒抓人:直接给第一题(菜单一点就进第一关,别先放教程墙);
• "关卡地图/章节图鉴"的进度预告(点亮了 3 格、后面还有一长串);
• 成绩对比预期(最佳纪录摆在结算正中,"下把能更高");
• 称号/星级当门面(情感锚 + 炫耀点)。

---

8. 设计阶段输出配方(生成 agent 据 brief 产出这些 → 喂代码生成)

给定一句话 brief,设计阶段应产出一份结构化玩法设计,逐项落到运行时:

1. 谜题主范式(从 §1 选一个;一句话:玩家看什么线索 → 怎么想 → 点什么);
2. 关卡阶梯(3–6 关起步:每关的盘面大小 / 规则维度 / 新引入什么——逐关写清,这是解谜的解锁阶梯);
3. 数值骨架(基分 / 连击倍率 / 过关奖励 / 错点惩罚 / 观察窗口与一关时长 —— 按 §3 区间给具体值,交 core/balance);
4. 卡壳兜底(几秒算卡壳 / 提示形式);
5. 美术风格词(一组,全资产共用)+ 谜面元素清单(格子/目标/干扰项,标 mmx 或程序化);
6. 音效清单(正确/错误/连击/过关/星级)+ BGM 情绪；标准 Match-3 只写主题听感与动作反馈目标，标明由 host director 自动提供，不给 Writer 音频实现任务;
7. UI 布局(线索横幅 / HUD / 连击飘字 / 结算面板,§5);
8. 插件选择清单(普通 puzzle 常用:sceneFsm + sessionScore + hudUi + timerScheduler + audioMusic + juice,记忆类加 save 存最佳；标准 Match-3 不选 audioMusic);
9. 首 3 分钟脚本(逐关:示范关→舒适关→首个顿悟关→内容预告);
10. 可点性可见声明(§9:当前该点的目标靠什么视觉特征与干扰项区分、多步范式下一步怎么指引——设计阶段就写清,别等实现时才想)。
11. 动作转场声明(标准 Match-3 必填:交换/消失/下落补位/连锁/稳定/无效回滚各自的可见反馈、时长与输入锁;其它多步谜题说明状态切换如何让玩家看懂因果)。

MVP-first 铁律(关乎 code agent 能否收敛):首版只做可玩核心——1 个谜题主范式 + 3–5 关阶梯 + 基分/连击 + 基础音效,谜面元素 ≤3 种属性维度。每日谜题 / 图鉴 / 称号系统 / 无尽模式 / 提示券商店 一律标「后续·MVP 不做」,别一稿堆满 —— 设计太满 → code agent 实现负担过重 → read-thrash 不收敛。先出能玩的核心,再谈丰富。

这份设计 = 代码生成阶段的"图纸";生成 agent 照 littlejs-game-dev 把它实现为多文件代码。设计阶段把"好玩"想清楚,代码阶段只管正确实现。

---

9. 可达性红线(落不到运行时的设计 = 废稿,必剔除/简化)

• ❌ 拖拽 / 滑动 / 连线 / 画线为核心操作(华容道滑块、连连看划线、一笔画)→ 竖屏小格上拖拽误操作率高、单击是手机 casual 最稳的输入形态 → 改成点选等价形态(点两格交换、点格子步进、点序列下一项)。
• ❌ 大段文字谜面 / 灯谜 / 阅读理解 → 竖屏小字读不动、机器也验不了;线索用视觉属性(颜色/形状/数量/位置)表达,横幅一行字封顶。
• ❌ 多屏关卡地图 / 大世界章节 → 单/少场景(menu→play→over),章节感用主题轮换与图鉴表达。
• ❌ 复杂谜题编辑器 / 用户出题 → 超出便宜档;盘面一律 core 纯逻辑程序化生成(受控随机,可复现)。
• ❌ 超过 2 个主机制(谜盘+消除+记忆混一款)→ 聚焦 1 主范式 + 1 成长点缀。
• ❌ 「解」肉眼不可辨——这是解谜品类的头号翻车点:当前该点的正确目标必须有可见的视觉区分(线索横幅指明规则 + 目标属性肉眼可判——颜色/形状/数量差异要够大),解谜逻辑再对、屏上看不出哪里该点 = 玩家与测试员一样卡死。多步范式(翻牌配对:先翻 A 再翻 B)必须随状态给"下一步该点的"视觉指引(翻开 A 后,提示区亮出 A 的花色);做不到就改单步范式。
• ❌ 重写盘面生成器而丢「可解性质」——解谜品类第二号翻车点(批产实测:自写符文生成器产出 0 解盘面 → 第一关就无解 → 谁玩都卡死):脚手架的 generateBoard 保证每关恰好 N 个解、至少 1 个解、干扰项绝不撞规则;换主题/换规则维度优先只改 THEME/LEVELS 表、别动生成器;确要自写规则系统,必须保住同一性质(生成后自检一遍「符合规则的格数 == 预期解数、≥1」,0 解=不可解关=废稿)。
• ❌ 在场景 render 回调里引用未定义变量——render 回调抛错会被 scene-fsm 隔离成告警不崩,画面异常但局不死(批产实测:renderMenu 里一个未定义的 cy 曾让整局 E/G/H 三门连锁挂——当时按钮命中区还靠 render 返回值回写 menuStartBtn = renderMenu(...),render 一抛错命中区永远拿不到、卡死菜单)。2026-07-03 起模板已改约定:命中矩形在场景 onEnter 用纯几何函数确定性建立,render 只画不赋值(cheap-system v1.6.1 硬约束),旧连锁已断;但 render 抛错仍会黑屏丢反馈,改完 render 先顺一遍所有变量来源。
• ❌ 点错即死 / 三错清零重开 → 错点轻惩罚(§3),乱点不该赢、但点错不该死。
• ✅ 留下的:规则匹配谜盘、找目标、顺序推理、点选消除、记忆配对(守下一步指引纪律)、星级收集、关卡阶梯、连击计分 —— 全在 11 注入插件 + 单屏 + 便宜模型可生成范围内。

---

10. 反"无趣"落地清单(design 自检,逐条必过)

通用 8 条(全品类同一张表,与 sim-business §10 同源;解谜视角的落点写在括号里):

1. 即时反馈:每次正确点击有没有"飘字 + 音效 + 粒子"三件套?(无 → 必加；标准 Match-3 的消除粒子由 host 自动合成，Writer 不重复制作)
2. 可见成长:分数/关数有没有肉眼可见地涨?(连击倍率让它涨得有戏剧性)
3. 下一个解锁:任意时刻有没有"下一关引入什么/差几颗星解锁下一章"的钩子?
4. 30 秒爽点:开局 30 秒内有没有连过两关 + 第一次连击奖励?
5. 数值滚雪球:连击×剩时奖励有没有让"聪明又快"变成大分差(而非匀速加分)?
6. 情感锚:有没有一个可积攒的拥有物(星星/图鉴/称号)让玩家"想凑齐"?
7. 放置回归:回来有没有惊喜(每日谜题/连胜保留)?(便宜档至少一种,标「后续」也要在设计里留位)
8. 音反馈:正确/错误/过关有没有声音?(哪怕程序化)

解谜品类扩展 5 条(机器版同源 = cheap-worker/fixtures/genre-rubrics/puzzle.json,LLM 验证 agent 按它评分;改条目两处必须同改 + 金标复验):

#	层	条目	一句判据	正例	反例
P1	L2	谜题规则递进	关卡引入 ≥2 种谜题规则/维度,后关比前关多一层复杂度,不是同一规则换数字重复	1–2 关按颜色找、3–4 关按形状找、5 关颜色+形状组合	8 关全是"找红色",只是格子变多
P2	L2	顿悟距离	谜面需观察/比对/推理才能定位解,线索与答案之间有"想一下"的距离,不是看见就点的纯反应	线索"数量为 3 的宝石",盘面要数一数才敢点	目标自己发光闪烁,无脑点亮的
P3	L3	关卡阶梯可见	玩家任意时刻能看到关卡进度(第 N/共 M 关或下一关预告),过关有明确庆祝节点	HUD 常驻"第 3/8 关"+ 过关全屏庆祝	只有分数在涨,玩家不知道自己走到哪
P4	L2	卡壳兜底	卡住 ≥8–12s 有软提示(高亮/排除/线索重播),卡壳不出局不清零	10s 无正确操作,候选格开始脉动提示	卡住只能干等到超时判负
P5	L4	成绩可炫耀	结算展示可比较成绩(用时/连击/星级/称号,配最佳纪录),不是打完就黑屏	结算面板:分数+最高连击+3 星+历史最佳+称号	结算只有一行"游戏结束"

通用 8 条命中越多越好玩;品类 5 条对齐质量模型的档位观测线(便宜档批次:L2 组均分 ≥60%、L3 ≥2/3、L4 ≥1/2,消费于品类小批验收、不拦单款)。设计阶段就过这两张表,别等做出来才发现无趣。

底线四件的解谜映射(质量模型 §4 结构底线,设计必须给全):成长轴 = 分数+关卡数;解锁阶梯 = 关卡链逐关引入新规则(≥3 关,任意时刻可见下一关);第二动机 = 星级/图鉴/称号可积攒;音反馈 = 正确/过关必有声。四件全可映射,无需替代轴申报。

---

金标锚点(12 条口径基线 · 质量模型 SoT §4 规范三)

每品类需 ≥1 金标正例 + ≥1 薄反例锚住评分尺(rubric 文本或评分 prompt 变更须金标复验,单款分组小计漂移 >±1 即回退)。解谜的锚 2026-07-03 以 12 条口径实测(生产口径 genre=puzzle,同输入复采样 n=3 取中位,入口 cheap_verify.verify_richness):

• 金标正例 = game-runtime/games/_fewshot-puzzle(「深海寻宝谜航」,骨架上做出规则递进 + 连击 + 星级 + 结算炫耀的完整款)。通用 12 条 = 11/12:L2 7/7 · L3 2/3 · L4 2/2;第 12 条「核心操作非无脑」3/3 命中(读线索按颜色/形状/数量/组合四维筛对,点错扣星 + 抖屏 + 锁定 400ms,含真实判错代价);品类扩展 5/5;三样 11/11/11、最稳。
• 脚手架参照 = game-runtime/games/_template-puzzle(规则谜盘轻脚手架,克隆起点)。通用 12 条 = 10/12:L2 6/7 · L3 2/3 · L4 2/2;第 12 条 3/3 命中;品类扩展 5/5。它品类面已满 5/5、仅通用维度比 few-shot 正例薄一档——是能过门的黄金脚手架、不构成品类薄反。
• 薄反例 = 合成薄壳(单规则纯反应 / 目标自发光 / 无进度 / 无提示 / 结算一行字,照各条 negative 面同构):材料尚未入仓,是本品类金标欠账(与 cheap-worker/fixtures/genre-rubrics/puzzle.json 的 _note 记的同一笔;红线是不臆造合成材料充数)。其历史锚(未真跑)= 通用 0/11 · 品类 0/5。
• 方差纪律:M3 单发方差 ±2~4,取中位;品类段(两款均 5/5)与 L4(均 2/2)跨样最稳,是回退判定最可靠的观测维。

---

相关

• 代码层实现 → littlejs-game-dev.md(11 注入插件 API / 结构 / 资产-mmx / 工厂契约)
• 品类轻脚手架(克隆起点)→ game-runtime/games/_template-puzzle/(规则匹配谜盘骨架:盘面生成/线索/判定/关卡流转已接好)
• 过门正例(few-shot,读它看"丰富成什么样")→ game-runtime/games/_fewshot-puzzle/src/(在骨架上做出规则递进+连击+星级+结算炫耀的完整款)
• 品类 rubric 机器版(喂 LLM 验证 agent)→ cheap-worker/fixtures/genre-rubrics/puzzle.json
• 便宜模型生成 worker / 九门 → cheap-model-game-generation.md
• 质量分层与档位观测线(上位标准)→ docs/architecture/架构/生成引擎/游戏质量与爆火能力.md