> For the complete documentation index, see [llms.txt](https://axiomemu.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://axiomemu.gitbook.io/docs/data/game-data-sync.md).

# Game Data Sync

How the server pushes config to the client at login, and why that matters for admin workflow

The GameServer ships most gameplay-critical config **to the client** at login instead of relying on client-side data files. This is why editing a single XML or `.txt` on the server changes behavior for every player without patching the client.

Understanding what gets synced, when it syncs, and what does not sync is essential for predicting whether your edit takes effect immediately, on next login, after a GameServer restart, or after a full patch.

## What Gets Synced

At login, the server sends the following data blocks to the client. All blocks travel over opcode `0xEC` and each block's payload is zlib-compressed and then split into fixed-size chunks for delivery:

| Block                                                          | Source file                                                                                                                                    |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Skills                                                         | [Skill.txt](/docs/data/skill.md)                                                                                                               |
| Gates / warps                                                  | [Gate.txt](/docs/data/gate.md)                                                                                                                 |
| Move commands (teleport list)                                  | [Move.txt](/docs/data/gate/move.md)                                                                                                            |
| Item database (base item stats)                                | [Item.xml](/docs/data/item/item.md)                                                                                                            |
| Set item mapping and options                                   | [SetItemType.xml](/docs/data/item/setitemtype.md), [SetItemOption.xml](/docs/data/item/setitemoption.md)                                       |
| Chaos mix recipes                                              | [ChaosMix plugin](/docs/data/plugins/chaosmix.md)                                                                                              |
| Stackable items                                                | [ItemStack.xml](/docs/data/item/itemstack.md)                                                                                                  |
| Custom item visuals                                            | [CustomItemVisual.xml](/docs/data/plugins/customitemvisual.md)                                                                                 |
| Item option names                                              | [ItemOptionNames.xml](/docs/data/item/itemoptionnames.md), otherwise synthesized from the item option tables                                   |
| Item option filter rules                                       | [ItemOption.xml](/docs/data/item/itemoption.md)                                                                                                |
| 380 item definitions                                           | [380ItemType.xml](/docs/data/item/380itemtype.md)                                                                                              |
| Socket item options                                            | [SocketItemOption.xml](/docs/data/item/socketitemoption.md)                                                                                    |
| Socketable item types                                          | [SocketItemType.xml](/docs/data/item/socketitemtype.md)                                                                                        |
| Minimap NPC / portal positions                                 | derived from [Monster.xml](/docs/data/monster/monster.md) + [Gate.txt](/docs/data/gate.md)                                                     |
| Harmony options                                                | [JewelOfHarmonyOption.xml](/docs/data/item/jewelofharmonyoption.md)                                                                            |
| Item move permissions                                          | [ItemMove.xml](/docs/data/item/itemmove.md)                                                                                                    |
| Custom monster visuals                                         | [CustomMonsterVisual.xml](/docs/data/plugins/custommonstervisual.md)                                                                           |
| Item effect buffs                                              | [ItemEffect.xml](/docs/data/plugins/itemeffect.md)                                                                                             |
| Consumable effect buffs                                        | [Effect.xml](/docs/data/effect.md)                                                                                                             |
| Custom jewels                                                  | [CustomJewel.xml](/docs/data/plugins/customjewel.md)                                                                                           |
| Bracket-event entry gates (DS/BC/CC/IT)                        | [Event.dat](/docs/gameserver/event-dat.md)                                                                                                     |
| Custom quest catalog                                           | [CustomQuests](/docs/data/plugins/customquests.md)                                                                                             |
| Per-mesh-page item effect overrides                            | [ItemPageEffects.xml](/docs/data/item/itempageeffects.md)                                                                                      |
| MuHelper price / interval config                               | [Common.dat](/docs/gameserver/common-dat.md)                                                                                                   |
| Downgrade flags                                                | [Downgrade.xml](/docs/data/plugins/downgrade.md)                                                                                               |
| Custom pets and mounts                                         | [CustomPets.xml](/docs/data/plugins/custompets.md)                                                                                             |
| Tooltip labels, colors and borders                             | [TooltipExpansion.xml](/docs/data/plugins/tooltipexpansion.md)                                                                                 |
| Per-map display names                                          | [MapManager.xml](/docs/data/mapmanager.md) `Name=""`                                                                                           |
| Item effect emitters                                           | [ItemEmitters.xml](/docs/data/plugins/itememitters.md)                                                                                         |
| Item implicits (resolved value tables)                         | [ItemImplicit.xml](/docs/data/plugins/itemimplicit.md)                                                                                         |
| Display strings (ids from 10000)                               | [GameStrings.xml](/docs/data/gamestrings.md)                                                                                                   |
| Item quality tiers and multipliers                             | `Plugins/Items/ItemTiers.xml` (paid Item Tier module)                                                                                          |
| Talent tree catalog (layout, categories, nodes)                | `Plugins/Characters/TalentTree.xml`                                                                                                            |
| Dungeon catalog (ladders, tiers, levels, fees, schedules)      | [Dungeons](/docs/data/plugins/dungeons.md) - empty when the module is not licensed                                                             |
| Achievement catalog (categories, achievements, tiers, rewards) | [Achievements](/docs/data/plugins/achievements.md) - empty when the module is not licensed; per-character progress is sent separately at login |
| Monster affixes and tiers (names, tints, glows, tooltips)      | [MonsterAffix.xml](/docs/data/plugins/monsteraffix.md)                                                                                         |
| Inscription entries                                            | `Plugins/Inscription/Pools.xml` (paid Inscription module) - empty when not licensed or disabled                                                |
| Custom skills (look, cast, effects, tooltip)                   | `Plugins/Characters/CustomSkills.xml`                                                                                                          |
| Monster walk speeds                                            | [Monster.xml](/docs/data/monster/monster.md) `MoveSpeed` - the client walks monsters at the server's pace                                      |
| Potion restore rates (item tooltip)                            | the `*PotionRate` keys in [Common.dat](/docs/gameserver/common-dat.md)                                                                         |
| Item level damage/defense curve (item tooltip)                 | `Plugins/Items/ItemLevelCurve.xml`                                                                                                             |

The data sync protocol is currently version 47 (block types 0 to 41). The GameServer and client must be built for the same version, so always update both together.

A separate timing-configuration packet is pushed alongside these blocks: attack-speed formula parameters, MuHelper minimum level, the CS-skills-in-all-maps flag, and `KeepSkillBelowLearnReq` (whether the client greys out learned skills whose stat requirements are no longer met) - all from [Common.dat](/docs/gameserver/common-dat.md).

Blocks are delivered over the normal game connection immediately after login. The client caches them for the session.

## Transport

Each block moves in three phases:

1. **Header** announces the block type, uncompressed size, compressed size, record count, and a protocol version byte.
2. **Chunks** carry the compressed payload. Each chunk carries an index and total-chunk count so the client can reassemble in order. A chunk holds under 8 KB of payload.
3. **Completion** notifies the client the block finished, with a success flag and the total record count for validation.

The server caches both the raw-serialized and compressed form of each block at startup, so every player's login shares the same pre-built buffers. An empty block (0 records) is still announced so the client knows the data type was processed.

## What Does Not Get Synced

Anything that is server-authoritative combat or logic does not sync - the server handles it internally and the client only receives the outcomes.

Examples:

* All damage math ([Character.dat](/docs/gameserver/character-dat.md), [Skill.dat](/docs/gameserver/skill-dat.md), [SkillDamage.txt](/docs/data/skill/skilldamage.md))
* Monster stats and AI ([Monster.xml](/docs/data/monster/monster.md), MonsterAI\* files). Only the `MoveSpeed` column of Monster.xml is synced (see the table above); HP, damage, defense and the rest stay on the server
* Drop rates, event schedules, map properties ([MapManager.xml](/docs/data/mapmanager.md), [Event.dat](/docs/gameserver/event-dat.md), [Event/\*](/docs/data/event.md)). MapManager.xml map display names are the one synced part
* Account and character persistence (handled by DataServer)
* Chat, trade, PK rules

Changing any of these files takes effect for all players once the GameServer reloads it (the matching `/reload` command, see below) or restarts. No client action needed.

## Effect Timing for Admin Edits

When you edit a server config, the time-to-effect depends on which bucket the file falls into:

| Category                                                                       | Edit takes effect after...                                                      |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| Server-authoritative file (Monster.xml stats, MapManager.xml, Event.dat, etc.) | The matching `/reload` command, or a GameServer restart                         |
| Synced file (Skill.txt, CustomItemVisual, etc.)                                | GameServer restart + each player's next login (or the reload steps below)       |
| Plugin with hot reload (ChaosMix, ResetSystem, SkillTweaks, etc.)              | `/reload plugins` (rebuilds the sync blocks too) + relog for synced plugin data |
| Client binary asset                                                            | Client patch + client relaunch                                                  |

The "synced file" row is the one that surprises admins. Edit [Skill.txt](/docs/data/skill.md), restart the GameServer, and **existing players keep the old skill data until they reconnect**. New players get the new data immediately.

### Reloading synced data without a restart

The GameServer builds the sync blocks once at startup. A normal `/reload` updates what the server uses, but most `/reload` commands do **not** rebuild the sync blocks, so players logging in afterwards still get the old client data. These reloads do rebuild their own block:

| Command           | Rebuilds the sync block for                                                                          |
| ----------------- | ---------------------------------------------------------------------------------------------------- |
| `/reload monster` | Monster walk speeds (Monster.xml `MoveSpeed`)                                                        |
| `/reload common`  | Potion restore rates (the `*PotionRate` keys in Common.dat)                                          |
| `/reload item`    | Item level damage/defense curve (ItemLevelCurve.xml)                                                 |
| `/reload plugins` | **Every** sync block, from what the server has loaded right now. It also reloads every plugin config |

So for any other synced file: run its own `/reload` first (for example `/reload skill`), then `/reload plugins` to rebuild the sync blocks. In every case, players already online keep the old data until they **relog**.

## Diagnosing Sync Issues

GameDataSync runs transparently over the normal game connection. Admins do not configure it. When a sync misbehaves, check the GameServer log for `[GameDataSync]` entries - the loader emits per-block success/failure lines there.

## Common Issues

* **Edit to Skill.txt works for new logins but not existing players** - expected. Synced files require relog for already-connected clients
* **Client says "item not found" for a newly added entry** - the sync block for that category failed to load before the player entered the world. Check GameServer log
* **Custom visual shows for one player but not another** - one logged in before the sync block was ready; they need to relog
* **Edit to server-authoritative file (e.g. Monster.xml HP or damage) not visible to players** - these values never sync to the client; the change does apply server-side (damage, HP, behavior). The client renders based on its local assets, so visible differences need a client patch. Monster.xml `MoveSpeed` is the exception: it is synced, so after `/reload monster` players see the new walk speed once they relog

## Cross-File Dependencies

Every page documenting a synced config file links back here to explain the relog semantic. If a page mentions "sync at login", this is the mechanism.

Related:

* [ServerList.xml](/docs/connectserver/serverlist-xml.md) and [ConnectServer.ini](/docs/connectserver/connectserver-ini.md) handle the pre-login routing that delivers the player to the GameServer that then runs this sync.
* [Common.dat](/docs/gameserver/common-dat.md) holds server-authoritative gameplay globals that are applied server-side instead of shipped in this sync.
* [MonsterSetBase](/docs/data/monster/monstersetbase.md) drives monster spawn positions that feed the minimap-NPC block.