> 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/overlays.md). # Data Overlays The GameServer supports a **data overlay** mechanism that lets a single installation serve multiple worlds (for example a primary world plus a Castle Siege subserver) without duplicating configuration files. You point each GameServer process at a shared main folder and an optional small overlay folder containing only the files you want to change. Any file missing from the overlay is read from the main folder unchanged. This eliminates the old pattern of maintaining two parallel `Data\` folders that had to be kept in sync by hand. ## The Two Folder Roots There are **two independent folder roots**, each with its own optional overlay. An admin can override one, both, or neither. ### GameData (shared game content) The game content tree: item drops, monster spawns, plugin XML configs, map data, effects, messages, and so on. | Property | Value | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Default location | `..\Data\` relative to `GameServer.exe` (one folder up) | | Contains | [Item](/docs/data/item/item.md), [Monster](/docs/data/monster/monster.md), `MonsterSetBase\`, `MapManager.xml`, `MapServerInfo.xml`, [Effect.xml](/docs/data/effect.md), `Message.xml`, `Plugins\*.xml`, `Skill\`, [Event](/docs/data/event.md), etc. | ### GameServerData (server identity config) The per-server config tree. These are the six `GameServerInfo - *.dat` files that define the server name, port, code, license key, and event toggles. | Property | Value | | ---------------- | --------------------------------------------------------------------------------------------------------------- | | Default location | `Data\` next to `GameServer.exe` (i.e., `GameServer\Data\`) | | Contains | `GameServerInfo - Common.dat`, `- Character.dat`, `- Command.dat`, `- Custom.dat`, `- Event.dat`, `- Skill.dat` | {% hint style="info" %} **Which root does my file belong to?** If it's a `GameServerInfo - *.dat` file, it's in **GameServerData**. Everything else - plugin XMLs, item/monster data, drop tables, maps, effects - is in **GameData**. {% endhint %} ## How an Overlay Works An overlay is simply a second folder containing **only** the files you want to override. When the GameServer needs a file, it checks the overlay first. If the file exists there, it's used. If not, it falls back to the main folder. * Files present in the overlay → **overlay version is used** * Files absent from the overlay → **main version is used** * Zero duplication of anything you're not changing Each root has its own independent overlay setting, so you can overlay game content only, server config only, both, or neither. ## Configuration Sections You can configure overlay paths in three ways. When more than one is set, the highest-precedence source wins. ### 1. Command-Line Flags (highest precedence) Pass these when launching `GameServer.exe`. Both `--flag value` and `--flag=value` forms are accepted. | Flag | Purpose | | ---------------------------- | --------------------------------------- | | `--game-data ` | Override the GameData main folder | | `--game-data-overlay ` | Set the GameData overlay folder | | `--config ` | Override the GameServerData main folder | | `--config-overlay ` | Set the GameServerData overlay folder | ``` GameServer.exe --game-data-overlay D:\Servers\CS\Overlay\GameData --config-overlay D:\Servers\CS\Overlay\Config ``` ### 2. Environment Variables If no command-line flag is given, the GameServer checks these environment variables. | Variable | Equivalent Flag | | ---------------------- | --------------------- | | `GS_GAME_DATA` | `--game-data` | | `GS_GAME_DATA_OVERLAY` | `--game-data-overlay` | | `GS_CONFIG` | `--config` | | `GS_CONFIG_OVERLAY` | `--config-overlay` | ### 3. Common.dat Key (GameData overlay only) If neither a flag nor an environment variable sets the **GameData** overlay, the GameServer reads it from `GameServerInfo - Common.dat` inside the GameServerData folder: ```ini [GameServerInfo] GameDataOverlay = D:\Servers\CS\Overlay\GameData\ ``` {% hint style="warning" %} There is **no Common.dat key** for the GameServerData overlay. Common.dat itself lives inside the GameServerData folder, so it cannot sensibly override the folder it lives in. Use a command-line flag or environment variable for the config overlay. {% endhint %} ### Path Format * Absolute Windows paths (`D:\Servers\CS\Overlay\`) and relative paths both work. * Forward slashes and backslashes are interchangeable. * A trailing slash is optional. * An empty value disables the overlay. ## Important Behavior {% hint style="info" %} **Boot Log Confirmation**: On startup the GameServer logs the resolved GameData root, GameData overlay (or `(none)`), GameServerData root, and GameServerData overlay. **Always check these lines** after changing overlay settings to confirm your configuration loaded correctly. {% endhint %} {% hint style="warning" %} **Per-File, Not Per-Key**: The overlay replaces files whole. If you place `GameServerInfo - Common.dat` in an overlay, it must contain **every key** you want to apply - there is no per-key merging. A partial file in an overlay will leave unset keys at their defaults, not inherit them from the main file. {% endhint %} {% hint style="warning" %} **Silent Fallthrough**: If the overlay folder does not contain a given file, the GameServer reads it from the main folder with no warning. This is intentional - it's what makes "override only what you need" work - but it means a typo in an overlay filename will silently load the main file instead. The boot log is your first line of debugging. {% endhint %} {% hint style="info" %} **The Two Roots Are Independent**: You can set a GameData overlay without a GameServerData overlay, or vice versa, or both. Picking one does not force the other. {% endhint %} {% hint style="warning" %} **Plugin XMLs Are GameData, Not GameServerData**: If you want a subserver to use different drop tables, ChaosMix recipes, VIP benefits, or item effect configurations, those files go in a **GameData** overlay. The GameServerData overlay is only for the six `GameServerInfo - *.dat` files. {% endhint %} {% hint style="danger" %} **The Overlay Folder Must Exist**: The GameServer does not create the overlay folder for you. If you point it at a path that does not exist, every lookup falls through to the main folder as if the overlay were empty - your overrides will silently have no effect. {% endhint %} ## Examples {% tabs %} {% tab title="Single World (Default)" %} No overlay is needed. Launch `GameServer.exe` with no flags and the server reads: * **GameData** from `..\Data\` (one folder up from the exe) * **GameServerData** from `Data\` (next to the exe) ``` D:\Servers\Main\ ├── Data\ <- GameData (shared content) │ ├── Item\ │ ├── Monster\ │ ├── MapManager.xml │ └── Plugins\ └── GameServer\ ├── GameServer.exe └── Data\ <- GameServerData (server identity) ├── GameServerInfo - Common.dat ├── GameServerInfo - Event.dat └── ... ``` Launch: ``` GameServer.exe ``` Nothing new to configure. Existing installations keep working exactly as before. {% endtab %} {% tab title="Main + Castle Siege Subserver" %} The headline use case. One shared installation runs both worlds as separate processes. The Castle Siege world only differs in three settings: `EnableCastleSiege`, `ServerCode`, and `ServerPort`. **Folder layout:** ``` D:\Servers\ ├── Shared\ <- ONE copy of everything │ ├── Data\ <- GameData (shared by both worlds) │ │ ├── Item\ │ │ ├── Monster\ │ │ └── Plugins\ │ └── GameServer\ │ ├── GameServer.exe │ └── Data\ <- GameServerData for PRIMARY world │ ├── GameServerInfo - Common.dat (ServerCode=0, Port=55901, CS=0) │ └── ... └── CS-Overlay\ <- Tiny overlay for the CS process └── GameServerInfo - Common.dat (ServerCode=1, Port=55902, CS=1) ``` **Launch the primary world** (no overlay needed): ``` D:\Servers\Shared\GameServer\GameServer.exe ``` **Launch the Castle Siege subserver** (same exe, config overlay pointed at the tiny folder): ``` D:\Servers\Shared\GameServer\GameServer.exe --config-overlay D:\Servers\CS-Overlay ``` The CS process inherits every item, monster, drop table, plugin setting, chaos mix recipe, character config, and command from the shared folders. The only thing it overrides is the one `GameServerInfo - Common.dat` file in the overlay, which flips `EnableCastleSiege=1` and sets its own code and port. {% hint style="info" %} Any future change you make to the shared `Data\` folders automatically applies to **both** worlds on the next restart. No more forgetting to sync a second folder. {% endhint %} {% endtab %} {% tab title="Event Subserver with Custom Drops" %} An event world that uses all the same server settings but a different drop table and chaos mix recipe. ``` D:\Servers\ ├── Shared\ │ ├── Data\ │ │ └── Plugins\ │ │ ├── ItemDrop.xml │ │ └── ChaosMix.xml │ └── GameServer\ │ ├── GameServer.exe │ └── Data\ └── Event-GameData\ <- GameData overlay only └── Plugins\ ├── ItemDrop.xml (2x drop rates, event items) └── ChaosMix.xml (holiday recipe) ``` Launch the event process: ``` GameServer.exe --game-data-overlay D:\Servers\Event-GameData ``` Only those two plugin files are overridden. Items, monsters, maps, and every other GameData file come from the shared folder. The server identity (name, port, code) is whatever is in the main GameServerData folder - no config overlay is used here. {% endtab %} {% tab title="Both Overlays at Once" %} A subserver that needs **both** different server identity (for its own port and code) **and** different game content (for event drops). ``` D:\Servers\ ├── Shared\ │ ├── Data\ │ └── GameServer\ │ ├── GameServer.exe │ └── Data\ ├── Sub-Config\ <- GameServerData overlay │ └── GameServerInfo - Common.dat └── Sub-GameData\ <- GameData overlay └── Plugins\ └── ItemDrop.xml ``` Launch: ``` GameServer.exe --config-overlay D:\Servers\Sub-Config --game-data-overlay D:\Servers\Sub-GameData ``` Or equivalently with environment variables: ``` set GS_CONFIG_OVERLAY=D:\Servers\Sub-Config set GS_GAME_DATA_OVERLAY=D:\Servers\Sub-GameData GameServer.exe ``` The two roots are fully independent - you can mix and match as needed. {% endtab %} {% endtabs %} ## Common Issues {% hint style="warning" %} **Overlay not taking effect**: Check the boot log first. The GameServer prints the resolved GameData root, GameData overlay, GameServerData root, and GameServerData overlay on startup. If the overlay line shows `(none)` or the wrong path, your flag, environment variable, or Common.dat key did not reach the process. Remember that command-line flags win over environment variables, which win over the Common.dat key. {% endhint %} {% hint style="warning" %} **Typo in overlay filename**: If you name an overlay file `GameServerInfo - Commom.dat` (note the typo) or `ItemDrops.xml` instead of `ItemDrop.xml`, the GameServer silently falls through to the main file and your override has no effect. File names inside the overlay must match the main file names exactly. {% endhint %} {% hint style="warning" %} **Wrong root chosen**: Putting a plugin XML in a GameServerData overlay or a `GameServerInfo - *.dat` file in a GameData overlay does nothing - each root only checks its own overlay for its own files. If an override isn't applying, double-check you're putting the file in the right root. {% endhint %} {% hint style="warning" %} **Partial .dat file**: Remember the overlay is per-file, not per-key. If you copy `GameServerInfo - Common.dat` into the overlay and delete the keys you "don't care about," those keys will fall back to built-in defaults, not inherit from the main file. Always copy the **entire** file and then change the keys you want. {% endhint %} {% hint style="danger" %} **Overlay folder does not exist**: If the path you configured points to a folder that does not exist on disk, every lookup falls through to main as if no overlay were set. The boot log will still show the configured path, but no files will ever be loaded from it. Create the folder before launching. {% endhint %} {% hint style="info" %} **Castle Siege flag in the wrong place**: `EnableCastleSiege` lives in `GameServerInfo - Common.dat`, which is a **GameServerData** file. To enable it for a subserver only, use `--config-overlay`, not `--game-data-overlay`. {% endhint %} ## Multi-World Deployment Now that the overlay system exists, running multiple worlds from a single GameServer binary is straightforward. Each world is a separate `GameServer.exe` process launched with its own `--config-overlay` pointing at a folder containing a unique `GameServerInfo - Common.dat` (different `ServerName`, `ServerCode`, `ServerPort`). All processes share the same GameData folder and the same base GameServerData configs - no file duplication. ### Requirements * **One DataServer per world.** Game state (characters, items, guilds) is per-world, so each world needs its own DataServer instance or at minimum a separate database. * **Unique `ServerCode` and `ServerPort`** in each world's `GameServerInfo - Common.dat` overlay. * **ConnectServer routes players to worlds** via `ServerList.xml` - each world appears as its own server entry. * **No shared state between processes.** GameServer uses no shared mutexes or file locks, so multiple instances on the same machine do not conflict. ### Example: Main + Castle Siege {% tabs %} {% tab title="Folder Layout" %} ``` D:\Server\ ├── GameServer.exe (single binary, shared) ├── Data\ (GameServerData - shared .dat files) │ ├── GameServerInfo - Common.dat (ServerCode=0, Port=55901, EnableCastleSiege=0) │ ├── GameServerInfo - Character.dat │ ├── GameServerInfo - Command.dat │ ├── GameServerInfo - Custom.dat │ ├── GameServerInfo - Event.dat │ └── GameServerInfo - Skill.dat ├── GameData\ (shared game content) │ ├── Item\ │ ├── Monster\ │ ├── Plugins\ │ └── ... └── Overlays\ └── castle-siege\ └── GameServerInfo - Common.dat (ServerCode=1, Port=55902, EnableCastleSiege=1) ``` {% endtab %} {% tab title="Launch Script" %} `start-worlds.bat`: ```bat @echo off echo Starting Main World... start "Main World" GameServer.exe --game-data .\GameData\ echo Starting Castle Siege World... start "Castle Siege" GameServer.exe --game-data .\GameData\ --config-overlay .\Overlays\castle-siege\ echo Both worlds started. ``` {% hint style="info" %} `--game-data` is set explicitly here because this folder layout differs from the default `..\Data\` convention. When using the standard GameServer distribution layout, you can omit `--game-data`. {% endhint %} {% endtab %} {% endtabs %} ### ConnectServer Setup Each world must appear in the ConnectServer's `ServerList.xml` so players can select it: ```xml ``` {% hint style="warning" %} Each `Code` value in `ServerList.xml` must match the `ServerCode` in the corresponding world's `GameServerInfo - Common.dat`. A mismatch will prevent players from connecting to the correct world. {% endhint %} ### Scaling Beyond Two Worlds The pattern scales to any number of worlds - just add more overlay folders, each with its own `GameServerInfo - Common.dat` containing a unique `ServerCode` and `ServerPort`. You can also combine `--config-overlay` with `--game-data-overlay` if a specific world needs different drop tables, monster spawns, or plugin configs.