How to edit Creeper World custom map (.cwm) files by hand

Started by mopa42, October 29, 2010, 10:28:04 AM

Previous topic - Next topic


I've been curious for a while about custom map files and what's behind the binary format. I poked around some, and it turns out that there is a (relatively) simple explanation!
Note: this info is based on the latest Creeper World (v0572) and Creeper World Map Editor (v0380), running on Windows.

Quick answer: map files are XML data files compressed using the zlib / deflate algorithm, the same compression algorithm used in ZIP files.

Long Explanation:

To convert a .cwm file into a .xml file, you need a program that can compress/uncompress using zlib (it doesn't work to simply treat it as a .zip file). You'll likely also need to know how to use the command line.
One tool set that can do the extraction are the offzip / packzip programs (if you use these, make sure you have the latest version of them).

  • From the command line, offzip.exe my_map.cwm my_map.xml 0 will create my_map.xml by uncompressing my_map.cwm
  • After that, you can edit the XML file by hand (see below for details).
  • Finally you can use packzip.exe -c my_map.xml my_map.cwm to compress the XML file back into the custom map format.
  • One additional concern: packzip v0.2 might complain about missing libgcc_s_dw2-1.dll; you can download it here and put it in the same directory as packzip.
Or, if you know a programming language with the zlib/deflate support, it isn't that hard to make a program to do this for you. (see below for mine)

Technical details on cwm format:

  • The compressed zlib format is also known as RFC1950.
  • The first two bytes in the file are 0x78 0xda, which is the zlib header meaning "deflate algorithm, 32k window, max compression"
  • The next bytes are the XML file compressed using deflate
  • The final 4 bytes are the Adler32 check sum of the input file

A couple of comments on the XML map format:

  • Units of time are given in frames (36 frames per second)
  • The grid runs from 0 to 47 in the vertical (y) direction and from 0 to 69 in the horizontal (x) direction.
    (0,0) is in the top-left, (69,47) is in the bottom-right (you can see this in the map editor).
  • Terrain and wall data are stored as a list on numbers running from left to right and top to bottom: (0,0), (1,0), (2,0) ... (69,0), (0,1), (1,1) ...
    The values are 1-5 for terrain (giving the elevation at that point) and 0, 1, or 1000000 for no wall, normal wall, indestructible (crazonium) wall
  • Most of the other game objects have parameters gameSpaceX and gameSpaceY for their coordinates
  • Totems are listed under places
  • Odin City and the Rift are under specialplaces, and have seemingly-unused health and energyLevel parameters
  • Odin City is called BaseGun
  • Artifacts are called Ruins
  • The text for title, opening, and artifacts is html-escaped (space is %20, etc)
  • Custom background (if any) is base64-encoded image data (the game and editor are ok with .jpg or .png data of any size and quality initially; if you use the editor it converts any custom background to a 700x480 jpg @ 85% quality). An online base64-encoder is here.
  • backgroundMap is 0 to 5, and must be given even if there is a custom background
  • Colors are the decimal equivalents of the hexadecimal 0xRRGGBB

Attached are FormatDemo.cwm and FormatDemo.xml (as a .zip), a map with two of everything in place so you can easily see the syntax of the XML file.

Ways to use this knowledge about the custom map format:

  • Easily delete all collectors/mines/totems/...
  • Edit spore waves by hand
  • Set emitter settings to precalculated values (such as stacked emitters whose intensity doubles each minute)
  • Automatically generate a custom background based on the terrain, or vice versa.
  • Create a map with randomly-generated terrain
  • Someone very ambitious with too much extra time could even write their own map editor program, with whatever desired features (circle terrain brush, undo, etc) that the current map editor doesn't yet have.

Being able to view and edit the underlying XML data for the map is mainly a time-saving tool than anything else.
About the only thing I found I could do only by editing the XML by hand was set the terrain to 0 or 6 (which the game still displays, giving two additional elevations to work with). Also, you can set walls to other values than 0, 1, or 1000000 (a 2-value wall survives about twice as long as a 1-value wall; the editor doesn't display it even though the game does), and you can tweak timing values in smaller increments than tenths of a second.

A word of caution: the map editor doesn't display any useful error if you give it a badly formatted map, and sometimes needs to be restarted if you really mess up its internal state.

For the curious, I have attached (as a .zip), which is the program I wrote to help me automate this conversion process. It is a perl script to be run on the command line. Feel free to use/copy/adapt it however you want (if you can run it).
(I am also working on some terrain-generation and image-conversion programs, which I'll share if/when I'm satisfied with them)

Edit: I clarified some of the text and attached a couple screenshots of this technology in action.
Edit: added link to base64-encoder, added "tenths of a second" discussion.


Interesting, i'll have a look at working with this later then ;)
Join the chat! :D
- The only echo present here...


Oooh, could be used to create even more interesting maps, and also have walls that decay faster/slower. :O


Very professional analysis mopa! I read your post before, but I awaited Virgil's approval before responding.

I also decompressed some CWM files in the past (with Virgil's help) to be able to shift maps by a few blocks for instance (the terrain height array that is) by programming a tool for this, but you have found some very interesting parameters that I'm certainly gonna play with.

Thanks for your detailed post! :)
My CW1 maps: downloads - overview
My CW2 maps: downloads - overview



We have become the creeper...


Quote from: thepenguin on November 06, 2010, 07:55:38 PM
I can't get packzip to work

Can you give some details, such as:

1) What exact problem are you having?
2) Does the packzip program run at all?
3) What exact command are you using?
4) What version of the program are you running?
5) If you've tried using the corresponding offzip program, have you also had issues with that?


1)DLL is missing
3)packzip.exe -c my_map.xml my_map.cwm
4)the one you linked to
5)yes, no
We have become the creeper...


could you just packzip them for me?

I send you xml, you send cwm
We have become the creeper...


Quote from: thepenguin on November 07, 2010, 08:13:43 AM
1)DLL is missing <- Download the DLL
2)yes <- good.
3)packzip.exe -c my_map.xml my_map.cwm <- congrats.
4)the one you linked to <-w00tyt00ty
5)yes, no <- mk.


Dll does not download

can one of you who has it working just pack it for me? (I'd like to know before I try editing xml)
We have become the creeper...


Quote from: thepenguin on November 07, 2010, 01:42:30 PM
can one of you who has it working just pack it for me? (I'd like to know before I try editing xml)

Attached xmltest.cwm, and xmltest2, 3, 4, and 5 for thepenguin.
And now:, which contains (surprise, surprise) packzip.exe, offzip.exe, and the DLL needed to make packzip work, all in one convenient location. (All are exactly the same as from the three download links I gave in my original post, by the way).

One other thing: if anyone is looking for a good XML editor, I use the free Notepad++, which gives useful color-coding and collapsible structure.


We have become the creeper...


Quote from: thepenguin on November 07, 2010, 01:42:30 PM
Dll does not download

can one of you who has it working just pack it for me? (I'd like to know before I try editing xml)

Google and Download the DDL...


Join the chat! :D
- The only echo present here...