Document formats in wiki

I think that all custom formats used by VCMI should be documented in the wiki.
This should include formats used by the original game that have been reverse-engineered and new formats created (json schema).

It would be great if the wiki included all known documentation on Heroes III formats available.

What license does the content in the wiki have? If it is CC-BY-SA 3.0 then for example could be used as a starting point (see

I noticed there is the file h3m.txt in the VCMI source. It could be translated and added to the wiki. Unfortunately I cannot read the language (Polish, I guess).

Also useful would be command-line programs that convert the original formats into more useful formats (unpack archives, decode pcx, ……). I started doing this in python, using the above wiki and VCMI source as documentation. I can post them if someone would find them useful.

Another idea would be to make the VCMI binary able to decode these formats using a command-line switch.

I think a lot of things should be documented on Wiki, but there are some issues:

  • Someone has to do that and we don’t have enough programmers to do even the current coding
  • Formats used by original game have already been reverse-engineered by generation :wink: of moders. Old formats are not supposed to be used anymore.
  • Json formats should be self-explanatory
  • Config files are due to change

Regarding H3 formats:
I remember some kind of wiki with incomplete documentation of some formats (lod, def, pcx). Can’t find it right now unfortunately.

OpenHoMM (dead project with same goals as VCMI) have some documentation as well: … oc/formats

Apart from this all documentation we have is our source code.

Regarding programs - check this link (as well as site itself):
It has Windows-only programs but everything works in Wine AFAIK.

REWiki came to my mind, but they only have MM6 lod documented. … le_formats ]

It’s incomplete mess.
The only complete and reliable format documentation is our h3m parser implementation. If one can can read source code, it should suffice (otherwise, what’s the use?). We will help, if something is not clear. :slight_smile:

I once gathered a number of H3 tools, they’re available at (sadly no description what is what)

I only need enough information to know what is stored inside the format. Then I can think of proposals for new formats that are more flexible than the old ones.
I think all new formats should be fully editable and viewable with standard software, not any custom programs. This way VCMI does not need to write new tools for modders.

For example I was thinking of def files for animations. I think a better alternative would be some kind of archive that does not mix or compress the files (easy, fast opening, images don’t compress well anyway) that can be opened by 7zip. There is a json file with the included sequences and the frames are stored as files in the archive. This way anyone can easily create animations using standard tools (well, anyone artistic enough to create the frames…). A converter should not be too difficult. A program could be written to generate the json file.

In the long term I think all old formats should be replaced and deprecated, perhaps even removed if there are good converters.

The new formats must of course be well documented in the wiki.

Aha! Found that wiki! A lot of data is incomplete but looks to be correct
(for some reason Google marks this site as “dangerous”)

You’re a bit late here. Check .json files in Sprites folder. This is pretty much what you described except for not supported archives (and zip looks to be more portable solution than 7z).

It is not documented right now because it is still subject to change. But it looks that I will have to do this soon.

EDIT: one more link:

Thanks, but I already linked to it in the first post :).

Do you mean the menu files? Def files support many sequences per file. This should also be supported to have one animation file per unit. Perhaps it is better to have one file per sequence.
Zip is probably good. The best format is the one that is easiest to implement and editable using free tools on any platform.

Fail :slight_smile:

Yup. There is optional entry “group” with 0 as default value. So multiple sequences are supported as well.