LeanCore: server RAM governor for Hytale

LeanCore is built to lower 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. How much it frees depends on your world, and chunk unload only kicks in after you run /leancore probe.

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 %  +  chunk 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. The sections below are the actual logic.

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:

Tier	What it means	What LeanCore does
COMFORT	within your server's normal range	stays out of the way, full view radius
WATCH	above the usual baseline	gentle view trims, starts demoting idle zones
TIGHT	memory is pressed	stronger trims, unloads distant dormant zones
CRITICAL	near the edge	most aggressive trims and unload, optional GC hint and webhook

The same percentage can read COMFORT on a roomy host and TIGHT on a tight one. Everything below scales with this tier.

2. The map is grouped into zones with a temperature

LeanCore does not reason about single chunks. It groups the map into zones (small blocks of chunks) and tracks a temperature for each:

HOT -> WARM -> DORMANT -> FROZEN

State	Meaning	Unload eligible
HOT	a player is in or near it, or it is pinned	never
WARM	the last player just left	no
DORMANT	idle past your warm timer	yes, under TIGHT or worse
FROZEN	idle for a long time	yes

A zone is HOT while any player is in or near it, then cools on timers you set once everyone leaves. Only DORMANT and FROZEN zones that are also far from every player are ever candidates. This is what tells "nobody has been here in 20 minutes" apart from "the player stepped out for a second".

3. Distance is measured honestly

When it checks how far a zone is from a player, it measures to the zone's nearest chunk edge, not its center (point-to-box, not point-to-point). Center distance would overestimate how far a large zone is and let the mod evict chunks right next to you.

Hard rule: a zone within any player's view distance plus one region of slack is never an unload candidate. That line is the difference between reclaiming memory and causing pop-in.

4. It watches motion, so it protects where you are going

Position alone is not enough. A player sprinting toward fresh terrain needs it kept before arrival, or the loader falls behind and you hit a wall of empty chunks. LeanCore runs a per-player motion model: smoothed velocity, estimated acceleration, a confidence value, and a projected position a few seconds ahead. That predicted point becomes a second anchor, so the cone in front of a moving player is protected in advance. Current view and predicted view are both off-limits.

An optional cinematic view boost widens view distance for fast movers. It is off by default: rewriting the client view radius every tick churns chunk loading and can stutter on the current engine. On a dedicated host or a strong machine with CPU and disk headroom the extra streaming is absorbed more easily, so it is reasonable to enable there; leave it off on embedded or constrained setups.

5. It learns which zones actually matter to you

Your base, your mine, the path between them: you keep returning. A spot you crossed once chasing a mob, you never see again. LeanCore keeps a reuse-distance and survival model per zone: how often and how recently it goes HOT, turned into a revisit score that stretches or shrinks that zone's cooldowns.

When memory is tight and something must go, eviction is ranked by two signals at once:

how far the zone is from players, and
how unlikely it is to be revisited.

Far and forgettable goes first. Far but part of your routine is held back. With the reuse model off, this collapses cleanly to plain distance, so behavior stays predictable.

6. It accounts for who the player is

A builder hauling materials, a miner deep underground, and an explorer crossing biomes stress memory differently. An online classifier (Activity Sense) watches breaks, places, crafting, combat, and movement, and labels each player from a softmax over recent activity:

MINER LUMBERJACK FARMER BUILDER FIGHTER EXPLORER

That feeds a demand model that sets a per-player retention weight inside a global budget, so decisions favor the players who genuinely need the chunks. On larger hosts a policy bandit explores which view-scale policy works best per context, a holdout group stays untouched as a control, and a false-cut tracker plus reward feedback let the mod walk back a cut that hurt a high-demand player instead of repeating it.

7. It acts carefully, and on the right thread

Two failure modes matter for a memory mod: corrupting world state, and unloading too aggressively. LeanCore guards both:

World-thread affinity: every read or write of chunk stores, chunk trackers, or view radius runs on the owning world's thread. The background scheduler only orchestrates.
Probe gate: chunk unload stays off until a one-time capability probe (/leancore probe) confirms the engine hooks work.
Capped sweeps: unload is limited per pass, so it can never go on a dropping spree.
Visibility check: it only releases chunks no player's tracker can currently see.
Trim before drop, and roll back: under load it trims view distance before unloading, and reverts a change when the tier history shows it backfired.

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)	light governor, adaptive view, AFK reclaim, demand learning
STANDARD	a few friends	15s	adds Activity Sense, optional governor and learning
FULL	dedicated server	5s	full set, including policy bandit and holdout

LITE reads two pressure signals (heap tier and chunk saturation, meaning loaded chunks against the view budget) and only reclaims distant dormant zones once you have been away long enough.

What it deliberately does not do

Touch client FPS, GPU, or render performance. It is server heap only. Obviously, optimizing RAM usage can occasionally help stabilize or even boost FPS. But that's not guaranteed!
Change TPS or simulation behavior.
Ship surprising defaults: solo is conservative and the cinematic boost is opt-in.

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 chunk pressure, never below your floor, with rollback on bad cuts
Probe-gated, capped chunk unload that only releases chunks nobody can see
Activity Sense classifier and per-player demand weighting inside a global budget
Policy bandit, holdout, and reward feedback on STANDARD and FULL
Learning that persists across restarts (gzip snapshot with prune and TTL)
Always-on diagnostics: the server log alone explains what the mod did and why
Session savings report, admin HUD (opt-in), heatmap, zone pin, optional CRITICAL webhook

Installation

Download the latest LeanCore JAR from the Files tab
Place it in your server's mods/ folder (or %AppData%\Hytale\UserData\Mods\ on Windows)
Start the server. Config is created at mods/durkz_LeanCore/LeanCore.json
Run /leancore probe if you rely on chunk unload
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

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