[Release] Map Porter — Fix EP36+ .mcl maps for EP35- clients (by Maxxor) Source

[maxxor]

f you've ever tried dragging a .mcl map file from a newer client (EP36+) into an older EP35-and-below client, you probably know the drill:

- Client freezes/crashes the moment you try to enter the map
- TMap Converter throws an error and refuses to open the file
- If you force it through some hex-editing, you end up with scrambled doodads, missing water/terrain effects, and objects floating in the wrong place

I hit this wall while porting some newer maps into an older-generation client and ended up reverse engineering exactly what changes between the two .mcl generations. Turns out it's not one bug, it's two, stacked on top of each other:

1. Every doodad record from index 1 onward has an extra padding byte inserted before it (doodad[0] is untouched). If you don't strip it, every object after the first reads garbage — this is the "freeze on enter" bug.
2. There's a second, separate 1-byte insertion right between the unk0 array and the big 256x256 tile-flag block (unkuba0). This one is sneaky because it doesn't break the file's total length, so a naive fix (just correcting #1) still "works" but leaves your water/walkable-tile data silently misaligned — which is why some people report normal-looking maps with broken/glitched water even after doing the doodad fix.

I built a small local tool (Python + a browser UI, runs on your own PC, nothing uploaded anywhere) that:

- Scans two client folders (yours + the source you're porting from) and shows you, map by map, exactly what's wrong: byte-shift needed, version byte mismatch, missing Object\ models, missing World\worldN.enc
- Converts with one click — backs up your existing file first, patches both byte-shift bugs, fixes the header version byte, copies over any missing model files automatically
- Also has a drag-and-drop mode if you just want to fix one .mcl file on the spot, no client folders needed
- PT/EN interface, dark "frozen tundra" theme because why not

Verified byte-for-byte against known-good already-converted reference maps — not guesswork, the output matches exactly (aside from the intentional version byte patch).

Currently tested/confirmed working on several maps; a chunk of older maps use a third, still-undocumented header variant that the tool correctly detects and refuses to touch rather than risk corrupting your files — that part's still being reverse engineered.

Credits: Maxxor
Discord: xxmaxxorxx

Feedback and bug reports welcome — if you hit a map that fails to convert, send it my way and I'll add it to the investigation list.

 

[online178]

Thanks for your support !
I've got error when start using .bat file

 

[josueinaki]

Thanks for your support !
I've got error when start using .bat file
View attachment 307304

pip install mcl-format

 

[szparny]

f you've ever tried dragging a .mcl map file from a newer client (EP36+) into an older EP35-and-below client, you probably know the drill:

- Client freezes/crashes the moment you try to enter the map
- TMap Converter throws an error and refuses to open the file
- If you force it through some hex-editing, you end up with scrambled doodads, missing water/terrain effects, and objects floating in the wrong place

I hit this wall while porting some newer maps into an older-generation client and ended up reverse engineering exactly what changes between the two .mcl generations. Turns out it's not one bug, it's two, stacked on top of each other:

1. Every doodad record from index 1 onward has an extra padding byte inserted before it (doodad[0] is untouched). If you don't strip it, every object after the first reads garbage — this is the "freeze on enter" bug.
2. There's a second, separate 1-byte insertion right between the unk0 array and the big 256x256 tile-flag block (unkuba0). This one is sneaky because it doesn't break the file's total length, so a naive fix (just correcting #1) still "works" but leaves your water/walkable-tile data silently misaligned — which is why some people report normal-looking maps with broken/glitched water even after doing the doodad fix.

I built a small local tool (Python + a browser UI, runs on your own PC, nothing uploaded anywhere) that:

- Scans two client folders (yours + the source you're porting from) and shows you, map by map, exactly what's wrong: byte-shift needed, version byte mismatch, missing Object\ models, missing World\worldN.enc
- Converts with one click — backs up your existing file first, patches both byte-shift bugs, fixes the header version byte, copies over any missing model files automatically
- Also has a drag-and-drop mode if you just want to fix one .mcl file on the spot, no client folders needed
- PT/EN interface, dark "frozen tundra" theme because why not

Verified byte-for-byte against known-good already-converted reference maps — not guesswork, the output matches exactly (aside from the intentional version byte patch).

Currently tested/confirmed working on several maps; a chunk of older maps use a third, still-undocumented header variant that the tool correctly detects and refuses to touch rather than risk corrupting your files — that part's still being reverse engineered.

Credits: Maxxor
Discord: xxmaxxorxx

Feedback and bug reports welcome — if you hit a map that fails to convert, send it my way and I'll add it to the investigation list.

Hi,


I downloaded your Map Porter — Fix EP36+ MCL maps for EP35- clients and I'm having a problem running it.


I get this error:


ModuleNotFoundError: No module named 'mcl_format'


I checked the downloaded ZIP, but there is no mcl_format module included. I also tried:


pip install mcl-format


but pip says:


ERROR: No matching distribution found for mcl-format


Could you please provide the missing mcl_format module or tell me where I can download it?


I'm trying to use the tool to port an EP42 MCL map to EP33.


Thanks for your help!

 

[maxxor]

Hi,


I downloaded your Map Porter — Fix EP36+ MCL maps for EP35- clients and I'm having a problem running it.


I get this error:


ModuleNotFoundError: No module named 'mcl_format'


I checked the downloaded ZIP, but there is no mcl_format module included. I also tried:


pip install mcl-format


but pip says:


ERROR: No matching distribution found for mcl-format


Could you please provide the missing mcl_format module or tell me where I can download it?


I'm trying to use the tool to port an EP42 MCL map to EP33.


Thanks for your help!

Hi,

Thank you for reporting this issue, and sorry for the inconvenience!

mcl_format is not a public package on PyPI (pip), but rather the internal binary parser module built specifically to read and handle Cabal's .mcl structures (headers, doodads, models, effects, tiles, and texture blocks). It was accidentally omitted when creating the initial release archive.

I have updated the download archive to include the missing file.

How to fix:​

1. Re-download the updated map_porter.zip (or simply extract mcl_format.py into the same folder as converter.py and app.py).
2. Run Start Map Porter.bat (or python app.py from your terminal).

All required files are now included:

• app.py
• converter.py
• mcl_format.py
• Start Map Porter.bat

Let me know if you run into any other issues while porting your maps!

 

[masterme]

Here Offline Mode
Owner : maxxor
Modify : GST

​

 

[hyperfork]

Here Offline Mode
Owner : maxxor
Modify : GST

​

badboy