LeanCore

Install, commands, config, and permissions for LeanCore.

---

Overview

LeanCore is a server-side memory governor for Hytale. It reads the heap left after each garbage collection (plus old gen after GC and its growth trend) and acts on that: it trims view and simulation radius under real pressure, keeps recently visited chunks loaded while there is spare heap so walking back does not reload them from disk, and brakes chunk streaming when memory is tight. The engine already unloads every chunk no player tracks after about 7.5 seconds; LeanCore never removes chunks itself. Solo embedded runs profile LITE; STANDARD and FULL add the full governor paths when enabled. Includes Activity Sense, session heap reporting (/leancore savings), dedicated bootstrap, always-on [diag] diagnostics, learning snapshot v9, and world-thread-safe dispatch. Requires Hytale server >=0.7.0. Does not touch client FPS, GPU, or TPS.

---

Installation

1. Download LeanCore-1.8.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. Grant staff HUD/admin access (see Permissions below)
5. 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), pressure check every 5s	Lite governor, adaptive view, retention, 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.8.0 setup (localHostMode=AUTO). and Runtime started profile=LITE. Friend joins → profile LITE -> STANDARD.

---

Memory tiers

Tier	Heap after GC (default)	What LeanCore does
COMFORT	under watchHeapRatio (0.70)	full view, chunk retention active
WATCH	from 0.70	gentle view trims, held chunks released
TIGHT	from tightHeapRatio (0.82)	stronger trims, smaller simulation radius, chunk rate brake
CRITICAL	from criticalHeapRatio (0.90)	most aggressive trims, harder brake, optional webhook

Old gen is read after GC too, so dead chunk data waiting for collection does not count. Raw heap alone only means CRITICAL at 97%. A climbing live set can raise the tier early. Changes need two readings to confirm, policy changes are spaced by policyChangeMinIntervalSec, and giving view back is undone if the heap climbs right after. A cut is never undone just because the heap kept rising.

---

Chunk retention

When a chunk leaves every player’s view the engine unloads it about 7.5 seconds later, whatever the heap looks like. While the tier is COMFORT and the heap after GC stays under chunkRetentionMaxPostGcRatio (0.50), LeanCore takes an engine keep-loaded reference on such chunks, up to a budget sized from that headroom (chunkRetentionMbPerChunk, capped by chunkRetentionMaxChunks). The engine stops ticking held chunks.

• Player walks back: the chunk is already loaded, nothing is read from disk.
• Any tier above COMFORT: everything is released on the next check (every 2s).
• A held chunk is released after chunkRetentionMaxHoldSeconds (600).
• Chunks closest to an online player are taken first, and nothing farther than chunkRetentionMaxDistanceBlocks (1024) is held. Over budget, the farthest go first, 64 per check, so a short rise in the heap does not drop the whole trail. The trail of someone who left the area is the last thing kept.
• At most 64 new chunks per check, so the heap reading keeps up, and none once the heap after GC is within 5% of the ceiling.

LeanCore never removes chunks; releasing only drops the reference and the engine unloads as usual. /leancore status shows retention held=… budget=….

---

Chunk rate brake

On TIGHT and CRITICAL each player’s chunk send rate is capped at chunkRateBrakeTightPerSecond (512) and chunkRateBrakeCriticalPerSecond (192) sections per second; COMFORT and WATCH restore the engine’s own rate. It only ever lowers the rate. Skipped while QuantumHy is loaded, or when chunkThroughputGovernanceEnabled is on.

---

Working with QuantumHy

With both mods installed, QuantumHy takes the client view radius and the chunk send rate (its anti-stutter smoothing). 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. Setting chunkThroughputGovernanceEnabled: true hands the send rate to LeanCore instead.

---

Features

• Runtime profiles: LITE, STANDARD, FULL on embedded vs dedicated hosts
• Live-heap tiers: COMFORT, WATCH, TIGHT, CRITICAL from heap after GC, old gen after GC and growth trend; rollback when giving view back backfires
• Chunk retention (1.8): spare heap keeps recently left chunks loaded
• Chunk rate brake (1.8): slows streaming on TIGHT/CRITICAL; off with QuantumHy
• View-radius trims (LITE) and simulation radius trims under real pressure, never below liteMinClientViewRadius
• Cinematic view boost (motionViewRadiusBoostEnabled, opt-in): raises view distance for fast movers; off by default (per-tick view radius rewrites churn chunk loading on the current engine)
• Always-on diagnostics (diagnosticLogEnabled): startup/shutdown summaries and [diag] decision logs per profile
• Learning data: heap windows (60s / 15m / 24h), demand model, zone reuse stats; saved across restarts (schema v9)
• Activity Sense: online softmax classifier (MINER, LUMBERJACK, FARMER, BUILDER, FIGHTER, EXPLORER)
• Session savings: /leancore savings reports JVM heap peak/baseline/delta and governor activity
• 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, tier, pressure line (heap after GC, old gen, allocation, GC time, trend), retention line
/leancore memory	Everyone	Heap snapshot, tier, footprint
/leancore savings	Everyone	Session JVM heap and governor state
/leancore zones	Everyone	Zone counters
/leancore learn	Everyone	Learning diagnostics
/leancore learn player	Everyone	Demand features, posterior, activity EMAs
/leancore probe	Everyone	API capability probe (S1–S5), diagnostic only
/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
embeddedStandardProfile	false	Solo embedded → STANDARD instead of LITE
dedicatedServerMode	false	Force FULL profile
dedicatedViewRadiusGraceSeconds	600	Dedicated hosts: no view-radius cuts for this long after start
watchHeapRatio	0.70	WATCH threshold, heap after GC
tightHeapRatio	0.82	TIGHT threshold, heap after GC
criticalHeapRatio	0.90	CRITICAL threshold, heap after GC
liteMemoryGovernorEnabled	true	Solo lite governor
liteLearningEnabled	true	Solo demand model + persistence
liteViewRadiusEnabled	true	Adaptive view on solo
liteMinClientViewRadius	8	Never trim view below this
liteViewPressureThreshold	0.85	COMFORT cap when chunk saturation is high
chunkRetentionEnabled	true	Keep recently left chunks loaded while there is spare heap
chunkRetentionMaxPostGcRatio	0.50	Ceiling for heap after GC (kept below watchHeapRatio). New holds stop 5% under it; above it the farthest go first, 64 per check
chunkRetentionMbPerChunk	1.0	Heap estimate per held chunk for the budget
chunkRetentionMaxChunks	2048	Hard cap on held chunks
chunkRetentionMaxHoldSeconds	600	Release a held chunk after this long
chunkRetentionMaxDistanceBlocks	1024	Hold nearest-first; nothing farther than this from an online player
chunkRateBrakeEnabled	true	Brake chunk streaming on TIGHT/CRITICAL
chunkRateBrakeTightPerSecond	512	Sections/s cap per player on TIGHT
chunkRateBrakeCriticalPerSecond	192	Sections/s cap per player on CRITICAL
chunkThroughputGovernanceEnabled	false	Hand the send rate to LeanCore’s tier-scaled throughput (QuantumHy then yields)
motionModelEnabled	true	Per-player motion model
zoneReuseModelEnabled	true	Reuse-distance + survival model per zone
motionViewRadiusBoostEnabled	false	Opt-in cinematic view boost for fast movers
diagnosticLogEnabled	true	Always-on [diag] session/decision logs
checkForUpdates	true	Notify ops/admins when a newer JAR is published
gcHintEnabled	false	Experimental LITE idle GC nudge

No longer used since 1.8.0, kept so old configs load: unloadEnabled, liteUnloadEnabled, liteUnloadIdleSeconds, unloadProbeGateEnabled, probePassedAtMs.

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

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

---

Recommended

• Solo / local: keep localHostMode: AUTO. 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 and leave chunkThroughputGovernanceEnabled off.
• 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.8.0 setup (localHostMode=AUTO). and profile=LITE on solo
2. /leancore status: profile LITE, a pressure= line and a retention on held=… budget=… line
3. Walk away from spawn and stop: held goes up while the tier stays COMFORT
4. Friend joins → log profile LITE -> STANDARD
5. Mine ore → /leancore learn player shows posterior=MINER and demand/viewScale

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

---

License

MIT License. Copyright (c) 2026 DurkzPRG