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.

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.

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.

Folders that are read as a whole#

Some content is not one file but a folder of files that the GameServer reads all at once. For these, the overlay works per folder, not per file: if the folder exists in the overlay, the GameServer reads only the overlay folder and ignores the main folder completely. Files from the two folders are never merged.

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.

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.

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:

[GameServerInfo]
GameDataOverlay = D:\Servers\CS\Overlay\GameData\

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#

Examples#

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
        └── ...

GameServer.exe

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)

D:\Servers\Shared\GameServer\GameServer.exe

D:\Servers\Shared\GameServer\GameServer.exe --config-overlay D:\Servers\CS-Overlay

D:\Servers\
├── Shared\
│   ├── Data\
│   │   ├── Item\
│   │   │   └── ItemDrop.xml
│   │   └── Plugins\Items\ChaosMix\
│   │       └── ChaosMix_Recipes.xml
│   └── GameServer\
│       ├── GameServer.exe
│       └── Data\
└── Event-GameData\                <- GameData overlay only
    ├── Item\
    │   └── ItemDrop.xml           (2x drop rates, event items)
    └── Plugins\Items\ChaosMix\
        └── ChaosMix_Recipes.xml   (holiday recipe)

GameServer.exe --game-data-overlay D:\Servers\Event-GameData

D:\Servers\
├── Shared\
│   ├── Data\
│   └── GameServer\
│       ├── GameServer.exe
│       └── Data\
├── Sub-Config\                   <- GameServerData overlay
│   └── GameServerInfo - Common.dat
└── Sub-GameData\                 <- GameData overlay
    └── Item\
        └── ItemDrop.xml

GameServer.exe --config-overlay D:\Servers\Sub-Config --game-data-overlay D:\Servers\Sub-GameData

set GS_CONFIG_OVERLAY=D:\Servers\Sub-Config
set GS_GAME_DATA_OVERLAY=D:\Servers\Sub-GameData
GameServer.exe

Common Issues#

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#

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)

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

ConnectServer Setup#

Each world must appear in the ConnectServer's ServerList.xml so players can select it:

<Server Code="0" Name="Main World" ... />
<Server Code="1" Name="Castle Siege" ... />

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.