上线前的性能与体验

写在最前

第 11 课你给"弹珠机肉鸽"加了一堆反馈——画面会颤、命中会停、数字会飘——爽是爽了，但你打开调试面板瞄一眼帧率，发现它从原来的 60 掉到了 40 多，遇到 Boss 阶段甚至跌到 30。

这一节就是来解决这个问题。

🚨 先说清楚：这一节不是必修课。
- 如果你只是在自己电脑上玩、给朋友玩——你电脑性能够，掉个十几帧无所谓，这节课可以跳过；
- 如果你想导出到 Steam Deck / 手机 / 微信小游戏 / 小程序 / 浏览器这类设备性能受限的平台，必修——一台中端手机带不动 30 帧，玩家打开第一秒就关掉了；
- 明确性能优化服务目标平台，不要单纯优化技术实现。你开始做之前，需要先确定 PC、手机或小程序等目标环境。

弹珠肉鸽是天然的"性能压力测试场"——一屏几十颗弹珠 + 上百颗钉子 + 命中粒子爆开 + 飘字 + 屏幕震动，每一帧都在撞、都在算、都在画。这一节要做四件事：

用 AI 录一段性能报告并读懂它（不需要懂术语，让 AI 翻译）；
找出真正的瓶颈；
一次只优化一个瓶颈，每次改完都重新录一遍报告对比；
知道哪些"显而易见的优化"其实是反向优化，做了反而更慢。

〇、动手前先翻一次 Bible

老规矩，写代码前先翻 Bible。这次涉及的模块比较少，因为性能优化是横切关注点——它不改玩法，只改"实现方式"。

你要改什么	读哪个文件	对应到本次任务
改实体的实现方式（钉子用静态 / 弹珠走对象池）	`02_entities.md`	✅ 涉及（标注实体的"性能侧实现"）
调数值（帧率上限、可见弹珠上限等）	`03_rules.md`	✅ 涉及（新增"性能预算"段落）
加新模块 / 调目录	`07_file_layout.md`	✅ 可能涉及（新增对象池脚本）
改 UI / HUD	`05_ui_hud.md`	❌ 一般不涉及

写代码前，先把"性能预算"这一段写进 bible/03_rules.md：

bible/03_rules.md · 性能预算

## 性能预算（MVP 目标平台）

### 帧率目标
- PC（中端笔记本）：稳定 60 帧，不低于 55 帧。
- 手机 / Steam Deck：稳定 30 帧，不低于 28 帧。
- 微信小游戏 / 浏览器：稳定 30 帧，不低于 25 帧。

### 屏内活跃元素上限（同时存在）
- 弹珠：最多 12 颗
- 钉子：最多 200 颗
- 命中粒子：每次命中最多 8 个（同屏总数不超过 60）
- 飘字：同屏不超过 20 条

### 触发降级的阈值
- 帧率连续 1 秒低于"不低于"线 → 自动降级（关粒子、降震屏幅度、合并飘字）

一、第 1 轮对话：让 AI 教你怎么"录一段性能报告"

打开 CodeBuddy 新建会话。第一件事不是改代码，是录一段报告。

每个引擎都有自带的"性能录制工具"——按一个键开始录，玩一会，再按一下停止，会生成一份报告，告诉你这段时间里"画面 / 物理 / 内存 / 脚本"各自占了多少时间。不需要你看懂报告本身——你的工作只是录下来，然后把报告丢给 AI 翻译。

提示词模板（直接抄）：

Prompt · 教我录性能报告

背景：我用 ____（Godot 4 / Unity 2D / 其它）做了一款弹珠肉鸽，目标平台是 ____（PC / 手机 / 小程序），目标帧率 ____（60 / 30）。

任务：教我怎么用这个引擎自带的工具录一段性能报告。请按以下顺序回答（不要写代码）：
这个引擎的性能录制工具叫什么？怎么打开？
我应该录什么场景？录多长时间？
录之前要不要做什么准备（比如关掉编辑器自身的开销、用发布版而不是开发版）？
录完之后我应该把哪几个截图/数字发给你，你才能告诉我瓶颈在哪？
普通玩家的电脑和我的电脑性能不一样——我用我的电脑录的报告，对低端机有参考价值吗？如果没有，我应该怎么补？

⚠️ 新手最常踩的坑：在编辑器里直接看帧率，发现掉帧就开始改代码。编辑器本身就吃性能——你看到的 40 帧可能在发布版本里是 60。性能优化必须基于发布版（导出后）的数据，不是开发版的体感。在自己 i7/M2 笔记本上跑 60 帧就觉得没问题，目标平台是手机？那必须在手机上录。

录制报告要求（AI 回复节选）：

AI 会告诉你录完后截以下三个东西发回去：

A. 监视器面板（Monitors）的数字：在中负载（5-8 颗弹珠在场）和峰值负载（12 颗弹珠 + 大量碰撞）各截一张。关键字段：

字段	含义	关注点
`performance/process_time`	脚本 `_process` 耗时(ms)	> 8ms 说明脚本逻辑重
`performance/physics_time`	物理 `_physics_process` 耗时(ms)	> 8ms 说明物理负载过高
`rendering/draw_calls`	绘制调用数	> 500 有优化空间
`rendering/objects_drawn`	绘制的对象数	结合上面的看
`rendering/particles_drawn`	粒子数目	结合你的预算（≤60）比对
`physics/collision_pairs`	碰撞对数	弹珠×钉子的物理碰撞量

B. 可视化剖析器（Visual Profiler）的峰值帧截图：找一帧耗时最长的，把它按分类展开的瀑布图截给我。典型关注：Physics 占比过高 → 碰撞计算量大 / 碰撞体形状复杂；Script 占比过高 → 某段 GDScript 逻辑在 _process 或碰撞回调里干了重活；Rendering 占比过高 → 粒子/材质/灯光/后处理太重。
C. 你的机器概况：报一下 CPU 型号、GPU 型号、内存，我好判断这些数字在你的机器 vs 目标低端机的差距。

按 AI 给的步骤录完一段报告之后，截图丢回去，进入下一轮。

二、第 2 轮对话：让 AI 翻译报告，找出"真正的瓶颈"，一次只优化一个瓶颈

把性能报告的关键截图丢给 AI，让它解读：

Prompt · 让 AI 翻译报告找瓶颈

这是我刚刚录的性能报告（截图见附件）。场景说明：第 3 局，屏幕里有 8 颗弹珠 + 180 颗钉子 + 粒子爆发 + 屏幕震动。我感觉到的现象：帧率从 60 掉到 35，玩家操作明显延迟。

请你：
1. 用大白话解释这张图里每一栏代表什么。不要直接给我建议，先确保我能看懂。
2. 告诉我画面/物理/脚本/内存四类里，哪一类是"真瓶颈"——也就是说，把这一类的开销砍掉一半，帧率能明显回来；而把别的类砍掉一半，帧率几乎不动。
3. 在"真瓶颈"那一类里，最大的几个开销项分别是什么？
4. 列一个"先做哪个、后做哪个"的顺序——按"性价比"排序：性价比 = 预期收益 ÷ 工作量。先做高性价比的，做一个看一次效果。
5. 哪些"看起来很慢但其实很便宜"的项不要去碰？解释一下为什么改了反而可能更慢或者得不偿失。

不要写代码，只做诊断。

注意：让 AI 读取图片需要选择支持图片输入（也就是有视觉）的模型，不然 AI 就是在编造内容而你不知情。

⚠️ 新手最常踩的坑：拿到报告就开始"全面优化"——五处一起改。优化是有取舍的——优化 A 经常会让 B 更慢。一次只改一个，每改完重新录一次报告，看真瓶颈是不是真的小了。

⚠️ 新手最常踩的坑：盯着 CPU 占用率优化。CPU 占用 80% 不一定是问题——只要帧率达标就没事。真正要看的是"每一帧花了多少毫秒"——目标 60 帧 = 16 毫秒一帧，目标 30 帧 = 33 毫秒一帧。

AI 给的诊断大概长这样（参考样本，不要抄数字）：

类别	是不是真瓶颈	备注
画面（渲染）	🔴 是	主要是粒子和屏幕震动
物理	🟡 部分是	钉子的碰撞检测开销大
脚本逻辑	❌ 不是	控制在合理范围
内存 / 垃圾回收	🟡 偶发	飘字会触发短暂卡顿

示例瓶颈诊断结果（AI 实际回答节选）：

哪一类是"真瓶颈"？ 答案是：物理（Physics）。

证据：

指标	数值	换算帧率	说明
Frame Time	3.14ms	~318 FPS	渲染和脚本其实很快
Physics Frame Time	16.66ms	~60 FPS	物理引擎刚好卡在 60 帧门槛

关键洞察：你的渲染 pipeline 能跑 300+ FPS，但物理引擎只能维持 60 FPS。当物理算不完时，游戏会等物理，所以你感觉到的延迟是"渲染在等物理"。

诊断完了再进入第 3 轮——针对最大的瓶颈，要一个具体的优化方案。

三、第 3 轮对话：一次只动一个瓶颈

针对 AI 指出的"真瓶颈"，让它给一个具体的最小改动方案。不要一次给五条。

提示词模板（以"物理碰撞对过多导致的性能瓶颈"为例）：

Prompt · 修复物理瓶颈（最小改动）

修复 scripts/peg_board.gd 的物理性能瓶颈。

问题：_spawn_typed_peg() 第 93-102 行创建了一个 AudioDetector Area2D，但从未连接任何信号，是死代码。180 颗钉子各一个，产生 180 个无用碰撞形状，导致物理碰撞对暴增到 173 对。

修复：删除 _spawn_typed_peg() 中 audio_area 相关的 10 行代码。音效已由 peg.gd 的 _play_hit_sfx() 处理，不需要独立 Area2D。

⚠️ 新手最常踩的坑：让 AI 在"复杂方案"和"简单方案"里选，它会经常推复杂方案。问它"有没有更笨但更安全的版本"，很多时候性能优化最简单的办法就是"少做一点"（少生粒子、少飘字），而不是"做得更聪明"。尽量不要让 AI 大胆做你可能看不懂的方案。

优化做完之后，必须重新录报告

Prompt · 优化后对比报告

我按你给的方案改完了。这是改完之后重新录的报告（截图见附件）。

请你：
1. 对比改之前的报告，这次优化实际省了多少？
2. 有没有"原本不是瓶颈、改完后变成瓶颈"的项？（即"按下葫芦浮起瓢"）
3. 帧率有没有达到 Bible 里写的预算？
   - 如果达到了，给我一个"这次到此为止"的判断；
   - 如果没达到，告诉我下一个最该动的瓶颈是什么。

优化前后对比数据如实说明了一件事：碰撞对从 173 降到了 58，减少了三分之二。这个数字变化是真实的——关掉无效碰撞层之后，引擎每帧需要检测的物体配对量大幅缩减。

但帧率两次都是 165，物理耗时反而从 1.63ms 涨到了 4.70ms。这不是优化失效，而是两次截图的游戏状态本来就不一样：第一次场上有 5 个活动物理对象，第二次是 4 个，但恰好赶上粒子或音效同时触发，拉高了当帧的处理时间。这种波动属于正常噪声，不代表性能变差了。

真正的结论是：这个项目在当前规模下根本没有性能问题。 录报告的意义不是"发现问题再去修"，而是先建立一条健康基线——知道正常状态长什么样，以后真的出现掉帧时才有参照。165fps、碰撞对不超过 200、脚本函数总耗时不超过 1ms，这就是你这个项目的健康基线。

四、几个常见的"反向优化"陷阱

下面这几条是新手特别容易踩的——看起来在优化，其实在帮倒忙。让 AI 在它的方案里主动避开这些。

看起来在优化的事	为什么是反向的
把所有东西都改成"对象池"	对象池只对频繁创建/销毁的东西有意义。给一秒生 1 次的 UI 面板加对象池，毫无收益还多写代码。
把所有钉子合并成一张大图	合并之后单颗钉子的独立动画（被撞时晃一下、变色）就做不了了——你优化了画面性能，但破坏了 Juice，整体感受变差。
把脚本逻辑全塞到"每隔 N 帧执行一次"	一旦节奏对不上，弹珠的反弹判定会延迟一帧——玩家说"撞钉子有时候没反应"。
关闭"垂直同步"换更高帧率	帧率数字上去了，但画面撕裂得厉害。手机上还会更耗电。
一上来就上 GPU 加速 / 多线程	90% 的中小项目根本不需要——主线程随便优化都够用。提前上 GPU/多线程会引入一堆 debug 困难的问题。

让 AI 替你把关：

Prompt · 检查反向优化陷阱

我准备做你刚才推荐的优化方案（____）。做之前请帮我检查：这个方案有没有踩到下面任何一条"反向优化"陷阱？（粘贴上面那张表）

如果有，告诉我换哪种方案能避开。

五、几个新名词的简单解释

这一节出现的几个常见词，给你一个不带技术细节的版本：

FPS（帧率）：每秒画面更新的次数。60 帧 = 每秒画 60 张图，画面顺滑；30 帧 = 每秒 30 张，能玩但稍涩；20 帧以下 = 玩家会说"卡"。60 / 30 是两条公认的"够用线"——超过它人眼的提升收益会快速递减。
Profile（性能录制）：让游戏跑一段时间，引擎自动把"这段时间里画面 / 物理 / 脚本各自花了多少时间"记下来，生成一份报告。优化的起点不是改代码，是录一份 Profile。注意每次 profile 后一次只优化一个瓶颈，改完再比较优化前后的表现。
对象池（Object Pool）：把"频繁出生又频繁死亡"的东西（飘字、粒子、子弹）做成"复用池"——每次需要时从池里拿一个用，用完丢回池里，而不是每次都新建/销毁。只对频繁出生死亡的东西有意义，不要无脑套。

只有这三个词需要你心里有数，剩下的全部让 AI 替你处理。

六、最后一步：让 AI 回写 Bible

性能优化做完了，把第 05 课的 prompts/update_bible.md 内容粘进同一个会话，让 AI 同步 Bible。这次涉及的事实变化大致是：

03_rules.md 新增"性能预算"段落（结构在第〇节，目标帧率 + 屏内活跃元素上限 + 降级阈值）；
02_entities.md 标注"性能侧实现"——比如"钉子默认走静态实现，被撞瞬间临时切换成可动"；
07_file_layout.md 登记新增的对象池脚本（具体名字以 AI 在前面环节给的方案为准）；
新建一份"性能日志"文件，每一轮 Profile 报告 + 优化前后的关键数字归档进去，下一轮回看。

⚠️ 老规矩，审 diff 这一步不能省。