MAP CONVERTER
This guide explains the built in map converter, what it does, how to use it, and what to expect from it. If you have older maps written in the legacy space separated syntax and want them in the current key=value syntax, this is the tool for that job.

DISCLAIMER
Always back up your original map file before converting anything. The converter works on text you paste in and gives you text back out, it never opens, overwrites, or saves a file on its own, but you are still the one who decides what happens to your original file afterward, so keep a copy before you start replacing anything.
The converter is thorough and has been fixed up over several versions to correctly handle things like 2D axis differences, old volume conventions, and reverb parameter renames, but it is still a best effort tool. Review the Statistics panel after every conversion, check any lines marked as errors, and read through the converted output before you trust it in place of your original map. If something looks wrong, the original line is always kept right below any error comment so you can fix it by hand.
You do not have to convert your maps at all. The game still loads maps written in the old syntax, so converting is optional. It mainly helps if you want cleaner, more readable map files, or if you plan to use something that depends on the newer syntax going forward.

WHAT IT IS
The map converter is a built in tool that rewrites old style, space separated map lines into the current key=value; syntax. For example, an old platform line like this:
platform 0 50 0 50 0 0 grass
becomes this:
platform minx=0; maxx=50; miny=0; maxy=50; minz=0; maxz=0; type=grass;
It is built on the same generation system the map builder itself uses, so the output you get is the same kind of line the builder would produce for you.

WHERE TO FIND IT
Open the game's settings, go to the Map category, and choose Map Converter (spatial to key=value). This opens a separate window with an Input box, an Output box, a Statistics box, and a row of buttons: Convert, Validate, Copy to Clipboard, and Help.

HOW TO USE IT
Open your old map file in a text editor and copy all of its text. Paste that text into the Input box. Click Convert. The Output box fills in with the converted map text, and the Statistics box tells you how many lines were processed, how many elements were converted, how many were left unchanged, whether the map was detected as 2D or 3D, and a breakdown of how many of each element type were converted. If you want a second check, click Validate to confirm the output lines are all in valid key=value form. When you are happy with the result, click Copy to Clipboard and paste it into a new or existing map file of your own. The Help button opens a short in game summary of all of this if you need a reminder later.

WHAT IT HANDLES
The converter covers the full range of map elements, including platforms, walls, zones, blockages, hazards, clocks, calendars, checkpoints, dialogs, signs, text squares, doors, gates, travel points, ambiences, sources, timed sources, x sources, excludable zones, music, playlists, streams, reverb spaces, occluded spaces, reflection spaces, acoustic materials, zone reverbs, lifts, belts, vanishing platforms, and slants.
It also handles a number of details you would otherwise have to fix by hand. It detects whether a map is 2D or 3D from the 2d flag and swaps the vertical axis accordingly, since the old engine used Z as the vertical axis while the current engine uses Y. It combines multi word text fields, like zone descriptions or sign text, into a single quoted string instead of cutting them off at the first word. It strips old @track@ markers from zone text and turns them into the current track=yes parameter. It converts yes/no and 1/0 style booleans into true/false. It corrects the old volume convention, where 0 meant full volume, into the current convention, where 0 means silent and 100 means full.

WHAT TO EXPECT
Lines that are already in key=value; form are passed through unchanged. Comments, blank lines, and simple map settings like name, health, category, contributor, and dislikes are preserved as is. If a line cannot be converted, the converter keeps your original line intact and adds a comment right above it explaining the error, so nothing is silently lost or dropped. Anything reported as a warning is worth a second look even if the line converted successfully, since it usually means an assumption had to be made on your behalf.
Keep in mind this tool only understands Golden Crayon's own legacy map syntax. It will not make sense of map files from other games or custom formats you may have written yourself.
