HyTari Studios Ā· Official guide

Server Inventory Sync

Synchronize inventories across servers without relying on runtime indexes.

This base guide describes the already documented public behavior of the mod: shared inventory, player profile, anti-duplication locking, and semantic ItemQuality preservation across different registries.

START THE GUIDE MOD PAGE

BEFORE YOU START

Getting started

STEP 01

Install on participating servers

Use the same version on the nodes that should share the profile.

STEP 02

Connect the shared storage

Participating servers must use the same data backend expected by the release.

STEP 03

Test a complete transfer

Verify inventory, equipment, and quality values before opening the network.

This base guide deliberately does not invent configuration field names: the current mod repository is empty, so exact JSON details will be added only after the source/release binary is verified.

CHAPTER 01 Ā· 1 EXAMPLES

What it synchronizes

Inventory, armor, backpack, additional slots, and compatible profile data.

01FLOW

Shared profile across servers

The mod keeps supported profile elements synchronized across servers participating in the same system.

FLOW
Server A
  ā†“ save profile
Shared database
  ā†“ load profile
Server B

Mod behavior

WHAT IT DOES

The mod keeps supported profile elements synchronized across servers participating in the same system.

IMPORTANT BEHAVIOR

  • The goal is inventory continuity across hubs, survival, dungeons, arenas, or other servers.
  • Inventory, armor, backpacks, and supported additional slots are included.
  • Profile data added by compatible mods can be synchronized when the integration supports it.

CHAPTER 02 Ā· 1 EXAMPLES

Synchronization flow

Loading, saving, and transfers follow a protected lifecycle.

01SEQUENCE

Protected loading and saving

The profile is loaded and saved at controlled points in the player lifecycle to avoid concurrent overwrites.

SEQUENCE
JOIN / TRANSFER
ā†’ acquire lock
ā†’ load profile
ā†’ gameplay
ā†’ autosave / final save
ā†’ release lock

Runtime behavior

WHAT IT DOES

The profile is loaded and saved at controlled points in the player lifecycle to avoid concurrent overwrites.

IMPORTANT BEHAVIOR

  • The system is designed not to interrupt ordinary internal world changes.
  • Automatic saving reduces the potential data-loss window.
  • Loading/lock messages can inform the player when the profile is not yet available.

CHAPTER 03 Ā· 1 EXAMPLES

Locks and anti-duplication

The profile is protected from concurrent access during critical phases.

01RULE

Anti-concurrency lock

A profile must not be modified by two servers at the same time.

RULE
1 player UUID
ā†’ 1 active profile
ā†’ 1 valid lock
ā†’ no concurrent access

Internal safety

WHAT IT DOES

A profile must not be modified by two servers at the same time.

IMPORTANT BEHAVIOR

  • Locking protects against duplication and cross-server race conditions.
  • Transfer logic must complete the save and handoff before another server uses the profile.
  • Expired-lock or error cases are treated as safety conditions, not as a reason to load two copies.

CHAPTER 04 Ā· 1 EXAMPLES

Safe ItemQuality handling

Qualities are identified semantically instead of depending only on runtime indexes.

01EXAMPLE

Semantic ItemQuality preservation

The same quality can have different runtime indexes on servers with different mods or registries.

EXAMPLE
Server A: CustomEpic = runtime index 12
Server B: CustomEpic = runtime index 27

Sync uses the quality identity, not only 12/27.

ItemQuality mapping

WHAT IT DOES

The same quality can have different runtime indexes on servers with different mods or registries.

IMPORTANT BEHAVIOR

  • If the destination knows the original quality, it is reconstructed correctly.
  • If it cannot resolve it, a safe Common fallback is used while preserving the original identity when possible.
  • When the quality becomes available again, it can be restored.

CHAPTER 05 Ā· 1 EXAMPLES

Diagnostics

ItemQuality mapping can be logged when two servers do not resolve the same qualities.

01USAGE

Mapping diagnostics

When two servers have different registries, mapping logs help compare ItemQuality names and indexes.

USAGE
ItemQuality mapping diagnostics
ā†’ enable only for investigation
ā†’ compare server A / server B
ā†’ disable after testing

Optional diagnostics

WHAT IT DOES

When two servers have different registries, mapping logs help compare ItemQuality names and indexes.

IMPORTANT BEHAVIOR

  • Diagnostics help explain registry differences; they are not required for normal operation.
  • Avoid leaving detailed logging enabled without a reason.
  • This page will be completed with exact configuration fields once the current mod repository is realigned.

Before using an example

The core goal is profile safety, not simply copying slots.

ItemQuality preservation is designed specifically for networks with different registries.

We can replace the descriptive diagrams with the real configuration once the mod repository is realigned.

BACK TO TOP