scenario-roblox-performance

Roblox 性能与发布

目标：通过 scenario-roblox-expert 工具包驱动，在 macOS 上使用 Roblox Studio（2026 年 10 月版）。

这里的专家级意味着：每项结论都用有利的一方数据来衡量，在一次改动前后进行测量；每项修复都要减少工作，而不是掩盖问题。预算以低端手机为准，Studio 数据须明确标注为 Studio 数据。发布也是性能的一部分：发布时要有重启计划和回滚路径，且未经所有者许可绝不发布。

如果此处提到的同级技能未包含在你可用的技能中，请用户安装（npx skills add scenario-labs/skills --skill <name>）；若需无人值守地继续，则根据工具架构推进，并标记这一缺口。

必备背景： scenario-roblox-expert（通道、评审循环、工具包、当前 Roblox 易踩的坑）。

立场（专家级差异）

1. 以低端手机为预算基准；将 Studio 数据标注为 Studio 数据。 McNeill 的预算卡以 2 GB 手机为目标：500 次绘制调用、500,000 个三角形、1.3 GB、150,000 个实例、下行 50 KB/s（RDC 2024）。手机的 CPU 工作速度约为桌面的 1/4。Studio 内存“在 Studio 中不准确，必须进行线上测试”（McNeill）。Studio 会在同一进程中运行 playtest 服务器和客户端，因此服务器工作会影响客户端帧时间［新增，实测］。
2. 先指出原因，再修复。 使用 debug.profilebegin 为每个逐帧系统标注，并修复耗时最长的最底层标签（Roblox Learn，MicroProfiler）。Studio 的 execute_luau 可访问 Script Profiler，因此 Agent 通过代码也能得出相同结论：BasePart.CFrame [C] 和扫描标签占用了实验中最多的服务器时间（实测）。
3. 以逐帧对比来检验帧时间一致性。 59 帧各耗时 10 ms，再加一帧耗时 410 ms，仍会在“60 fps”下出现卡顿（Roblox Learn）。采用主要门槛：p95 不超过预算的 1.2 倍，最差帧不超过预算的 2 倍；健康场景在 60 fps 下的 p95 为 17.2 至 17.4 ms。对比每帧的脚本耗时：修复提高帧率后，逐帧工作会运行得更频繁［新增，实测］。
4. 移除玩家看不到的服务器工作。 “绝不要在服务器上做补间动画”（Crusherfire）。调整焊接服务器部件的大小会导致整个装配体重新复制（McNeill 和 Lynn，RDC 2025）。将闲置僵尸锚定后，一款游戏的服务器 CPU 使用率减半（同一演讲）。但如果服务器仍在移动部件，仅锚定并不足够：由服务器旋转的锚定金币在 Studio 中发送了 7.6 至 10 MB/s，而由客户端旋转后仅为 12 KB/s（实测；DataSendKbps 的单位是千字节每秒）。
5. 泄漏意味着内存下限不断上升，并且要指出其所有者。 健康的内存曲线呈锯齿状（Roblox Learn）。在相同状态下连续拍摄 3 或 4 次快照，只相信持续上升的行（Crusherfire）。服务器泄漏最重要，因为服务器的生命周期可能长于数百名玩家（Crusherfire）。Destroy 不会释放部件对其他信号的连接：每个光球都留在内存中，虽已取消父级，但仍被其 Heartbeat 闭包持有（实测）。
6. 复制会影响内存、带宽和加入耗时。 每个部件上的标签和属性都会复制给每个客户端：一款游戏的崩溃率从 3% 至 4% 上升到 45%（McNeill 和 Lynn）。每个由服务器拥有的移动装配体约消耗 1 KB/s，而每秒加入时会复制约 10,000 个实例（McNeill）。将仅服务器使用的数据存放在 Luau 表中，将大型文件夹放在 ServerStorage 中；应调整流式传输，而不是将其关闭（Roblox Learn）。
7. 发布也是性能的一部分，而且发布必须由人来完成。 处理 ServerRestartScheduled，只重启过时的服务器，并在更新后客户端崩溃率超过 2% 至 3% 时进行调查（文档）。回滚流程是恢复、发布、重启：仅恢复并不会发布任何内容（文档）。Agent 负责准备和试运行；由所有者发布。

首先明确

• 症状和侧别：客户端帧率低、服务端卡顿（心跳频率低于 60，所有人都出现橡皮筋效应）、崩溃或内存问题、加入耗时，或带宽问题。每种症状指定一位负责人。
• 目标设备：你支持的最低规格手机。默认：2 GB 手机、60 fps，预算见critique.md。
• 实时数据：如果游戏已上线，查看性能仪表板数据（崩溃率、按运行时长划分的服务端内存、按设备划分的帧率）。
• 复现：能在游玩测试中展示问题的地点或脚本场景，并配备用于加载测试的调试生成器（N 名玩家、N 个 NPC、N 个物品）。
• 发布状态：尚未发布、已有玩家的线上版本，或正在更新中；注明谁可以发布和重启（必须是人）。
• 未收到答复时的默认做法：测量服务端和客户端，每次游玩测试只改一项，不发布。

流程

1. 在负载下复现。 目标：在游玩测试中复现较慢的场景，并记录两端的数据。方法：使用由 Workspace 属性驱动的调试生成器（N 名玩家、N 个 NPC、N 个物品；McNeill 和 Lynn），然后在服务端和客户端的相同服务器 time() 时刻运行 rbx_perf.measure(pt, 6)（P2）。验收条件：已保存两端的基线；已指出未通过帧率门槛的一端。
2. 静态审计。 目标：在游玩测试前找出高开销模式和计数。方法：在 Lune 中运行 rbx_perf.audit_place(path)；在 Edit 中运行 PerfAudit.all(game)（P1）。验收条件：每条警告均已修复或用一句话说明理由；计数已填入 Numbers 表格。
3. 指出原因。 目标：确定产生开销的函数、标签或资源。方法：在游玩测试中运行 rbx_perf.script_profile(s, side)；在 Edit 中使用 MicroProf.capture 查看标签；使用 SceneScan.all() 查看三角形数量、实例数量和脚本内存（P3、P6）。验收条件：指出耗时最高的函数或标签，并注明每帧耗时（毫秒）。
4. 每次游玩测试只修一项。 目标：确认性能有所提升，其他内容不变。方法：切换一个属性，在相同时间偏移处测量，并使用 rbx_perf.compare(before, after) 及其 5% 噪声下限。模式见 P4。验收条件：修复所针对的指标提升幅度超过噪声下限；其他指标均未变差；性能较差一端通过帧率门槛。
5. 长时间运行以检查泄漏。 目标：找出不会回落的内存及其来源。方法：在服务端运行 PerfProbe.soak、HeapProf.diff 和 SceneScan 的 UnparentedInstances，持续 20 秒或更久，并分别测试泄漏路径开启和关闭的情况（P5）。验收条件：各类内存的增长量和未设父级的实例数量保持稳定；受跟踪对象的数量有上限。
6. 检查场景、绘制调用和流式加载。 目标：确保最差视角符合手机预算。方法：在客户端查看 Stats.SceneDrawcallCount 和 SceneTriangleCount，运行批处理探测（P7），并检查项目文件中的流式加载半径（P8）。验收条件：最差视角下的绘制调用、三角形和实例数量均符合 Numbers 表格中的预算。
7. 将手机测试清单交给负责人。 目标：获取 Studio 无法提供的设备数据。方法：使用 P9 中的清单和gui-paths.md中的 GUI 路径。验收条件：获得真实手机的内存和帧率数据，或在报告中注明“仅限 Studio”。
8. 发布。 目标：发布玩家能够顺利使用的更新，并准备回退方案。方法：使用重启处理程序（P10）、scenario-roblox-data 中的存档，以及来自 scenario-roblox-tooling 的 ShipCheck；负责人发布更新并重启过时的服务端。验收条件：已在游玩测试中测试处理程序；已记录负责人的发布许可；Agent 绝不发布。

数值

项目	数值	参照
场景绘制调用	500 次或更少，包含 UI	低端手机，最差视角（McNeill）
场景三角形数	500,000 个或更少	同上
阴影绘制调用	最多为场景绘制调用的 3 倍	同上
客户端内存	低于 1.3 GB；超过 2 GB 的约 66% 后开始被逐出	2 GB 手机，设备端（McNeill）
实例数	低于 150,000 个；加入时约每秒 10,000 个	加入时（McNeill）
下行复制流量	低于 50 KB/s	每个客户端（McNeill；Crusherfire）
服务端拥有的移动程序集	每个约 1 KB/s	McNeill
手机 CPU	约为桌面的 4 倍	桌面端 10 ms 约等于 40 ms
帧率门槛	p95 不超过预算的 1.2 倍（20 ms），最差不超过 2 倍（33.3 ms）；健康场景的 p95 为 17.2 至 17.4 ms	60 fps（主要门槛）
服务端内存	6.25 GiB 加上每位玩家 100 MiB；保持在一半以下	文档
客户端崩溃率	高于 2% 至 3% 时进行调查	文档
BulkMoveTo	0.255 ms，而逐部件写入耗时 0.49 ms	Crusherfire 的旋转装置
实验室，所有修复	服务端脚本每帧 12.0 至 0.36 ms；服务端发送 6,526 至 11 KB/s；HUD 实例 6,002 至 302	Studio 0.743，桌面端，单进程

质量门槛

可测量：

• 在影响较大的一侧检查帧率门槛，数据来自 PerfProbe.window(...).gate 或主要指标 Stats.frames。
• 对每项修复涉及的指标，检查超过噪声底限的 rbx_perf.compare 行，每个变体各有一个结果文件。
• PerfAudit 有 0 条警告，或对每条警告给出合理说明。
• 压力测试：内存类别增长和未设父级的实例数量保持稳定；受跟踪对象数量有上限。
• SceneScan 和客户端 Stats：绘制调用、三角形数和实例数均在“数值”表的范围内。
• 每个逐帧系统都带有 debug.profilebegin 标签；长生命周期线程设置 debug.setmemorycategory。
• 在试玩测试中连接重启处理程序；由负责人报告 P9 手机数据，或标记为“仅限 Studio”。

视觉：通过 rbx_review 获取最差视角修复前后的试玩截图（rbx_review.contact_sheet）；若声明引用了 MicroProfiler 或 Script Profiler，则手动获取相应截图（gui-paths.md）。完整评分标准见 critique.md。

常见错误

错误	症状	修正
根据 fps 或 Studio 内存设置门槛	数值远超手机上的实际表现	以帧时间 p95 和最差值为准；使用 P9 手机列表
修复后比较每秒的毫秒数	fps 上升后，每帧工作量看起来更糟	比较每帧毫秒数
在 Studio 中根据 Stats.HeartbeatTime、客户端 DataReceiveKbps 或 FrameTime 设置门槛	波动范围达 8 到 100 ms；0 KB/s；帧时间为 323 ms	Heartbeat dt、服务端 DataSendKbps、物理计数、Script Profiler
一次游戏测试中进行两项更改	无法确定效果来自哪项更改	每次运行只更改一个属性
在不同时间截取窗口数据	泄漏会让后续运行更沉重	等待相同的服务器 time()
锚定部件，但仍在服务器上移动它们	复制流量达到 MB/s	在客户端移动装饰物
调用 Destroy，却没有释放外部连接	未设父级的部件和表条目不断增加	在 Destroying:Once 中断开连接
从 execute_luau 读取 gcinfo()	约 0.9 MB：注入代码块的堆	使用 HeapProf 内存类别
在服务器上创建补间动画或调整焊接部件的大小	复制流量激增	在客户端创建补间动画并调整大小
为每个部件添加标签或属性	内存占用和崩溃率上升	将服务器数据存储在 Luau 表中
从被遮挡的 Studio 窗口读取渲染统计数据	计数器停留在同一个值	将部件置于视野内，并先确认计数器会变化
使用 Vector2 作为网格单元的键	每次查找都失败	使用 Vector3 或数字作为键
发布以测试修复	玩家会收到未经验证的构建	由所有者发布；通过 Version History 恢复、发布并重启

交接

• 接收自 scenario-roblox-environment：EnvAudit 计数和各模型的流式传输模式 （环境负责各模型的模式；流式传输设置在此处决定）。
• 接收自 scenario-roblox-luau：Bench 和 Parallel 结果、本机候选项和泄漏斜率。
• 接收自 scenario-roblox-gameplay：NPC 基准测试数据；接收自 scenario-roblox-vfx-audio： 发射器、光束和翻页动画计数；接收自 scenario-roblox-networking：有效负载大小和发送速率。
• 交付给 scenario-roblox-luau：发生泄漏的函数或热点循环。清理代码（Leak、类模板）、 本机代码和 Actors 都在该处。
• 交付给 scenario-roblox-tooling：发布批准。ShipCheck、Saved 版本、Open Cloud 发布和 :restartServers 自动化都在该处；Agent 仅运行干跑。
• 交付给 scenario-roblox-data：重启计划，以便 BindToClose 和会话保存能满足 30 秒的 关机时限。
• 交付给 scenario-roblox-ui、scenario-roblox-assets 和 scenario-roblox-animation：未通过 门槛的 UI 绘制调用、纹理或网格预算以及绑定计时器（updateInvalidatedFastClusters）。

当前 Roblox 说明

• ScriptProfilerService 和 HeapProfilerService 属于 PluginSecurity。Studio 的 execute_luau 可在 Playtest Server 和 Client 上访问两者；游戏 Script 会收到“lacking capability Plugin” （已测量，P3）。
• SceneAnalysisService 通过六项查询提供 Scene Analysis 窗口。它在 Edit、Playtest Server 和 Client 上均有响应，游戏 Script 也可以调用它（已测量）。
• Client 上的脚本可通过 Stats.SceneDrawcallCount 和 SceneTriangleCount 读取绘制调用数和三角形数。 Studio 窗口停止绘制 3D 内容时，这些数值会冻结（已测量）。
• 新 place 默认启用流式传输。其 Workspace 设置对游戏脚本不可脚本化，也未出现在类型定义中。 只有 StreamingEnabled 能通过 execute_luau 读取和写入；半径设置会报错：“is not a valid member of Workspace” （已测量）。请在 Properties 面板或 Rojo 项目中设置这些值。
• RunService.PreRender 取代 RenderStepped。Lighting.LightingStyle 取代 Technology （Future 即 Realistic 加 PrioritizeLightingQuality）。4K 纹理自 2026-01-30 起已上线。
• 发布需要填写 Maturity and Compliance 问卷，且 place 发布 API 无法更新 SurfaceAppearance、union、 EditableImage、EditableMesh 或 BaseWrap 内容。
• require("@rbx/LibMP") 会向 execute_luau 和命令栏开放 MicroProfiler（MCP 技能 rbx-perf-profiling）。Edit 快照包含完整帧；Playtest 快照包含 0 到 128 帧，场景越繁重， 帧数越少（已测量）。

参考资料

• references/expert-notes.md：专家的原则和判断，附时间戳和实时测量结果。
• references/procedures.md：P1 到 P10 阶段的完整代码，以及各阶段的测试 ID 和实时结果。
• references/critique.md：通过与失败的评估标准，以及预算门槛表。
• references/memory-and-crowds.md：客户端内存构成、资源和批处理审计 （PerfAudit.assets）、角色和宠物开销（updateInvalidatedFastClusters 超过 4 ms），以及流式传输 无法解决的群集问题。
• references/gui-paths.md：MicroProfiler、Developer Console、Scene Analysis、仪表板和发布菜单，以及脚本替代方案。
• references/sources.md：所有文档和视频，附凭据和时间戳。
• scripts/rbx_perf.py：工具包运行器、离线审计、实验室属性、Server 和 Client 窗口、带噪声底限的对比，以及分析器封装器。
• scripts/agentkit/performance/：PerfProbe、ScriptProf、 MicroProf、HeapProf、SceneScan、PerfAudit、lune_perf_audit.luau。