HyTari Studios · Official configuration guide

Server Diagnostics

Validated cleanup always active, optional diagnostics only when needed.

Server Diagnostics is designed to correct specific, validated cases without becoming a generic cleanup system. The recommended profile is operational and quiet: EntityTracker cleanup ON, optional modules and debug OFF.

BEFORE YOU START

Getting started

STEP 01

Install and start

The generated configuration is already the recommended production profile.

STEP 02

Keep the validated cleanup enabled

Dropped Item Tracker Cleanup is the automatic module enabled by default; the other tools are optional.

STEP 03

Enable diagnostics only when needed

EntityTracker, world-transfer and ItemQuality diagnostics are investigation tools, not requirements.

Server Diagnostics follows a fail-open, narrow-fix philosophy: uncertain cases are left to Hytale instead of applying generic cleanup.

CHAPTER 01 · 1 EXAMPLES

Production profile

A clean configuration is already ready for normal use.

01PROPERTIES

Recommended production profile

On a clean installation the validated cleanup is active while optional protection and diagnostic tools remain disabled.

PROPERTIES
config.version=1
enabled=true

module.droppedItemTrackerCleanup.enabled=true
module.droppedItemTrackerCleanup.dryRun=false
module.flyingNpcRotationFix.enabled=false
module.flyingNpcRotationFix.debug=false

module.worldTransferDiagnostics.enabled=false
module.worldTransferDiagnostics.debug=false
module.entityTrackerDiagnostics.enabled=false
module.entityTrackerDiagnostics.debug=false
module.itemQualityMapping.enabled=false

mods/ServerDiagnostics/config.properties

WHAT IT DOES

On a clean installation the validated cleanup is active while optional protection and diagnostic tools remain disabled.

IMPORTANT BEHAVIOR

  • dryRun=false means the validated cleanup is actually active.
  • Deep diagnostics are not required for the cleanup to work.
  • The normal profile is designed to be quiet and lightweight.

CHAPTER 02 · 1 EXAMPLES

Flying NPC Rotation Fix

Optional protection that repairs only non-finite NaN/Infinity roll values on configured flying models.

01PROPERTIES

Flying NPC rotation correction

The optional module checks configured models when they enter ECS and repairs only non-finite rotation values.

PROPERTIES
module.flyingNpcRotationFix.enabled=true
module.flyingNpcRotationFix.debug=false

config.properties

WHAT IT DOES

The optional module checks configured models when they enter ECS and repairs only non-finite rotation values.

IMPORTANT BEHAVIOR

  • It does not change AI, pathfinding, velocity, spawn rules, or valid rotations.
  • The default eligible model prefix remains NPC/Flying_.
  • The module is disabled by default; enable it only when this protection is needed.

CHAPTER 03 · 1 EXAMPLES

Dropped Item Tracker Cleanup

Removes only already-invalid updates that can be safely correlated to removed dropped items.

01PROPERTIES

EntityTracker cleanup for dropped items

Runs between update queuing and packet sending, but only when an invalid reference can be safely correlated with an already removed dropped item.

PROPERTIES
module.droppedItemTrackerCleanup.enabled=true
module.droppedItemTrackerCleanup.dryRun=false
module.droppedItemTrackerCleanup.logToFile=true
module.droppedItemTrackerCleanup.summaryIntervalSeconds=300

config.properties

WHAT IT DOES

Runs between update queuing and packet sending, but only when an invalid reference can be safely correlated with an already removed dropped item.

IMPORTANT BEHAVIOR

  • It does not modify live dropped items, ItemStacks, quantities, pickup/despawn timers, or valid updates.
  • Unexpected conditions fail open so Hytale handles the case normally.
  • The 300-second summary interval avoids production spam.

CHAPTER 04 · 1 EXAMPLES

Deep diagnostics

Observation-only tools for EntityTracker/ECS and cross-world investigations.

01PROPERTIES

Enable deep diagnostics only temporarily

When investigating EntityTracker/ECS warnings you can enable the observation-only module.

PROPERTIES
module.entityTrackerDiagnostics.enabled=true
module.entityTrackerDiagnostics.debug=true

config.properties

WHAT IT DOES

When investigating EntityTracker/ECS warnings you can enable the observation-only module.

IMPORTANT BEHAVIOR

  • It can produce much more local telemetry and larger files.
  • World-transfer diagnostics and ItemQuality mapping are separate optional tools and remain disabled until needed.
  • After the investigation, return to the minimal profile.

CHAPTER 05 · 1 EXAMPLES

Logs and retention

One persistent file per category, compacted at startup and shutdown.

01PROPERTIES

Retention per category

The mod keeps one file per category and removes old records from that same file.

PROPERTIES
logs.retention.enabled=true
logs.retention.entityTrackerDays=9
logs.retention.entityArchetypesDays=15
logs.retention.dropTrackerCleanupDays=9
logs.retention.flyingNpcRotationDays=15

config.properties

WHAT IT DOES

The mod keeps one file per category and removes old records from that same file.

IMPORTANT BEHAVIOR

  • Compaction runs during initialization and clean shutdown.
  • It does not create endless daily files just to implement retention.
  • Logs stay local to the server and are not uploaded by the mod.

Before using an example

Automatic operation requires no player commands; the administrative status/stats/reload commands use dedicated permissions.

Logs may contain useful debugging context; review them before publishing.

Cleanup counters staying at zero does not necessarily mean the mod is not working; the target case may simply not have occurred.

Available admin commands: /serverdiagnostics status, /serverdiagnostics stats and /serverdiagnostics reload.

BACK TO TOP