QuantumHy

QuantumHy is a server-side mod that makes your client run smoother in Hytale. It works by cutting how much the server tells your client to draw, and it adjusts that per player depending on where you are.

Status

Active. The current development build targets small servers and solo worlds. Runtime behavior and config migration are covered by unit tests, but performance numbers below remain historical captures from earlier releases until the current build gets a new paired client capture.

Known limitations

• The server does not receive the client's FPS, so QuantumHy responds to entity density, streaming backlog, visible entity pressure, and server MSPT instead.
• /q optimize off disables every per-player lever for that player. Explicit server-wide admin controls such as world levers, spawn pause, and global LOD still affect the whole world.

How it actually works

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's the whole trick here: fewer chunks and entities in view means fewer things to draw, which means more FPS.

Two honest limits:

• It only helps where it's installed. Your singleplayer world, your own server, or a server that runs it. If you just join someone else's server, this can't do anything there.
• It never pushes your view further than you asked for. Your own view radius is the cap. QuantumHy only ever pulls it down, never up.

What it does

Every few seconds it checks how crowded the area around each player is (lots of entities means expensive to render) and turns that into one shrink factor for two levers: chunk view radius and entity stream radius.

• Packed area: both levers pull in toward the minimum. At full shrink the entity radius drops to the floor in one pass, not over many ticks.
• Out in the open: expand is allowed only after load has been calm for a couple of passes, at least half the density scan is loaded, you are not flying, and the world is not hitching. Radius never jumps from min to full in one pass (at most +1 chunk per check).
• Joining, streaming, or moving fast: it skips the density walk and holds expand so the client is not told to drop chunks it is still loading.
• World hitching (high MSPT): expand stays frozen and shrink can step faster until both the recent average and the last tick are calm.

Out of the box there's no hard cap. If you'd rather trade some view distance for FPS everywhere, set targetClientViewRadius above 0.

It also smooths how fast chunks stream to you, so moving into fresh terrain arrives spread out instead of in one burst that makes the client hitch. That's the smoothChunkStreaming keys below.

Each player can use /q optimize on|off. The preference is stored by UUID and does not change how QuantumHy treats anyone else.

Performance

Client frametime capture on the Hytale Client process. Same test PC for every run below. Not lab benchmarks: different sessions, real play, spikes still happen.

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). QuantumHy disabled vs default config enabled. Run lengths differ slightly (~205s off, ~233s on).

At a glance

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

P95 stayed high on both runs (~277 off, ~271 on). The big win is less time spent under 60 FPS and higher floor percentiles when the scene is busy. Massive frametime spikes (500ms–1s+) still show up on both runs, so QuantumHy helps sustained crowd load more than it removes one-off hitches.

Full capture

Metric	Mod off	Mod on
Recording length	~205 s	~233 s
Average FPS	102	146.1
P95	276.7	271.1
P5	51.6	91.1
P1	36.2	64.4
1% low average	14.0	19.8
P0.2	28.3	40.4
P0.1	21.6	30.7
0.1% low average	2.4	3.0
Stuttering (time)	5.3% (10.7 s)	5.5% (12.8 s)
Smooth	94.6%	94.5%
Under 240 FPS	94.4%	92.4%
Under 60 FPS	25.3%	6.9%
Under 30 FPS	5.5%	4.8%
Under 10 FPS	4.0%	4.5%
Frametime variance < 2 ms	70.0%	86.5%

Charts

Each capture is the full session: frametime graph on top, plus one analysis panel below.

Mod off

Mod on

Video

Mod off: https://www.youtube.com/watch?v=H6Vns8b4hAg

Mod on: https://www.youtube.com/watch?v=CKGlXmX1M6k

Normal gameplay (0.2.1)

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

At a glance

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

The 0.2.1 recalibration is meant for real exploration, not only mob piles: higher average FPS, a much higher floor (P5/P1), less time under 60 FPS, and tighter frametime consistency (87.8% → 95.1% of frames with <2 ms variance). Chunk-load hitches still show up on both runs; the mod cuts how long you sit in them.

Full capture

Metric	Mod off	Mod on
Session length	~5 min	~5 min
Average FPS	159.6	226.9
P95	219.7	272.7
P5	111.1	178.1
P1	77.2	139.1
1% low average	43.7	111.7
P0.2	51.5	105.5
P0.1	45.1	90.5
0.1% low average	11.6	61.9
Stuttering (time)	1.9%	0.2%
Smooth	98.1%	99.8%
Under 240 FPS	99.5%	64.3%
Under 60 FPS	2.2%	0.1%
Under 30 FPS	1.2%	0.1%
Under 10 FPS	1.0%	0.0%
Frametime variance < 2 ms	87.8%	95.1%

Charts

Mod off

Mod on

Config

Lives in QuantumHy.json in the plugin data folder, created on first run.

Key	Default	What it does
enabled	true	Turn the whole thing on or off.
verboseLog	false	Log every pass with each player's density and view decision. Off on new installs.
checkForUpdates	true	Notify operators or QuantumHy admins when the mod page lists a newer JAR.
tickIntervalSeconds	5	How often it re-checks each player.
initialDelaySeconds	20	Wait this long after start before the first pass.
targetClientViewRadius	0	Hard cap in chunks. 0 means no cap, just adapt.
minClientViewRadius	6	Never pull anyone below this.
maxClientViewRadius	32	Ceiling for the hard cap (your own view radius still wins).
adaptiveTerrainViewEnabled	true	Adapt terrain view radius during normal play.
emergencyTerrainTrimEnabled	true	Allow temporary terrain trim after sustained visual pressure.
densityScanChunkRadius	4	How many chunks around you it counts entities in.
densityLowPerChunk	1.0	Weighted entities per chunk at or below this: you get the full radius (minus optional baseline).
densityHighPerChunk	4.0	Weighted entities per chunk at or above this: you get pulled to the minimum.
densityRingWeighting	true	Count center chunks fully, outer scan rings less (no per-species tables).
densityRingEdgeWeight	0.55	Ring weight at the scan edge when ring weighting is on (1.0 = flat count).
baselineShrinkFraction	0.10	Minimum shrink even in "open" density (0 = off).
chunkLoadShrinkEnabled	true	Extra shrink from loaded + streaming section count (render backlog).
chunkLoadLowChunks	700	Loaded + loading sections at or below this: no chunk-load shrink.
chunkLoadHighChunks	1550	At or above this section count: chunk-load shrink hits full strength.
densitySmoothing	0.4	Smooths the density signal so a moving player's view doesn't flip-flop. Lower is smoother; 1.0 is off.
adaptEntityRadius	true	Also shrink how far entities are streamed (not just chunks). The big win in mob-heavy spots.
minEntityViewBlocks	48	Never stream entities closer than this, in blocks (16 blocks = 1 chunk).
entityLodAggressiveness	1.0	Explicit global entity LOD override. 1.0 keeps the engine default.
maxEntityVerticalDistance	32	Drop entities too far above/below you from the stream (caves, ceilings). 0 = off.
maxVisibleEntitiesPerPlayer	80	Cap streamed entities per player in crowds (0 = off).
holdSpawnOnLoadingChunks	false	Pause environmental spawning during a heavy client stream backlog. Global admin control.
minViewRadiusDelta	2	Don't bother changing the view for tiny differences. Ramped +1 expands still apply.
maxExpandChunksPerPass	1	Max chunks the client view radius may increase in one pass.
maxShrinkChunksPerPass	2	Max chunks it may decrease in one pass (doubled under MSPT pressure).
maxExpandEntityBlocksPerPass	16	Max entity-stream blocks the radius may increase in one pass.
expandHysteresisPasses	2	Calm passes required before an expand is allowed.
worldPassBudgetMs	8	Wall-clock budget for radius writes on the world thread. 0 disables the cap.
pressureExitRequiresLastTick	true	Pressure only exits when both the 10s MSPT average and the last tick are calm.
respectStreamingGrace	true	Don't shrink while you're still loading chunks.
streamingBacklogThreshold	80	How many loading sections counts as "still streaming".
smoothChunkStreaming	true	Spread chunk streaming out so moving into new terrain doesn't hitch.
maxChunksPerSecond	128	Cap on sections streamed per second to a managed client. 0 keeps the engine default.
maxChunksPerTick	8	Cap on sections streamed per tick. 0 keeps the engine default.
streamCatchUpEnabled	true	Raise the managed cap temporarily after fast travel while MSPT is healthy.
streamCatchUpIntervalMs	250	Interval for the lightweight stream controller.
streamCatchUpPerSecond	256	Temporary healthy catch-up cap per second.
streamCatchUpPerTick	12	Temporary healthy catch-up cap per tick.
streamCatchUpHoldMs	1500	Minimum time to hold catch-up after fast movement.
leanCoreTakeover	true	If LeanCore is installed, take the view radius over from it (see below).
yieldToLeanCoreViewRadius	false	The opposite: leave the view radius to LeanCore (see below).
pressureGovernorEnabled	true	Tighten render levers when world MSPT stays high.
pressureMsptEnter	48	10s average MSPT at or above this enters pressure mode.
pressureMsptExit	43	MSPT at or below this exits pressure mode (hysteresis).
pressureSustainSeconds	4	How long MSPT must stay high before levers tighten.
pressureCooldownSeconds	15	How long MSPT must stay low before levers restore.
pressureDensityMultiplier	1.45	Under pressure, density thresholds tighten by this factor.
pressureChunkRateMultiplier	0.75	Under pressure, multiply chunk streaming caps.
pressureLodMultiplier	1.15	Pressure multiplier used only with an explicit global LOD value above 1.0.
pressureVerticalTrimBlocks	8	Under pressure, subtract from maxEntityVerticalDistance.
pressureWorldLevers	false	Under pressure, pause NPC spawn and block tick on the world config (restored on release).
pressureTrimClientEffects	false	Under pressure, trim bloom/sunshaft client effects (restored on release).
pressureEffectScale	0.5	Multiplier for client effect intensities while trimmed.

Running with LeanCore

Both mods can run together. Each one owns different levers, so they are not fighting over the same ChunkTracker or Player fields.

Lever	Who drives it (typical setup)
Client view radius	QuantumHy when leanCoreTakeover=true (default). QuantumHy turns off LeanCore view governance on startup.
Entity stream radius	QuantumHy
Hot/simulation radius	LeanCore
Chunk send rate (maxChunks/s, maxChunks/tick)	QuantumHy when smoothChunkStreaming=true (default)
MSPT render trim (density, LOD, vertical, effects)	QuantumHy
Spawn stream pause	QuantumHy
Zone dormancy / memory	LeanCore

Defaults on both mods already line up: leanCoreTakeover=true, QuantumHy smoothChunkStreaming=true, LeanCore handling sim/memory. No extra LeanCore config required for a normal install.

Knobs if you need them

• leanCoreTakeover (default true): QuantumHy drives client view radius and disables LeanCore view governance. Set false only if you want LeanCore on view radius instead (both mods may conflict).
• yieldToLeanCoreViewRadius (default false): QuantumHy stays out of view radius and chunk send-rate entirely. Use this if you deliberately want LeanCore in charge of those levers.

Do not flip on QuantumHy pressureWorldLevers alongside LeanCore unless you mean to pause NPC spawn and block tick under MSPT. LeanCore does not touch those flags.

/q status shows live ownership (chunkRateOwner=, LeanCore: view=...) and the last adaptive pass per player.

Commands

• /q optimize on|off (aliases /quantumhy, /qhy): persistently enable or disable per-player optimization for yourself.
• /q status: players see only their own mode and last decision. Admins and console see full server diagnostics.
• /q help: lists the commands.

Build

You need a Hytale install (that's where HytaleServer.jar comes from) and JDK 25.

./gradlew build

The jar lands in build/libs/. Drop it in %AppData%\Hytale\UserData\Mods\ on Windows.

Links

• Mod page
• Docs
• GitHub
• CurseForge

License

MIT. See LICENSE.