HyFixes

Essential bug fixes for Hytale Early Access servers. Prevents crashes and player kicks caused by known issues in Hytale's core systems.

BUG REPORTS SUBMITTED ON CURSEFORGE WILL BE IGNORED. PLEASE USE GITHUB. IF YOU NEED MY ATTENTION GO TO DISCORD.

Support

Need help? Join our Discord for community support!

Discord: https://discord.gg/6g7McTd27z

Found a bug? Report it on GitHub:

GitHub Issues: https://github.com/John-Willikers/hyfixes/issues

Installation

HyFixes consists of two plugins that work together:

Runtime Plugin (Required)

The main plugin that fixes most crashes.

Download hyfixes.jar
Place in your server's mods/ folder
Restart the server

Early Plugin (Recommended)

Fixes deep networking bugs that cause combat/interaction desync.

Download hyfixes-early.jar
Place in your server's earlyplugins/ folder
Start the server with one of these options:
- Set environment variable: ACCEPT_EARLY_PLUGINS=1
- OR press Enter when you see the early plugins warning at startup

What Gets Fixed

Runtime Plugin

Pickup Item Crash - World thread crash when player disconnects while picking up item
RespawnBlock Crash - Player kicked when breaking bed/sleeping bag
ProcessingBench Crash - Player kicked when bench is destroyed while open
Instance Exit Crash - Player kicked when exiting dungeon with corrupted data
Chunk Memory Bloat - Server runs out of memory from unloaded chunks
CraftingManager Crash - Player kicked when opening crafting bench
InteractionManager Crash - Player kicked during certain interactions
Quest Objective Crash - Quest system crashes when target despawns
SpawnMarker Crash - World crash during entity spawning

Early Plugin (Bytecode Fixes)

Sync Buffer Overflow - Fixes combat/food/tool desync (400-2500 errors per session)
Sync Position Gap - Fixes "out of order" exception that kicks players
Instance Portal Race - Fixes "player already in world" crash when entering portals
Null SpawnController - Fixes world crashes when spawn beacons load
Null Spawn Parameters - Fixes world crashes in volcanic/cave biomes
Duplicate Block Components - Fixes player kicks when using teleporters
Null npcReferences (Removal) - Fixes crash on spawn marker removal
Null npcReferences (Constructor) - ROOT CAUSE FIX: Initializes array in SpawnMarkerEntity constructor
BlockCounter Not Decrementing - Fixes teleporter limit stuck at 5
WorldMapTracker Iterator Crash - Fixes server crashes every ~30 min on high-pop servers

Verifying Installation

Runtime Plugin

Look for these messages in your server log at startup:

[HyFixes|P] Plugin enabled - HyFixes vX.X.X
[HyFixes|P] [PickupItemSanitizer] Active - monitoring for corrupted pickup items
[HyFixes|P] [ChunkCleanupSystem] Active on MAIN THREAD

Early Plugin

Look for these messages in your server log at startup (10 transformers):

[HyFixes-Early] Transforming InteractionChain class...
[HyFixes-Early] InteractionChain transformation COMPLETE!

[HyFixes-Early] Transforming World class...
[HyFixes-Early] World transformation COMPLETE!

[HyFixes-Early] Transforming SpawnReferenceSystems$BeaconAddRemoveSystem...
[HyFixes-Early] SpawnReferenceSystems transformation COMPLETE!

[HyFixes-Early] Transforming BeaconSpawnController...
[HyFixes-Early] BeaconSpawnController transformation COMPLETE!

[HyFixes-Early] Transforming BlockComponentChunk...
[HyFixes-Early] BlockComponentChunk transformation COMPLETE!

[HyFixes-Early] Transforming SpawnReferenceSystems$MarkerAddRemoveSystem...
[HyFixes-Early] MarkerAddRemoveSystem transformation COMPLETE!

[HyFixes-Early] Transforming SpawnMarkerEntity...
[HyFixes-Early] SpawnMarkerEntity transformation COMPLETE!

[HyFixes-Early] Transforming TrackedPlacement$OnAddRemove...
[HyFixes-Early] TrackedPlacement transformation COMPLETE!

[HyFixes-Early] Transforming WorldMapTracker...
[HyFixes-Early] WorldMapTracker transformation COMPLETE!

Admin Commands

Command	Description
`/hyfixes`	Show HyFixes statistics and crash prevention counts
`/chunkstatus`	Show loaded chunk counts and memory info
`/chunkunload`	Force immediate chunk cleanup
`/fixcounter`	Fix/view teleporter BlockCounter values

Aliases: /hfs, /interactionstatus, /fc, /blockcounter

Troubleshooting

Plugin not loading

Check that the JAR is in the correct folder:
- Runtime plugin: mods/hyfixes.jar
- Early plugin: earlyplugins/hyfixes-early.jar
Check server logs for errors during startup
Verify Java 21+ is installed: java -version

Early plugin warning at startup

This is normal! Hytale shows a security warning for early plugins because they can modify game code. HyFixes only modifies the specific buggy methods to fix them.

To bypass the warning:

Set ACCEPT_EARLY_PLUGINS=1 environment variable
OR press Enter when prompted

Still seeing crashes

Check which version of HyFixes you have: /hyfixes
Update to the latest version
Report the crash on GitHub with:
- Full server log showing the error
- Steps to reproduce (if known)
- HyFixes version

Compatibility

Hytale: Early Access (2025+)
Java: 21 or higher
Side: Server-side only (no client install needed)

More Information

For detailed technical documentation, source code, and contribution guidelines:

GitHub Repository: https://github.com/John-Willikers/hyfixes

Full Bug Documentation: https://github.com/John-Willikers/hyfixes/blob/main/BUGS_FIXED.md

Support the Project

Star the repo on GitHub
Report bugs you encounter
Join our Discord community
Share HyFixes with other server admins!

Discord: https://discord.gg/6g7McTd27z

Hyfixes