# 引擎性能调试 所有调优默认关闭,通过 XFE 自研加载器加载本插件即可使用。插件引用已安装游戏的 Harmony;不会替换、分发或改写游戏程序集文件。调优操作只在主菜单或明确授权的离线副本中接收;持久设置在之后的游戏启动中继续生效。 ## 可撤销配置 ```powershell $cli = './src/XFE.SeAgent.Cli/bin/Release/net10.0/xfe-se.exe' & $cli call performance.configure --pid 1234 --params '{"renderUncapped":true,"disableVsync":true,"terminalAccessCache":true,"actorBatching":true,"physicsWorkers":0,"persist":true}' ``` | 字段 | 默认 | 行为 | | --- | --- | --- | | `renderUncapped` | false | 仅解除渲染线程等待器的 120 FPS 限制;不修改模拟时间步长。 | | `disableVsync` | false | 在 DXGI Present 中使用零同步间隔,同时覆盖普通和动态分辨率路径;不会修改画质或用户图形配置文件。显示器刷新率仍是实际显示上限。 | | `terminalAccessCache` | false | 同一模拟帧、同一终端系统、同一最后应用的拥有者复用方块权限结果;拥有者交替、方块增删、归属、阵营关系、管理员权限变化均使其失效。 | | `actorBatching` | false | 将引擎原本允许并行的渲染组件按 32 个一组交给现有任务池,减少逐组件互斥锁竞争。保留原优先级,并等待所有批次完成后再执行串行场景更新。非阻塞或显式限制工作线程的调用回退原方法。 | | `actorBatchSize` | 32 | 每批 16–1024 个组件,供对照实验;更大的批次可能减少均衡任务的机会。 | | `actorWorkers` | 0 | 0 保留原并行上限,否则限制本组件阶段的并行任务数(1 到逻辑处理器数);不创建新线程池。 | | `entityBatching` | false | 实验选项:只将 `PerformParallelUpdate` 中引擎原本允许并行的实体循环改为批次。保留初始化、Havok 共享读取作用域、优先级和完成等待;调用线程复制枚举,避免工作线程逐实体争用共享枚举器锁。非阻塞或显式线程上限回退原方法。寰宇号关闭/开启/关闭对照的差异不足以证明收益,默认关闭。 | | `entityBatchSize` | 8 | 每批 1–128 个实体,供上述实验使用。 | | `idleRotation` | false | 对已停止、速度增量为零、没有目标角度的旋转组件省去无效矩阵写入。活动旋转、加减速和目标角度处理保留原实现。安装时校验已实测引擎方法体指纹,不支持的版本拒绝启用。 | | `texturePriority` | false | 在贴图批次的原子最大值调用点先读取已有优先级,只在确需提高时竞争写入。保留原有两层锁、贴图生命周期、逐帧更新及计算结果;不降低贴图质量。 | | `hierarchyUpdates` | false | 子网格位置传播直接使用具体集合的结构枚举器,避免在每一级递归中装箱。保留原线程、顺序、矩阵副本及全部回调;校验原方法与局部函数的 IL 指纹。 | | `mainThreadL3` | false | 实验选项,需要 `preferLargestL3`。只将游戏主线程固定到大缓存核心组,其他线程保留原进程可用核心;取消时恢复原线程掩码。本机实测只绑主线程提高了模拟更新频率,却降低了渲染 FPS,最终保持关闭。 | | `pinRenderWorkers` | false | 需要同时开启上面两个选项。将渲染线程与经过组件批次的原生工作线程也固定到同一 L3 组;不创建线程池。状态报告实际固定线程数与错误;本机观测到 9 个,其他引擎工作线程仍可使用其余核心。 | | `lowLatencyGc` | false | 活跃游戏期间申请 CLR `SustainedLowLatency`;菜单/暂停时恢复之前的模式,可用物理内存低于 `max(2GiB, 总内存10%)` 时回退。尊重其他组件后续更改,不使用禁止 GC 的区域。此模式不能消除所有 GC 停顿,需实测内存与长帧。 | | `lockFreeParallelLoops` | false | 实验选项:启用引擎自带的无互斥锁 `ForEach` 调度分支,作用范围比 `actorBatching` 大。两者叠加未在本次实测中取得额外收益,最终配置保持此项关闭。 | | `preferLargestL3` | false | 针对 L3 容量不同的核心组,用 Windows 拓扑信息选择缓存最大的一组作为进程亲和性。保留该组内的多核、SMT 和引擎线程池,减少跨缓存组调度;不硬编码核心编号。当前只支持 x64、单处理器组、唯一较大的 L3;不满足条件时拒绝此项。必须对照测试,不能假定所有 CPU 都受益。 | | `validateCache` | false | 对每次拟复用的所有权限逐一调用原版判定核对。出现差异立即停用缓存并记录日志;此模式有明显额外开销,不用于速度对照,不持久化。 | | `physicsWorkers` | 0 | 0 使用游戏原值;否则为 2 到逻辑处理器数量(最多 64)。使用原生 Havok 线程池配置入口,下次载入世界才生效。实际值以 `havokWorkers` 为准;更多线程未必更快。 | | `persist` | false | 保存到 `%LOCALAPPDATA%/XFE/SpaceEngineersAgent/performance.json`,保留上一份 `.bak`。 | 恢复原行为:将 `renderUncapped`、`disableVsync`、`terminalAccessCache`、`actorBatching`、`entityBatching`、`lockFreeParallelLoops`、`preferLargestL3`、`mainThreadL3`、`pinRenderWorkers`、`idleRotation`、`texturePriority`、`hierarchyUpdates`、`lowLatencyGc` 全部设为 false,`physicsWorkers` 设为 0,选择持久化,然后重新载入世界。正常卸载插件也会移除自身补丁并恢复原渲染等待器、GC 延迟模式和任务循环选项。CPU 亲和性恢复到插件启动前的值;如果外部程序在调优后另行改变它,则尊重外部设置。与其他修改相同引擎方法的插件组合时需重新验证。 `actorWorkers` 现在以有限数量的任务入口动态领取批次,避开本机引擎 `Parallel.For` 会用迭代数覆盖 `MaximumThreads` 的行为。引擎兼容测试核验 1/2 个入口的实际并发峰值和所有回调完成。它修正的是线程上限语义,不代表指定更多或更少线程就能提高 FPS。 批次快照逐项填入复用列表,避开本机 .NET Framework `List.AddRange(ICollection)` 即使容量足够也会分配中间数组的行为。真实 CLR 分配调用栈暴露了此开销;引擎测试使用 16,384 项、预热后的 32 次调度,核对调用线程分配以及所有工作完成,不用禁用 GC 或删减实体更新来换取分数。 权限缓存只在原版主线程脚本执行期间工作,不接管其他插件的并行脚本调度。物理与渲染继续使用引擎自身的并行任务系统;不会把任意修改方块的脚本直接扔进线程池。 方法补丁验证已知 IL 调用位置,不能匹配的引擎版本会拒绝该补丁。不同配置项依次应用;某项失败时,之前成功应用的项目仍可能开启,以 `performance.status.tuning` 为准。升级游戏或其他引擎插件后应重新做功能与性能对照。 ## 多线程垃圾回收 在游戏完全退出后,可为 XFE 自研加载器创建启用 Server GC 的新版本: ```powershell ./tools/Set-LoaderRuntime.ps1 -ServerGc $true ./tools/Start-DebugSession.ps1 ``` 工具验证加载器及游戏文件哈希,复制现有加载器到新的版本目录,仅修改新副本的 CLR 启动配置;随后备份并原子更新 ToolBox 加载器路径。不会修改游戏原始 EXE/DLL、存档或旧加载器。它同时启用后台 GC,运行中用 `performance.status.gc.server` 验证实际生效。 可选 `-HeapCount N -NoGcAffinity $true` 限制 Server GC 堆数并解除 GC 线程的固定 CPU 绑定。必须按实际 CPU 亲和性和长帧表现测试;线程越多不等于停顿越短。`-HeapCount 0 -NoGcAffinity $false` 恢复 CLR 默认堆数/绑定,省略参数也使用该默认值。`.NET Framework` 的 [GCHeapCount](https://learn.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/runtime/gcheapcount-element) 与 [GCNoAffinitize](https://learn.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/runtime/gcnoaffinitize-element) 使用进程启动配置,不是运行中热切换。 本机 .NET Framework 4.8.9363 的实际验证中,配置文本 `16` 得到 22 个堆;工具已改为将十进制参数转成十六进制配置文本(例如 16 → `10`),并通过 CLR DAC 再确认实际堆数。不得把请求值当作实测值。`lowLatencyGc` 则通过 [CLR 低延迟模式](https://learn.microsoft.com/en-us/dotnet/standard/garbage-collection/latency) 在活跃游戏期间申请减少前台 Gen2 回收,内存压力及显式强制回收仍可能造成阻塞。 Server GC 使用多个堆和专用回收线程,可能增加内存占用,需与游戏中的帧时间一起测量。它不是任意游戏逻辑的并行开关。恢复工作站 GC:退出游戏,执行 `./tools/Set-LoaderRuntime.ps1 -ServerGc $false`,再启动。此设置独立于 `performance.json`;只关闭插件调优不会恢复 GC。ToolBox 重建加载器后也需重新确认 GC 配置。 依据 [.NET Framework 的 gcServer 配置](https://learn.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/runtime/gcserver-element) 和 [gcConcurrent 配置](https://learn.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/runtime/gcconcurrent-element),通过加载器的 `.exe.config` 设置,而非假定进程环境变量已生效。 ## 采样 ```powershell ./tools/Measure-Performance.ps1 -GamePid 1234 -Label baseline -Seconds 60 -OutputDirectory artifacts/performance ./tools/Measure-Performance.ps1 -GamePid 1234 -Label diagnostics -Seconds 30 -EngineStages -OutputDirectory artifacts/performance ``` 脚本保存完整报告和同期游戏/Blender 进程 CPU 累计时间,以及可用时的 NVIDIA GPU 负载。另通过 Windows GPU Engine 计数器记录占用至少 1% 的前 20 项进程/引擎负载,以发现 `nvidia-smi` 进程列表可能遗漏的 WDDM 图形应用。不同引擎的百分比不能相加作为整卡占用;计数器缺失或名称本地化失败会显式报告不可用。它不会暂停其他进程。 加 `-RayTracing` 时,另在每次外部采样中记录光追启用、场景收集、快照和原生 CPU/GPU 通道状态,便于识别预热/重建区间。采样间隔约 5 秒,这些状态不能当作逐帧占空比;光追通道 GPU 时间也不是整帧 GPU 时间。 `renderIntervals` 是渲染线程 `BeforeDraw` 的墙钟间隔,`updateIntervals` 是插件 Update 间隔,不能混称为同一个 FPS。另附原生模拟速度、CPU 累计时间、GC 次数、窗口 `drawEnabled` 和当前 GUI 屏幕。它不是 GPU Present/显示器扫描输出追踪;菜单记录不代表大舰船性能。没有绘制或正在加载的区间不能作为正常游玩结果。 平均 FPS 为总帧数除以总时间;1% low 为最慢 1% 帧耗时均值的倒数。P50/P95/P99 使用 nearest-rank。每个序列最多保留 131072 个间隔,超出计入 `Dropped`;出现丢弃不能声称覆盖完整采样时段。 `LongFrames` 按时间顺序记录超过 `max(50ms, 2×P50)` 的间隔,保留前 256 条;`LongFrameCount` 为全部长帧数。`EndMs` 从本序列首个时间标记起算,可与半秒样本中的 `elapsedMs` / GC 次数交叉核查(两者起点有首帧偏差)。相邻 GC 计数变化只支持关联判断,不是精确的 GC 暂停追踪。 `graphics.status` 和采样中的 `graphics` 同时核查 DPI、实际后缓冲和动态分辨率。仅配置文件或截图文件为 4K 不足以证明最终窗口没有被 Windows 缩放;DRS 关闭时其内部预设 fraction 也不能解释为实际渲染比例。 阶段探针只覆盖固定的引擎方法,完成后移除。耗时为包含子调用的墙钟时间;嵌套与并行阶段不可直接求和。高频位置更新方法的探针会增加开销,优化效果必须再用关闭探针的采样确认。原生 profiler 使用引擎自身平均值,不重置它的计数。 `engineStages.slowCalls` 记录最先完成的 256 次、耗时至少 50 ms 的被测调用,按开始时间排序;`slowCallCount` 包含超出保留上限的调用。`StartMs` 相对于探针采样时钟,附方法名、主线程标记和托管线程 ID。父子调用可能同时上榜,不能当作独立卡顿相加;覆盖不到的方法或线程调度等待仍可能没有归因。探针也包含本插件 Update 和 PerformanceStatus,便于排除采样自身的长停顿。 渲染组件类型计数只在 `engineStages` 与 `actorBatching` 同时开启时采集,计时包含同步等待,且探针自身有开销。它用于定位组件类型,不用于报告正式帧率收益。 对照应使用同一备份、画质、视角与稳定后的飞船状态;记录后台 GPU/CPU 任务。切换线程配置需要重新加载并预热。保留船体数量、损伤、脚本错误和画面证据,不能以 FPS 上升代替功能验证。 参考与许可见 [THIRD-PARTY.md](THIRD-PARTY.md)。 实机记录见 [首次寰宇号性能实测](performance-2026-11-16.md) 与 [原生 4K、引擎热点及长帧复测](performance-2026-11-17.md)。 退出外部游戏后的原生 4K 对照、显式任务入口、批次分配、DX11/DX12 等待及 CLR 诊断见 [玻璃、残影与 CPU 复测](glass-history-cpu-2026-11-17.md)。