LeanCore

LeanCore está hecho para reducir el uso de heap de la JVM en servidores Hytale. A medida que los jugadores exploran, cada zona que tocan mantiene sus chunks y entidades residentes en memoria, y el engine es lento para liberarlos, así que el heap sube y se mantiene alto mucho después de que todos se han ido. LeanCore es la pieza que decide qué sigue cargado y qué se libera, modelando dónde están los jugadores, hacia dónde van y qué partes del mapa realmente vuelven a visitar. Cuánto libera depende de tu mundo, y la descarga de chunks solo se activa después de que ejecutas /leancore probe.

En mundos locales / solo, usa el perfil LITE: gobernador ligero con vista adaptativa, reclaim AFK de chunks y aprendizaje de demanda activado por defecto. Con amigos, pasa a STANDARD. En servidor dedicado, perfil FULL.

No afecta FPS, GPU ni TPS del cliente.

Requiere servidor Hytale >=0.5.6. Tras instalar, ejecuta /leancore status cuando el servidor lleve un minuto encendido.

Con vs sin LeanCore

Misma sesión en solitario, RAM del servidor a lo largo del tiempo. Sin el mod, cada zona que visitas queda residente y la heap solo sube hasta que reinicias. Con LeanCore, las zonas inactivas se enfrían y se liberan, así que la RAM sube bajo carga y luego baja.

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

Cómo decide LeanCore

Dos señales guían cada acción: qué tan ajustada está la memoria ahora, y si una zona sigue siendo necesaria. La escalera decide la intensidad; la comprobación por zona decide qué es seguro liberar.

Presión a acción

                           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

Mantener o liberar una zona

   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

Cómo piensa LeanCore

No es un temporizador que descarga chunks según un horario. Mantiene un pequeño modelo vivo de tu mundo y decide a partir de él.

1. La presión es relativa a tu propio servidor

Un heap al 70% es holgado en un host y el borde del bloqueo en otro, así que LeanCore no fija umbrales. Muestrea la razón de heap continuamente, construye una distribución móvil con el historial del propio servidor y clasifica la lectura actual en un tier:

Tier	Qué significa	Qué hace LeanCore
COMFORT	dentro del rango normal del servidor	se mantiene al margen, view radius completa
WATCH	por encima de la línea base usual	recortes suaves de vista, empieza a degradar zonas inactivas
TIGHT	memoria presionada	recortes más fuertes, descarga zonas dormidas lejanas
CRITICAL	cerca del límite	recortes y unload más agresivos, hint de GC y webhook opcionales

2. El mapa se agrupa en zonas con temperatura

LeanCore no razona sobre chunks aislados. Agrupa el mapa en zonas y sigue una temperatura: HOT -> WARM -> DORMANT -> FROZEN.

Estado	Significado	Elegible para unload
HOT	un jugador está dentro o cerca, o la zona está fijada	nunca
WARM	el último jugador acaba de salir	no
DORMANT	inactiva más allá de tu timer warm	sí, bajo TIGHT o peor
FROZEN	inactiva por mucho tiempo	sí

Solo zonas DORMANT y FROZEN que además están lejos de todo jugador llegan a ser candidatas. Eso distingue “nadie ha estado aquí en 20 minutos” de “el jugador salió un segundo”.

3. La distancia se mide con honestidad

Al comprobar cuán lejos está una zona de un jugador, mide hasta el borde de chunk más cercano de la zona, no su centro. Una zona dentro de la view distance de cualquier jugador más una región de margen nunca es candidata a unload. Esa línea es la diferencia entre recuperar memoria y causar pop-in.

4. Protege hacia dónde vas

Un jugador corriendo hacia terreno nuevo necesita que se mantenga antes de llegar. LeanCore corre un modelo de movimiento por jugador: velocidad suavizada, aceleración estimada, un valor de confianza y una posición proyectada unos segundos por delante. Ese punto previsto se vuelve un segundo ancla, así que la vista actual y la prevista quedan ambas fuera de alcance.

Un boost cinematográfico de vista, opcional, amplía la view distance para quien se mueve rápido. Viene desactivado por defecto: reescribir la view radius cada tick genera churn de carga en el engine actual. Razonable activarlo en un host dedicado o una máquina potente; déjalo apagado en setups limitados.

5. Aprende qué zonas te importan

Tu base, tu mina, el camino entre ellas: siempre vuelves. Un punto que cruzaste una vez, no lo vuelves a ver. LeanCore mantiene un modelo de reuse-distance y supervivencia por zona, convertido en un score de revisita que estira o encoge los cooldowns de esa zona. Cuando algo debe irse, la eviction se ordena por cuán lejos está la zona y cuán improbable es revisitarla. Con el modelo de reuse apagado, esto colapsa limpiamente a distancia pura.

6. Tiene en cuenta quién es el jugador

Un clasificador online (Activity Sense) etiqueta a cada jugador con un softmax sobre la actividad reciente: MINER LUMBERJACK FARMER BUILDER FIGHTER EXPLORER. Eso alimenta un demand model que fija un peso de retención por jugador dentro de un presupuesto global. En hosts más grandes un policy bandit explora qué política de escala de vista funciona mejor, un grupo holdout queda intacto como control, y el reward feedback deja que el mod deshaga un corte que perjudicó a un jugador de alta demanda.

7. Actúa con cuidado, y en el hilo correcto

• Afinidad de world-thread: toda lectura o escritura de chunk stores, chunk trackers o view radius corre en el hilo del world dueño. El scheduler en segundo plano solo orquesta.
• Probe gate: el unload de chunks queda apagado hasta que un probe de capacidad único (/leancore probe) confirme que los hooks del engine funcionan.
• Sweeps limitados: el unload está limitado por pasada, así que nunca se va en una racha de drops.
• Chequeo de visibilidad: solo libera chunks que ningún tracker de jugador puede ver en ese momento.
• Recortar antes de soltar, y revertir: bajo carga, recorta view distance antes de descargar y revierte un cambio cuando el historial de tier muestra que salió mal.

Perfiles de runtime

LeanCore se dimensiona al host automáticamente, por número de jugadores, sin interruptor manual:

Perfil	Cuándo	Tick	Qué corre
LITE	mundo solo embebido	30s (60s idle)	gobernador ligero, vista adaptativa, reclaim AFK, demand learning
STANDARD	unos pocos amigos	15s	añade Activity Sense, gobernador y learning opcionales
FULL	servidor dedicado	5s	conjunto completo, incluido policy bandit y holdout

Lo que deliberadamente no hace

• Tocar FPS, GPU o rendimiento de render del cliente. Es solo heap del servidor.
• Cambiar TPS o el comportamiento de simulación.
• Descargar un chunk que un jugador ve, o actuar de forma agresiva con el heap en COMFORT.
• Traer defaults sorpresa: solo es conservador y el boost cinematográfico es opt-in.

Características

• Perfiles de runtime: LITE solo, STANDARD amigos, FULL dedicado (localHostMode: AUTO)
• Gobernador LITE en solo: vista adaptativa, degradación de zonas, unload AFK, aprendizaje de demanda; tick 30s (60s en idle)
• Tiers de heap: COMFORT, WATCH, TIGHT, CRITICAL. Rollback si un corte causa problemas.
• Dormancia de zonas: HOT cerca de jugadores. Zonas vacías bajan WARM, DORMANT, FROZEN según timers.
• Retención predictiva (1.6): el modelo de movimiento por jugador inclina el unload lejos de hacia dónde va el jugador; las zonas en la vista actual o prevista nunca son candidatas a unload
• Modelo de reuse-distance + supervivencia (1.6, zoneReuseModelEnabled): aprende qué zonas se revisitan y ajusta los umbrales de dormancia por zona
• Presupuesto de retención: tope global con peso por jugador según actividad
• Recortes de view-radius: bajo presión de heap o chunks (LITE en solo; STANDARD/FULL en multi-player / dedicado)
• Unload de chunks: zonas dormant/frozen cuando el tier lo exige; puerta de probe bloquea hasta que /leancore probe pase
• Datos de aprendizaje: ventanas de heap, bandit (STANDARD/FULL), demand model, stats de reuse de zona; snapshot v8 gzip (compatible con v7) con prune/TTL
• Aprendizaje LITE: demand model ajusta cortes de vista en solo; sin bandit ni holdout en LITE
• Activity Sense: clasificador softmax online (MINER, LUMBERJACK, FARMER, BUILDER, FIGHTER, EXPLORER)
• Session savings: /leancore savings reporta heap JVM y actividad del gobernador lite o standard
• Puerta de probe: unload LITE y STANDARD/FULL bloqueado hasta /leancore probe si la puerta está activa
• Bootstrap dedicado: preset único en el primer arranque dedicado
• Boost cinematográfico de vista (1.6, motionViewRadiusBoostEnabled, opt-in): sube la distancia de visión de forma suave para quien se mueve rápido. Desactivado por defecto porque reescribir el view radius cada tick genera churn de chunks en el engine actual.
• Diagnóstico siempre activo (diagnosticLogEnabled): resúmenes de inicio/cierre y logs de decisión [diag] explican qué hizo el mod y por qué, directo desde el log del servidor
• HUD admin (/leancore hud on): overlay heap/tier. Desactivado por defecto.
• Heatmap, zone pin, webhook CRITICAL opcional

Instalación

1. Descarga LeanCore-1.7.0.jar en la pestaña Files de CurseForge
2. Coloca el JAR en la carpeta mods/ del servidor (o %AppData%\Hytale\UserData\Mods\ en Windows)
3. Inicia el servidor. Config en mods/durkz_LeanCore/LeanCore.json
4. Ejecuta /leancore probe si dependes del unload de chunks
5. Ejecuta /leancore status tras un minuto de uptime

Comandos

Comando principal: /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

Comandos admin, permisos y config completa: documentación

Config

Archivo: mods/durkz_LeanCore/LeanCore.json

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

Snapshot de aprendizaje: mods/durkz_LeanCore/learning.state.gz (schema v8, gzip; v7 migra en el primer flush).

Permisos

• HUD: grupos en hudViewerGroups y/o durkz.leancore.hud
• Admin heatmap, zone pin: hudAdminGroups y/o durkz.leancore.admin

Recomendado

• Solo / local: localHostMode: AUTO (por defecto). Gobernador y aprendizaje LITE activados por defecto.
• Dedicado o amigos: activa governEnabled, learningEnabled y unloadEnabled según necesites; ejecuta /leancore probe antes del unload por política.
• El log de arranque debe mostrar profile=LITE en solo y LITE -> STANDARD cuando entra un amigo.

Licencia

MIT License