LeanCore

LeanCore es un gobernador de memoria del lado del servidor para Hytale. Lee cuánto heap está realmente en uso tras cada garbage collection y actúa sobre eso: recorta la vista y el radio de simulación cuando la memoria aprieta de verdad, usa el heap sobrante para mantener cargados los chunks visitados hace poco (volver por el mismo camino no los relee del disco) y frena el streaming de chunks bajo presión real.

En mundos locales / solo, LeanCore usa el profile LITE. Cuando entran amigos, pasa a STANDARD. Los servidores dedicados usan FULL.

No toca FPS, GPU ni TPS del cliente.

Requiere servidor Hytale >=0.7.0. Tras instalar, ejecuta /leancore status con el servidor encendido alrededor de un minuto.

Por qué existe

El motor ya descarga cualquier chunk que ningún jugador ve, unos 7,5 segundos después de salir de la vista. Dos cosas no hace:

• Juzga la memoria por el heap bruto, que incluye la basura que espera la próxima recolección. El heap bruto oscila entre 40% y 90% en un servidor sano, así que todo lo que reacciona a él recorta sin motivo.
• Tira chunks aunque sobre heap. Vuelve por donde viniste y cada chunk se lee otra vez del disco.

LeanCore cubre esos dos huecos.

Medido

Release 0.7.0 de Hytale, perfil dedicado (FULL), heap de 6 GB. Cuatro exploradores virtuales salen del spawn en direcciones distintas a 20 bloques/s y generan terreno nuevo todo el tiempo, mientras un jugador guionizado vuela 600 bloques, espera 90s y vuelve. Servidor sin mods contra LeanCore 1.8.0, mismo mundo y misma ruta.

	sin mod	LeanCore 1.8.0
Tick del mundo, media	19,6 ms	13,4 ms (-32%)
Tick del mundo, p95	44,8 ms	35,1 ms (-22%)
Peor tick	1440 ms	299 ms (-79%)
Tiempo total en pausas de GC	7,3 s	5,0 s (-31%)
Pausa de GC más larga	1194 ms	201 ms (-83%)
Heap tras GC, p95	6071 MB	4906 MB (-19%)
Pico del heap tras GC	99,99% del máximo	83% del máximo

Sin LeanCore el heap tras GC llegó al 99,99% del máximo, por encima del 85% en el que el motor empieza su propia descarga de emergencia. Con él, el pico se quedó en el 83%.

El coste: el radio de vista promedió 16 chunks en lugar de 24 (mínimo 12). Cuando la vista vuelve en el vuelo de regreso, la zona que se había soltado carga de nuevo, así que la vuelta leyó un 24% más de chunks del disco y su tick fue un 17% más lento. LeanCore usó el 0,42% de la CPU del servidor. Una prueba por variante; tu mundo será distinto.

Solo, retención de chunks

Pre-release de Hytale 0.7: solo, heap de 3 GB, el mismo vuelo guionizado, la build anterior a la retención de chunks contra la 1.8.0.

	antes	1.8.0
Chunks recargados del disco en la vuelta	1203	653 (-46%)
Tick del mundo en la vuelta	12,5 ms	10,9 ms (-13%)
Radio de vista al entrar	recortado a 8 por una falsa alarma del heap bruto	mantenido en 10
Cambios de policy en la prueba	13	5

El coste: más heap en uso durante la prueba (limitado al 50% tras el GC) y cerca de un 0,16% más del tiempo en pausas de GC. Una prueba por build; tu mundo será distinto.

Cómo decide LeanCore

         cada 5s en solo, cada tick del gobernador en servidores
                                   │
       heap tras GC  +  old gen tras GC  +  tendencia de subida
                                   │
        ┌──────────────┬───────────┴───────────┬──────────────┐
        ▼              ▼                       ▼              ▼
     COMFORT         WATCH                   TIGHT         CRITICAL
  vista completa   recorte suave        recorte mayor    recorte máximo
  retiene chunks   suelta chunks        suelta chunks    suelta chunks
   de sobra         retenidos          + frena la carga  + frena más

Retención de chunks

   un chunk sale de la vista de todos los jugadores
                 │
                 ▼
   el motor lo descargaría en ~7,5s
                 │
   COMFORT y heap tras GC bajo 45%?  ── no ──►  el motor lo descarga
                 │ sí
                 ▼
   LeanCore lo retiene (referencia keep-loaded del motor; deja de tickear)
                 │
   el jugador vuelve           ──►  ya cargado, sin leer el disco
   heap tras GC sobre 50%      ──►  se sueltan los más lejanos, 64 cada 2s
   presión, o pasaron 10 min   ──►  se suelta, el motor lo descarga normal

Cómo piensa LeanCore

1. Lee el heap que de verdad se queda

Justo después de cada garbage collection la JVM informa lo que sobrevivió. Ese número, más el old gen tras GC y su tendencia, es lo que LeanCore llama presión. Tiers por defecto:

Tier	Heap tras GC	Qué hace LeanCore
COMFORT	menos de 70%	vista completa, retiene chunks de sobra
WATCH	70% o más	recortes suaves de vista, suelta chunks retenidos
TIGHT	82% o más	recortes mayores, radio de simulación menor, frena la carga de chunks
CRITICAL	90% o más	recortes máximos, freno más fuerte, webhook opcional

El heap bruto por sí solo solo cuenta como CRITICAL al 97%, el punto en que la memoria se acaba de verdad. Un heap que no deja de subir puede cambiar de tier antes de cruzar la línea.

2. Reacciona rápido y confirma antes de actuar

En solo la comprobación de presión corre cada 5 segundos y despierta al gobernador al momento cuando sube el tier. Un cambio necesita dos lecturas para confirmarse, los cambios de policy se espacian, y si el heap sube justo después de devolver la vista, el recorte vuelve.

3. Usa el heap sobrante en vez de desperdiciarlo

Cuando un chunk sale de la vista de todos los jugadores, el motor lo tira unos segundos después, esté como esté el heap. Mientras el tier es COMFORT y el heap tras GC está bajo el 45%, LeanCore mantiene un presupuesto de esos chunks cargados con la propia referencia keep-loaded del motor. El motor deja de tickearlos, así que cuestan memoria, no CPU. Al volver ya están ahí. Si el heap tras GC pasa del 50%, se sueltan primero los más lejanos, 64 cada 2 segundos, para que una subida corta no tire todo el camino. Cualquier tier de presión los suelta todos en la siguiente comprobación, y LeanCore nunca elimina un chunk por su cuenta.

4. Frena la carga solo cuando la memoria lo pide

En TIGHT y CRITICAL la tasa de envío de chunks de cada jugador se limita (512 y 192 secciones por segundo por defecto), lo que sigue el ritmo de caminar y volar pero evita que las ráfagas de entrada y teletransporte caigan sobre un heap lleno. COMFORT y WATCH devuelven la tasa del propio motor.

5. Tiene en cuenta quién es el jugador

Un clasificador online (Activity Sense) etiqueta a cada jugador por su actividad reciente: MINER LUMBERJACK FARMER BUILDER FIGHTER EXPLORER. Eso alimenta un modelo de demanda que decide cuánto se recorta la vista de cada jugador dentro de un presupuesto global.

6. Actúa en el hilo correcto

Toda lectura o escritura de chunk stores, chunk trackers o radio de vista corre en el hilo del mundo dueño. El scheduler de fondo solo orquesta.

Con QuantumHy

LeanCore y QuantumHy funcionan solos o juntos. Con los dos instalados, QuantumHy toma el radio de vista del cliente y la tasa de envío de chunks (su suavizado anti-stutter), y 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.

Profiles de runtime

LeanCore se ajusta al host solo, por número de jugadores, sin interruptor manual:

Profile	Cuándo	Tick	Qué corre
LITE	mundo solo embebido	30s (60s inactivo), presión cada 5s	gobernador ligero, vista adaptativa, retención, aprendizaje de demanda
STANDARD	algunos amigos	15s	añade Activity Sense, gobernador y aprendizaje opcionales
FULL	servidor dedicado	5s	conjunto completo

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 la simulación.
• Eliminar chunks. Descargar es trabajo del motor; LeanCore solo decide cuánto tiempo los mantiene el heap sobrante.
• Recortar por basura. Los picos del heap bruto entre recolecciones se ignoran hasta que el heap está de verdad cerca del límite.

Funcionalidades

• Profiles de runtime: LITE solo, STANDARD amigos, FULL dedicado (localHostMode: AUTO)
• Tiers por heap real: COMFORT, WATCH, TIGHT, CRITICAL a partir del heap tras GC, old gen tras GC y la tendencia; rollback cuando devolver la vista sale mal
• Retención de chunks (1.8, chunkRetentionEnabled): el heap sobrante mantiene cargados los chunks recién dejados y volver no lee el disco
• Freno de chunks (1.8, chunkRateBrakeEnabled): frena el streaming en TIGHT/CRITICAL; apagado mientras QuantumHy está cargado
• Recortes de radio de vista (LITE) y de radio de simulación bajo presión real, nunca por debajo de liteMinClientViewRadius
• Activity Sense: clasificador softmax online (MINER, LUMBERJACK, FARMER, BUILDER, FIGHTER, EXPLORER) que alimenta la demanda por jugador
• Datos de aprendizaje: ventanas de heap, modelo de demanda, estadísticas de reuso de zonas; se guardan entre reinicios (schema v9)
• Session savings: /leancore savings muestra pico/base/delta del heap JVM y actividad del gobernador
• Diagnóstico siempre activo (diagnosticLogEnabled): resúmenes de inicio/cierre y logs [diag] de decisiones directamente en el log del servidor
• Avisos de actualización para ops/admins cuando sale un JAR nuevo (desactivar: checkForUpdates)
• HUD de admin (/leancore hud on): pequeño overlay de heap/tier. Apagado por defecto.
• Heatmap, zone pin, webhook opcional en CRITICAL

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 (o %AppData%\Hytale\UserData\Mods\ en Windows)
3. Inicia el servidor. La config se crea en mods/durkz_LeanCore/LeanCore.json
4. Ejecuta /leancore status tras un minuto aproximadamente

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, liteLearningEnabled, chunkRetentionEnabled, chunkRateBrakeEnabled, watchHeapRatio, tightHeapRatio, criticalHeapRatio, diagnosticLogEnabled, governEnabled, learningEnabled, embeddedStandardProfile, dedicatedServerMode.

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

Permisos

• Quien ve el HUD: grupos en hudViewerGroups y/o durkz.leancore.hud
• Heatmap, zone pin y diagnóstico de webhook (admin): hudAdminGroups y/o durkz.leancore.admin

Recomendado

• Solo / local: localHostMode: AUTO (por defecto). 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; se reparten el trabajo solos.
• El log de arranque debe mostrar profile=LITE en solo y LITE -> STANDARD cuando entra un amigo.

Licencia

MIT License