Replay Nsight

Replay Nsight

Use Vibris MCP directly for shader reloads, live captures, and performance profiles. Use this skill only for offline glc2vk replay or Nsight GPU Trace analysis of a capture produced by MCP.

Files

• bin/replay-gl.jar: OpenGL replayer.
• bin/replay-vk.jar: Vulkan replayer.
• config.json: local machine defaults. This file is ignored by git.
• config.example.json: portable template.
• scripts/run-replayer.ps1: runs the OpenGL or Vulkan replayer.
• scripts/capture-gputrace.ps1: runs a replayer under Nsight GPU Trace.
• <project-root>/.tmp/vibris/: generated replay argfiles and replay AOT caches.

Always prefer config.json for jdk and capture_path. If a command does not pass an explicit capture path, the scripts resolve capture_path as:

1. an exact capture directory when it contains resource_metadata.json;
2. otherwise, a root directory containing capture subdirectories, selecting the newest resource_metadata.json.

replay_frames controls the default frame count for both replayer scripts. Prefer running several frames rather than a single frame; this gives the driver and replay setup room to settle before the measured frame.

Both replay scripts write generated argfiles and replay AOT caches under the project root at .tmp/vibris/, not under the skill directory. The current files are replay-<backend>.args and replay-<backend>.aot.

Live control

Use vibris_profile for routine performance comparisons. It snapshots the worktree, applies shader config, reloads, resets temporal state, warms up, and measures the requested future frames in the running game. Use vibris_capture_pass for a known compute pass or vibris_capture_multi for a prepare, begin, deferred, or composite group. Poll vibris_get_capture_status until capture and saving complete, then pass its output path to the replayers.

Captured resources are recorded on first reference. If replacement shader code uses a resource absent from the capture, recapture instead of accepting an invalid replay.

Replayer Usage

Use scripts/run-replayer.ps1 with -Backend gl or -Backend vk. Omit -Capture to use config.json capture selection, or pass a capture directory explicitly. Use -ShaderRoot <path> for replacement shaderpack source and -ShaderPass <passName> to limit replacement to selected passes.

The underlying replay CLI accepts <captureDir> [frameLimit] [--shader-path|--shader-root <path>] [--shader-pass <passName>]....

OpenGL replay uses the captured original OpenGL shader source unless --shader-root is supplied. Vulkan replay uses runtime patching for shader replacement. Do not manually copy edited shaderpack sources into the capture directory; pass -ShaderRoot instead. When using a full shaderpack root to test a known hotspot, also pass -ShaderPass <passName> so only that pass is replaced and the other captured passes keep their original shader sources.

Nsight GPU Trace

Use the bundled Nsight Analyzer at ..\nsight-graphics-analyzer\scripts\nsight.py. Do not read BASE/GPUTRACE_REGIMES.xls directly; use the generated JSON files or the gputrace-stages, gputrace-actions, and gputrace-metric analyzer subcommands.

In most cases, capture GPU Trace with the OpenGL replayer. It uses the same OpenGL shader compiler path as the target game and is the best default for Alpha-Piscium performance work.

Use the Vulkan replayer only when you need finer Nsight information that is harder to get from OpenGL, such as shader source profiling or per-line stall reason detail inside one pass. In that case, run Vulkan trace with Nsight multi-pass metrics and shader profiling options. Treat the result as a diagnostic lens, not as exact OpenGL performance truth: Vulkan uses a different driver compiler path, so shader codegen and stall behavior may differ from the OpenGL shaderpack runtime.

Use scripts/capture-gputrace.ps1 with -Backend gl by default. Select a capture with -Capture, replacement source with -ShaderRoot and -ShaderPass, and trace timing or limits with the parameters below. For fine-grained Vulkan diagnostics, use -Backend vk with -MultiPassMetrics and -ShaderProfile.

GPU Trace parameter coverage in capture-gputrace.ps1:

• Start trigger: -StartAfterFrames, -StartAfterSubmits, -StartAfterMs, -StartAfterHotkey, -StartWithNgfxSdk, -StartOnReplayBegin.
• Stop/limit: -MaxDurationMs, -LimitToFrames, -LimitToSubmits, -StopWithNgfxSdk, -StopOnReplayEnd.
• Buffers: -AllocatedEventBufferMemoryKb, -AllocatedHesBufferMemoryKb, -AllocatedTimestamps.
• Metrics: -Architecture, -MetricSet, -MetricSetId, -PerArchConfigPath, -MultiPassMetrics.
• Profiling: -NoTimeEveryAction, -ShaderProfile, -PerLineActiveThreads, -PcSamplesPerPmIntervalPerSm, -PmBandwidthLimit, -HesEnabled.
• Collection and runtime: -SetGpuClocks, -CollectScreenshot, -DisableCollectShaderPipelines, -DisableCollectExternalShaderDebugInfo, -DisableTraceShaderBindings, -DisableNvtxRanges, -AllowTracingReplayReset, -KeepGoing, -TraceTimeout, -UseNgfxTimeout, -VerboseNgfx, -Timeout, -DryRun.