Ctrlk
Homepage
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Data Overlays

Run multiple worlds from one GameServer binary without duplicating config files using the data overlay system

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, Monster, Monster\MonsterSetBase\, MapManager.xml, MapServerInfo.xml, Effect.xml, Message.xml, Plugins\, Skill\, Event, Shop\, EventItemBag\, 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

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.

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.

Folder (inside GameData)
What it holds

Monster\MonsterSetBase\

Monster and NPC spawns, one file per map

Event\Invasions\

Invasion definitions

EventItemBag\

Event item bag (loot) files

Shop\

NPC shop files

Plugins\Quests\

Custom quest files

Plugins\LuckySpin\

Lucky Spin files

Plugins\Achievements\

Achievement files

Plugins\Dungeons\

Dungeon files

A partial overlay folder hides every main file. If you put only Monster\MonsterSetBase\ with one changed map file in the overlay, that process spawns monsters for that one map only - every other map is empty. To change one file in a folder like this, copy the whole folder into the overlay, then edit the file you want.

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 <path>

Override the GameData main folder

--game-data-overlay <path>

Set the GameData overlay folder

--config <path>

Override the GameServerData main folder

--config-overlay <path>

Set the GameServerData overlay folder

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:

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.

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

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.

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.

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.

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.

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.

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.

Examples

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)

Launch:

Nothing new to configure. Existing installations keep working exactly as before.

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:

Launch the primary world (no overlay needed):

Launch the Castle Siege subserver (same exe, config overlay pointed at the tiny folder):

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.

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.

An event world that uses all the same server settings but a different drop table and chaos mix recipe.

Launch the event process:

Only those two 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.

A subserver that needs both different server identity (for its own port and code) and different game content (for event drops).

Launch:

Or equivalently with environment variables:

The two roots are fully independent - you can mix and match as needed.

Common Issues

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.

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.

Monsters, shops or invasions missing on the overlay process: you put only some files of a folder that is read as a whole (for example Monster\MonsterSetBase\ or Shop\) into the overlay. The overlay folder replaces the main folder entirely. Copy the whole folder into the overlay. See Folders that are read as a whole.

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.

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.

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.

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.

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

start-worlds.bat:

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

ConnectServer Setup

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

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.

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.

PreviousOverview
NextGame Data Sync

Last updated