QuietFrame

Stability that quietly follows the machine you actually have.

QuietFrame is a Fabric performance mod scaffold that continuously measures frame pacing and system pressure, then gently tunes game quality and simulation cost without asking the player to micromanage settings.

As of 0.1.4, the mod also exposes its main controls through Mod Menu, so players can decide exactly which automatic adjustments they want QuietFrame to manage.

First playable version

This first version is intentionally conservative:

• It never raises view distance, simulation distance, particles, or FPS cap above the values the player already had configured.
• It logs profile changes and detected runtime information so real-world testing is easier.
• It detects Sodium and becomes less aggressive when another performance renderer is already helping.
• It limits entity AI throttling to integrated singleplayer worlds and avoids applying it in the QUALITY profile.
• It keeps automatic view distance, simulation distance, and chunk simulation disabled by default until the player enables them.

Mod Menu configuration

QuietFrame now includes a dedicated Mod Menu config screen.

Players can toggle or tune:

• Adaptive engine behavior
• Idle mode
• Entity throttling
• Chunk simulation hooks
• Automatic view distance
• Automatic simulation distance
• Shader-friendly optimizations
• FPS limit management
• Target FPS and idle FPS cap
• Minimum render and simulation distances

This keeps the default release safer while still letting advanced users opt into more aggressive tuning.

By default, QuietFrame no longer manages the game's max FPS limit. It uses FPS as telemetry, but leaves the framerate cap under player or modpack control.

The default preset is now PERFORMANCE, which biases the engine toward holding high FPS and only stepping down quality after more persistent pressure.

This makes it a safer candidate for testing on a MacBook Air M1 with and without other performance mods.

Baseline target

• Minecraft 26.1.2
• Fabric Loader 0.19.2
• Fabric API 0.146.1+26.1.2
• Java 25

Why this baseline:

• Fabric's March 14, 2026 26.1 guidance moves the toolchain to the unobfuscated line and Java 25.
• This project now follows the current example-mod layout so future ports stay closer to Fabric's maintained template.

Architecture overview

1. Adaptive Performance Engine

AdaptivePerformanceEngine reads data from PerformanceMonitor and SystemAwarenessEngine, then chooses one of four profiles:

• QUALITY
• BALANCED
• DEFENSIVE
• SURVIVAL

Each profile can change:

• View distance
• Simulation distance
• Particle density
• Entity AI throttle divisor
• Idle FPS cap

The engine intentionally restores quality slower than it reduces quality, which helps prevent visible oscillation.

2. Smart Chunk and Simulation Control

ChunkSimulationController is the server-side policy layer. It currently:

• Exposes distance-aware decisions for chunk suppression
• Provides a safe place to gate future redstone and spawn throttles
• Limits aggressive logic to singleplayer by default for compatibility

This keeps the first version conservative while leaving a clear integration point for deeper server optimization.

3. Entity Optimization System

EntityThrottleController classifies far mobs and returns whether AI work should be skipped on a given tick. The included mixin only cancels MobEntity#mobTick, not the entire entity tick, which avoids freezing physics, passengers, and core entity state.

4. Dynamic Idle System

IdleStateController watches focus state, minimization state, key input, and player movement. When the player is AFK or the game window is not active, the engine switches to a low-cost idle posture.

5. Rendering Optimization Layer

RenderTuner applies quality settings today through vanilla options. RenderBackendAdapter is the abstraction boundary for future backends, so OpenGL-specific assumptions do not leak into optimization policy.

6. System Awareness Engine

SystemAwarenessEngine inspects:

• CPU core count
• Max JVM memory
• OS family
• CPU architecture

It then returns an aggressiveness bias. Apple Silicon and Linux get slightly different heuristics so the adaptive engine can favor lower draw-call pressure on macOS and lower CPU pressure on Linux.

Key class structure

src/main/java/dev/quietframe/
  QuietFrameMod.java
  config/QuietFrameConfig.java
  engine/AdaptivePerformanceEngine.java
  engine/OptimizationLevel.java
  engine/OptimizationProfile.java
  monitor/SystemAwarenessEngine.java
  render/RenderBackendAdapter.java
  world/ChunkSimulationController.java
  entity/EntityThrottleController.java
  mixin/MobEntityMixin.java
src/client/java/dev/quietframe/client/
  QuietFrameClient.java
  idle/IdleStateController.java
  monitor/PerformanceMonitor.java
  render/RenderTuner.java

Example code paths

FPS monitoring

See PerformanceMonitor.java.

Highlights:

• Samples FPS from the client every few ticks
• Calculates smoothed frame time
• Tracks heap pressure using the active JVM

Dynamic render distance adjustment

See RenderTuner.java and AdaptivePerformanceEngine.java.

Highlights:

• Applies changes incrementally
• Restores view distance more slowly than it lowers it
• Avoids touching graphics internals directly

Entity tick throttling

See EntityThrottleController.java and MobEntityMixin.java.

Highlights:

• Only targets far, non-critical mobs
• Uses a divisor-based cadence instead of a blanket disable
• Leaves close-range gameplay effectively vanilla

Step-by-step flow

1. Client tick updates the performance monitor and idle detector.
2. Every 20 ticks, the adaptive engine evaluates current pressure.
3. A target optimization profile is selected from telemetry plus hardware bias.
4. RenderTuner applies client-side quality changes without exceeding the player's original settings.
5. The current profile is mirrored to server-safe logic for integrated worlds.
6. Server-side entity AI work is throttled only for distant mobs and only through mobTick.

Suggested test matrix

Apple Silicon

For your MacBook Air M1, test these cases separately:

1. Vanilla Fabric plus QuietFrame.
2. QuietFrame plus Sodium.
3. QuietFrame plus your usual pack after re-enabling the other performance mods.

What to watch:

• Whether the log reports sodiumLoaded=true when Sodium is installed
• Whether frame drops recover without obvious render-distance oscillation
• Whether AFK/minimized behavior reduces load correctly
• Whether mob behavior near the player still feels vanilla

Future scaling suggestions

Porting beyond 26.1.2

• Keep backend-sensitive logic behind RenderBackendAdapter.
• Expect render API churn as Vulkan support expands beyond OpenGL-only releases.
• Revalidate mixin targets carefully on each minor release because unobfuscated names are more stable, but behavior can still shift.

Vulkan-era rendering changes

• Keep optimization policy in AdaptivePerformanceEngine.
• Implement backend-specific behavior behind RenderBackendAdapter.
• Avoid raw OpenGL calls; use Blaze3D- or Fabric-level abstractions only.

Safer advanced features

• Add a packet-synced server profile for multiplayer opt-in.
• Introduce chunk-local redstone budgets rather than global tick skipping.
• Add billboard impostors through official render hooks instead of replacing base models.

Notes

• This scaffold favors compatibility and clear extension points over invasive hacks.
• The world-side optimizations are intentionally conservative in the first pass to avoid gameplay regressions.