Sampler Mod 1.12.2, Wiki

Sampler is a technical utility mod created to investigate performance-related issues in Minecraft. Unlike content mods, Sampler does not add new mobs, items, blocks, or biomes to the game world. Instead, it provides a suite of powerful commands and visual tools for server administrators and players to diagnose exactly why a game instance is running slowly.

The mod is designed with a "zero-overhead" philosophy, meaning it has no observable impact on performance while idle and minimal impact during active profiling. It is primarily used to differentiate between client-side rendering issues, server-side tick lag, and Java Virtual Machine (JVM) memory mismanagement.

One of the most immediate features Sampler adds is an enhanced frame time graph to the standard F3 debug overlay. This graph tracks the last ~2,000 frames to show the consistency of the game's performance.

Graph Components

• Horizontal (X) Axis: Represents time, with the oldest recorded frames on the left and the most recent on the right.
• Vertical (Y) Axis: Represents frame time in milliseconds (ms). Lower lines indicate higher FPS (e.g., 16.67ms equals 60 FPS).
• Horizontal White Lines: These act as benchmarks for 0 ms (infinite FPS), 16.67 ms (60 FPS), 33.33 ms (30 FPS), and 66.67 ms (15 FPS).

Color Coding

• Blue: Time spent in the client tick (simulation logic).
• Green: Time spent in rendering, VSync, and miscellaneous tasks.
• Red Rhomb Markers: These appear at the bottom of the graph whenever Sampler detects a Garbage Collection (GC) run. If a frame spike aligns with a red marker, the lag is caused by memory management rather than rendering or logic.

Sampler uses a command-driven interface. Commands are split into /sampler for server-side/single-player logic and /csampler for client-side rendering logic.

Core Diagnostic Commands

Profiling Commands

These commands are used to generate .nps files for analysis in external tools like VisualVM.

Investigation Tools

Sampler helps categorize lag into three main types to streamline troubleshooting.

1. Low Memory Issues

Caused when the JVM's heap space is insufficient or a mod has a memory leak.

• Symptoms: Freezes right before the F3 memory counter drops; high CPU load on all cores during freezes; "GC Overhead Limit Exceeded" crashes.
• Diagnosis: Check /sampler memory. If the last two rows (GC time) are consistently high after the first few minutes of uptime, the heap size (-Xmx) likely needs to be increased.

2. Client-Side Issues

Problems affecting the rendering thread.

• Symptoms: Low FPS; stuttering when moving the mouse; freezes during chunk updates.
• Diagnosis: Observe the F3 graph. If the green area is excessively high or jagged, the issue is related to rendering settings, shaders, or complex block models.

3. Server-Side Issues

Problems affecting the simulation thread (TPS lag).

• Symptoms: Blocks reappearing after being broken; delayed GUI opening; "Can't keep up" console warnings.
• Diagnosis: Use /sampler tps. If the average tick time is significantly above 50ms, use the profiling commands to find the specific entity or tile entity causing the delay.

For deep-dive analysis, Sampler exports .nps files that can be opened in VisualVM, a Java profiling tool.

Analysis Workflow

1. Load the File: In VisualVM, go to File > Load, set the filter to "Profiler Snapshots," and select your exported .nps file.
2. Identify the Thread: Locate the "Server thread" (for /sampler exports) or "Client thread" (for /csampler exports).
3. Verify Data Integrity: Check the "Time" vs. "Invocations" columns. Under default settings, there should be roughly 10ms for every invocation. If the numbers are wildly different, the data may be skewed by a GC run.
4. Expand the Call Tree: Unfold the thread entries to see which methods are consuming the most time.
   • MinecraftServer.tick: High values here indicate entity or block tick lag.
   • Thread.sleep: High values here are actually good; they indicate the server has idle time and is not overloaded.
5. Deobfuscation: Note that method names may appear as func_12345_a. These can be translated using MCP mapping files or by identifying the parent class (e.g., net.minecraft.entity.EntityLiving).

Sampler operates by taking periodic "snapshots" of the JVM stack traces. By default, it samples every 10ms. This frequency can be adjusted in the sampler.cfg file, though the default is recommended for a balance of accuracy and low overhead.

Key Mechanics

• Sampling vs. Profiling: Unlike standard profilers that instrument every method call (which causes massive lag), Sampler simply "looks" at what the CPU is doing at set intervals. This allows it to be used on live production servers without disrupting gameplay.
• Trigger System: The /sampler trigger command is specifically designed to catch "lag spikes." It continuously records data in a circular buffer and only saves the last minute of data when a spike is detected or the command is finalized.