LeanCore

Active

Hytale • Version 1.7.0

servidor memória ram governador dormência performance admin aprendizado solo co-op

O LeanCore é feito para reduzir o uso de heap JVM em servidores Hytale. Conforme os jogadores exploram, toda área que tocam mantém seus chunks e entidades residentes na memória, e o engine é lento para liberá-los, então a heap sobe e fica alta muito depois de todo mundo ter saído. O LeanCore é a peça que decide o que continua carregado e o que é liberado, modelando onde os jogadores estão, para onde estão indo e quais partes do mapa eles realmente revisitam. O quanto ele libera depende do seu mundo, e o unload de chunks só entra em ação depois que você roda /leancore probe.

No mundo local / solo, roda profile LITE: governador leve com view adaptativa, reclaim AFK de chunks e learning de demanda ligado por padrão. Com amigos, sobe para STANDARD. Em servidor dedicado, profile FULL.

Não mexe em FPS, GPU ou TPS do cliente.

Requer servidor Hytale >=0.5.6. Depois de instalar, rode /leancore status com o servidor rodando cerca de um minuto.

Com vs sem o LeanCore

Mesma sessão solo, RAM do servidor ao longo do tempo. Sem o mod, toda área que você visita fica residente e a heap só sobe até você reiniciar. Com o LeanCore, áreas ociosas esfriam e são liberadas, então a RAM sobe sob carga e depois recua.

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

Como o LeanCore decide

Duas coisas guiam cada ação: o quão apertada está a memória agora, e se uma zona ainda é necessária. A escada decide a intensidade; a checagem por zona decide o que é seguro liberar.

Pressão para ação

                           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

Manter ou liberar uma 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

Como o LeanCore pensa

Não é um timer que despeja chunks num cronograma. Ele mantém um pequeno modelo vivo do seu mundo e decide a partir dele.

1. A pressão é relativa ao seu próprio servidor

Um heap a 70% é folgado num host e o limite do travamento em outro, então o LeanCore não fixa limiares. Ele amostra a razão de heap continuamente, monta uma distribuição móvel a partir do histórico do próprio servidor e classifica a leitura atual num tier:

Tier	O que significa	O que o LeanCore faz
COMFORT	dentro da faixa normal do servidor	fica de fora, view radius cheia
WATCH	acima da linha de base usual	cortes suaves de view, começa a rebaixar zonas ociosas
TIGHT	memória pressionada	cortes mais fortes, descarrega zonas dormentes distantes
CRITICAL	perto do limite	cortes e unload mais agressivos, dica de GC e webhook opcionais

2. O mapa é agrupado em zonas com temperatura

O LeanCore não raciocina sobre chunks isolados. Ele agrupa o mapa em zonas e acompanha uma temperatura: HOT -> WARM -> DORMANT -> FROZEN.

Estado	Significado	Elegível a unload
HOT	um jogador está dentro ou perto, ou a zona está fixada	nunca
WARM	o último jogador acabou de sair	não
DORMANT	ociosa além do seu timer warm	sim, sob TIGHT ou pior
FROZEN	ociosa há muito tempo	sim

Só zonas DORMANT e FROZEN que também estão longe de todo jogador chegam a ser candidatas. Isso separa “ninguém esteve aqui há 20 minutos” de “o jogador saiu por um segundo”.

3. A distância é medida com honestidade

Ao checar quão longe uma zona está de um jogador, ela mede até a borda de chunk mais próxima da zona, não o centro. Uma zona dentro da view distance de qualquer jogador mais uma região de folga nunca é candidata a unload. Essa linha é a diferença entre recuperar memória e causar pop-in.

4. Ele protege para onde você vai

Um jogador correndo rumo a terreno novo precisa que ele seja mantido antes da chegada. O LeanCore roda um modelo de movimento por jogador: velocidade suavizada, aceleração estimada, um valor de confiança e uma posição projetada alguns segundos à frente. Esse ponto previsto vira uma segunda âncora, então a view atual e a view prevista ficam ambas fora de alcance.

Um boost cinematográfico de view, opcional, amplia a view distance para quem se move rápido. Vem desligado por padrão: reescrever a view radius a cada tick gera churn de carregamento no engine atual. Razoável ligar num host dedicado ou numa máquina forte; deixe desligado em setups limitados.

5. Ele aprende quais zonas importam pra você

Sua base, sua mina, o caminho entre elas: você sempre volta. Um ponto que você cruzou uma vez, nunca mais vê. O LeanCore mantém um modelo de reuse-distance e sobrevivência por zona, transformado num score de revisita que estica ou encolhe os cooldowns daquela zona. Quando algo precisa sair, a eviction é ordenada por quão longe a zona está e quão improvável é revisitá-la. Com o modelo de reuse desligado, isso colapsa de forma limpa para distância pura.

6. Ele considera quem é o jogador

Um classificador online (Activity Sense) rotula cada jogador por um softmax sobre a atividade recente: MINER LUMBERJACK FARMER BUILDER FIGHTER EXPLORER. Isso alimenta um demand model que define um peso de retenção por jogador dentro de um orçamento global. Em hosts maiores um policy bandit explora qual política de escala de view funciona melhor, um grupo holdout fica intocado como controle, e o reward feedback deixa o mod desfazer um corte que prejudicou um jogador de alta demanda.

7. Ele age com cuidado, e na thread certa

Afinidade de world-thread: toda leitura ou escrita de chunk stores, chunk trackers ou view radius roda na thread do world dono. O scheduler em background só orquestra.
Probe gate: o unload de chunks fica desligado até um probe de capacidade único (/leancore probe) confirmar que os hooks do engine funcionam.
Sweeps limitados: o unload é limitado por passada, então nunca sai num surto de drops.
Checagem de visibilidade: só libera chunks que nenhum tracker de jogador consegue ver no momento.
Cortar antes de soltar, e reverter: sob carga, corta view distance antes de descarregar e reverte uma mudança quando o histórico de tier mostra que ela saiu pela culatra.

Perfis de runtime

O LeanCore se dimensiona ao host automaticamente, por contagem de jogadores, sem chave manual:

Perfil	Quando	Tick	O que roda
LITE	mundo solo embarcado	30s (60s idle)	governador leve, view adaptativa, reclaim AFK, demand learning
STANDARD	poucos amigos	15s	adiciona Activity Sense, governador e learning opcionais
FULL	servidor dedicado	5s	conjunto completo, incluindo policy bandit e holdout

O que ele deliberadamente não faz

Mexer em FPS, GPU ou performance de render do cliente. É só heap do servidor.
Mudar TPS ou comportamento de simulação.
Descarregar um chunk que um jogador vê, ou agir de forma agressiva com o heap em COMFORT.
Trazer defaults surpresa: solo é conservador e o boost cinematográfico é opt-in.

Features

Perfis de runtime: LITE solo, STANDARD amigos, FULL dedicado (localHostMode: AUTO)
Governador LITE solo: view adaptativa, demotion de zonas, unload AFK, learning de demanda; tick 30s (60s em idle)
Tiers de heap: COMFORT, WATCH, TIGHT, CRITICAL. Rollback se um corte causar problema.
Dormência de zonas: HOT perto dos jogadores. Áreas vazias descem WARM, DORMANT, FROZEN nos timers configurados.
Retenção preditiva (1.6): modelo de movimento por jogador inclina o unload para longe de onde o jogador está indo; zonas na view atual ou prevista nunca são candidatas a unload
Modelo de reuse-distance + sobrevivência (1.6, zoneReuseModelEnabled): aprende quais zonas são revisitadas e ajusta os limiares de dormência por zona
Orçamento de retenção: cap global com peso por jogador a partir da atividade
Cortes de view-radius: quando heap ou pressão de chunks sobe (LITE no solo; STANDARD/FULL em multi-player / dedicado)
Unload de chunks: zonas dormant/frozen quando o tier exige; portão de probe bloqueia até /leancore probe passar
Dados de learning: janelas de heap, bandit (STANDARD/FULL), demand model, stats de reuse de zona; snapshot v8 gzip (compatível com v7) com prune/TTL
Learning LITE: demand model molda cortes de view no solo; sem bandit ou holdout em LITE
Activity Sense: classificador softmax online (MINER, LUMBERJACK, FARMER, BUILDER, FIGHTER, EXPLORER)
Session savings: /leancore savings reporta heap JVM e atividade do governador lite ou standard
Portão de probe: unload LITE e STANDARD/FULL bloqueado até /leancore probe quando o portão está ligado
Bootstrap dedicado: preset único no primeiro boot dedicado
Boost cinematográfico de view (1.6, motionViewRadiusBoostEnabled, opt-in): sobe a view distance suavemente para quem se move rápido. Desligado por padrão porque reescrever a view radius a cada tick gera churn de chunks no engine atual.
Diagnóstico sempre ligado (diagnosticLogEnabled): resumos de início/fim e logs de decisão [diag] explicam o que o mod fez e por quê, direto do log do servidor
HUD admin (/leancore hud on): overlay heap/tier. Desligado por padrão.
Heatmap, zone pin, webhook CRITICAL opcional

Instalação

Baixe LeanCore-1.7.0.jar na aba Files do CurseForge
Coloque o JAR na pasta mods/ do servidor (ou %AppData%\Hytale\UserData\Mods\ no Windows)
Inicie o servidor. Config em mods/durkz_LeanCore/LeanCore.json
Rode /leancore probe se depender de unload de chunks
Rode /leancore status após cerca de um minuto online

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, permissões e config completa: documentação

Config

Arquivo: mods/durkz_LeanCore/LeanCore.json

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

Snapshot de learning: mods/durkz_LeanCore/learning.state.gz (schema v8, gzip; v7 migra no primeiro flush).

Permissões

HUD: grupos em hudViewerGroups e/ou durkz.leancore.hud
Admin heatmap, zone pin: hudAdminGroups e/ou durkz.leancore.admin

Licença

MIT License

For server owners

Need permissions, commands & config?

The full administration guide covers every permission node, admin command, LuckPerms examples, and all config options.

Read server documentation