PalPerfWatch - Linux分支

PalPerfWatch for Linux

通过 UE4SS 为《幻兽帕鲁》打造的性能监控模组。跟踪帧时间、检测卡顿、推断可能原因，并生成包含 FPS 图表、卡顿分析和可疑模组分析的 HTML 报告。

鸣谢

原版模组作者为 xerbe85。此分支改编了代码以实现 Linux/Proton 兼容性，将所有文本翻译成英文，并移除了特定机器的路径。

需求

• 幻兽帕鲁（Steam，通过 Proton 运行）
• 已安装 UE4SS 并能与幻兽帕鲁正常工作
• UE4SS 的 Mods 目录中至少有一个可用的 Lua 模组槽位

安装

1. 将 PalPerfWatchLinux 放入 Pal/Binaries/Win64/ue4ss/Mods。尽情享受信息吧！

配置

首次启动时，模组会在其文件夹中创建 PalPerfWatch.ini。编辑并重启游戏以应用更改。

设置	默认值	描述
Display	1	1 = 显示屏幕叠加层，0 = 隐藏
SamplingMs	16	轮询间隔（毫秒）。如果模组自身导致卡顿，可提高到 33
StutterMs	25	认定为卡顿的最小冻结时长（毫秒）
HeavyMs	100	无可见触发因素分类的长时间冻结阈值
FpsDropPercent	60	低于平均 FPS 百分比时触发 FPS 下降事件
SpawnMonitoring	1	1 = 跟踪新 Actor 和 UserWidget 创建，0 = 禁用
WriteData	1	1 = 写入会话数据文件，0 = 禁用
OpenReport	1	1 = 生成报告时自动打开 HTML 报告，0 = 仅手动打开
ReadUe4ssLog	1	1 = 解析 UE4SS.log 以获取各模组错误，0 = 跳过
DataEverySecond	2	每 N 秒写入一行 FPS 数据（0 = 禁用周期行）
MaxEvents	500	内存中存储的最大卡顿事件数
DisplayX	24	叠加层水平位置
DisplayY	24	叠加层垂直位置
DisplayZ	1000	叠加层 Z 顺序（绘制深度）
DisplayMs	250	叠加层刷新间隔（毫秒）
DisplayFont	7	叠加层文本字体大小
DisplayScale	1.0	字体大小设置失败时的渲染缩放后备方案
Language	auto	强制指定语言或保持自动。此分支仅提供英文

热键

按键	功能
Shift+F3	切换屏幕叠加层的显示/隐藏

工作原理

该模组在游戏线程上以 SamplingMs 设置的间隔运行一个轮询循环。每次循环：

1. 从游戏的 GetWorldDeltaSeconds 函数读取帧时间
2. 将循环自身的到达时间与预期间隔进行比较。如果循环到达延迟，则表示游戏已冻结，延迟时长即为卡顿持续时间
3. 统计当前窗口内新增的 Actor 生成和 UserWidget 创建次数
4. 推断可能的原因：地图流式加载、对象生成、UI 构建、自身开销、长时间冻结或无法确定
5. 将事件记录到数据文件并更新屏幕叠加层

会话结束时（或崩溃后），模组将生成一个 HTML 报告，其中包含：

• 摘要卡片：平均 FPS、1% 低帧、总卡顿次数、总冻结时间、最长卡顿、冻结占比
• FPS 随时间变化的图表（SVG 格式，带卡顿标记的每秒平均值和最低值）
• 按原因分类的卡顿分析及建议的补救措施
• 使用圆形统计（瑞利检验）进行规律间隔检测，以识别定时器驱动的卡顿模式
• 单独的卡顿日志（最近 200 个事件）
• 可疑模组：卡顿后不久生成的、非基础游戏的对象
• UE4SS 日志错误分析（按模组归属）
• 已安装模组清单，包含状态和文件大小
• 注意事项和警告（FPS 下降、UE4SS 重复、模组数量过多）

生成的文件

所有文件均创建于 PalPerfWatch 模组文件夹中：

文件	用途
PalPerfWatch.ini	配置文件（自动创建，可编辑）
PalPerfWatch.log	模组启动和运行时消息的纯文本日志
PalPerfWatch.data	管道分隔的会话数据（事件、FPS 行、模组列表、注意事项）
PalPerfWatch.data.prev	上一会话数据（崩溃检测后重命名）
PalPerfWatch.session	会话标记文件（存在表示上次退出不干净）
PalPerfWatch.report.html	生成的 HTML 报告（如果 OpenReport=1 则自动打开）

Linux/Proton 注意事项

• 模组会先尝试使用 xdg-open 打开报告，在 xdg-open 不可用的 Wine/Proton 环境中，则回退到 Windows 的 start 命令
• 目录列表会先尝试使用 ls，在仅有 Wine 的 cmd.exe 可用的环境中，则回退到 dir
• 在 Linux 上运行时（无 LOCALAPPDATA），HTML 报告中的崩溃报告路径会显示 Proton prefix 路径
• 屏幕叠加层从头构建 UMG 控件。如果 UMG 类不可用，则回退到 PrintString（持续时间更短，控制能力更弱）
• 所有路径均根据脚本自身位置动态解析。代码中没有任何硬编码路径

解读报告

卡顿原因

原因	含义
关卡变更或世界流式加载	游戏加载了新区域或流式加载了新地形。属于正常现象，但频繁发生可能表明视野距离或流式加载预算设置过高
流式加载（120+ 对象）	游戏或模组一次性创建了多个对象。怀疑是战利品/帕鲁/物品生成模组。请逐个禁用
轻量流式加载（30+ 对象）	中等程度的对象创建。不太严重但仍可测量
UI 构建（15+ 控件）	某个模组在游戏过程中构建了 UI 元素。菜单模组应只构建一次，之后显示/隐藏
PalPerfWatch 自身	本分析器的自身开销超过了卡顿时长的一半。请提高 SamplingMs 或禁用叠加层
长时间冻结（100 毫秒以上）	未检测到游戏内触发因素。可能是磁盘加载、着色器编译或 Lua 模组在游戏线程上执行了高开销操作
无法确定	无明显原因。禁用一半模组并比较报告

规律间隔检测

如果卡顿以高度规律的间隔发生，报告会使用集中度百分比（瑞利 R 统计量）进行标记。集中度高于 45% 表明存在定时器驱动的原因：

• 如果卡顿是“静默的”（没有新对象或控件），引擎的垃圾回收器可能是罪魁祸首。调整 Engine.ini 中 [[/Script/Engine.GarbageCollectionSettings]] 下的 gc.TimeBetweenPurgingPendingKillObjects 来进行测试
• 如果无论垃圾回收设置如何，间隔始终保持不变，那么在该精确间隔上运行的模组就是可疑对象

可疑模组

报告会列出在卡顿后不久创建的、其类路径不以 /Game/Pal 开头的对象。这些仅仅是基于时间巧合的怀疑，并非确凿证据。一个 Lua 模组无法直接从游戏线程内部测量另一个模组的执行时间。

局限性

• 只能测量时间相关性，无法直接测量因果关系
• 无法从游戏线程内部对单个模组的执行时间进行插桩
• 叠加层控件需要加载 UMG 类。在游戏早期启动或地图过渡期间，叠加层可能会暂时回退到 PrintString 或根本无法显示
• 生成监控会增加少量开销。如果分析器自身开销过高，可通过 SpawnMonitoring=0 禁用
• 节拍器（规律间隔检测）需要至少 12 次持续时间 90 毫秒或以上的卡顿才能得出结果

许可协议

此分支遵循 xerbe85 原版 PalPerfWatch 的许可协议。如果原版模组未指定许可，则适用默认版权。如需重新分发，请联系原作者获得许可。