Main menu and saving

To choose between continuing a previous game or starting a new one we need a main menu. But wait: our initialization logic and game loop are tightly bound, so they’re not really prepared for these tasks. To avoid code duplication, we need to break them down into meaningful blocks (functions). We can then put them together to change between the menu and the game, start new games or load them, and even go to new dungeon levels. It’s much easier than it sounds, so fear not!

Take a look at your initialization and game loop code, after all the functions. I can identify 4 blocks:

We can use these as the building blocks to make up the higher-level tasks like loading the game or moving to a new level:

Let’s put everything from main except for the system initialisation and the main loop into a new_game function:

We return a tuple with two elements: the vec of Objects and the Game struct.

new_game is calling initialise_fov so we need to create it and move the FOV-related code to it:

Finally, the game loop and the few bits before it belong to their own function as well:

And now we just call new_game and play_game from our slimmed-down main function:

let (a, b) = some_tuple is how we turn a tuple into its parts. We have to put mut in front of each one so Rust lets us change them later.

You can think of let (mut a, mut b) as two separate bindings: let mut a = …​ and let mut b = …​. Except since new_game returns a tuple, we can’t really have them as separate.

Anyway, the game should compile again and the setup code is more modular. Which will come in handy in the coming sections.

To keep our main menu from appearing a bit bland, it would be pretty cool to show a neat background image below it. Fortunately, tcod lets us load and display images!

Since libtcod emulates a console, we can’t directly show arbitrary images, since we can’t access the console’s pixels. We can, however, modify the background color of every console cell to match the color of a pixel from the image. The downside is that the image will be in a very low resolution.

However, libtcod can do a neat trick: by using specialized characters, and modifying both foreground and background colors, we can double the resolution! This is called subcell resolution, and this page of the docs shows some images of the effect (at the end of the page).

This means that, for our 80x50 cells console, we need a 160x100 pixels image. We’ll be using the image from the original Python tutorial.

Now replace the calls to new_game and play_game in main with:

If you try it out now, you’ll see a nice menu with a dungeon-y backdrop!

Now let’s add the game’s title and some credits. You’ll probably want to modify the values. Put this in the main_menu before calling the menu function:

You’ll notice that the menu rectangle starts with a blank line. That is because the header string is empty, but root.get_height_rect reports its height as 1 by default.

To make the line go away, we need to check that condition in the menu function:

Finally, when you start a game, go back to the main menu with Escape and start another game results in a bug! Parts of the first game are still visible in the second game. To fix that, we need to clear the console.

At the end of initialise_fov:

There it is, a neat main menu, and with only a handful of lines of code!

Storing a game state to disk (and then reloading it) is not conceptually hard: You could imagine just taking all the data from our game and objects variables and writing them to a file value by value.

It would, however, be a huge hassle that would require a ton of code, you’d need to define a way to structure the data in the file and there’s a good chance you’d get a lot of bugs at first.

Luckily, there are ways of automating most of this that make saving and loading quite painless. Here’s the teaser:

Don’t mind the ? operator at the end of the line for now, it’s there for error handling and we’ll explain it in a bit.

The first line (serde_json::to_string(&some_data)) takes the data we want to save (objects and the game state in our case) and turns it to a JSON-encoded String.

That functionality comes from the serde and related crates so we need to add them to our [dependencies] in the Cargo.toml file and we’ll also enable the "serialization" feature in the tcod crate:

The serde crate provides the main functionality for serializing and deserializing of Rust data. This includes the Serialize and Deserialize traits which describe what to do for a given struct/enum/whatever. The optional derive feature provides a way to derive those traits so we don’t need to implement them ourselves and finally serde_json converts any serializable struct to and from JSON. If we wanted to use a different format (YAML, TOML or anything else, we’d replace this crate with another one that supports what you want).

Now let’s add those traits our source code, including the save_game function and try to compile:

Unfortunately, the compilation will fail:

Apparently, we need to implement the Serialize trait. That tells Rust how to encode each bit of data in our structs. We can do it manually, but it would be error-prone and really tedious. Luckily, we can just use #[derive(Serialize)] and have Rust do it for us!

If you try to compile it now, you’ll see that the complaint has shifted from Game to Object. We’ll need to derive Serialize for every struct and enum we’ll be saving.

There is a complementary trait called Deserialize which goes the other way: from a serialised representation to a struct.

So let’s add them all at once:

It’s a bit of a bother but not the end of the world. After that, our code should be compiling, though it will warn that save_game is not actually called from anywhere. Let’s fix that!

Traditionally, roguelikes only let you save when you’re quitting the game, so we’ll call save_game in play_game right before the break that ends the game:

If you run the game now and then quit it, you should see a new file called savegame created. You can look inside it — thanks to it being JSON-encoded, it’s actually somewhat readable. It will contain all the objects and the entire game state.

But if we’re not able to do anything with the save file, what use does it have? We need to add a load_game function, too:

It’s basically just the reverse of save_game: we read the save file contents to a String, then we decode it into our objects Vec and Game struct and if it all succeeds, return the pair.

In main_menu we’ll handle the load game choice now:

To make things compile, you’ll have to derive Deserialize to every struct and enum that has the Serialize trait, too.

After that, you should be able to load a previously saved game and continue playing!

But what if there is no game to load? Or if the file gets corrupted? We haven’t talked about error handling much, but now we need to.

The Rust book has a whole chapter on error handling so we’ll do only a tiny introduction. You should read that chapter.

Both save_game and load_game return a Result value. Result is similar to Option in that it has two possibilities it can return — one that usually indicates a success and the other failure. But in Result’s case, the failure can have associated data as well. The successful variant is called `Ok and the failure is Err.

There’s also the Error trait which represents an error and lets you get its textual description. All the file-handling serialisation errors in our save/load code implement Error.

So, looking at save_game, the serde_json::to_string call returns either Ok(String) with the encoded value or Err(serde_json::error::Error) on failure. File::create and the write_all method work similarly although with different success and error types.

Since we can return more then one error type, we return Box<Error> instead. That lets us return any type that implements Error and the caller can get at the description and the raw error if they want.

:?: https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html?highlight=with,result#recoverable-errors-with—​result

The {?}[? operator] is a convenient way of saying "If this failed, return from the function with error immediately, otherwise give me the success value". The operator also does an extra conversion to the error type specified in the functions return value.

So let mut file = File::create("savegame")?; is almost equivalent to

Only difference is that the ? operator also does the conversion of the error to whatever Error type the calling function asks for. In our case, since we’re using Box<Error>, no conversion will actually be done.

So, that explains the save/load game functions. But what about using their results?

If you tried to compile the game, you’ve seen this warning:

It did not cause an error but Rust is being passive-aggressive about how we’re calling a function that can fail and then ignoring it.

So, we can keep ignoring it, try to actually handle the error or simply crash by calling unwrap :-)

Unwrap will make Rust happy that we’ve processed the Result, but it will simply abort the program whenever we get Err back.

Replace the call to save_game with save_game(objects, game).unwrap().

You have to realise however, that if this ever happens, it will make your users really unhappy. If save_game fails for any reason, your game will just quit without any warning and the player will lose their progress. You should always try to handle errors gracefully.

Let’s do that when we load the game. Calling load_game right now uses unwrap as well, so if there is no game to load or something similar, we’ll just quit the game.

We could just print a message and let the player start a new game instead:

And we’ll add a function to display messages that relies on menu to do all the heavy lifting:

And that’s it! The actual saving and loading code was quite small, but we had to learn a ton of new stuff to understand it.

Here’s the complete code so far.

Continue to the next part.