LeanCore

Instalação, comandos, config e permissões do LeanCore.

---

Visão geral

O LeanCore é um governador de memória server-side para Hytale. Ele lê a heap que sobra depois de cada garbage collection (mais o old gen pós-GC e a tendência de crescimento) e age em cima disso: corta view e raio de simulação sob pressão real, mantém chunks visitados há pouco carregados enquanto sobra heap (voltar não relê do disco) e freia o streaming de chunks quando a memória aperta. O engine já descarrega todo chunk que nenhum jogador acompanha depois de uns 7,5 segundos; o LeanCore nunca remove chunks por conta própria. O solo embutido roda profile LITE; STANDARD e FULL adicionam os caminhos completos do governador quando ligados. Inclui Activity Sense, relatório de heap da sessão (/leancore savings), bootstrap dedicado, diagnóstico [diag] sempre ligado, snapshot de learning v9 e dispatch seguro na thread do mundo. Requer servidor Hytale >=0.7.0. Não mexe em FPS, GPU ou TPS do cliente.

---

Instalação

1. Baixe LeanCore-1.8.0.jar na aba Files do CurseForge
2. Coloque o JAR na pasta mods/ do servidor
3. Inicie o servidor. A config é gerada em mods/durkz_LeanCore/LeanCore.json
4. Dê acesso de HUD/admin à staff (veja Permissões abaixo)
5. Rode /leancore memory e /leancore status depois de cerca de um minuto

Singleplayer / host local: use os hudViewerGroups / hudAdminGroups padrão (OP, Admin) ou dê os nodes de permissão com /perm.

---

Profiles no host embutido

Jogadores	Profile	Tick	O que roda
1 (solo local)	LITE	30s (60s parado), pressão a cada 5s	Governador lite, view adaptativa, retenção, learning lite
1 + embeddedStandardProfile	STANDARD	15s	Teste local de govern/learning sem o tick de 5s do FULL
2–8 (amigos)	STANDARD	15s	Classificador; govern/learning/HUD se ligados na config
9+ (local cheio)	FULL	5s	Runtime completo conforme a config
JVM dedicada	FULL	5s	Runtime completo conforme a config

Config: localHostMode: "AUTO" (padrão). Use "PASSIVE" para desligar o runtime de fundo. Use dedicatedServerMode: true numa JVM dedicada.

Log de boot (solo): LeanCore 1.8.0 setup (localHostMode=AUTO). e Runtime started profile=LITE. Amigo entra → profile LITE -> STANDARD.

---

Tiers de memória

Tier	Heap pós-GC (padrão)	O que o LeanCore faz
COMFORT	abaixo de watchHeapRatio (0.70)	view cheia, retenção de chunks ativa
WATCH	a partir de 0.70	cortes leves de view, chunks retidos soltos
TIGHT	a partir de tightHeapRatio (0.82)	cortes maiores, raio de simulação menor, freio de chunks
CRITICAL	a partir de criticalHeapRatio (0.90)	cortes máximos, freio mais forte, webhook opcional

O old gen também é lido depois do GC, então dados de chunk mortos esperando coleta não contam. A heap bruta sozinha só vira CRITICAL em 97%. Uma heap viva subindo pode elevar o tier antes. Mudanças precisam de duas leituras para confirmar, mudanças de policy são espaçadas por policyChangeMinIntervalSec, e devolver a view é desfeito se a heap sobe logo depois. Um corte nunca é desfeito só porque a heap continuou subindo.

---

Retenção de chunks

Quando um chunk sai da visão de todos os jogadores o engine descarrega ele uns 7,5 segundos depois, não importa como está a heap. Enquanto o tier é COMFORT e a heap pós-GC fica abaixo de chunkRetentionMaxPostGcRatio (0.50), o LeanCore pega uma referência keep-loaded do engine nesses chunks, até um orçamento calculado a partir dessa folga (chunkRetentionMbPerChunk, limitado por chunkRetentionMaxChunks). O engine para de tickar os chunks retidos.

• O jogador volta: o chunk já está carregado, nada é lido do disco.
• Qualquer tier acima de COMFORT: tudo é solto na próxima checagem (a cada 2s).
• Um chunk retido é solto depois de chunkRetentionMaxHoldSeconds (600).
• Os chunks mais perto de um jogador online entram primeiro, e nada além de chunkRetentionMaxDistanceBlocks (1024) é retido. Acima do orçamento, os mais longe saem primeiro, 64 por checagem, para uma subida curta da heap não largar o caminho todo. O rastro de quem saiu da área é o último a ficar.
• No máximo 64 chunks novos por checagem, para a leitura da heap acompanhar, e nenhum quando a heap pós-GC está a menos de 5% do teto.

O LeanCore nunca remove chunks; soltar só larga a referência e o engine descarrega normalmente. O /leancore status mostra retention held=… budget=….

---

Freio de chunks

Em TIGHT e CRITICAL a taxa de envio de chunks de cada jogador fica limitada a chunkRateBrakeTightPerSecond (512) e chunkRateBrakeCriticalPerSecond (192) seções por segundo; COMFORT e WATCH devolvem a taxa do próprio engine. Só reduz, nunca aumenta. Fica de fora enquanto o QuantumHy está carregado, ou com chunkThroughputGovernanceEnabled ligado.

---

Convivência com o QuantumHy

Com os dois mods instalados, o QuantumHy assume o view radius do cliente e a taxa de envio de chunks (a suavização anti-stutter dele). O LeanCore fica com a memória: tiers, raio de simulação e retenção de chunks. O QuantumHy lê o tier do LeanCore e aperta o render radius em TIGHT ou CRITICAL. O freio de chunks do LeanCore fica desligado enquanto o QuantumHy está carregado. Ligar chunkThroughputGovernanceEnabled: true entrega a taxa de envio ao LeanCore.

---

Funcionalidades

• Profiles de runtime: LITE, STANDARD, FULL em host embutido ou dedicado
• Tiers pela heap real: COMFORT, WATCH, TIGHT, CRITICAL pela heap pós-GC, old gen pós-GC e tendência; rollback quando devolver a view piora
• Retenção de chunks (1.8): a heap de sobra mantém chunks recém-saídos carregados
• Freio de chunks (1.8): desacelera o streaming em TIGHT/CRITICAL; desligado com o QuantumHy
• Cortes de view radius (LITE) e de raio de simulação sob pressão real, nunca abaixo de liteMinClientViewRadius
• Boost cinematográfico de view (motionViewRadiusBoostEnabled, opcional): aumenta a distância de visão para quem se move rápido; desligado por padrão (reescrever o view radius a cada tick sacode o carregamento de chunks no engine atual)
• Diagnóstico sempre ligado (diagnosticLogEnabled): resumos de início/fim e logs [diag] de decisão por profile
• Dados de learning: janelas de heap (60s / 15m / 24h), modelo de demanda, estatísticas de reuso de zona; salvos entre reinícios (schema v9)
• Activity Sense: classificador softmax online (MINER, LUMBERJACK, FARMER, BUILDER, FIGHTER, EXPLORER)
• Session savings: /leancore savings mostra pico/base/delta da heap JVM e atividade do governador
• Bootstrap dedicado: preset único no primeiro boot dedicado
• HUD de admin (/leancore hud on): overlay pequeno de heap/tier. Desligado por padrão.
• Heatmap, zone pin, webhook opcional em CRITICAL

---

Comandos

Comando principal: /leancore

Comando	Acesso	Descrição
/leancore status	Todos	Profile, tier, linha de pressão (heap pós-GC, old gen, alocação, tempo de GC, tendência), linha de retenção
/leancore memory	Todos	Snapshot da heap, tier, footprint
/leancore savings	Todos	Heap JVM da sessão e estado do governador
/leancore zones	Todos	Contadores de zona
/leancore learn	Todos	Diagnóstico de learning
/leancore learn player	Todos	Features de demanda, posterior, EMAs de atividade
/leancore probe	Todos	Probe de capacidade da API (S1–S5), só diagnóstico
/leancore hud on	Quem vê o HUD	Liga o overlay opcional de memória
/leancore hud off	Quem vê o HUD	Desliga o overlay
/leancore hud status	Quem vê o HUD	Elegibilidade e estado do HUD
/leancore heatmap [limit]	Staff	Heatmap de zonas
/leancore zone pin	Staff	Fixa a zona atual como HOT
/leancore zone unpin	Staff	Desfixa a zona atual
/leancore zone pins	Staff	Lista zonas fixadas

/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

---

Permissões

O LeanCore usa nodes de permissão e/ou listas de grupos na config. Qualquer um dos dois libera o acesso.

Permissão	Descrição
durkz.leancore.hud	Ligar e ver o HUD opcional de memória (/leancore hud …)
durkz.leancore.admin	Heatmap, zone pin/unpin/pins e ferramentas de HUD de admin

• Quem vê o HUD: grupos em hudViewerGroups e/ou durkz.leancore.hud
• Heatmap e zone pin (admin): hudAdminGroups e/ou durkz.leancore.admin

Grupos na config (padrão)

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

Setup rápido com /perm do Hytale

/perm group add OP durkz.leancore.admin

---

Configuração (LeanCore.json)

Caminho: mods/durkz_LeanCore/LeanCore.json

Chave	Padrão	Descrição
enabled	true	Liga/desliga geral
localHostMode	AUTO	AUTO, PASSIVE ou FULL no host embutido
governEnabled	false	Governador STANDARD/FULL
learningEnabled	false	Learning STANDARD/FULL
embeddedStandardProfile	false	Solo embutido → STANDARD em vez de LITE
dedicatedServerMode	false	Força o profile FULL
dedicatedViewRadiusGraceSeconds	600	Host dedicado: sem cortes de view por esse tempo depois do início
watchHeapRatio	0.70	Limite do WATCH, heap pós-GC
tightHeapRatio	0.82	Limite do TIGHT, heap pós-GC
criticalHeapRatio	0.90	Limite do CRITICAL, heap pós-GC
liteMemoryGovernorEnabled	true	Governador lite no solo
liteLearningEnabled	true	Modelo de demanda + persistência no solo
liteViewRadiusEnabled	true	View adaptativa no solo
liteMinClientViewRadius	8	Nunca corta a view abaixo disso
liteViewPressureThreshold	0.85	Teto em COMFORT quando a saturação de chunks é alta
chunkRetentionEnabled	true	Mantém chunks recém-saídos carregados enquanto sobra heap
chunkRetentionMaxPostGcRatio	0.50	Teto da heap pós-GC (sempre abaixo de watchHeapRatio). Chunks novos param 5% abaixo dele; acima dele os mais longe saem primeiro, 64 por checagem
chunkRetentionMbPerChunk	1.0	Estimativa de heap por chunk retido, usada no orçamento
chunkRetentionMaxChunks	2048	Teto de chunks retidos
chunkRetentionMaxHoldSeconds	600	Solta um chunk retido depois desse tempo
chunkRetentionMaxDistanceBlocks	1024	Retém do mais perto para o mais longe; nada além dessa distância de um jogador online
chunkRateBrakeEnabled	true	Freia o streaming de chunks em TIGHT/CRITICAL
chunkRateBrakeTightPerSecond	512	Teto de seções/s por jogador em TIGHT
chunkRateBrakeCriticalPerSecond	192	Teto de seções/s por jogador em CRITICAL
chunkThroughputGovernanceEnabled	false	Entrega a taxa de envio ao throughput escalado por tier do LeanCore (o QuantumHy então cede)
motionModelEnabled	true	Modelo de movimento por jogador
zoneReuseModelEnabled	true	Modelo de reuso + sobrevivência por zona
motionViewRadiusBoostEnabled	false	Boost cinematográfico de view opcional
diagnosticLogEnabled	true	Logs [diag] de sessão/decisão sempre ligados
checkForUpdates	true	Avisa ops/admins quando sai um JAR novo
gcHintEnabled	false	Empurrão experimental de GC no LITE parado

Sem uso desde a 1.8.0, mantidas para configs antigas carregarem: unloadEnabled, liteUnloadEnabled, liteUnloadIdleSeconds, unloadProbeGateEnabled, probePassedAtMs.

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

Estado do HUD por jogador: mods/durkz_LeanCore/hud.state.

---

Recomendado

• Solo / local: mantenha localHostMode: AUTO. Governador LITE, retenção e learning vêm ligados.
• Dedicado ou com amigos: ligue governEnabled e learningEnabled. Mais heap significa mais espaço para retenção.
• Com o QuantumHy: instale os dois e deixe chunkThroughputGovernanceEnabled desligado.
• Use /leancore savings depois de 15+ minutos em hosts dedicados para ver o delta da heap e os contadores do governador.

---

Como conferir se está funcionando

1. O log deve mostrar LeanCore 1.8.0 setup (localHostMode=AUTO). e profile=LITE no solo
2. /leancore status: profile LITE, uma linha pressure= e uma linha retention on held=… budget=…
3. Afaste-se do spawn e pare: held sobe enquanto o tier fica em COMFORT
4. Amigo entra → log profile LITE -> STANDARD
5. Minere minério → /leancore learn player mostra posterior=MINER e demand/viewScale

O que importa é a heap JVM do servidor, não FPS ou GPU do cliente.

---

Licença

MIT License. Copyright (c) 2026 DurkzPRG