LeanCore: server RAM governor for Hytale

LeanCore lowers JVM heap use on Hytale servers. As players explore, every area they touch keeps its chunks and entities resident in memory, and the engine is slow to release them, so heap climbs and stays high long after everyone has moved on. LeanCore is the piece that decides what stays loaded and what gets released, by modeling where players are, where they are about to be, and which parts of the map they actually return to.

Server heap only. It never touches client FPS, GPU, or TPS, and it never drops a chunk someone can still see.

With vs without LeanCore

Same solo session, server RAM over time. Without the mod, every area you visit stays resident and heap only climbs until you restart. With LeanCore, idle areas cool down and release, so RAM rises under load and then settles back.

Server RAM over a long session   (taller bars = more RAM in use)

Without LeanCore   ▁▂▃▄▅▆▇███████████   climbs to the limit, then you restart
With LeanCore      ▂▄▆▄▂▄▆▄▂▄▆▄▂▄▆▄▂▄   rises and falls, stays under control

How LeanCore decides

Two signals drive every action: how tight memory is right now, and whether a zone is still wanted. The ladder picks how hard to act; the per-zone check decides what is safe to release.

Pressure to action

                           every tick
                                │
                 read heap %  +  section pressure
                                │
               rank against THIS server's history
                                │
        ┌───────────────┬───────┴───────┬───────────────┐
        ▼               ▼               ▼               ▼
     COMFORT          WATCH           TIGHT         CRITICAL
    full view      gentle trim   unload distant    max trim +
   do nothing     + demote idle   dormant zones    unload + GC
                                                    + webhook

Keep or release a zone

   each idle zone
        │
        ▼
   player in / near it, or pinned?     ──► HOT   keep, never touched
        │ no
        ▼
   inside current or predicted view?   ──► keep  would cause pop-in
        │ no
        ▼
   idle long enough to be dormant?     ──► WARM  keep, still cooling
        │ yes
        ▼
   rank: far away + unlikely to return + low built content
        │
        ▼
   release   capped per pass, only chunks nobody can see,
             and rolled back if it backfires

How LeanCore thinks

It is not a timer that dumps chunks on a schedule. It keeps a small live model of your world and decides from it.

1. Pressure is relative to your own server

A heap at 70% is roomy on one host and the edge of a stall on another, so LeanCore does not hardcode thresholds. It samples the heap ratio continuously, builds a rolling distribution from your server's own history, and sorts the current reading into a tier:

Section pressure uses loaded sections against the 3D view budget.

2. The map is grouped into zones with a temperature

LeanCore groups the map into zones and tracks a temperature for each:

HOT -> WARM -> DORMANT -> FROZEN

3. Predictive retention

A per-player motion model biases unload away from where players are heading. The current and predicted view are never evicted by policy unload.

4. Scaled runtime

Features

• Adaptive heap tiers (COMFORT, WATCH, TIGHT, CRITICAL) learned from your server's history
• Zone dormancy with HOT, WARM, DORMANT, FROZEN states, your timers, and zone pinning
• Predictive retention: motion model protects the current and predicted view
• Reuse-distance and survival model: per-zone cooldowns and eviction order from revisit history
• View-radius trims under heap or section pressure, never below your floor, with rollback on bad cuts
• Probe-gated, capped chunk unload that only releases chunks nobody can see
• Update notifications for ops/admins when a newer JAR is published (opt-out: checkForUpdates)
• Activity Sense classifier and per-player demand weighting inside a global budget
• Learning that persists across restarts
• Session savings report, admin HUD (opt-in), heatmap, zone pin, optional CRITICAL webhook

Installation

1. Download LeanCore-1.7.2.jar from the Files tab
2. Place it 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 probe if you rely on chunk unload
5. 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 commands, permissions, and the full config reference: DurkzPRG documentation Found a bug? Issues

Recommended

• Solo or local: keep localHostMode: AUTO. LITE governor and learning are on by default.
• Dedicated or friends: enable governEnabled, learningEnabled, and unloadEnabled as needed, and run /leancore probe before policy unload.
• Read /leancore savings after 15+ minutes to see real heap delta and governor activity.

License: MIT