Documentação do servidor

QuantumHy

Ativo

Hytale • Version 0.4.0

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.7.

Visão geral 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.7. 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 para reduzir o raio de visão em chunks e o raio de stream de entidades. Cada jogador pode ativar ou desativar a otimização para si sem alterar os outros.

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.4.0.jar na aba Files da CurseForge
Coloque o JAR na pasta mods/ do servidor, ou no Windows: %AppData%\Hytale\UserData\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 optimize on
/q optimize off
/q help

Aliases: /quantumhy, /qhy. Um jogador comum vê apenas seu próprio modo e última decisão em /q status. Admins e console veem o diagnóstico completo. /q optimize on|off altera apenas o jogador que executa e salva a escolha pelo UUID.

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, com cache recente do mesmo chunk, e enquanto já estiver no mínimo com expand travado. O cache de um jogador parado expira após 15 segundos.
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 e global. O padrão 1.0 mantém o LOD do engine. Valores acima de 1.0 são um override explícito do admin, e só nesse caso a pressão de MSPT aplica pressureLodMultiplier.

Configuração

Arquivos de runtime: QuantumHy.json e PlayerPreferences.json na pasta de dados do plugin, criados no primeiro boot. Instalações novas recebem configVersion 8.

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).
`adaptiveTerrainViewEnabled`	`true`	Adapta o raio de visão do terreno durante o jogo normal.
`emergencyTerrainTrimEnabled`	`true`	Permite redução temporária do terreno após pressão visual sustentada.
`clientRenderCapEnabled`	`true`	Limita a distância de desenho e a névoa do cliente ao raio cortado. Exige reinício.
`clientStrainEnabled`	`true`	Alivia o raio e o envio de chunks pra um cliente que fica pra trás. Exige reinício.
`clientStrainFrameLagLowMs`	`25`	Atraso do loop principal do cliente (ms) onde a sobrecarga começa a contar (uns 40 FPS).
`clientStrainFrameLagHighMs`	`60`	Atraso tratado como sobrecarga total (uns 16 FPS).
`clientStrainQueueLow`	`64`	Fila de pacotes do cliente onde a sobrecarga começa a contar.
`clientStrainQueueHigh`	`512`	Fila de pacotes tratada como sobrecarga total.
`effectBudgetEnabled`	`true`	Orçamento de partículas e sons 3D distantes por jogador. Exige reinício.
`effectBudgetPerSecond`	`120`	Efeitos distantes que cada jogador pode receber por segundo.
`effectProtectRadius`	`16`	Efeitos dentro desse número de blocos nunca são descartados.
`effectSoftRadius`	`48`	Depois de gastar metade do orçamento, efeitos além disso caem primeiro.
`effectMaxDistance`	`0`	Corte fixo em blocos pra efeitos posicionais. `0` = só o orçamento.
`distantUpdateThrottleEnabled`	`false`	Envia updates de posição de entidades distantes com menos frequência. A posição mais recente sempre chega. Exige reinício.
`distantUpdateNearBlocks`	`32`	Entidades mais perto que isso recebem todo update.
`distantUpdateFarBlocks`	`64`	Entidades além disso recebem 1 a cada 4 updates.
`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`	`2800`	Sections loaded+loading em ou abaixo disso: sem shrink por chunk-load. Também é onde a visão assenta quando está calmo (por volta de view 10 no 0.7).
`chunkLoadHighChunks`	`5900`	Nesse número de sections ou acima: shrink por chunk-load no máximo (por volta de view 14).
`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`	`1.0`	Override global explícito de LOD. `1.0` mantém 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`	`false`	Pausa spawn ambiental durante backlog pesado de sections. Controle global do admin.
`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).
`streamCatchUpEnabled`	`true`	Eleva temporariamente os limites após viagem rápida enquanto o MSPT está saudável.
`streamCatchUpIntervalMs`	`250`	Intervalo do controlador leve de streaming.
`streamCatchUpPerSecond`	`256`	Limite saudável de catch-up em sections por segundo.
`streamCatchUpPerTick`	`12`	Limite saudável de catch-up em sections por tick.
`streamCatchUpHoldMs`	`1500`	Tempo mínimo de catch-up após movimento rápido.
`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`	Multiplicador de pressão usado apenas com LOD global explícito acima de `1.0`.
`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`	`false`	Sob pressão, corta bloom/sunshaft (adiado se o last tick for hitch).
`pressureEffectScale`	`0.5`	Multiplicador das intensidades de efeito enquanto cortadas.
`pressureItemMerge`	`false`	Sob pressão, junta itens dropados de mais longe pra pilhas virarem menos entidades. Exige reinício.
`pressureItemMergeRadius`	`4.0`	Raio de merge em blocos enquanto isso está ativo (padrão da engine é 2).
`leanCoreMemoryAware`	`true`	Com o LeanCore, reduz o raio enquanto o tier de heap dele está TIGHT ou CRITICAL. Só leitura.

Permissões

Permissão	Quem
`durkz.quantumhy.admin`	Avisos de update e `/q status` completo. 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.4.0 setup. config: verboseLog=false tickInterval=5s ... densityLow=1.0/ch densityHigh=4.0/ch baseline=10% ... entityLod=1.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