Skip to content

Converting config.ini to the new format

Locomotive configuration used to be stored as a list of anonymous value lines. The current format names every element with a key and describes it by type. Old config.ini files are not read by the simulator anymore, so a locomotive or a livery made for an older version has to be converted.

Conversion is done by the Locomotive Config Editor, either from a button in Content Editor or from the command line.

The two formats

Old format — the comment names the element instance, the line below it holds bare values, and their order is what identifies them:

;LocCamera=X Y Z
0.77 5.95 3.5
;CabLight1=X Y Z Color
0 6.2 4.2 $DDFFFF
;RightMirror=X Y Z AngleZ
1.555 6.52 3.43 30

New format — the comment names the element type and its field list, and the value line carries an explicit snake_case key:

;CabCamera=Position.X Position.Y Position.Z Angle.X Angle.Y Angle.Z Bounds.Left Bounds.Right Bounds.Height
cab.camera=0.92 5.83 3.55 -3 0 0 1.4 1.4 0.5
;Light=Position.X Position.Y Position.Z Color Radius
cab.main_light=0 6.2 4.2 $DDFFFF 8.33
;RearViewMirrors=Position.X Position.Y Position.Z AngleZ
rear_view_mirrors=1.555 6.52 3.43 30

Besides the renaming, the new format also adds fields that simply did not exist before (Radius for lights, Bounds.* for the cab camera, bounding spheres and sounds for custom objects). The simulator looks entries up by key, so the order of lines in a new-format file does not matter — but a key the engine expects and does not find is an error at load time.

What you need before starting

The converter needs a template

It does not invent the new structure. You must supply an already converted config.ini of the same series (or the closest series available). The template provides the key set, the order of entries and the default values; your old file only supplies the values that can be matched onto it.

All locomotives shipped with the simulator are already in the new format, so the template is normally data\<series>\config.ini from the game content.

Converting in Content Editor

Select the locomotive or the livery in the content tree and use the buttons on the right:

Node Button What it does
Locomotive Convert config.ini converts the series config
Livery Convert config.ini converts the livery config
Livery Deduplicate config.ini removes livery keys equal to the series config

The editor picks the paths itself:

  • Template — <content>\data\<loco>\config.ini
  • Result — <content>\data\<loco>\config.ini, or <content>\data\<loco>\<livery>\config.ini for a livery
  • Source (old file) — the same relative path inside the game folder if such a file exists there, otherwise the result file itself

A confirmation dialog shows all three paths before anything is written, and the previous file is saved as config.ini.bak. The full report goes to the Log tab, and its last lines are repeated in a dialog.

Old config must differ from the series template

For a series config the result path and the template path are the same file. That is why the old file has to be somewhere else — put it into the game folder under data\<loco>\config.ini. If it is not there, the editor refuses with this message instead of converting a file into itself. Liveries are not affected: their template is the series config, so a livery can be converted in place.

Converting from the command line

The same executable works as a console tool. It sits next to Content Editor, in the LocomotiveConfigEditor folder of the tools installation.

ZDSimulator.LocomotiveConfigEditor.exe convert <old.ini> <template.ini> <out.ini>

For example, converting an old VL80s livery against the current series config:

ZDSimulator.LocomotiveConfigEditor.exe convert ^
  D:\old\vl80s\2538\config.ini ^
  D:\ZDSimulator-content\data\vl80s\config.ini ^
  D:\ZDSimulator-content\data\vl80s\2538\config.ini

Unlike the button, the CLI never creates a backup and never guesses paths — it writes exactly the file you name, so you are free to convert into a scratch file first and compare.

Reading the report

Every run prints three kinds of lines and a summary such as 178 mapped, 655 default, 6 unmatched old.

Line Meaning What to do
MAPPED: cab.camera <- LocCamera a value from the old file was placed into a new key spot-check the renames that look surprising
DEFAULT: <key>: no legacy value, kept template default the old file had nothing for this field fine for genuinely new fields; check the ones your locomotive actually needs
UNMATCHED_OLD: CabLight2 the old file had this element and the template has nowhere to put it this data is lost — add the entry by hand if the locomotive needs it

DEFAULT lines are numerous and mostly harmless: the result always contains the entire key set of the template, including entries your locomotive does not use. UNMATCHED_OLD is the short list worth reading line by line.

Check by hand after converting

Camera and element angles

When an old header had only X Y Z, those same three values are also matched onto Angle.X Angle.Y Angle.Z of the new entry, because bare X is accepted as an alias for both. After conversion cab.camera will read like cab.camera=0.77 5.95 3.5 0.77 5.95 3.5 1.4 1.4 0.5 — the second triplet is wrong. Reset those angles to the values you want (usually 0 0 0 or a small yaw).

Other things to look at:

  • The old Sounds block has no counterpart in the new config.ini and is dropped silently.
  • Radii, bounding spheres and other new fields keep the template's values, which belong to a different locomotive — go over the lights and custom objects.
  • Converting a livery against the series template produces a full config, not a short override file. Run Deduplicate config.ini afterwards so that only the keys that actually differ from the series stay.

Re-running the converter on an already converted or half-converted file is safe: the parser accepts old, new and mixed files, so you can convert, fix a few entries by hand, and convert again.

Checking a config

ZDSimulator.LocomotiveConfigEditor.exe verify <config.ini>

Prints OK: <path> and exits with 0 when the file is clean, or a list of warnings and exit code 1. It catches unknown element types, header field lists that do not match the type schema, value counts that disagree with the header, headers with no value line and value lines with no header — i.e. exactly the damage that hand editing tends to cause. Run it on the result of every conversion.

Removing livery duplicates

ZDSimulator.LocomotiveConfigEditor.exe dedupe <livery.ini> [<series.ini>]

Drops every livery key whose value is identical to the series config; when the second argument is omitted, the series file is taken from the parent folder. The original is saved as .bak. A livery config only has to list what it changes — the rest falls through to the series file.