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.

NpcData:
  strategy: zone_based
  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

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: source_mapped
  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

Sorted by ID, one entity per file.

AchievementData:
  strategy: id_sorted
  server_path: "Achievements"
  server_pattern: "*.xml"
  client_folder: "AchievementData"
  client_pattern: "AchievementData-{seq:D5}.xml"
  root_element: "AchievementData"
  xsd_file: "AchievementData/AchievementData.xsd"
  expected_count: 500

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
zone_mapping	ZoneBased, Merged	Zone → sequence mapping
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

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

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

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