> 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

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                       | synthesized from 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)                                              |
| 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)                                                               |

A separate timing-configuration packet (attack-speed formula parameters, MuHelper minimum level, CS-skills-in-all-maps flag) is pushed alongside these blocks.

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)
* Drop rates, event schedules, map properties ([MapManager.xml](/docs/data/mapmanager.md), [Event.dat](/docs/gameserver/event-dat.md), [Event/\*](/docs/data/event.md))
* Account and character persistence (handled by DataServer)
* Chat, trade, PK rules

Changing any of these files takes effect for all players after the GameServer restart, 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, MapManager.xml, Event.dat, etc.) | GameServer restart                            |
| Synced file (Skill.txt, CashShop, CustomItemVisual, etc.)                | GameServer restart + each player's next login |
| Plugin with hot reload (ChaosMix, ResetSystem, SkillSpeedScale, etc.)    | Admin reload command                          |
| 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.

## 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) not visible to players** - server-authoritative files never sync to 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

## 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.