QuantumHy: server-side FPS helper for Hytale

QuantumHy makes your client run smoother in Hytale by cutting how much the server tells it to draw, and it adjusts that per player depending on where you are. Out in the open you keep your full view; in a crowded, expensive spot it pulls things in so your FPS does not tank.

The Hytale client is native, so no mod can touch the renderer. What a server mod can do is decide how much each client has to render, and that is the whole trick: fewer chunks and entities in view means fewer things to draw, which means more frames.

Two honest limits. It only helps where it is installed (your solo world, your own server, or a server that runs it), not on a server you merely join. And it never pushes your view past what you asked for: your own view radius is the cap, QuantumHy only ever pulls it down.

Performance

Client frametime capture on Hytale Client. Same test PC for every run below.

Test PC

Component	Spec
CPU	AMD Ryzen 5 3600
GPU	NVIDIA GeForce GTX 1650 4GB
RAM	16 GB (2×8 GB)

Stress route

Solo world, same stress route (birds and mobs on screen). Mod off vs QuantumHy default (~205s off, ~233s on).

Metric	Mod off	Mod on	Change
Average FPS	102	146	+43%
P5	51.6	91.1	+76%
P1	36.2	64.4	+78%
1% low average	14.0	19.8	+41%
Time under 60 FPS	25.3%	6.9%	−73% of that slice

Full tables and chart images

This is not a lab benchmark. Massive frametime spikes (500ms–1s+) still appear on both runs; QuantumHy helps sustained crowd load more than it removes one-off hitches.

Stress route mod off:

Stress route mod on:

Normal gameplay (0.2.1)

Solo world, normal session (~5 min each). No intentional stress route, just regular play. Mod off vs QuantumHy 0.2.1 default config.

Metric	Mod off	Mod on	Change
Average FPS	159.6	226.9	+42%
P5	111.1	178.1	+60%
P1	77.2	139.1	+80%
1% low average	43.7	111.7	+155%
Time under 60 FPS	2.2%	0.1%	−95% of that slice

Full tables and chart images

How it works

Every few seconds QuantumHy counts the entities in the chunks around each player as a stand-in for render cost, smooths that signal, and turns it into a single shrink factor. That one factor drives two levers at once:

The chunk view radius, so distant terrain stops streaming when it is busy.
The entity stream radius in blocks, so the server stops sending far-off mobs. This is independent of chunks and is where most of the gain comes from when you are looking at a crowd.

On top of that, a global entity LOD setting drops small and distant entities sooner. An optional per-player visible cap can keep only the nearest entities in view when crowds get extreme. When server tick time (MSPT) climbs, the pressure governor can trim render levers further until the server calms down.

In the open everything ramps back up to where you started. While you are still loading chunks (just joined, or sprinting), cuts are held and ambient spawn can pause so the client is not told to drop chunks it is busy loading.

Features

Adaptive chunk view radius driven by local entity density, capped at your own view radius
Adaptive entity stream radius in blocks, the big lever in mob-heavy areas
Global entity LOD culling that drops small and distant entities sooner
Entity cull system with vertical (Y) prune and optional per-player visible cap
Density smoothing so a moving player's view does not flip-flop
Chunk streaming smoothing so moving into new terrain does not hitch
Spawn stream pause while a player's chunks are still loading
MSPT pressure governor that trims render load when the server is under tick pressure
Automatic LeanCore coexistence so the two mods never fight over the same levers
/q command (status, help, perf) to see what it is doing live
Verbose server log that explains every decision per player per pass

Installation

Download QuantumHy-0.2.1.jar from the Files tab
Place it in your server's mods folder (or %AppData%\Hytale\UserData\Mods\ on Windows)
Start the server. Config is created as QuantumHy.json in the plugin data folder

Config

Everything lives in QuantumHy.json, created on first run. Defaults work out of the box: no hard view cap, adapt only when crowded. Set targetClientViewRadius above 0 to trade some view distance for FPS everywhere. Set verboseLog to false once you trust it. For a live look at what it is doing, use /q status in game or the console.

Found a bug? Issues

Running with LeanCore

Both mods can run together. Each one owns different levers so they are not fighting over the same fields. Defaults already line up: QuantumHy drives client view radius (leanCoreTakeover=true); LeanCore keeps hot/sim radius and memory. QuantumHy yields chunk streaming when LeanCore throughput governance is on. See the README for the ownership table and optional knobs (leanCoreTakeover, yieldToLeanCoreViewRadius).

Solo or your own server: leave the defaults. You only lose view distance when it is actually crowded.
Want FPS everywhere: set targetClientViewRadius to a value like 12 to 16 to cap view distance even in the open.
Watch the log for a pass or two to see density and view decisions, then set verboseLog to false.

License: MIT