Complete roguelike tutorial using C++ and libtcod -originally written by JiceText in this tutorial was released under the Creative Commons Attribution-ShareAlike 3.0 Unported and the GNU Free Documentation License (unversioned, with no invariant sections, front-cover texts, or back-cover texts) on 2015-09-21.

In this part, we will implement saving and loading the game to be able to close it and resume it later. And this is not going to be pleasing. C++ has a few great feats, but it certainly sucks at type introspection and object serialization. Most modern languages have these features built in. For this reason, the article 10 of Jotaf's python tutorial will be split in two for the C++ version.

In fact, there's a way to serialize a C++ object and store it on the disk using only a couple of lines of code : using boost Serialization library. But we're not going to use it for several reasons :

this tutorial is not about using boost but rather how to code the features yourself using basic C++.

even if using boost would considerably reduce the size of the code to write, you still have to embed boost in your game. Using hand-made code will replace 8000 lines of boost code with less than 300 lines of specific code, resulting in a lighter executable and a simplified compilation process for your project.

using libtcod's zip toolkit means that the save file will be compressed. Of course, this means less space used on the disk, but also harder to hack savegame files. Of course, using boost doesn't keep you from compressing the file, but it just comes at no cost when using libtcod.

Anyway if you prefer to use boost, you can follow this article to reorganize the Map and Engine code, and just skip the whole Persistent stuff and replace Engine::load and Engine::save code with boost invocation.

The plan

Since this part does not include a game menu, we're going to do a minimal savegame support :

when the player closes the game window, the game state is saved to a file

when the player starts the game, it resumes the last saved game

when the player dies, the savegame is deleted (you wouldn't write a roguelike without permadeath, would you?)

While this simplifies the article, it leaves an annoying case : when the player manage to kill all monsters, he will be stuck. The only way to restart a game is to erase the savegame by hand. This will be fixed in the next article.

Refactoring

The engine

The first thing, obviously, is to be able to save and load the whole game. We also need to remove the initializing code from the Engine constructor, because when the Engine is created, we don't know yet if we have to generate a new map or load a previously saved one. We put the functions in the Engine class :

The map

We could save the map by putting every tile property in the file. Or we can only save the seed of the random number generator and re-generate the map. For this, we need to store the seed and the random number generator in the map class. Previously, we were using libtcod's default random number generator with an unknown seed. We also have to move the map initialization code out of the constructor so that we're able to call it when the map is loaded from the file :

In case you wonder, 0x7FFFFFFF is the highest possible 32 bit signed integer value. The init function uses the code that was previously in the constructor, but the splitRecursive function now uses the map's RNG :

The withActors boolean is passed the the BSP listener in the userData parameter. It's a void * parameter that can contain pretty much anything. You can use it to store any numeric value (an int, a float, a boolean, a char...) or the adress of some struct/class. Here, we're simply casting the boolean into void *.

The room creation code now uses the map's RNG instead of libtcod's default one. It also retrieve the withActors value to pass it to the createRoom function. In Map.cpp, BspListener::visitNode :

If you want to be able to restart a game using the exact same map as before by entering the same seed, you also need to use the map's RNG in the createRoom, addMonster and addItem functions. But since there's no way to enter a seed right now, we won't do it.

A persistent engine

Now everything is ready and all we have to do is to implement the Engine::save and Engine::load functions. If you want to use boost, it's time you leave this tutorial and go on your own. For the others, brace yourselves ! It's time to reinvent the wheel ! Let's define some abstract interface for everything that must be saved :

We're going to use the top-down way, starting with the higher level class down to the smallest ones. In the attached source code, all the save/load method have been implemented in the Persistent.cpp file. While that might not be very orthodox, it helps keeping the bloat out of all the cpp files and having all the persistent stuff in a single file. Let's start with the Engine class. We obviously have to save the map and the actors. Another thing is the message log.

The map could save the width/height fields in its own save function, but since it won't be able to load them (because we need them to create the Map object), we keep the symmetry between the load and save functions and handle the width/height field in the Engine.

then the actors. Note that since we want to be able to know who is the player, we save him first. That's why we decrement the number of remaining actors (actors.size()-1).

// then the player
player->save(zip);
// then all the other actors
zip.putInt(actors.size()-1);
for (Actor **it=actors.begin(); it!=actors.end(); it++) {
if ( *it != player ) {
(*it)->save(zip);
}
}

Note that we have to call the Actor constructor with dummy parameters. We could define some default Actor::Actor() constructor for that. If there is no game.sav file, we initialize some new random map :

} else {
engine.init();
}
}

A persistent message log

Ok that was pretty easy so far. The message log persistence is also quite simple to implement :

The data returned by TCODZip::getString() won't be available once the TCODZip object is destroyed (as soon as we exit the Engine::load function). So it's very important to always duplicate the string. In our case, we don't need to do it because the message function already duplicates the text parameter using strdup.

Once again, we use a dummy value in the constructor but you could add a constructor with no parameter.

Now Destructible is quite different because our actors don't contain Destructible fields, but rather MonsterDestructible or PlayerDestructible. Since we can't call the load function on an object because we don't know what to create, we'll use some simplified factory pattern, using a static function on the Destructible class to create the Destructible object for us ;

if ( hasDestructible ) {
destructible = Destructible::create(zip);
}

The same happens for the Ai and Pickable classes since they both have descendant classes :

Persistent destructibles

To be able to restore the right type of destructible, we'll store some type information in the savegame file. The factory function will first read this type, then instantiate the Destructible and finally call the load function.

Note how we always duplicate the data returned by the getString function. This will create a small memory leak since the corpseName field is not destroyed when the Destructible is deleted. In fact we cannot delete the corpseName field because it does not always contain a dynamically allocated string (using new, _strdup of malloc/calloc). So far, corpseName always contained a static string (like "dead orc") that cannot be deleted because it points to a static part of memory inside the program's code (in fact if you open the .exe file with an hexadecimal editor, you will find those strings). One way to get rid of the memory leak is to always use dynamically allocated strings :

Persistent pickables

Well now that you've seen the method on the destructibles, you can apply it to the pickable. There's a small difference though. The destructible child classes share the same data, thus can use generic save/load function on the base class. On the other hand, the different Pickable child classes are quite different and have to implement their own persistence functions. The only place where we can reuse some code is in the Fireball class. Since it shares the same data as the LightningBolt class, it only needs to implement the save function (to put the right PickableType).

Afterword

You can now compile and should be able to exit the game and restart it where you left it. I'm conscious that that's a damn lot of code and a quite boring article and I really wish libtcod provided something out of the box for this (I mean something more elaborated than TCODZip). If you want to use this method for a more complex game, be also aware that this code is very error prone. You have to be very careful to always maintain the symmetry between the save and load functions. Forget a field in one of the functions and it's crash time. A better way to organize the savegame file would be to store data using some kind of TLV encoding (tag, length, value). Providing a tag for each field would at least allow some error checking while reading the file along with a possibility for backward compatibility (being able to load an older version of a savegame file). All this is beyond the scope of this tutorial.