FrameGuard
FrameGuard is a configurable performance, protection, and diagnostics mod for Minecraft Forge servers and large modpacks.
The main goal of FrameGuard is to help server owners and modpack developers control common performance problems without forcing one fixed playstyle or one aggressive optimization strategy. Instead of changing everything automatically, FrameGuard provides multiple separate systems that can be enabled, disabled, and tuned through configuration files.
FrameGuard is designed for modpacks, survival servers, technical servers, and test environments where performance problems often come from many small sources at once: too many dropped items, too many XP orbs, excessive TNT chains, overloaded entity clusters, banned/problematic items, unstable TPS, or world generation spikes.
FrameGuard 0.2.0
FrameGuard 0.2.0 is a major stability and diagnostics update.
This version focuses on making FrameGuard safer for public use, improving modpack compatibility, and adding the first Better WorldGen diagnostics systems.
A major issue from earlier versions has also been fixed: unstable client mixin hooks that could cause startup crashes on some Forge 1.20.1 setups have been removed. This fixes crashes related to the player tab overlay ping rendering mixin, especially on newer Forge 47.4.x environments.
Main Features
Better WorldGen Diagnostics
FrameGuard 0.2.0 introduces Better WorldGen diagnostics.
These diagnostics are designed to help server owners and modpack developers identify when world generation, chunk loading, chunk unloading, or general server/world load becomes unusually heavy.
The system can report:
-
High server/world load
-
High average tick time during diagnostic windows
-
High chunk load and unload activity
-
Chunk activity spikes per second
-
Dimension-specific chunk activity information in the log
This is especially useful for large modpacks where world generation can be affected by many different biome mods, structure mods, terrain mods, dungeon mods, or datapacks.
Better WorldGen diagnostics are intentionally safe. They do not delete chunks, regenerate terrain, rewrite structures, block world generation, or modify terrain generation. In FrameGuard 0.2.0, this system is focused on visibility and diagnostics.
Optional OP Chat Warnings
Better WorldGen diagnostic warnings can now optionally be sent directly to online server operators.
By default, these warnings are only written to the log to avoid chat spam. Server owners can enable OP chat notifications in the server config.
Example use case:
A server owner or modpack developer is testing a new worldgen-heavy modpack. Instead of constantly watching the log file, they can enable OP chat warnings and receive live diagnostic messages when chunk activity or server/world load becomes unusually high.
Normal players do not receive these diagnostic messages. The notification system is intended for operators and administrators.
Dropped Item Optimization
FrameGuard includes tools for reducing dropped item entity load.
Dropped items can be merged in a configurable radius, reducing the number of item entities that need to be ticked by the server. This can help with farms, mob grinders, mining areas, technical builds, and situations where many items are created at once.
The system includes several configuration options, such as:
-
Merge radius
-
Scan interval
-
Stack multiplier
-
Maximum merged stack size
-
Maximum items scanned per pass
-
Maximum merges per scan
-
Player-dropped item protection time
Player-dropped item protection helps prevent recently dropped player items from being instantly merged or cleaned up.
Dropped Item Cleanup
FrameGuard can also clean up excessive unprotected dropped items after a warning countdown.
This system is configurable and can be adjusted for different server types. Server owners can define how many unprotected item entities are allowed before cleanup starts, how long the warning countdown should be, and whether warning messages should be broadcast.
This is useful for servers where item buildup can become a major lag source.
XP Orb Optimization
FrameGuard includes XP orb merging to reduce excessive XP entity counts.
Large farms, mob grinders, mining systems, and modded XP systems can sometimes create many XP orbs. FrameGuard can merge compatible XP orbs to reduce entity load while preserving the intended XP value.
Configuration options include:
TNT Guard
FrameGuard includes TNT protection tools for servers where large TNT chains can cause lag spikes or instability.
TNT Guard can limit how many TNT entities actively tick at once and can freeze excess TNT until active slots become available. This helps reduce extreme TNT lag while still allowing TNT-based gameplay when configured correctly.
TNT Guard includes options for:
-
Maximum active TNT
-
Freezing excess TNT
-
Promoting older waiting TNT first
-
Handling TNT in unloaded chunks
-
Queueing TNT blocks triggered by explosions
-
Limiting queued TNT activations per tick
-
Hiding or freezing waiting TNT entities
This system is useful for technical servers, survival servers, and modpacks where TNT duplication, large explosions, or chain reactions can otherwise overload the server.
Entity Cramming Guard
FrameGuard includes an entity cramming guard for overloaded blocks or entity clusters.
This system can help control situations where too many entities stack into the same block or location. It can be configured to include or ignore certain entity types, such as dropped items, TNT, or armor stands.
Configuration options include:
Item Ban System
FrameGuard includes a configurable item ban system.
Server owners can define item registry IDs that should not be allowed. FrameGuard can remove banned items from player inventories and from dropped item entities in the world.
This is useful for modpacks where certain items are broken, unfinished, overpowered, crash-prone, or not intended for public use.
The item ban system can be configured through the server config and supports command-based management depending on the installed version and server permission setup.
TPS Synchronization
FrameGuard can synchronize server TPS information to clients when needed.
This allows supported client-side FrameGuard systems to display or react to server performance information. The sync interval is configurable.
Compatibility Focus
FrameGuard is designed to be configurable instead of aggressive by default.
Most systems can be adjusted individually. This is important for large modpacks because not every optimization is safe for every modpack. Some packs need strict cleanup, while others need more conservative settings to avoid interfering with technical builds, custom items, modded entities, or special worldgen behavior.
FrameGuard 0.2.0 also improves compatibility by removing unstable client mixin hooks from earlier versions. This makes startup behavior safer on Forge 1.20.1 and helps avoid crashes related to changed Minecraft or Forge internals.
Server and Client Usage
FrameGuard is mainly focused on server-side performance and diagnostics.
For most server-side features, FrameGuard should be installed on the server. Clients do not need to install the mod for basic server-side systems to work.
If FrameGuard is installed on the client as well, client-side support features may be available depending on the version and configuration.
FrameGuard is intended to remain modpack-friendly and configurable.
Configuration
FrameGuard uses config files to control its systems.
Server owners and modpack developers can adjust performance settings, warning thresholds, merge limits, cleanup behavior, banned items, TNT protection, Better WorldGen diagnostics, and other systems.
FrameGuard 0.2.0 includes configuration for:
The Better WorldGen OP chat warning option is disabled by default:
notify_ops_in_chat = false
This keeps the default behavior log-based and avoids unnecessary chat spam.
Recommended Use Cases
FrameGuard is useful for:
-
Large Forge modpacks
-
Survival servers
-
Technical Minecraft servers
-
Modpack development and testing
-
Servers with many farms
-
Servers with heavy TNT usage
-
Servers with item entity lag
-
Servers with XP orb lag
-
Modpacks with heavy world generation
-
Admins who want configurable diagnostics instead of blind optimization
Version 0.2.0 Highlights
-
Added Better WorldGen diagnostics
-
Added chunk activity spike diagnostics
-
Added high server/world load diagnostics
-
Added optional OP chat warnings for Better WorldGen diagnostics
-
Added configurable chunk activity warning threshold
-
Improved server config structure
-
Improved package/code organization internally
-
Removed unstable client mixin hooks from earlier versions
-
Fixed startup crash related to PlayerTabOverlayMixin on some Forge 1.20.1 setups
-
Improved Forge 1.20.1 compatibility
-
Improved modpack safety by keeping diagnostic systems configurable and conservative
Important Notes
FrameGuard is not intended to magically fix every performance problem in every modpack.
Different modpacks can have very different causes of lag. FrameGuard is designed to give server owners and modpack developers practical tools, limits, and diagnostics so they can identify and reduce common performance issues.
For best results, review the config and adjust values for your server or modpack.
License and Usage
FrameGuard is released under All Rights Reserved.
You may use FrameGuard on private and public servers.
You may include the unmodified FrameGuard .jar file in free modpacks, as long as the modpack itself is not sold.
You may share modified FrameGuard configuration files, for example adjusted limits, server-specific balancing, banned item lists, performance settings, or other configuration changes.
Voluntary donations for servers or modpacks using FrameGuard are allowed, as long as the donation is not required to download the modpack or access FrameGuard itself.
You are not allowed to:
-
Sell FrameGuard
-
Sell modified versions of FrameGuard
-
Redistribute modified .jar files
-
Redistribute the source code
-
Publish modified source code
-
Claim FrameGuard as your own work
