← Back to documentation

Server documentation

QuantumHy

In Development

Hytale • Version 0.2.1

Instalação, chaves de config, como funcionam o raio adaptativo de chunks e de entidades, o cull global por LOD e a coexistência com o LeanCore.

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 pro Hytale. 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. Em área aberta tudo volta ao teto do próprio jogador; o QuantumHy nunca infla a visão além do que o jogador pediu. Ele só ajuda onde está instalado, nunca num servidor remoto que você só entra.

Instalação

  1. Baixe QuantumHy-0.2.1.jar na aba Files da CurseForge
  2. Coloque o JAR na pasta mods/ do seu servidor (ou %AppData%\Hytale\UserData\Mods\ no Windows)
  3. Inicie o servidor. A config é gerada como QuantumHy.json na pasta de dados do plugin
  4. Acompanhe o log do servidor pela linha de setup e pelas decisões de cada passada (veja Conferindo se está funcionando)

Como funciona

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

  1. Amostra a densidade. Conta as entidades nos chunks ao redor do jogador (um quadrado de densityScanChunkRadius chunks pra cada lado) e divide pelo número de chunks carregados varridos, dando entidades por chunk. Um mundo normal fica ocioso por volta de 1 a 1,5 por chunk.
  2. Suaviza. O valor por chunk passa por uma média móvel exponencial (densitySmoothing), pra um jogador que atravessa uma multidão rápida não ter a visão sacudida.
  3. Vira um fator de redução. Em ou abaixo de densityLowPerChunk o fator é 0 (sem corte). Em ou acima de densityHighPerChunk é 1 (corte total). Entre eles, escala linearmente.
  4. Aplica nas duas alavancas. O mesmo fator escala o raio de visão em chunks (pra baixo, em direção a minClientViewRadius) e, com adaptEntityRadius ligado, o raio de stream de entidades em blocos (pra baixo, em direção a minEntityViewBlocks). A alavanca de entidade é o grande ganho em áreas cheias de mobs, já que controla a que distância o servidor transmite entidades, independente dos chunks.

As duas alavancas sobem de volta em área aberta. Enquanto o jogador ainda está transmitindo chunks (acabou de entrar, está correndo), o corte fica segurado pra o cliente não ser mandado a descartar chunks que está ocupado carregando. Como escrever o raio de visão também reduz o valor que o getter reporta, o QuantumHy lembra o maior valor que já viu por jogador e sobe de volta em direção a ele, pra a visão se recuperar corretamente.

O entityLodAggressiveness é separado: é um multiplicador único, válido pro servidor todo, no cull de LOD de entidades do engine, aplicado uma vez no boot e restaurado no shutdown. Valores mais altos descartam entidades pequenas e distantes mais cedo pra todo mundo.

Configuração

Arquivo de runtime: QuantumHy.json na pasta de dados do plugin, criado no primeiro boot.

ChavePadrãoO que faz
enabledtrueInterruptor mestre. Quando false, o QuantumHy nunca toca em raio de visão nenhum.
verboseLogtrueLoga cada passada com a densidade e a decisão de visão de cada jogador.
tickIntervalSeconds5De quanto em quanto tempo ele recheca cada jogador.
initialDelaySeconds20Espera esse tempo após o start antes da primeira passada.
targetClientViewRadius0Teto fixo em chunks. 0 significa sem teto, só adapta pela densidade.
minClientViewRadius6Nunca puxa ninguém abaixo desse raio em chunks.
maxClientViewRadius32Teto pro limite fixo (o próprio raio de visão do jogador ainda vence).
densityScanChunkRadius4Quantos chunks pra cada lado contar entidades.
densityLowPerChunk2.0Entidades por chunk em ou abaixo disso: raio cheio.
densityHighPerChunk8.0Entidades por chunk em ou acima disso: puxado pro mínimo.
densitySmoothing0.4Peso da amostra mais nova na EMA, em (0, 1]. Menor é mais suave; 1.0 desliga.
adaptEntityRadiustrueTambém reduz o raio de stream de entidades por jogador, não só os chunks.
minEntityViewBlocks48Limite inferior do raio de entidades, em blocos (16 blocos = 1 chunk).
entityLodAggressiveness1.5Cull global de LOD de entidades. 1.0 é o padrão do engine; maior descarta pequenas/distantes mais cedo.
minViewRadiusDelta2Mudança mínima (chunks) antes de mandar uma atualização, pra evitar churn.
respectStreamingGracetrueSegura os cortes enquanto o jogador ainda está transmitindo chunks.
streamingBacklogThreshold8Quantos chunks carregando contam como “ainda transmitindo”.
leanCoreTakeovertrueSe o LeanCore estiver instalado, assume o raio de visão dele.
yieldToLeanCoreViewRadiusfalseO oposto: deixa o raio de visão do cliente inteiramente pro LeanCore.

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.

Recomendado

  • Solo ou seu próprio servidor: deixe os padrões. Você só perde distância de visão quando está realmente cheio.
  • Quer FPS em todo lugar: defina targetClientViewRadius entre 12 e 16 pra limitar a distância de visão até em área aberta.
  • Farms de mob / eventos pesados: mantenha adaptEntityRadius: true; é o que segura os frames quando tem centenas de entidades na tela.
  • Quando confiar nele, defina verboseLog: false pra silenciar o log.

Conferindo se está funcionando

  1. Inicie o servidor e procure a linha de setup: QuantumHy 0.2.1 setup. config: verboseLog=true tickInterval=5s ... densityLow=1.0/ch densityHigh=4.0/ch baseline=10% ... entityLod=2.00x ...
  2. Depois a linha de início do runtime: QuantumHy runtime started (interval=5s, hardCap=0, min=6, max=32, scan=4, entityRadius=true).
  3. 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.
  4. Com verboseLog=true, cada passada loga uma linha por jogador. Lendo: Durkz_z 312/81ch 3.9/ch~2.7 cl 14->13 ent 448->404 [density] significa 312 entidades em 81 chunks (3,9 por chunk, suavizado pra 2,7), raio de visão em chunks indo de 14 pra 13, raio de entidades indo de 448 pra 404 blocos, motivo density.
  5. Em área aberta o motivo aparece como [open] e os dois valores ficam no teto; numa multidão eles caem, com [density-min] quando batem no piso.

Licença

Licença MIT