
LeanCore
Server RAM governor for Hytale
Acts on the heap that is really in use, and spends spare heap on keeping chunks you just left.
Worst tick -79% | Longest GC pause -83% | Disk reloads -46%
Server heap only. It never touches client FPS, GPU or TPS, and it never removes a chunk itself.
■ Why it exists
The engine already unloads any chunk no player can see, about 7.5 seconds after it leaves view. Two things it does not do:
- It judges memory by the raw heap, which includes garbage waiting for the next collection, so anything reacting to it cuts for nothing
- It throws chunks away even with plenty of free heap, so walking back reads every chunk from disk again
LeanCore fills those two gaps: it reads the heap after each garbage collection, trims view and simulation radius only when memory is really tight, keeps recently visited chunks loaded while there is room, and slows chunk loading under real pressure.
■ Measured
Dedicated server
Hytale 0.7.0, FULL profile, 6 GB heap, same world both times. I flew 600 blocks out, waited 90 s and flew back, while four extra explorers (server-side bots) left spawn in different directions at 20 blocks/s and generated new terrain the whole time. No mods vs LeanCore 1.8.0.
| No mods | LeanCore 1.8.0 | |
|---|---|---|
| World tick, average | 19.6 ms | 13.4 ms (-32%) |
| World tick, p95 | 44.8 ms | 35.1 ms (-22%) |
| Worst tick | 1440 ms | 299 ms (-79%) |
| GC pause time, total | 7.3 s | 5.0 s (-31%) |
| Longest GC pause | 1194 ms | 201 ms (-83%) |
| Heap after GC, p95 | 6071 MB | 4906 MB (-19%) |
| Peak heap after GC | 99.99% of max | 83% of max |
Without LeanCore the heap after GC hit 99.99% of max, past the 85% where the engine starts its own emergency unload. With it, the peak was 83%.
The cost: view radius averaged 16 chunks instead of 24 (lowest 12). When the view came back on the return flight, the dropped area loaded again, so the way back read 24% more chunks from disk and its tick was 17% slower. LeanCore itself used 0.42% of the server CPU.
Solo, chunk retention
Hytale 0.7 pre-release, solo, 3 GB heap, same flight. The build before chunk retention vs 1.8.0.
| Before | 1.8.0 | |
|---|---|---|
| Chunks reloaded from disk on the way back | 1203 | 653 (-46%) |
| World tick on the way back | 12.5 ms | 10.9 ms (-13%) |
| View radius at join | cut to 8 by a raw-heap false alarm | kept at 10 |
| Policy changes during the run | 13 | 5 |
The cost: more heap in use during the run (capped at 50% after GC) and about 0.16% more of the time spent in GC pauses. One run per setup; your world will differ.
■ How LeanCore decides
Every few seconds it reads the heap after GC, the old generation after GC and the growth trend, and picks a tier:
| Tier | Heap after GC | What LeanCore does |
|---|---|---|
| COMFORT | under 70% | full view radius, holds spare chunks |
| WATCH | 70% or more | gentle view trims, releases held chunks |
| TIGHT | 82% or more | stronger trims, smaller simulation radius, brakes chunk loading |
| CRITICAL | 90% or more | most aggressive trims, harder brake, optional webhook |
Raw heap alone only counts as CRITICAL at 97%, the point where memory really runs out.
■ Chunk retention
- A chunk leaves every player's view. The engine would unload it in about 7.5 s.
- If the tier is COMFORT and heap after GC is under 45%, LeanCore holds it loaded (it stops ticking).
- Walk back and it is already there: no disk read.
- Heap after GC above 50%: the farthest held chunks are released first, 64 every 2 s. Pressure or 10 minutes also release them, and the engine unloads them as usual.
■ Runtime profiles
| LITE | solo / local host | light governor, adaptive view, retention, learning on by default |
| STANDARD | friends join | adds Activity Sense, optional governor and learning |
| FULL | dedicated | full governor surface |
■ Features
- Live-heap tiers from heap after GC, old gen after GC and the growth trend, with rollback when giving view back backfires
- Chunk retention: spare heap keeps recently left chunks loaded so walking back skips the disk
- Chunk rate brake on TIGHT and CRITICAL, off while QuantumHy is loaded
- View and simulation radius trims under real pressure, never below your floor
- Activity Sense and per-player demand weighting inside a global budget
- Learning that persists across restarts
- Also: session savings report, admin HUD (opt-in), heatmap, zone pin, optional CRITICAL webhook, update notices for admins (
checkForUpdates)
■ With QuantumHy
Both work alone or together. With both installed, QuantumHy takes the client view radius and the chunk send rate, and LeanCore keeps memory: tiers, simulation radius and chunk retention. QuantumHy reads LeanCore's tier and tightens its render radius on TIGHT or CRITICAL. Nothing to configure.
■ Installation
- Download LeanCore-1.8.0.jar from the Files tab
- Drop it in your server's
mods/folder, or on Windows solo:%AppData%\Hytale\UserData\Mods - Start the server. Config is created at
mods/durkz_LeanCore/LeanCore.json - Run
/leancore statusafter about a minute
■ Commands
/leancore status | Tier, profile and what LeanCore is doing now |
/leancore memory | Heap after GC, old gen and trend |
/leancore savings | What this session saved |
/leancore zones / zone pin|unpin|pins | Zones and pinned areas |
/leancore learn / learn player | Learned behaviour |
/leancore hud on|off|status | Admin HUD |
/leancore heatmap [limit] / probe | Diagnostics |
Staff commands, permissions and the full config: DurkzPRG documentation.
■ Recommended
- Solo or local: keep
localHostMode: AUTO. LITE governor, retention and learning are on by default. - Dedicated or friends: enable
governEnabledandlearningEnabled. More heap means more room for retention. - With QuantumHy: install both. They split the work on their own.
Mod page • Docs • GitHub • Report a bug
License: MIT