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, such as your solo world, your own server, or a server that runs it. It does not help on a server you merely join. It also never pushes your view past what you asked for: your own view radius is the cap, and QuantumHy only ever pulls it down.

Performance

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

Test PC

Stress route

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

Full tables and chart images: https://github.com/DurkzPRG/QuantumHy#stress-route

This is not a lab benchmark. Massive frametime spikes of 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 of about five minutes each. No intentional stress route, just regular play. Mod off vs QuantumHy 0.2.1 default config.

Full tables and chart images: https://github.com/DurkzPRG/QuantumHy#normal-gameplay-021

The 0.2.1 recalibration targets real exploration, not only mob piles: higher average FPS, a much higher floor through P5 and P1, and less time under 60 FPS. Chunk-load hitches still show up on both runs.

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 shrink factor. That factor drives two per-player levers:

• The chunk view radius, so distant terrain stops streaming when an area 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 looking at a crowd

An optional per-player visible cap can keep only the nearest entities in view when crowds get extreme. When server tick time rises, the pressure governor can trim configured per-player render levers further until the server calms down.

In the open, everything ramps back up to where you started. While a player is loading chunks after joining or moving quickly, QuantumHy holds cuts so it does not tell the client to drop chunks that are still loading. Ambient spawn pause and the global entity LOD override are optional admin settings and remain disabled by default.

Players who prefer the server's original per-player limits can use /q optimize off. Their choice persists across restarts in PlayerPreferences.json. Explicit global settings enabled by an admin can still affect the world.

Features

• Adaptive chunk view radius driven by local entity density and capped by each player's own view radius
• Adaptive entity stream radius in blocks, the main lever in mob-heavy areas
• Persistent per-player opt-out through /q optimize on and /q optimize off
• Optional global entity LOD override, disabled by default
• Entity cull system with vertical Y prune and an optional per-player visible cap
• Density smoothing and cache expiry so movement stays stable while stationary players still detect local changes
• Chunk streaming smoothing and recovery so temporary limits are restored after loading
• Optional spawn stream pause while a player's chunks are still loading
• MSPT pressure governor that can trim configured render levers while a world remains under pressure
• Multi-world pressure handling that uses the highest active pressure for global decisions
• Automatic LeanCore coexistence so both mods keep clear ownership of overlapping controls
• Update check on startup for operators or durkz.quantumhy.admin, configurable with checkForUpdates
• /q command with scoped status, optimization preference, and help
• Verbose diagnostic log through verboseLog, disabled by default

Installation

1. Download QuantumHy-0.3.0.jar from the Files tab
2. Place it in your server's mods folder, or %AppData%\Hytale\UserData\Mods\ for Windows solo play
3. Start the server. QuantumHy.json and PlayerPreferences.json are created in the plugin data folder

Commands

/q status
/q optimize on
/q optimize off
/q help

Aliases: /quantumhy, /qhy.

Regular players see their own optimization state with /q status. Admins with durkz.quantumhy.admin and the server console see the complete runtime report.

Config

Server settings live in QuantumHy.json. Per-player choices live in PlayerPreferences.json. Defaults work out of the box: no fixed view cap, adaptive changes only when local load justifies them, normal decision logs disabled, and no global entity LOD override.

Set targetClientViewRadius above 0 only if you want a fixed upper view limit everywhere. Enable verboseLog only while diagnosing behavior. Set checkForUpdates to false to skip the startup version check.

Full configuration reference: Config

Found a bug? Issues

Running with LeanCore

Both mods can run together. Each one owns different levers so they do not fight over the same fields. By default, QuantumHy owns the client view radius through leanCoreTakeover=true, while LeanCore keeps simulation, chunk throughput, and memory controls. QuantumHy yields chunk streaming when LeanCore throughput governance is on. leanCoreTakeover and yieldToLeanCoreViewRadius let the admin change that ownership explicitly.

Known limitations

• QuantumHy cannot read client FPS and cannot modify the native Hytale renderer
• /q optimize off disables per-player view and entity-stream adjustments, but explicit global controls enabled by an admin still affect the world
• Results depend on the scene, hardware, client settings, and server configuration

Recommended

• Solo or your own server: leave the defaults; view distance is reduced only when local load justifies it
• Prefer original per-player limits: use /q optimize off; use /q optimize on to enable the adjustments again
• Want a fixed view cap everywhere: set targetClientViewRadius to a value such as 12 to 16
• Diagnosing behavior: enable verboseLog temporarily, then disable it after checking the decisions

License: MIT