HyTari Studios · Official configuration guide

Server Diagnostics

Targeted fixes always active, heavy 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: automatic fixes ON, deep diagnostics OFF.

START THE GUIDE MOD PAGE

BEFORE YOU START

Getting started

STEP 01

Install and start

The generated configuration is already the recommended profile.

STEP 02

Keep the fixes enabled

Rotation Fix and Tracker Cleanup are the validated automatic modules.

STEP 03

Enable debug only when needed

EntityTracker Diagnostics is an investigation tool, not a requirement.

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 fixes are active while expensive tools remain disabled.

PROPERTIES
enabled=true

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

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

module.entityTrackerDiagnostics.enabled=false
module.entityTrackerDiagnostics.debug=false

mods/ServerDiagnostics/config.properties

WHAT IT DOES

On a clean installation the validated fixes are active while expensive 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

Repairs only non-finite NaN/Infinity roll values on configured flying models.

01PROPERTIES

Flying NPC rotation correction

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

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_.
  • Keep debug off unless you are investigating a specific case.

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 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.
  • It records context about ECS archetypes, components, lifecycle, viewers, and correlations.
  • 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=3
logs.retention.entityArchetypesDays=5
logs.retention.dropTrackerCleanupDays=3
logs.retention.flyingNpcRotationDays=5

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

No player command or permission is required.

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.

BACK TO TOP