LeanCore

Install, commands, config, and permissions for LeanCore.

---

Overview

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 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 the world, and chunk unload only starts after /leancore probe. Solo embedded runs profile LITE with a real memory governor, adaptive view, AFK reclaim, and on-by-default demand learning. STANDARD and FULL profiles add policy bandit, holdout, and full governor paths when enabled. As of 1.6.0 a per-player motion model drives predictive zone retention (unload biased away from where players head, current/predicted view never evicted) and a reuse-distance + survival model scales dormancy per zone. Includes Activity Sense, session heap reporting (/leancore savings), unload probe gate, dedicated bootstrap, always-on [diag] diagnostics, learning snapshot v8 (gzip + prune, v7 compatible), and world-thread-safe governor dispatch. Requires Hytale server >=0.5.6. Does not touch client FPS, GPU, or TPS.

---

Installation

1. Download LeanCore-1.7.0.jar from the CurseForge Files tab
2. Place the JAR in your server’s mods/ folder
3. Start the server. Config is generated at mods/durkz_LeanCore/LeanCore.json
4. Run /leancore probe if you rely on chunk unload (LITE or STANDARD/FULL)
5. Grant staff HUD/admin access (see Permissions below)
6. Run /leancore memory and /leancore status after about a minute

Singleplayer / local host: use default hudViewerGroups / hudAdminGroups (OP, Admin) or grant permission nodes with /perm.

---

Embedded host profiles

Players	Profile	Tick	What runs
1 (solo local)	LITE	30s (60s idle)	Lite governor, adaptive view, AFK unload, lite learning
1 + embeddedStandardProfile	STANDARD	15s	Local dogfood of govern/learning without FULL 5s tick
2–8 (friends)	STANDARD	15s	Classifier; govern/learning/HUD if enabled in config
9+ (dense local)	FULL	5s	Full runtime per config
Dedicated JVM	FULL	5s	Full runtime per config

Config: localHostMode: "AUTO" (default). Use "PASSIVE" to disable background runtime entirely. Set dedicatedServerMode: true on a dedicated JVM host.

Boot log (solo): LeanCore 1.7.0 setup (localHostMode=AUTO). and Runtime started profile=LITE. Friend joins → profile LITE -> STANDARD.

---

LITE profile (solo embedded)

Feature	Behavior
Adaptive view	100% in COMFORT until chunk or heap pressure; gentle cuts in WATCH; aggressive only in TIGHT/CRITICAL
Dual signals	JVM heap tier + chunk pressure (loaded / view budget)
Unload AFK	Dormant/frozen zones when idle; probe gate; no governEnabled required
Learning	liteLearningEnabled=true by default; demand shapes view cuts; no bandit in LITE
Tick budget	Heavy work on heap sample (~60s), world-thread dispatch

STANDARD/FULL: view-radius and chunk unload still require governEnabled, learningEnabled, and unloadEnabled as before.

---

Features

• Runtime profiles: LITE, STANDARD, FULL on embedded vs dedicated hosts
• LITE solo governor: adaptive view, zone demotion, AFK unload, demand learning
• 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, motionModelEnabled): per-player motion model biases unload away from a player’s heading; zones in the current or predicted view are never eviction candidates
• Reuse-distance + survival model (1.6, zoneReuseModelEnabled): learns revisited zones 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
• Cinematic view boost (1.6, motionViewRadiusBoostEnabled, opt-in): raises view distance for fast movers; off by default (per-tick view radius rewrites churn chunk loading on the current engine)
• Chunk unload: drops chunks in dormant/frozen zones when tiers require it; ranked by distance to a zone’s nearest chunk (AABB edge)
• Always-on diagnostics (diagnosticLogEnabled): startup/shutdown summaries and [diag] decision logs per profile
• Learning data: heap windows (60s / 15m / 24h), policy bandit (STANDARD/FULL), demand model, zone reuse stats; saved across restarts (schema v8)
• 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: unload blocked until /leancore probe passes when the gate is enabled
• Dedicated bootstrap: one-time preset on first dedicated boot
• Admin HUD (/leancore hud on): small heap/tier overlay. Off by default.
• Heatmap, zone pin, optional CRITICAL webhook

---

Commands

Main command: /leancore

Command	Access	Description
/leancore status	Everyone	Profile, preset, heap tier, lite flags, unload gate
/leancore memory	Everyone	Heap snapshot, tier, footprint
/leancore savings	Everyone	Session JVM heap, lite/standard governor state, zone/chunk actions
/leancore zones	Everyone	Dormancy map counters
/leancore learn	Everyone	Learning diagnostics; LITE shows demand model only
/leancore learn player	Everyone	Demand features, posterior, activity EMAs
/leancore probe	Everyone	API capability probe (S1–S5)
/leancore hud on	HUD viewers	Enable opt-in memory HUD overlay
/leancore hud off	HUD viewers	Disable HUD overlay
/leancore hud status	HUD viewers	HUD eligibility and toggle state
/leancore heatmap [limit]	Staff	Zone heatmap
/leancore zone pin	Staff	Pin current zone as HOT
/leancore zone unpin	Staff	Unpin current zone
/leancore zone pins	Staff	List pinned zones

/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

---

Permissions

LeanCore uses permission nodes and/or config group lists. Either path can grant access.

Permission	Description
durkz.leancore.hud	Toggle and view the opt-in memory HUD (/leancore hud …)
durkz.leancore.admin	Heatmap, zone pin/unpin/pins, and admin HUD tools

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

Config groups (default)

"hudViewerGroups": ["OP", "Admin"],
"hudAdminGroups": ["OP", "Admin"]

Quick setup with Hytale /perm

/perm group add OP durkz.leancore.admin

---

Configuration (LeanCore.json)

Path: mods/durkz_LeanCore/LeanCore.json

Key	Default	Description
enabled	true	Master enable
localHostMode	AUTO	AUTO, PASSIVE, or FULL on embedded host
governEnabled	false	STANDARD/FULL governor
learningEnabled	false	STANDARD/FULL learning
unloadEnabled	false	STANDARD/FULL policy chunk unload
unloadProbeGateEnabled	true	Block unload until /leancore probe passes
probePassedAtMs	0	Set when probe passes
embeddedStandardProfile	false	Solo embedded → STANDARD instead of LITE
dedicatedServerMode	false	Force FULL profile
liteMemoryGovernorEnabled	true	Solo lite governor
liteLearningEnabled	true	Solo demand model + persistence
liteViewRadiusEnabled	true	Adaptive view on solo
liteUnloadEnabled	true	AFK reclaim on solo
liteUnloadIdleSeconds	180	Idle before lite unload sweeps
liteViewPressureThreshold	0.85	COMFORT cap when chunk saturation high
motionModelEnabled	true	Per-player motion model + predictive retention
zoneReuseModelEnabled	true	Reuse-distance + survival model; per-zone dormancy thresholds
motionViewRadiusBoostEnabled	false	Opt-in cinematic view boost for fast movers
diagnosticLogEnabled	true	Always-on [diag] session/decision logs
dormantAfterMinutes	8	WARM → DORMANT idle time
frozenAfterMinutes	20	→ FROZEN idle time
gcHintEnabled	false	Experimental LITE idle GC nudge

Full key reference: see mod page config section or repo README.

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

HUD toggles per player: mods/durkz_LeanCore/hud.state.

---

Recommended

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

---

Verifying it works

1. Log should show LeanCore 1.7.0 setup (localHostMode=AUTO). and profile=LITE on solo
2. /leancore status: profile LITE, lite flags on, unload gate line when unload is enabled
3. /leancore savings: lite governor ON after ~60s on solo
4. Friend joins → log profile LITE -> STANDARD
5. Mine ore → /leancore learn player shows posterior=MINER and demand/viewScale
6. With unload enabled, run /leancore probe → gate opens and persists probePassedAtMs

What matters is server JVM heap, not client FPS or GPU.

---

License

MIT License. Copyright (c) 2026 DurkzPRG