Client Sync

Transforms server-side XML datasheets into client DataCenter format with XSD validation and attribute filtering.

Configuration

version: 1

paths:
  server: "D:/server/Datasheet"
  client: "D:/client/DataCenter_Final"
  schemas: "D:/client/DataCenter_Final"

defaults:
  id_attribute: "id"
  encoding: "utf-8"
  indent: "    "

entities:
  EquipmentEvolutionData:
    strategy: Monolithic
    server_file: "EquipmentEvolutionData.xml"
    client_folder: "EquipmentEvolutionData"
    client_file: "EquipmentEvolutionData-00000.xml"
    root_element: "EquipmentEvolutionData"
    id_attribute: "targetTemplateId"
    xsd_file: "EquipmentEvolutionData/EquipmentEvolutionData.xsd"

Paths

Property	Description
server	Server datasheet root path
client	Client DataCenter root path
schemas	XSD schemas directory path

Defaults

Property	Default	Description
id_attribute	"id"	Entity identifier attribute
encoding	"utf-8"	Output encoding
indent	" "	Indentation (4 spaces)

Strategies

Monolithic

One server file → one client file.

EquipmentEnchantData:
  strategy: Monolithic
  server_file: "EquipmentEnchantData.xml"
  client_folder: "EquipmentEnchantData"
  client_file: "EquipmentEnchantData-00000.xml"
  root_element: "EquipmentEnchantData"
  xsd_file: "EquipmentEnchantData/EquipmentEnchantData.xsd"

ZoneBased

Routes entities by zone attribute. Each server file contains data for a single zone, identified by a root-element attribute.

NpcData:
  strategy: ZoneBased
  server_pattern: "NpcData_*.xml"
  client_folder: "NpcData"
  client_pattern: "NpcData-{seq:D5}.xml"
  root_element: "NpcData"
  zone_attribute: "huntingZoneId"
  sorting: numeric
  xsd_file: "NpcData/NpcData.xsd"

Zone mapping resolution

The zone-to-sequence mapping determines which zone ID maps to which output file number. It is resolved using the following precedence:

zone_mapping	sorting	Behavior
present	any	Use explicit mapping
absent	present	Auto-generate from server files
absent	absent	Error at sync time

When sorting is set and zone_mapping is absent, the mapping is auto-generated at sync time:

1. Glob server files via server_pattern
2. Extract zone IDs from each file’s root element via zone_attribute
3. Sort zone IDs using the sorting algorithm
4. Assign 0-based sequential indices as sequence numbers

Sorting algorithms

Value	Behavior	Example order
numeric	Sort zone IDs as integers	2, 10, 100
alphabetical	Sort zone IDs as strings (ordinal)	10, 100, 2

Explicit mapping

For cases where auto-sorting does not match the expected client layout, an explicit zone_mapping can be provided. It takes precedence over sorting.

NpcData:
  strategy: ZoneBased
  server_pattern: "NpcData_*.xml"
  client_folder: "NpcData"
  client_pattern: "NpcData-{seq:D5}.xml"
  root_element: "NpcData"
  zone_attribute: "huntingZoneId"
  xsd_file: "NpcData/NpcData.xsd"
  zone_mapping:
    1: 0
    2: 1
    101: 100

Zone filtering

The --zones CLI option restricts ZoneBased sync to specific zone IDs. This is useful for partial migrations where only a subset of zones needs syncing.

dsl sync -c sync-config.yaml -e NpcData --zones 13,64,213

Zone filtering applies after zone mapping resolution — the mapping is always computed from all server files to keep sequence numbers stable. Only the output step is restricted to the filtered zones.

When --zones is used with non-ZoneBased entities, a warning is printed and the filter is ignored for those entities.

Bucket

Distributes entities by ID ranges.

ItemData:
  strategy: Bucket
  server_files:
    - "ItemTemplate.xml"
    - "ItemTemplate_Custom.xml"
  source_precedence:
    - "ItemTemplate_Custom.xml"
    - "ItemTemplate.xml"
  client_folder: "ItemData"
  client_pattern: "ItemData-{seq:D5}.xml"
  root_element: "ItemData"
  xsd_file: "ItemData/ItemData.xsd"
  default_bucket_seq: 2
  id_buckets:
    - seq: 0
      min: 1
      max: 99999
    - seq: 1
      min: 100000
      max: 199999

When default_bucket_seq is set, IDs that don’t match any explicit bucket range are routed to that sequence number instead of producing an error. Multiple bucket entries can share the same seq to map non-contiguous ID ranges to the same output file.

Merged

Multiple sources merge by template or zone keys.

UserSkillData:
  strategy: Merged
  sources:
    - server_pattern: "UserSkillData_*.xml"
      key_type: template
  client_folder: "SkillData"
  client_pattern: "SkillData-{seq:D5}.xml"
  root_element: "SkillData"
  xsd_file: "SkillData/SkillData.xsd"
  template_mapping:
    101: [0, 1]
    102: [2, 3, 4]

SourceMapped

Direct 1:1 filename mapping.

StrSheet_Item:
  strategy: SourceMapped
  server_files:
    - "StrSheet_Item.xml"
    - "StrSheet_Item_Custom.xml"
  client_folder: "StrSheet_Item"
  root_element: "StrSheet_Item"
  xsd_file: "StrSheet_Item/StrSheet_Item.xsd"
  source_mapping:
    "StrSheet_Item.xml": "StrSheet_Item-00000.xml"
    "StrSheet_Item_Custom.xml": "StrSheet_Item-00001.xml"

IdSorted

One server file per entity, sorted by ID. Each server file maps to a client file at the position determined by sorting all server files alphabetically (zero-based).

Quest:
  strategy: IdSorted
  server_path: "QuestData"
  server_pattern: "*.quest"
  client_folder: "Quest"
  client_pattern: "Quest-{seq:D5}.xml"
  root_element: "Quest"
  id_attribute: "id"
  xsd_file: "Quest/Quest.xsd"

Full sync

Writes all server entities to their sorted-position client files. Client files that no longer have a corresponding server file are deleted (orphan cleanup).

Partial sync (key filtering)

The --keys CLI option restricts IdSorted sync to specific entity IDs. Only those files are written at their correct global positions — other client files are left untouched and orphan deletion is skipped.

dsl sync -c sync-config.yaml -e Quest --keys 201,202,303

Key filtering applies after the full sorted position map is computed — positions remain stable regardless of filter. When --keys is used with non-IdSorted entities, a warning is printed and the filter is ignored.

Position-conflict guard

During partial sync, if the target client file already contains a different entity ID (from a previous sync with different server data), an E680 error is emitted and the file is not overwritten. This signals that a full sync is needed to correct shifted positions.

Entity Properties

Property	Strategies	Description
strategy	All	Sync strategy type
client_folder	All	Target folder under client path
root_element	All	XML root element name
xsd_file	All	XSD schema path
id_attribute	All	ID attribute (default from config)
server_file	Monolithic	Single source file
client_file	Monolithic	Single target file
server_pattern	ZoneBased, IdSorted	Glob pattern for sources
client_pattern	ZoneBased, Bucket, Merged, IdSorted	Output pattern with {seq:D5}
zone_attribute	ZoneBased	Zone ID attribute
sorting	ZoneBased	Zone sort algorithm (numeric, alphabetical)
zone_mapping	ZoneBased, Merged	Zone → sequence mapping (optional with sorting)
server_files	Bucket, SourceMapped	Source file list
source_precedence	Bucket	Priority for overlapping IDs
id_buckets	Bucket	ID range definitions
default_bucket_seq	Bucket	Fallback sequence for unmatched IDs
sources	Merged	Source definitions
template_mapping	Merged	Template → sequences mapping
source_mapping	SourceMapped	Source → target mapping
server_path	IdSorted	Source subdirectory
expected_count	IdSorted	Max entity count (validation only)

CLI

# Sync all entities
dsl sync --config sync-config.yaml --all

# Sync specific entities
dsl sync -c sync-config.yaml -e ItemData -e NpcData

# Dry run
dsl sync -c sync-config.yaml -a -d

# Verbose
dsl sync -c sync-config.yaml -a -v

# Sync only specific zones (ZoneBased entities only)
dsl sync -c sync-config.yaml -e NpcData --zones 13,64,213

# Sync only specific IDs (IdSorted entities only)
dsl sync -c sync-config.yaml -e Quest --keys 201,202,303

# Combine with dry run to preview filtered sync
dsl sync -c sync-config.yaml -e NpcData -z 13,64 -d

Option	Alias	Description
--config	-c	Config file path (required)
--entities	-e	Entities to sync (repeatable)
--all	-a	Sync all entities
--dry-run	-d	Preview without writing
--verbose	-v	Detailed output
--zones	-z	Filter to specific zone IDs (comma-separated)
--keys	-k	Filter to specific entity IDs (comma-separated, IdSorted only)

Entity Names

The --entities option accepts entity names as defined in your configuration file’s entities: section. The entity name is the key you assign to each entity configuration.

For example, given this configuration:

entities:
  ItemData:
    strategy: SourceMapped
    # ...
  NpcData:
    strategy: ZoneBased
    # ...
  EquipmentEvolutionData:
    strategy: Monolithic
    # ...

You can sync specific entities using their configuration keys:

dsl sync -c sync-config.yaml -e ItemData -e EquipmentEvolutionData

Common entity names (typical configurations):

Entity Name	Server Source	Description
ItemData	ItemTemplate*.xml	Item definitions
EquipmentData	EquipmentTemplate.xml	Equipment stats
EquipmentEvolutionData	EquipmentEvolutionData.xml	Evolution recipes
EquipmentEnchantData	EquipmentEnchantData.xml	Enchant data
NpcData	NpcData_*.xml	NPC definitions
SkillData	UserSkillData_*.xml	Player skills
StrSheet_Item	StrSheet_Item*.xml	Item localization
StrSheet_Creature	StrSheet_Creature*.xml	Creature localization
AchievementData	Achievements/*.xml	Achievements

Note: These are conventional names. You can use any key name in your configuration - the entity name is whatever you define in the entities: section.

Error Codes

Range	Category
E601-E609	Configuration
E610-E619	Schema loading
E620-E629	Key extraction
E630-E639	Route resolution
E640-E649	XSD validation
E650-E659	Output building
E660-E669	File I/O
E670-E679	Specific operations
E680+	IdSorted (position conflict)