Server documentation

QuantumHy

Active

Hytale • Version 0.2.3

Instalação, chaves de config, raio adaptativo de chunks e entidades, freeze de expand, governor de pressão e coexistência com o LeanCore no Hytale 0.6.

Mod overview GitHub CurseForge

Instalação, configuração e comportamento em runtime do QuantumHy.

Visão geral

O QuantumHy é um mod de FPS server-side para Hytale 0.6. O cliente é nativo e não dá pra modar, mas o servidor decide o quanto cada cliente precisa desenhar, então o QuantumHy corta isso por jogador. A cada poucos segundos ele amostra a densidade de entidades ao redor de cada jogador, suaviza e usa isso pra reduzir duas coisas: o raio de visão em chunks do cliente e o raio de stream de entidades por jogador. Um ajuste global de LOD de entidades descarta entidades pequenas e distantes mais cedo por cima disso.

Ele nunca infla a visão além do que o jogador pediu. O raio não volta no instante em que a densidade parece aberta: o expand fica congelado até a carga estar calma, o disco de density estar pelo menos metade carregado, o jogador não estar voando e o mundo não estar sob pressão de MSPT. Só ajuda onde está instalado, nunca num servidor remoto que você só entra.

Instalação

Baixe QuantumHy-0.2.3.jar na aba Files da CurseForge
Coloque o JAR na pasta mods/ do servidor, ou no solo Windows: %AppData%\Hytale\data\release\Mods
Inicie o servidor. A config é gerada como QuantumHy.json na pasta de dados do plugin
Acompanhe o log do servidor pela linha de setup (veja Conferindo se está funcionando)

Comandos

/q status
/q help

Aliases: /quantumhy, /qhy. /q status é diagnóstico só leitura. Não há /q perf público.

Como funciona

A cada passada (5s por padrão) o QuantumHy faz o trabalho por jogador na thread do mundo dono:

Amostra a densidade (às vezes pula). Conta entidades num disco de densityScanChunkRadius chunks (dx²+dz² ≤ r²). A varredura de 49 colunas é pulada na primeira passada, em voo (2+ chunks/passada), em streaming, no cache do mesmo chunk, e enquanto já estiver no mínimo com expand travado.
Suaviza. Uma amostra válida passa por uma média móvel exponencial (densitySmoothing).
Vira um fator de redução. A densidade usa smoothstep entre densityLowPerChunk e densityHighPerChunk. Isso combina com shrink por chunk-load (sections carregadas + carregando) e um piso baseline. O fator combinado só aumenta o shrink até o expand ser permitido (ratchet).
Rampa duas alavancas. Visão em chunks move no máximo +1 / −2 por passada (−4 sob pressão). O raio de entidades usa o mesmo fator; em shrink cheio ([min]) vai a minEntityViewBlocks num write. Escritas param depois de worldPassBudgetMs ou durante streaming.

O expand só é permitido depois de expandHysteresisPasses passadas calmas, disco de density ≥ 50% carregado, sem streaming, sem deslocamento rápido e sem pressão MSPT.

O entityLodAggressiveness é separado: multiplicador único no servidor no cull de LOD do engine, aplicado no boot e restaurado no shutdown.

Configuração

Arquivo de runtime: QuantumHy.json na pasta de dados do plugin, criado no primeiro boot. Install nova recebe configVersion 5.

Chave	Padrão	O que faz
`enabled`	`true`	Interruptor mestre. Quando false, o QuantumHy nunca toca em raio de visão nenhum.
`verboseLog`	`false`	Loga cada passada com a densidade e a decisão de visão de cada jogador. Off em install nova.
`checkForUpdates`	`true`	No boot, lê a página do QuantumHy e avisa operadores ou `durkz.quantumhy.admin` se um JAR mais novo estiver listado.
`tickIntervalSeconds`	`5`	De quanto em quanto tempo ele recheca cada jogador.
`initialDelaySeconds`	`20`	Espera esse tempo após o start antes da primeira passada.
`targetClientViewRadius`	`0`	Teto fixo em chunks. `0` significa sem teto, só adapta pela densidade.
`minClientViewRadius`	`6`	Nunca puxa ninguém abaixo desse raio em chunks.
`maxClientViewRadius`	`32`	Teto pro limite fixo (o próprio raio de visão do jogador ainda vence).
`densityScanChunkRadius`	`4`	Quantos chunks pra cada lado contar entidades.
`densityLowPerChunk`	`1.0`	Entidades ponderadas por chunk em ou abaixo disso: sem shrink por densidade.
`densityHighPerChunk`	`4.0`	Entidades ponderadas por chunk em ou acima disso: puxado pro mínimo.
`densityRingWeighting`	`true`	Chunks centrais contam cheio, anéis externos menos.
`densityRingEdgeWeight`	`0.55`	Peso no anel da borda (`1.0` = contagem plana).
`baselineShrinkFraction`	`0.10`	Shrink mínimo mesmo com densidade “aberta” (`0` = off).
`chunkLoadShrinkEnabled`	`true`	Shrink extra pela contagem de sections carregadas + em streaming.
`chunkLoadLowChunks`	`700`	Sections loaded+loading em ou abaixo disso: sem shrink por chunk-load.
`chunkLoadHighChunks`	`1550`	Nesse número de sections ou acima: shrink por chunk-load no máximo.
`densitySmoothing`	`0.4`	Peso da amostra mais nova na EMA, em (0, 1]. `1.0` desliga.
`adaptEntityRadius`	`true`	Também reduz o raio de stream de entidades por jogador, não só os chunks.
`minEntityViewBlocks`	`48`	Limite inferior do raio de entidades, em blocos (16 blocos = 1 chunk).
`entityLodAggressiveness`	`2.0`	Cull global de LOD de entidades. `1.0` é o padrão do engine.
`maxEntityVerticalDistance`	`32`	Descarta entidades longe demais acima/abaixo do jogador. `0` = off.
`maxVisibleEntitiesPerPlayer`	`80`	Teto de entidades streamadas por jogador em multidões. `0` = off.
`holdSpawnOnLoadingChunks`	`true`	Pausa spawn ambiental enquanto algum jogador tem backlog de sections.
`minViewRadiusDelta`	`2`	Mudança mínima (chunks) antes de mandar uma atualização. Expands +1 ainda aplicam.
`maxExpandChunksPerPass`	`1`	Máximo de chunks que o raio de visão sobe numa passada.
`maxShrinkChunksPerPass`	`2`	Máximo que desce numa passada (dobrado sob pressão).
`maxExpandEntityBlocksPerPass`	`16`	Máximo de blocos que o raio de entidades sobe numa passada.
`expandHysteresisPasses`	`2`	Passadas calmas exigidas antes de permitir expand.
`worldPassBudgetMs`	`8`	Budget de relógio para writes de raio na world thread. `0` desliga.
`pressureExitRequiresLastTick`	`true`	Pressure só sai quando a média de 10s e o last tick estão calmos.
`respectStreamingGrace`	`true`	Segura cortes enquanto o jogador ainda está transmitindo sections.
`streamingBacklogThreshold`	`80`	Quantas sections carregando contam como “ainda transmitindo”.
`smoothChunkStreaming`	`true`	Limita a velocidade com que sections chegam a cada cliente gerenciado.
`maxChunksPerSecond`	`128`	Teto de sections por segundo. `0` mantém o padrão do engine.
`maxChunksPerTick`	`8`	Teto de sections por tick (padrão do engine é 40 no 0.6).
`leanCoreTakeover`	`true`	Se o LeanCore estiver instalado, assume o raio de visão dele.
`yieldToLeanCoreViewRadius`	`false`	Deixa o raio de visão do cliente inteiramente pro LeanCore.
`pressureGovernorEnabled`	`true`	Aperta as alavancas de render quando o MSPT do mundo fica alto.
`pressureMsptEnter`	`48`	Média de 10s de MSPT nesse valor ou acima entra em pressure.
`pressureMsptExit`	`43`	MSPT nesse valor ou abaixo sai de pressure.
`pressureSustainSeconds`	`4`	Quanto tempo o MSPT precisa ficar alto antes de apertar.
`pressureCooldownSeconds`	`15`	Quanto tempo o MSPT precisa ficar baixo antes de restaurar.
`pressureDensityMultiplier`	`1.45`	Sob pressão, os limiares de densidade apertam por esse fator.
`pressureChunkRateMultiplier`	`0.75`	Sob pressão, multiplica os tetos de streaming de chunks.
`pressureLodMultiplier`	`1.15`	Sob pressão, cull extra de LOD de entidades.
`pressureVerticalTrimBlocks`	`8`	Sob pressão, subtrai de `maxEntityVerticalDistance`.
`pressureWorldLevers`	`false`	Sob pressão, pausa spawn de NPC e tick de bloco (restaurado na saída).
`pressureTrimClientEffects`	`true`	Sob pressão, corta bloom/sunshaft (adiado se o last tick for hitch).
`pressureEffectScale`	`0.5`	Multiplicador das intensidades de efeito enquanto cortadas.

Permissões

Permissão	Quem
`durkz.quantumhy.admin`	Avisos de update in-game. Operadores do servidor herdam isso via `*`.

Rodando com o LeanCore

O QuantumHy e o LeanCore podem ambos ajustar o raio de visão do cliente, e só um deve. Por padrão o QuantumHy assume: no boot ele detecta o LeanCore e desliga a governança de raio de visão do LeanCore (viewRadiusGovernanceEnabled, liteViewRadiusEnabled, motionViewRadiusBoostEnabled), e então passa a controlar o raio ele mesmo. O LeanCore continua com o raio de simulação, o throughput de chunks e a memória. Nenhuma mudança de config é necessária dos dois lados. O LeanCore é uma dependência opcional: quando ele não está presente, o QuantumHy roda sozinho.

leanCoreTakeover: false deixa o LeanCore em paz. Aí os dois podem brigar pelo raio de visão.
yieldToLeanCoreViewRadius: true faz o QuantumHy ficar fora do raio de visão do cliente por completo e deixa o LeanCore manter.

Conferindo se está funcionando

Inicie o servidor e procure a linha de setup: QuantumHy 0.2.3 setup. config: verboseLog=false tickInterval=5s ... densityLow=1.0/ch densityHigh=4.0/ch baseline=10% ... entityLod=2.00x ... expand=1 shrink=2 ... budget=8ms
Depois a linha de início do runtime: QuantumHy runtime started (interval=5s, hardCap=0, min=6, max=32, scan=4, entityRadius=true).
Se o LeanCore estiver presente: LeanCore detected: took over the client view radius (governance turned off). Caso contrário: LeanCore not detected after 3 checks: QuantumHy owns the client view radius standalone.
Com verboseLog=true, cada passada loga uma linha por jogador. Lendo: Durkz_z 32/49ch 0.7/ch~0.5 cl 6=6 ent 48=48 [hold] significa 32 entidades em 49 chunks, visão em chunks presa em 6, raio de entidades em 48 blocos, expand congelado (hold). Outros motivos comuns: [min], [pressure], [baseline], [chunk-load], [density].
O raio não salta 6→13 numa passada. Sob pressão ou voando você deve ver [pressure] ou [hold], não 6->7 [baseline].

Licença

Licença MIT