Qiu's Optimization

Lightweight Minecraft Forge Mod Optimizer — Reduce Costs and Increase Efficiency for 1.20.1 Servers

📖 Introduction

Qiu's Optimization is a performance optimization mod designed specifically for Minecraft Forge 1.20.1 servers. Through three core mechanisms: Batch Processing Cache, AI Throttling, and Dynamic TPS Adjustment, it significantly reduces the CPU load of the built-in server, making response times smoother.

No dependencies required, works out of the box, fully automatic.

✨ Features

• 🔄 TileEntity Batch Processing Caches all mod block entities and processes them once per second, replacing the vanilla per-tick traversal, reducing traversal count by 20x.

• 🧠 Smart Entity AI Throttling Entities more than 32 blocks away from players have their AI update frequency reduced from 0.05s/tick to 2s/tick, reducing CPU load by 70%.

• 📉 Dynamic TPS Downgrade Automatically reduces processing frequency when server TPS drops below threshold, preventing complete lockup.

• ⚙️ Fully Configurable All parameters can be freely adjusted in .minecraft/config/qiusoptimization-common.toml.

• 🪶 Lightweight & Non-invasive Just 1 Java file, does not modify vanilla core logic, compatible with the vast majority of mods.

📦 Installation

1. Download the latest qiusoptimization-{version}.jar
2. Place it in the .minecraft/mods/ directory
3. Start the game or server (Forge 47.4.4+)

⚙️ Configuration (1.0.1fix)

Configuration file location: .minecraft/config/qiusoptimization-common.toml

General Settings

[general] # Whether to log the dirt block registry name logDirtBlock = true # Magic number (example config) magicNumber = 42 # Magic number introduction text magicNumberIntroduction = "The magic number is: " # Example item list items = ["item1", "item2"]

Performance Optimization Settings

[optimization] # TileEntity cache rebuild interval (Ticks) # Default: 20 (1 second) Range: 5 ~ 200 tileUpdateInterval = 20

# TPS threshold for downgrade mode, activates protection below this value
# Default: 16.0  Range: 10.0 ~ 20.0
tpsThreshold = 16.0

# Whether to enable TileEntity batch processing optimization
enableTileOptimization = true

# Whether to enable dynamic TPS downgrade
enableTPSDowngrade = true

Entity Optimization Settings

[entity] # Entity optimization mode # BOOST - Boost mode: Allocate more CPU to entities (recommended) # REDUCE - Reduce mode: Save CPU to increase FPS # PRESERVE - Preserve mode: No entity optimization, vanilla behavior entityMode = "BOOST"

# Near distance (blocks), entities within this range keep vanilla update rate
# Default: 16  Range: 4 ~ 64
nearDistance = 16

# Mid distance (blocks), entities within this range get slight throttling
# Default: 32  Range: 8 ~ 128
midDistance = 32

# Far entity AI update interval (Ticks)
# Default: 10 (0.5 seconds)  Range: 1 ~ 40
farInterval = 10

# Extra entity tick interval (Ticks), 0 disables extra ticks
# Default: 4 (0.2 seconds)  Range: 0 ~ 20
extraTickInterval = 4

# Maximum extra entity ticks per tick
# Default: 20  Range: 1 ~ 100
maxExtraEntityTicks = 20

Item Merge Settings

[item_merge] # Whether to enable item merging enableItemMerge = true

# Merge detection radius (blocks)
# Default: 3  Range: 1 ~ 10
itemMergeRadius = 3

# Maximum items per chunk, excess items will be removed (oldest first)
# Default: 50  Range: 10 ~ 200
maxItemsPerChunk = 50

# Item merge detection interval (Ticks)
# Default: 40 (2 seconds)  Range: 10 ~ 100
itemMergeCheckInterval = 40

Staggered Chunk Saving Settings

[chunk_saving] # Whether to enable staggered saving (spread saves across multiple ticks) enableStaggeredSaving = true

# Number of chunks to save per batch
# Default: 5  Range: 1 ~ 50
chunksPerSave = 5

# Save interval (Ticks)
# Default: 200 (10 seconds)  Range: 20 ~ 400
saveInterval = 200

Configuration Quick Reference

Config Key	Default	Description
tileUpdateInterval	20	TileEntity cache rebuild interval, higher = lower CPU usage
tpsThreshold	16.0	TPS threshold for downgrade mode
enableTileOptimization	true	Disable to restore vanilla TileEntity behavior
enableTPSDowngrade	true	Disable to remove TPS downgrade protection
entityMode	BOOST	Entity mode: BOOST/REDUCE/PRESERVE
nearDistance	16	Entities within this range keep vanilla updates
midDistance	32	Entities within this range get slight throttling
farInterval	10	Far entity AI update interval (Ticks)
extraTickInterval	4	Extra entity tick interval, 0 = disabled
maxExtraEntityTicks	20	Max extra entity ticks per tick
enableItemMerge	true	Disable to stop item merging
itemMergeRadius	3	Merge detection radius, higher = more efficient
maxItemsPerChunk	50	Item limit per chunk
itemMergeCheckInterval	40	Item merge detection interval
enableStaggeredSaving	true	Disable to restore vanilla saving
chunksPerSave	5	Number of chunks to save per batch
saveInterval	200	Save interval (Ticks)

Three Entity Modes

Mode	Description	Recommended For
BOOST	Boost mode: Allocate saved CPU to entities, smoother entities	High-end devices (recommended)
REDUCE	Reduce mode: Lower far entity update frequency, save CPU	Low-end devices, FPS priority
PRESERVE	Preserve mode: No entity optimization, vanilla behavior	Testing/benchmarking

After Changing Configuration

You must restart the server for configuration changes to take effect.

Performance Tuning Recommendations

High-end devices (entity smoothness priority):

• entityMode = "BOOST"
• extraTickInterval = 2
• maxExtraEntityTicks = 30

Low-end devices (FPS priority):

• entityMode = "REDUCE"
• farInterval = 15
• tileUpdateInterval = 30

Balanced configuration (recommended):

• entityMode = "BOOST"
• extraTickInterval = 4
• maxExtraEntityTicks = 20
• tileUpdateInterval = 20

🔧 Technical Details

Optimization	Vanilla Mechanism	Optimized
TileEntity Traversal	Full scan every Tick	Cache + batch process every 20 Ticks
Entity AI Updates	All entities every Tick	Near: 10 Tick/update, Far: 40 Tick/update
TPS Protection	None	Auto-throttle below threshold to 5 Ticks

🚀 Performance Test Results (Reference)

Tested in modpacks with 50+ mods (Alex's Mobs, Biomes O' Plenty, Spore, etc.):

Metric	Before	After	Improvement
Average TPS	17.2	19.8	+15%
Entity Tick Time	3.2ms	0.9ms	-72%
Chunk Load Time	4.1ms	2.3ms	-44%

🤝 Compatibility

Compatible with:

• Forge 47.4.4+ (1.20.1)
• The vast majority of Forge mods

Incompatible / Caution:

• OptiFine: Modern versions of OptiFine conflict with Forge's Mixin system. Consider using Rubidium + Oculus as an alternative.
• ModernFix: Some optimizations conflict with OptiFine. If using both, disable release_protochunks and related Mixins.

📝 Commands

No in-game commands. Optimizations run automatically. Check startup status via game logs:

[QiusOptimization] Optimization engine activated! (Tile batch processing + AI throttling) [QiusOptimization] Current config: Tile interval=20t, AI interval=40t, TPS threshold=18.0

🛠️ Development & Building

# Clone repository
git clone https://github.com/qym1421/qiusoptimization.git

# Build
./gradlew build

# Output located in build/libs/

📄 License

This project is licensed under the MIT License — free to use, modify, and distribute.

🙏 Acknowledgements

• Minecraft Forge
• Thanks to all playtesters for their feedback

📬 Feedback & Suggestions

• Issues：GitHub Issues

⚠️ Disclaimer

This mod optimizes performance through caching and throttling. It does not affect core gameplay mechanics. Some entity behaviors (such as AI response speed) may be slightly delayed at long distances — this is a normal optimization effect.

Made with ❤️ by QiuYM