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:

XP merge radius
Scan interval
Maximum XP value per merged orb
Maximum merges per scan
Maximum XP orbs scanned per pass

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:

Check interval
Max entity cramming override
Armor stand handling
Dropped item handling
TNT handling
Ignored entity type list

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:

TPS sync
Command permissions
Performance profile
Entity cramming guard
XP orb merging
Dropped item merging
Dropped item cleanup
TNT Guard
Item banning
Better WorldGen diagnostics
Optional OP diagnostic chat notifications

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

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