FPS Tune

FPS Tune is a client-side Fabric and NeoForge frame-time stability toolkit for Minecraft 1.21.1, 1.21.11, 26.2, and 26.3. It applies opt-in controls to optional local rendering workloads when visual scenes become unusually heavy.

It is designed to protect the floor of the frame-time graph during particle storms and weather-heavy scenes, not to promise a universal FPS increase or replace broad rendering optimizers.

At a glance

Item	Value
Minecraft	Current v1.4.0: 26.3 Fabric, NeoForge and Forge, 1.21.11 Fabric and NeoForge. Historical v1.2.5: 1.21.1 Fabric/NeoForge, 1.21.11 Fabric, 26.2 Fabric/NeoForge, and 26.3 Fabric. Separate JAR per target.
Loader	Fabric 1.21.1: 0.16.14+; Fabric 1.21.11: 0.18.6+; Fabric 26.2: 0.19.3+; Fabric 26.3: 0.19.5+; NeoForge 1.21.1: 21.1.250+; NeoForge 1.21.11: 21.11.45+; NeoForge 26.2: 26.2.0.77+; NeoForge 26.3: 26.3.0.45-beta+ (loader still in beta); Forge 26.3: 66.0.9+.
Environment	Client only
Java	21+ for 1.21.1 and 1.21.11; 25+ for 26.2 and 26.3
Required dependency	Matching Fabric API for Fabric targets; NeoForge loader for NeoForge targets; Forge loader for the Forge target
Optional integration	Mod Menu on Fabric; native Mods screen on NeoForge and Forge
License	MIT

What it changes

• Limits local particle admission during a client tick when enabled.
• Can reserve part of the current effective budget for particles near the player, so distant cosmetic particles are rejected first during a storm.
• Can suppress the local rain/snow streaks and the landing splash particles they spawn when explicitly enabled; weather simulation and sounds continue.
• Can show an opt-in local diagnostics HUD with current-tick admission counters.
• Starts disabled and changes nothing until you opt in with F6 or the settings screen.

What it never changes

• No packets, custom networking, telemetry, analytics, update checker, or remote configuration.
• No movement, combat, inventory, targeting, rotation, click automation, or gameplay logic.
• No server simulation, world state, entity behavior, farms, or anti-cheat behavior.

FPS Tune cannot guarantee approval by any multiplayer server or anti-cheat. Check the server's current rules before enabling it.

Install

1. Install the matching loader version listed in the table above.

2. Install the matching Fabric API for Fabric targets; NeoForge targets use the NeoForge loader dependency instead.

3. Download the matching JAR from the GitHub Releases page:

   Minecraft	Loader	Published artifact
   1.21.1	Fabric	fps-tune-mc1.21.1-.jar
   1.21.1	NeoForge	fps-tune-neoforge-1.21.1-.jar
   1.21.11	Fabric	fps-tune-mc1.21.11-.jar
   1.21.11	NeoForge	fps-tune-neoforge-1.21.11-.jar
   26.2	Fabric	fps-tune-.jar
   26.2	NeoForge	fps-tune-neoforge-26.2-.jar
   26.3	Fabric	fps-tune-mc26.3-.jar

   Do not install multiple target JARs in one instance.

4. Put the JAR in the instance's mods folder and start Minecraft.

5. Press F6 to toggle the master switch, or install the matching Mod Menu version and choose FPS Tune → Configure.

The default particle budget is 300 admitted particles per client tick. Adaptive profiles use Auto to follow Minecraft's configured FPS cap; Advanced settings retain a numeric target for manual control or fallback. Nearby-particle prioritization uses a configured reserve of 100; the effective reserve is capped at half the current budget, so the default budget protects 100 nearby admissions and a 100-particle Adaptive budget protects 50. Weather rendering remains enabled unless you explicitly disable it in the settings, and the diagnostics HUD remains off by default.

Configuration

Configuration is stored locally in config/fpstune.properties.

The complete setting reference, defaults, file format, migration behavior, and UI semantics are in docs/CONFIGURATION.md.

Setting	Default	Purpose
enabled	false	Master switch; disabled by default.
particleAdmissionEnabled	true	Enables the particle budget while the master switch is active.
maxParticlesPerTick	300	Particle admissions allowed per client tick, clamped to 0..10000.
prioritizeNearbyParticles	true	Protects nearby particles with a reserved part of the existing budget.
nearbyParticleReserve	100	Configured upper bound for nearby admissions; the effective reserve is capped at half the current budget.
nearbyParticleDistance	16	Distance in blocks used to classify a particle as nearby.
diagnosticsHudEnabled	false	Shows local current-tick admission counters in the HUD.
adaptiveParticleBudgetEnabled	false	Adjusts the particle budget toward the target FPS when slow frames coincide with particle pressure.
adaptiveTargetAuto	true	Follows Minecraft's configured client FPS limit in Adaptive mode.
adaptiveTargetFps	120	Manual Adaptive target and fallback, clamped to 30..360.
adaptiveMinParticlesPerTick	100	Lowest Adaptive-mode particle budget.
adaptiveMaxParticlesPerTick	2000	Highest Adaptive-mode particle budget.
weatherMode	VANILLA	VANILLA keeps vanilla rain and snow; OFF hides them.

Mod Menu is optional. The FPS Tune details pane provides a long-form, plain-language overview of what it changes, what it leaves untouched, how to get started, and the intentional visual trade-off. The Configure screen shows a profile with a plain explanation and quick switches for particles, rain and snow, and the overlay; Advanced settings groups everything else into Particles, Weather and Display tabs, with rarely changed values behind Show more. Done or Escape on the main screen saves settings; Back returns from Advanced settings, while Cancel discards edits. F6 toggles only the master switch and saves immediately.

Adaptive mode is off by default. When enabled, Auto follows Minecraft's configured FPS cap unless you choose a numeric target; it starts from the fixed particle budget, lowers that budget only after sustained slow frames coincide with particle pressure, and uses a pressure-gated 25% emergency cut for severe sustained frame times. It raises the budget slowly after sustained healthy frames. Slow frames with little particle pressure hold the current budget. It never changes the FPS cap, render distance, weather setting, world simulation, or server behavior.

Compatibility and server rules

See docs/COMPATIBILITY.md for the verified baseline, companion-mod guidance, troubleshooting, and the client-only trust boundary.

FPS Tune is not affiliated with Mojang, Microsoft, or any server. Client-only does not mean server-approved; keep it disabled where current rules prohibit client modifications.

Performance methodology

FPS Tune should be evaluated using repeatable frame-time measurements, not a single FPS screenshot. docs/BENCHMARKING.md defines fair comparisons using average FPS, 1% lows, long-tail frame time, hitch counts, and explicit visual trade-offs.

In a real local stress test on an Apple M2 (macOS 26.6.2, Java 25, no shaders/resource packs/companion mods, Fancy graphics, render distance 16, simulation distance 12, VSync off, 240 FPS cap), average FPS and p95 frame time changed like this:

Version	Avg FPS before	Avg FPS after	FPS change	p95 frame time before	p95 frame time after	p95 change
1.21.11	210.10 FPS	215.17 FPS	+2.4%	6.65 ms	5.63 ms	-15.3%
26.2	78.69 FPS	102.78 FPS	+30.6%	17.61 ms	14.39 ms	-18.3%

Before means FPS Tune was off; after means it was on. The lower p95 frame time is the part players are most likely to notice as smoother motion: the longer frames in the measured tail were less severe, even when the average-FPS gain was small. The test used four alternating phases in one client process, 120 warm-up frames and 600 measured render-loop intervals per phase, with the enabled phases capped at the default 300 particles per client tick. These are machine-specific extreme-workload observations—not a universal FPS guarantee—and the enabled case intentionally renders fewer particles.

A separate manual smoke test on Minecraft 26.2 used a repeating command block to emit 4,000 minecraft:flame particles per activation on an Apple M2 with Java 25.0.1. In the paired captures, the disabled case showed 38 FPS with a dense flame field, while the enabled case showed 58 FPS with materially fewer visible particles:

FPS Tune state	F3 reading	Visual result
Disabled	38 FPS	Dense flame field
Enabled	58 FPS	Fewer admitted particles

That is an approximately 53% higher instantaneous FPS reading in the enabled capture, but it is not an average-FPS or p95 measurement. The two captures are useful confirmation that the controller visibly reduces this extreme local particle workload; they should not be treated as a universal performance guarantee. See docs/BENCHMARKING.md for the full methodology and limitations.

Build and test

Use GitHub Actions for the complete verification checklist. Open a pull request or trigger .github/workflows/ci.yml with workflow_dispatch; hosted CI builds all eight repository target profiles (four Fabric and four isolated NeoForge builds), runs tests and audits, and uploads artifacts. The stable v1.4.0 release contains three targets; hosted CI continues to validate all eight repository build profiles. Do not install or run Java, JDKs, Gradle, the Gradle Wrapper, or project dependencies on the owner's device. Release artifacts are produced by the hosted release workflow.

Updating FPS Tune

FPS Tune does not silently update itself or contact an update server. A maintainer updates dependencies and Minecraft compatibility in source, runs the verification checklist, and publishes a tagged GitHub release. Players then replace the older JAR in their mods folder and keep only one FPS Tune version installed.

NeoForge 26.2

The 1.2.5 release also includes fps-tune-neoforge-26.2-1.2.5.jar. Use it only with NeoForge 26.2 and Java 25; it uses the native NeoForge Mods screen, does not require Fabric API or Mod Menu, and must not be installed alongside the Fabric 26.2 JAR.

The root v1.2.5 release contains five primary artifacts: fps-tune-mc1.21.1-1.2.5.jar (1.21.1 Fabric), fps-tune-neoforge-1.21.1-1.2.5.jar (1.21.1 NeoForge), fps-tune-mc1.21.11-1.2.5.jar (1.21.11 Fabric), fps-tune-1.2.5.jar (26.2 Fabric), and fps-tune-neoforge-26.2-1.2.5.jar (26.2 NeoForge). The sixth target artifact, fps-tune-mc26.3-1.2.5.jar, is published in the separate v1.2.5-mc26.3 release.

Fabric 26.3

Fabric 26.3 is published as the separate, non-draft target-specific GitHub release v1.2.5-mc26.3, which includes fps-tune-mc26.3-1.2.5.jar. Use it only with Java 25, Fabric Loader 0.19.5+, and Fabric API 0.160.6+26.3. Mod Menu 21.0.0-beta.1 is an optional beta integration, not a required dependency; the hosted client smoke matrix covers both Mod Menu present and absent. Do not install it alongside another FPS Tune target JAR.

v1.4.0 targets

The stable v1.4.0 release, published 2026-09-26, contains four primary JARs, their sources JARs, and SHA256SUMS.txt. The NeoForge 26.3 JAR was added on 2026-10-04, and the Forge 26.3 JAR after that.

Minecraft	Loader	Artifact
26.3	Fabric	fps-tune-mc26.3-1.4.0.jar
1.21.11	Fabric	fps-tune-mc1.21.11-1.4.0.jar
1.21.11	NeoForge	fps-tune-neoforge-1.21.11-1.4.0.jar
26.3	NeoForge	fps-tune-neoforge-26.3-1.4.0.jar
26.3	Forge	fps-tune-forge-26.3-1.4.0.jar

Forge 26.3 needs Java 25 and Forge 66.0.9 or newer. It is a one-off Forge build: later FPS Tune versions may include Forge again, but that isn't guaranteed.

v1.3.0 targets

The previous stable v1.3.0 release, published 2026-09-25, contains exactly three primary JARs, their sources JARs, and SHA256SUMS.txt. Minecraft 1.21.1 and 26.2 remain available from the historical v1.2.5 releases.

Minecraft	Loader	Artifact
26.3	Fabric	fps-tune-mc26.3-1.3.0.jar
1.21.11	Fabric	fps-tune-mc1.21.11-1.3.0.jar
1.21.11	NeoForge	fps-tune-neoforge-1.21.11-1.3.0.jar

NeoForge 26.3 needs Java 25 and NeoForge 26.3.0.45-beta or newer. The NeoForge 26.3 loader is still in beta; a follow-up release will be built against its first stable version.

NeoForge 26.1.2 release addition

Minecraft 26.1.2 has an isolated NeoForge target (:neoforge-26.1.2, Java 25, NeoForge 26.1.2.114). The dedicated neoforge-26.1.2.yml workflow produces fps-tune-neoforge-26.1.2-1.4.0.jar, sources, and checksums after hosted verification. Client startup coverage is separate from manual gameplay and visual verification. The maintainer reported the .114 candidate good on 2026-10-09. Its exact binary and sources are added to v1.4.0 through the hosted promotion workflow after artifact privacy/safety checks; historical JARs and the existing tag are preserved. Publication status is verified by the promotion run and the v1.4.0 asset list.