Adaptive Performance Tweaks

Adaptive Performance Tweaks (APTweaks)

⚠️ 12.x is the current unified release line. Older docs or setup guides may still describe the legacy 11.x multi-module layout.

💾 Back up your world and config files before updating. 12.x is still a early-release and some configuration details may change between releases.

📝 Known limitations before stable release There is no in-game config GUI yet. 12.x currently uses a config-first workflow, and larger servers will usually need some spawn tuning beyond the defaults.

🔄 Upgrading from 11.x? Remove all old APTweaks module jars before installing 12.x. Do not mix 11.x and 12.x files in the same mods/ folder.

Adaptive Performance Tweaks is a server-side optimization mod for Forge, Fabric, and NeoForge. It watches Minecraft's server-side load and adjusts selected systems automatically to reduce lag pressure on dedicated servers, single-player worlds, and LAN-open worlds.

That means APTweaks is not only for public or dedicated servers. It can also help in normal client worlds, because single-player and LAN sessions still run the same server-side systems for spawning, ticking, gamerules, items, XP orbs, and simulation distance.

Instead of asking you to assemble separate modules, 12.x bundles the major feature groups in one mod:

• Spawn control and spawn presets
• Game rule adaptation
• Item, XP orb, and arrow cleanup
• Player login and beginner protection
• Adaptive simulation distance with movement-aware throttling
• Optional advanced throttles for AI, chunk generation, and view distance
• Monitoring and benchmarking tools

🎥 Introduction and Overview Video

What APTweaks is good at ✨

APTweaks helps most when performance problems are caused by:

• too many mobs or repeated spawn attempts
• large amounts of dropped items, XP orbs, or stuck arrows
• overloaded exploration and chunk generation
• worlds or servers that need softer automatic reactions instead of permanent hard limits

APTweaks is especially useful for:

• dedicated servers that need adaptive protection under changing player load
• modpacks with heavy entity pressure
• single-player worlds with farms, exploration, or too much dropped loot
• LAN worlds where the host machine struggles with the integrated server load

It is less helpful for issues that come mainly from:

• heavy redstone or machine logic
• one specific broken mod or entity
• world corruption or storage bottlenecks

Quick start 🚀

1. Remove any old 11.x APTweaks jars from mods/.
2. Install APTweaks 12.x via the CurseForge or Modrinth launcher. Manual install: download the jar for your loader from one of those pages and place it in mods/.
3. Start the game, world, or server once.
4. Review the generated files in config/adaptive_performance_tweaks/.
5. Leave defaults on for a first test run before tuning anything.
6. If you run a larger server, review spawn limits early. The fallback spawn defaults are tuned for about 4 players.

Spawn presets are loaded from:

• config/adaptive_performance_tweaks/spawn_presets/
• data/<namespace>/aptweaks/spawn_presets/

If you want to customize presets, start with the templates and examples in wiki/SpawnPresets.

Feature overview 🧩

Feature	What it does
Spawn	Limits mob pressure with load-aware checks, view-area logic, and configurable presets
Game Rules	Adjusts selected gamerules when the server gets stressed
Items	Merges or removes excess dropped items
Experience Orbs	Clusters XP orbs to lower entity counts
Arrows	Cleans up stuck arrows without touching active projectiles
Player Protection	Protects players during login and helps newer or listed players
Simulation Distance	Lowers simulation cost automatically under load and can temporarily throttle harder during heavy exploration
View Distance	Optional advanced safety valve for heavy servers
AI Throttling	Optional advanced slowdown for far-away mob AI
Chunk Gen Throttle	Optional advanced slowdown for chunk generation work
Monitoring	Optional log-based visibility into load and entity pressure
Benchmark	Built-in scenario-based baseline/active measurement suite for real worlds, servers, and modpacks

Simulation Distance stays load-aware as before, but can now also clamp down harder during heavy exploration at MEDIUM+ load and then recover gradually after players stop moving or finish logging in.

Commands 🔧

The main command root is /aptweaks.

Useful commands include:

• /aptweaks status
• /aptweaks load
• /aptweaks stats
• /aptweaks stats items
• /aptweaks stats xp_orbs
• /aptweaks stats arrows
• /aptweaks stats reset
• /aptweaks entities overview
• /aptweaks feature <id> <true|false>
• /aptweaks playerPositions
• /aptweaks kill all_dropped_items
• /aptweaks reload
• /aptweaks debug
• /aptweaks benchmark
• /aptweaks benchmark start
• /aptweaks benchmark start scenario <general|items|xp|entities|recovery>

If something feels wrong, run these four commands first:

• /aptweaks status
• /aptweaks load
• /aptweaks stats
• /aptweaks debug <module> true

Reload note:

• /aptweaks reload reloads the .cfg files
• spawn preset JSON changes are safer with vanilla /reload or a restart
• feature on/off changes may still require a restart to take full effect

Learn more 📚

The wiki is the main 12.x documentation:

• Home
• How To Use
• Modules and Features
• Spawn Presets
• FAQ
• Troubleshooting
• Benchmark
• Versions and Legacy Notes