Save file documentation

I want to create a program that can examine a game in more detail than what is provided in the morgue files and lua api. I figured the best way to do this is the examine the save file.
I’ve figured out that the save file save things in zlib compressed chunks, but not much else. I’ve been staring at the source code for a while, but I still cannot figure it out. Is there some documentation on the save file format anywhere?

The best documentation for the save file format is probably simply the source code: (also for the container format). The crawl binary (at least on linux/macos) has a CLI that will let you extract and replace individual chunks from the compressed package, so at this point in the game’s history almost no one deals with the package format. If I wanted to deal with crawl save files programmatically I’d probably attempt to reuse existing code; for one thing, many of the more complex data structures are crawlcode-specific.

However, could you clarify what it is exactly that you want to do? I do occasionally do crawl save file editing to fix broken online games that can’t be repaired more easily, and I think there are very, very few scenarios where looking at the raw save data is going to be the easiest thing to do. If I’m debugging a crash and want more info than what the morgue/crashlog provides, the first step is always to actually open the save (if available) in wizmode on a debug build, and use wizmode commands (under &) to look at things.

1 Thank

I want to build an external tool to calculate the probability of my characters one-shotting or two-shotting enemies, and also determine the probability of them one-shotting or two-shotting me. fsim does something similar, but not quite what I need. I need a way to export the game state to an external program, and I assume the save file will be my best bet.

Do you have more information on the CLI? that sounds useful.

If you run crawl --edit-save with no other arguments you get a summary of the commands, it’s reasonably straightorward I think.

For this goal though I think it’s going to be most doable to modify fsim, rather than create an external tool. The amount of game logic you’d have to re-implement to predict something like one-shots in an external script is really, really non-trivial. This is essentially why fsim is the way it is rather than an external program.

1 Thank

Thanks, look like there is alot of work to be done if I want to get this working.