LeanCore

LeanCore is a server-side memory governor for Hytale. It reads how much heap is really in use after each garbage collection and acts on that: it trims view and simulation radius when memory is genuinely tight, spends spare heap on keeping recently visited chunks loaded so walking back does not reload them from disk, and slows chunk streaming under real pressure.

On local / solo worlds, LeanCore runs profile LITE. When friends join, profile STANDARD kicks in. Dedicated servers get profile FULL.

Does not touch client FPS, GPU, or TPS.

Requires Hytale server >=0.7.0. After install, run /leancore status once the server has been up about a minute.

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. Raw heap swings between 40% and 90% on a healthy server, so anything reacting to it cuts for nothing.
• It throws chunks away even with plenty of free heap. Walk back the way you came and every chunk is read from disk again.

LeanCore fills those two gaps.

Measured

Hytale 0.7.0 release, dedicated profile (FULL), 6 GB heap. Four virtual explorers leave spawn in different directions at 20 blocks/s and generate new terrain the whole time, while a scripted player flies 600 blocks out, waits 90s and flies back. Server with no mods vs LeanCore 1.8.0, same world and route.

	no mod	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 reached 99.99% of max, past the 85% where the engine starts its own emergency unload. With it, the heap after GC peaked at 83%.

The cost: view radius averaged 16 chunks instead of 24 (lowest 12). When the view comes back on the return flight, the area that was dropped loads 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. One run per variant; your world will differ.

Solo, chunk retention

Hytale 0.7 pre-release, solo, 3 GB heap, the same scripted 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 build; your world will differ.

How LeanCore decides

              every 5s on solo, every governor tick on servers
                                   │
        heap after GC  +  old gen after GC  +  growth trend
                                   │
        ┌──────────────┬───────────┴───────────┬──────────────┐
        ▼              ▼                       ▼              ▼
     COMFORT         WATCH                   TIGHT         CRITICAL
    full view     gentle trim           stronger trim      max trim
   hold spare    release held           release held     release held
     chunks         chunks             + brake loading   + brake harder

Chunk retention

   a chunk leaves every player's view
                 │
                 ▼
   engine would unload it in ~7.5s
                 │
   COMFORT and heap after GC under 45%?  ── no ──►  engine unloads it
                 │ yes
                 ▼
   LeanCore holds it (engine keep-loaded reference; it stops ticking)
                 │
   player walks back           ──►  already loaded, no disk read
   heap after GC above 50%     ──►  farthest released first, 64 every 2s
   pressure, or 10 min passed  ──►  released, engine unloads it as usual

How LeanCore thinks

1. It reads the heap that actually stays

Right after each garbage collection the JVM reports what survived. That number, plus old gen after GC and its growth trend, is what LeanCore calls pressure. Default tiers:

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. A heap that keeps climbing can move up a tier before it crosses the line.

2. It reacts fast and confirms before acting

On solo the pressure check runs every 5 seconds and wakes the governor at once when the tier rises. A change needs two readings to confirm, policy changes are spaced out, and if the heap climbs right after view was given back, the cut comes back.

3. It spends spare heap instead of wasting it

When a chunk leaves every player’s view, the engine drops it a few seconds later, whatever the heap looks like. While the tier is COMFORT and the heap after GC is under 45%, LeanCore keeps a budget of those chunks loaded through the engine’s own keep-loaded reference. The engine stops ticking them, so they cost memory, not CPU. Walk back and they are already there. If the heap after GC passes 50%, the farthest go first, 64 every 2 seconds, so a short rise does not throw away the whole trail. Any pressure tier releases them all on the next check, and LeanCore never removes a chunk itself.

4. It slows loading only when memory needs it

Under TIGHT and CRITICAL each player’s chunk send rate is capped (512 and 192 sections per second by default), which still keeps up with walking and flying but stops join and teleport bursts from piling onto a full heap. COMFORT and WATCH give the engine’s own rate back.

5. It accounts for who the player is

An online classifier (Activity Sense) labels each player from recent activity: MINER LUMBERJACK FARMER BUILDER FIGHTER EXPLORER. That feeds a demand model that decides how hard each player’s view gets trimmed inside a global budget.

6. It acts on the right thread

Every read or write of chunk stores, chunk trackers, or view radius runs on the owning world’s thread. The background scheduler only orchestrates.

With QuantumHy

LeanCore and QuantumHy work alone or together. With both installed, QuantumHy takes the client view radius and the chunk send rate (its anti-stutter smoothing), and LeanCore keeps memory: tiers, simulation radius and chunk retention. QuantumHy reads LeanCore’s tier and tightens its render radius on TIGHT or CRITICAL. LeanCore’s chunk rate brake stays off while QuantumHy is loaded.

Runtime profiles

LeanCore sizes itself to the host automatically, by player count, no manual switch:

Profile	When	Tick	What runs
LITE	solo embedded world	30s (60s idle), pressure every 5s	light governor, adaptive view, retention, demand learning
STANDARD	a few friends	15s	adds Activity Sense, optional governor and learning
FULL	dedicated server	5s	full set

What it deliberately does not do

• Touch client FPS, GPU, or render performance. It is server heap only.
• Change TPS or simulation behavior.
• Remove chunks. Unloading is the engine’s job; LeanCore only decides how long spare heap keeps them around.
• Cut on garbage. Raw heap spikes between collections are ignored until the heap is truly near its limit.

Features

• Runtime profiles: LITE solo, STANDARD friends, FULL dedicated (localHostMode: AUTO)
• Live-heap tiers: COMFORT, WATCH, TIGHT, CRITICAL from heap after GC, old gen after GC and the growth trend; rollback when giving view back backfires
• Chunk retention (1.8, chunkRetentionEnabled): spare heap keeps recently left chunks loaded so walking back skips the disk
• Chunk rate brake (1.8, chunkRateBrakeEnabled): slows chunk streaming on TIGHT/CRITICAL; off while QuantumHy is loaded
• View-radius trims (LITE) and simulation radius trims under real pressure, never below liteMinClientViewRadius
• Activity Sense: online softmax classifier (MINER, LUMBERJACK, FARMER, BUILDER, FIGHTER, EXPLORER) feeding per-player demand
• Learning data: heap windows, demand model, zone reuse stats; saved across restarts (schema v9)
• Session savings: /leancore savings reports JVM heap peak/baseline/delta and governor activity
• Always-on diagnostics (diagnosticLogEnabled): startup/shutdown summaries and [diag] decision logs straight in the server log
• Update notifications for ops/admins when a newer JAR is published (opt-out: checkForUpdates)
• Admin HUD (/leancore hud on): small heap/tier overlay. Off by default.
• Heatmap, zone pin, optional CRITICAL webhook

Installation

1. Download LeanCore-1.8.0.jar from the CurseForge Files tab
2. Place the JAR in your server’s mods/ folder (or %AppData%\Hytale\UserData\Mods\ on Windows)
3. Start the server. Config is created at mods/durkz_LeanCore/LeanCore.json
4. Run /leancore status after about a minute of uptime

Commands

Main command: /leancore

/leancore status
/leancore memory
/leancore savings
/leancore zones
/leancore learn
/leancore learn player
/leancore probe
/leancore hud on|off|status
/leancore heatmap [limit]
/leancore zone pin|unpin|pins

Staff admin commands, permissions, and full config reference: documentation

Config

Runtime file: mods/durkz_LeanCore/LeanCore.json

Key toggles: localHostMode, liteMemoryGovernorEnabled, liteViewRadiusEnabled, liteLearningEnabled, chunkRetentionEnabled, chunkRateBrakeEnabled, watchHeapRatio, tightHeapRatio, criticalHeapRatio, diagnosticLogEnabled, governEnabled, learningEnabled, embeddedStandardProfile, dedicatedServerMode.

Learning snapshot: mods/durkz_LeanCore/learning.state.gz (schema v9, gzip).

Permissions

• HUD viewers: groups in hudViewerGroups and/or durkz.leancore.hud
• Admin heatmap, zone pin, webhook diagnostics: hudAdminGroups and/or durkz.leancore.admin

Recommended

• Solo / local: localHostMode: AUTO (default). LITE governor, retention and learning are on by default.
• Dedicated or friends: enable governEnabled and learningEnabled. More heap means more room for retention.
• With QuantumHy: install both; they split the work on their own.
• Boot log should show profile=LITE on solo and LITE -> STANDARD when a friend joins.

License

MIT License