LeanCore

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.

On local / solo worlds, LeanCore runs profile LITE: a lightweight memory governor with adaptive view-radius, AFK chunk reclaim, and on-by-default demand learning. When friends join, profile STANDARD kicks in. Dedicated servers get profile FULL.

Does not touch client FPS, GPU, or TPS.

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

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.

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

2. The map is grouped into zones with a temperature

LeanCore does not reason about single chunks. It groups the map into zones and tracks a temperature: 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

Only DORMANT and FROZEN zones that are also far from every player are ever candidates. This 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. 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 protects where you are going

A player sprinting toward fresh terrain needs it kept before arrival. 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 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 on the current engine. Reasonable to enable on a dedicated host or a strong machine; leave it off on constrained setups.

5. It learns which zones matter to you

Your base, your mine, the path between them: you keep returning. A spot you crossed once, you never see again. LeanCore keeps a reuse-distance and survival model per zone, turned into a revisit score that stretches or shrinks that zone’s cooldowns. When something must go, eviction is ranked by how far the zone is and how unlikely it is to be revisited. With the reuse model off, this collapses cleanly to plain distance.

6. It accounts for who the player is

An online classifier (Activity Sense) 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. On larger hosts a policy bandit explores which view-scale policy works best, a holdout group stays untouched as a control, and reward feedback lets the mod walk back a cut that hurt a high-demand player.

7. It acts carefully, and on the right thread

• 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

What it deliberately does not do

• Touch client FPS, GPU, or render performance. It is server heap only.
• Change TPS or simulation behavior.
• Unload a chunk a player can see, or act aggressively while the heap is at COMFORT.
• Ship surprising defaults: solo is conservative and the cinematic boost is opt-in.

Features

• Runtime profiles: LITE solo, STANDARD friends, FULL dedicated (localHostMode: AUTO)
• LITE solo governor: adaptive view, zone demotion, AFK unload, demand learning; 30s tick (60s when idle)
• Heap tiers: COMFORT, WATCH, TIGHT, CRITICAL. Rolls back if a cut causes problems.
• Zone dormancy: HOT near players. Empty wilderness steps down WARM, DORMANT, FROZEN on timers you set.
• Predictive retention (1.6): per-player motion model biases unload away from where players are heading; zones in the current or predicted view are never eviction candidates
• Reuse-distance + survival model (1.6, zoneReuseModelEnabled): learns which zones get revisited and scales dormancy thresholds per zone
• Retention budget: global cap with per-player weight from activity scores
• View-radius cuts: throttled when heap or chunk pressure is high (LITE on solo; STANDARD/FULL on multi-player / dedicated)
• Chunk unload: drops chunks in dormant/frozen zones when tiers require it; probe gate blocks unload until /leancore probe passes
• Learning data: heap windows, policy bandit (STANDARD/FULL), demand model, zone reuse stats; v8 gzip snapshot (v7 compatible) with player prune/TTL
• LITE learning: demand model shapes view cuts on solo; no bandit or holdout in LITE
• Activity Sense: online softmax classifier (MINER, LUMBERJACK, FARMER, BUILDER, FIGHTER, EXPLORER)
• Session savings: /leancore savings reports JVM heap peak/baseline/delta and lite or standard governor activity
• Unload probe gate: LITE and STANDARD/FULL unload blocked until /leancore probe passes when the gate is enabled
• Dedicated bootstrap: one-time preset on first dedicated boot
• Cinematic view boost (1.6, motionViewRadiusBoostEnabled, opt-in): smoothly raises view distance for fast movers. Off by default since rewriting view radius each tick churns chunk loading on the current engine.
• Always-on diagnostics (diagnosticLogEnabled): startup/shutdown summaries and [diag] decision logs explain what the mod did and why, straight from the server log
• Admin HUD (/leancore hud on): small heap/tier overlay. Off by default.
• Heatmap, zone pin, optional CRITICAL webhook

Installation

1. Download LeanCore-1.7.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 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 admin commands, permissions, and full config reference: documentation

Config

Runtime file: mods/durkz_LeanCore/LeanCore.json

Key toggles: localHostMode, liteMemoryGovernorEnabled, liteViewRadiusEnabled, liteUnloadEnabled, liteLearningEnabled, motionModelEnabled, zoneReuseModelEnabled, motionViewRadiusBoostEnabled, diagnosticLogEnabled, governEnabled, learningEnabled, unloadEnabled, unloadProbeGateEnabled, embeddedStandardProfile, dedicatedServerMode.

Learning snapshot: mods/durkz_LeanCore/learning.state.gz (schema v8, gzip; v7 migrates on first flush).

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 and learning are on by default.
• Dedicated or friends: enable governEnabled, learningEnabled, and unloadEnabled as needed; run /leancore probe before policy unload.
• Boot log should show profile=LITE on solo and LITE -> STANDARD when a friend joins.

License

MIT License