Skip to main content

Acknowledgment System

The Acknowledgment System verifies that your character data was successfully received and applied by other players. It provides reliability and transparency in the synchronization process.

What It Does​

The Acknowledgment System:

  • Verifies that sent data was received by the target player
  • Confirms that the data was successfully applied
  • Tracks acknowledgment success rates and performance metrics
  • Provides detailed error codes when acknowledgments fail
  • Automatically retries failed acknowledgments
  • Batches acknowledgment requests for efficiency

Why It Matters​

Before the Acknowledgment System:

  • You sent data but couldn't be sure if it was received
  • Failed syncs were difficult to diagnose
  • No visibility into sync reliability

With the Acknowledgment System:

  • You know exactly when your data was successfully applied
  • Failed syncs are clearly identified with specific error codes
  • You can track your overall sync reliability
  • Automatic retries improve success rates

How It Works​

Hash-Based Verification​

Each data packet includes a cryptographic hash:

  • Sender: Calculates hash of data before sending
  • Receiver: Verifies hash upon receiving data
  • Confirmation: Receiver sends acknowledgment with hash verification
  • Validation: Sender confirms the hash matches, ensuring data integrity

Session-Aware Tracking​

Acknowledgments are tracked per session:

  • Each connection has its own acknowledgment state
  • Session IDs prevent cross-session confusion
  • Clean tracking even with reconnections
  • Accurate metrics per connection

Batch Processing​

For efficiency:

  • Multiple acknowledgment requests are batched together
  • Reduces network overhead
  • Improves performance
  • Maintains accuracy

Timeout Handling​

When acknowledgments fail:

  • Automatic retry with exponential backoff
  • Configurable timeout periods
  • Detailed error codes for troubleshooting
  • Metrics tracking to identify problematic connections

Error Codes​

The system provides specific error codes when acknowledgments fail:

  • Timeout: No response within expected time
  • Hash Mismatch: Data was corrupted during transfer
  • Application Failed: Data was received but couldn't be applied
  • Permission Denied: Target player blocked the data (TODO)

Metrics and Monitoring​

Track your sync health:

  • Success rate: Percentage of successful acknowledgments
  • Average latency: Time from send to acknowledgment
  • Failure breakdown: Distribution of error types
  • Per-pair metrics: Individual connection statistics

Configuration​

Configure acknowledgment behavior in settings:

  • Notification settings: Choose when to receive acknowledgment notifications
  • Timeout duration: Adjust how long to wait before retrying
  • Retry attempts: Set maximum number of retry attempts
  • Admin check: Enable admin-only access to acknowledgment monitor

Debug UI​

The Status Debug UI provides detailed acknowledgment information:

  • Real-time acknowledgment status for all pairs
  • Failed acknowledgment history with error codes
  • Performance metrics and timing data
  • Manual acknowledgment triggers for testing

Tips​

  • Check the acknowledgment monitor if you suspect sync issues
  • High failure rates may indicate network problems
  • Hash mismatches suggest data corruption - check your file cache
  • Use the metrics to identify problematic connections