LeanCore

Instalación, comandos, config y permisos de LeanCore.

---

Resumen

LeanCore es un gobernador de memoria del lado del servidor para Hytale. Lee el heap que queda tras cada garbage collection (más el old gen tras GC y su tendencia) y actúa sobre eso: recorta la vista y el radio de simulación bajo presión real, mantiene cargados los chunks visitados hace poco mientras sobra heap (volver no relee del disco) y frena el streaming de chunks cuando la memoria aprieta. El motor ya descarga todo chunk que ningún jugador sigue tras unos 7,5 segundos; LeanCore nunca elimina chunks por su cuenta. El solo embebido usa el profile LITE; STANDARD y FULL añaden los caminos completos del gobernador cuando se activan. Incluye Activity Sense, informe de heap de la sesión (/leancore savings), bootstrap dedicado, diagnóstico [diag] siempre activo, snapshot de aprendizaje v9 y dispatch seguro en el hilo del mundo. Requiere servidor Hytale >=0.7.0. No toca FPS, GPU ni TPS del cliente.

---

Instalación

1. Descarga LeanCore-1.8.0.jar desde la pestaña Files de CurseForge
2. Pon el JAR en la carpeta mods/ del servidor
3. Inicia el servidor. La config se genera en mods/durkz_LeanCore/LeanCore.json
4. Da acceso de HUD/admin al staff (ver Permisos abajo)
5. Ejecuta /leancore memory y /leancore status tras un minuto aproximadamente

Un jugador / host local: usa los hudViewerGroups / hudAdminGroups por defecto (OP, Admin) o da los nodos de permiso con /perm.

---

Profiles en host embebido

Jugadores	Profile	Tick	Qué corre
1 (solo local)	LITE	30s (60s inactivo), presión cada 5s	Gobernador lite, vista adaptativa, retención, aprendizaje lite
1 + embeddedStandardProfile	STANDARD	15s	Prueba local de govern/learning sin el tick de 5s de FULL
2–8 (amigos)	STANDARD	15s	Clasificador; govern/learning/HUD si están activos en la config
9+ (local lleno)	FULL	5s	Runtime completo según la config
JVM dedicada	FULL	5s	Runtime completo según la config

Config: localHostMode: "AUTO" (por defecto). Usa "PASSIVE" para apagar el runtime de fondo. Usa dedicatedServerMode: true en una JVM dedicada.

Log de arranque (solo): LeanCore 1.8.0 setup (localHostMode=AUTO). y Runtime started profile=LITE. Entra un amigo → profile LITE -> STANDARD.

---

Tiers de memoria

Tier	Heap tras GC (por defecto)	Qué hace LeanCore
COMFORT	bajo watchHeapRatio (0.70)	vista completa, retención de chunks activa
WATCH	desde 0.70	recortes suaves de vista, chunks retenidos se sueltan
TIGHT	desde tightHeapRatio (0.82)	recortes mayores, radio de simulación menor, freno de chunks
CRITICAL	desde criticalHeapRatio (0.90)	recortes máximos, freno más fuerte, webhook opcional

El old gen también se lee tras el GC, así que los datos de chunks muertos que esperan recolección no cuentan. El heap bruto por sí solo solo es CRITICAL al 97%. Un heap vivo que sube puede elevar el tier antes. Los cambios necesitan dos lecturas para confirmarse, los cambios de policy se espacian con policyChangeMinIntervalSec, y devolver la vista se deshace si el heap sube justo después. Un recorte nunca se deshace solo porque el heap siguió subiendo.

---

Retención de chunks

Cuando un chunk sale de la vista de todos los jugadores, el motor lo descarga unos 7,5 segundos después, esté como esté el heap. Mientras el tier es COMFORT y el heap tras GC se mantiene bajo chunkRetentionMaxPostGcRatio (0.50), LeanCore toma una referencia keep-loaded del motor sobre esos chunks, hasta un presupuesto calculado a partir de ese margen (chunkRetentionMbPerChunk, limitado por chunkRetentionMaxChunks). El motor deja de tickear los chunks retenidos.

• El jugador vuelve: el chunk ya está cargado, no se lee nada del disco.
• Cualquier tier por encima de COMFORT: todo se suelta en la siguiente comprobación (cada 2s).
• Un chunk retenido se suelta tras chunkRetentionMaxHoldSeconds (600).
• Los chunks más cercanos a un jugador conectado entran primero, y nada más lejos que chunkRetentionMaxDistanceBlocks (1024) se retiene. Por encima del presupuesto, los más lejanos salen primero, 64 por comprobación, para que una subida corta del heap no suelte todo el camino. El rastro de quien dejó la zona es lo último que se queda.
• Como máximo 64 chunks nuevos por comprobación, para que la lectura del heap siga el ritmo, y ninguno cuando el heap tras GC está a menos del 5% del techo.

LeanCore nunca elimina chunks; soltar solo libera la referencia y el motor descarga como siempre. /leancore status muestra retention held=… budget=….

---

Freno de chunks

En TIGHT y CRITICAL la tasa de envío de chunks de cada jugador se limita a chunkRateBrakeTightPerSecond (512) y chunkRateBrakeCriticalPerSecond (192) secciones por segundo; COMFORT y WATCH devuelven la tasa del propio motor. Solo baja, nunca sube. Se omite mientras QuantumHy está cargado o con chunkThroughputGovernanceEnabled activado.

---

Convivencia con QuantumHy

Con los dos mods instalados, QuantumHy toma el radio de vista del cliente y la tasa de envío de chunks (su suavizado anti-stutter). LeanCore se queda con la memoria: tiers, radio de simulación y retención de chunks. QuantumHy lee el tier de LeanCore y aprieta su radio de render en TIGHT o CRITICAL. El freno de chunks de LeanCore queda apagado mientras QuantumHy está cargado. Activar chunkThroughputGovernanceEnabled: true le da la tasa de envío a LeanCore.

---

Funcionalidades

• Profiles de runtime: LITE, STANDARD, FULL en host embebido o dedicado
• Tiers por heap real: COMFORT, WATCH, TIGHT, CRITICAL por heap tras GC, old gen tras GC y tendencia; rollback cuando devolver la vista sale mal
• Retención de chunks (1.8): el heap sobrante mantiene cargados los chunks recién dejados
• Freno de chunks (1.8): frena el streaming en TIGHT/CRITICAL; apagado con QuantumHy
• Recortes de radio de vista (LITE) y de radio de simulación bajo presión real, nunca por debajo de liteMinClientViewRadius
• Boost cinematográfico de vista (motionViewRadiusBoostEnabled, opcional): aumenta la distancia de vista para quien se mueve rápido; apagado por defecto (reescribir el radio de vista cada tick agita la carga de chunks en el motor actual)
• Diagnóstico siempre activo (diagnosticLogEnabled): resúmenes de inicio/cierre y logs [diag] de decisión por profile
• Datos de aprendizaje: ventanas de heap (60s / 15m / 24h), modelo de demanda, estadísticas de reuso de zonas; se guardan entre reinicios (schema v9)
• Activity Sense: clasificador softmax online (MINER, LUMBERJACK, FARMER, BUILDER, FIGHTER, EXPLORER)
• Session savings: /leancore savings muestra pico/base/delta del heap JVM y actividad del gobernador
• Bootstrap dedicado: preset único en el primer arranque dedicado
• HUD de admin (/leancore hud on): pequeño overlay de heap/tier. Apagado por defecto.
• Heatmap, zone pin, webhook opcional en CRITICAL

---

Comandos

Comando principal: /leancore

Comando	Acceso	Descripción
/leancore status	Todos	Profile, tier, línea de presión (heap tras GC, old gen, asignación, tiempo de GC, tendencia), línea de retención
/leancore memory	Todos	Snapshot del heap, tier, footprint
/leancore savings	Todos	Heap JVM de la sesión y estado del gobernador
/leancore zones	Todos	Contadores de zonas
/leancore learn	Todos	Diagnóstico de aprendizaje
/leancore learn player	Todos	Features de demanda, posterior, EMAs de actividad
/leancore probe	Todos	Probe de capacidad de la API (S1–S5), solo diagnóstico
/leancore hud on	Quien ve el HUD	Activa el overlay opcional de memoria
/leancore hud off	Quien ve el HUD	Desactiva el overlay
/leancore hud status	Quien ve el HUD	Elegibilidad y estado del HUD
/leancore heatmap [limit]	Staff	Heatmap de zonas
/leancore zone pin	Staff	Fija la zona actual como HOT
/leancore zone unpin	Staff	Quita la fijación de la zona actual
/leancore zone pins	Staff	Lista las zonas fijadas

/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

---

Permisos

LeanCore usa nodos de permiso y/o listas de grupos en la config. Cualquiera de los dos da acceso.

Permiso	Descripción
durkz.leancore.hud	Activar y ver el HUD opcional de memoria (/leancore hud …)
durkz.leancore.admin	Heatmap, zone pin/unpin/pins y herramientas de HUD de admin

• Quien ve el HUD: grupos en hudViewerGroups y/o durkz.leancore.hud
• Heatmap y zone pin (admin): hudAdminGroups y/o durkz.leancore.admin

Grupos en la config (por defecto)

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

Configuración rápida con /perm de Hytale

/perm group add OP durkz.leancore.admin

---

Configuración (LeanCore.json)

Ruta: mods/durkz_LeanCore/LeanCore.json

Clave	Por defecto	Descripción
enabled	true	Interruptor general
localHostMode	AUTO	AUTO, PASSIVE o FULL en host embebido
governEnabled	false	Gobernador STANDARD/FULL
learningEnabled	false	Aprendizaje STANDARD/FULL
embeddedStandardProfile	false	Solo embebido → STANDARD en vez de LITE
dedicatedServerMode	false	Fuerza el profile FULL
dedicatedViewRadiusGraceSeconds	600	Host dedicado: sin recortes de vista durante este tiempo tras el inicio
watchHeapRatio	0.70	Umbral de WATCH, heap tras GC
tightHeapRatio	0.82	Umbral de TIGHT, heap tras GC
criticalHeapRatio	0.90	Umbral de CRITICAL, heap tras GC
liteMemoryGovernorEnabled	true	Gobernador lite en solo
liteLearningEnabled	true	Modelo de demanda + persistencia en solo
liteViewRadiusEnabled	true	Vista adaptativa en solo
liteMinClientViewRadius	8	Nunca recorta la vista por debajo de esto
liteViewPressureThreshold	0.85	Tope en COMFORT cuando la saturación de chunks es alta
chunkRetentionEnabled	true	Mantiene cargados los chunks recién dejados mientras sobra heap
chunkRetentionMaxPostGcRatio	0.50	Techo del heap tras GC (siempre bajo watchHeapRatio). Los nuevos se detienen un 5% por debajo; por encima, los más lejanos salen primero, 64 por comprobación
chunkRetentionMbPerChunk	1.0	Estimación de heap por chunk retenido para el presupuesto
chunkRetentionMaxChunks	2048	Tope de chunks retenidos
chunkRetentionMaxHoldSeconds	600	Suelta un chunk retenido tras este tiempo
chunkRetentionMaxDistanceBlocks	1024	Retiene del más cercano al más lejano; nada más allá de esta distancia de un jugador conectado
chunkRateBrakeEnabled	true	Frena el streaming de chunks en TIGHT/CRITICAL
chunkRateBrakeTightPerSecond	512	Tope de secciones/s por jugador en TIGHT
chunkRateBrakeCriticalPerSecond	192	Tope de secciones/s por jugador en CRITICAL
chunkThroughputGovernanceEnabled	false	Da la tasa de envío al throughput escalado por tier de LeanCore (QuantumHy entonces cede)
motionModelEnabled	true	Modelo de movimiento por jugador
zoneReuseModelEnabled	true	Modelo de reuso + supervivencia por zona
motionViewRadiusBoostEnabled	false	Boost cinematográfico de vista opcional
diagnosticLogEnabled	true	Logs [diag] de sesión/decisión siempre activos
checkForUpdates	true	Avisa a ops/admins cuando sale un JAR nuevo
gcHintEnabled	false	Empujón experimental de GC en LITE inactivo

Sin uso desde la 1.8.0, se mantienen para que las configs viejas carguen: unloadEnabled, liteUnloadEnabled, liteUnloadIdleSeconds, unloadProbeGateEnabled, probePassedAtMs.

Snapshot de aprendizaje: mods/durkz_LeanCore/learning.state.gz (schema v9, gzip).

Estado del HUD por jugador: mods/durkz_LeanCore/hud.state.

---

Recomendado

• Solo / local: deja localHostMode: AUTO. Gobernador LITE, retención y aprendizaje vienen activados.
• Dedicado o con amigos: activa governEnabled y learningEnabled. Más heap significa más espacio para la retención.
• Con QuantumHy: instala los dos y deja chunkThroughputGovernanceEnabled apagado.
• Usa /leancore savings tras 15+ minutos en hosts dedicados para ver el delta del heap y los contadores del gobernador.

---

Cómo comprobar que funciona

1. El log debe mostrar LeanCore 1.8.0 setup (localHostMode=AUTO). y profile=LITE en solo
2. /leancore status: profile LITE, una línea pressure= y una línea retention on held=… budget=…
3. Aléjate del spawn y para: held sube mientras el tier sigue en COMFORT
4. Entra un amigo → log profile LITE -> STANDARD
5. Mina mineral → /leancore learn player muestra posterior=MINER y demand/viewScale

Lo que importa es el heap JVM del servidor, no FPS ni GPU del cliente.

---

Licencia

MIT License. Copyright (c) 2026 DurkzPRG