Lesson 19.4 – Saving and loading the player information

Lesson objectives

At the end of this lesson, you will know…

• The basics of XML (Extensible Markup Language)
• How to save the player information to disk and reload it when the player restarts the game.
• How to make prevent your program from crashing, if it reads in a bad file.
• A very simple version of the “Factory” design pattern

Someone recently asked me how to save the player information for a game and reload it when they restart the game.

So, here’s a new lesson on how to do that.

NOTE: There is a lot happening in this lesson. But that’s what happens when you start to go beyond simple coding examples. In order to do one thing, you need to know how to do a couple other things. If you have problems understanding this lesson, take it one step at a time, until you are sure you know what is happening.

There are several different ways you could save data: in a database, a comma-separated value file, an XML file, etc.

We’re going to use an XML file. It doesn’t require installing anything extra, such as a database. It’s also easy to read, since an XML file includes the structure (definition) and the data.

Defining the XML file structure

It’s easier to understand XML with a sample. So, here is the format we’ll use to store the game’s data.

<Player>
    <Stats>
        <CurrentHitPoints>7</CurrentHitPoints>
        <MaximumHitPoints>10</MaximumHitPoints>
        <Gold>123</Gold>
        <ExperiencePoints>275</ExperiencePoints>
        <CurrentLocation>2</CurrentLocation>
    </Stats>
    <InventoryItems>
        <InventoryItem ID="1" Quantity="1" />
        <InventoryItem ID="2" Quantity="5" />
        <InventoryItem ID="7" Quantity="2" />
    </InventoryItems>
    <PlayerQuests>
        <PlayerQuest ID="1" IsCompleted="true" />
        <PlayerQuest ID="2" IsCompleted="false" />
    </PlayerQuests>
</Player>

What is XML?

Think of XML data as one long string, or file, with special formatting rules.

There are three main parts to XML: nodes, attributes, and values.

“Nodes”, or “tags”, are the names of values, kind of like a property in a class.

In our file, the nodes are: Player, Stats, CurrentHitPoints, Gold, ExperiencePoints, Currentlocation, InventoryItems, InventoryItem, PlayerQuests, and PlayerQuest.

A few thing you need to know about XML nodes:

1. Nodes have a start and an end. Notice that there is <Player> node at the very beginning, and </Player> at the end. The “/” before the node name indicates that it is the end of the node.
2. Node start and end names must match exactly. They are case-sensitive. So, you cannot start a node with “<NAME>” and end it with “</name>”.
3. Node names cannot contain a space. So, we can have a node named “CurrentHitPoints”, but not one named “Current Hit Points”.
4. Node starts and ends cannot cross. For example, you can have <A><B><C></C></B></A>, but you cannot have <A><B><C></B></C></A>. In the second example, the C node is started after the B node; however, the B node ends before the C node ends, which is not allowed in XML.
5. Nodes can also be “self-closing”. Notice that the InventoryItem nodes don’t have a corresponding </InventoryItem>. The “end” of those nodes is done with the “/” just before the “>”.
6. If you start a new node before the previous node ends (like the CurrentHitPoints node, being between the start and end of the Stats node) then it is called a “child node”. CurrentHitPoints is a child node of Stats, and Stats is a child node of Player.
7. A node can have multiple child nodes, even with the same name. See how InventoryItems has multiple InventoryItem nodes.
8. You can store data as “values”, like the 7 in CurrentHitPoints, or as “attributes”, like the ID and Quantity in the InventoryItems.

Notice in the InventoryItem nodes, we store the ID and Quantity as attributes. If you wanted to, you could store them as values in child nodes.

So, instead of this:

<InventoryItem ID="1" Quantity="1" />

You could have this:

<InventoryItem>
    <ID>1</ID>
    <Quantity>1</Quantity>
<InventoryItem>

It’s personal preference, which way you do it.

That’s enough information about XML for us to get started. There are some more rules you need to know about, if you want to do more work with XML. Check out the Wikipedia page on XML to learn about them.

One thing to watch out for is if you ever output user-entered data into XML. If the user enters a less-than sign “<“, XML thinks it is the beginning of a node – unless you follow some of the special techniques you’ll find on the Wikipedia page (look for CDATA).

Why we are writing our own serialization code, instead of using the built-in serialization

Sometimes you need to pass objects to something outside your program. The problem is that it doesn’t understand your program’s object, or class. One example is the file system, which understands strings (and a few other things).

One way to do pass an object is to use “serialization”.

There are built-in functions in the .Net framework to do serialization (converting from an object) and deserialization (converting back into an object).

However, these built-in functions can be a little complex to use, especially when you have an object that contains a list of other objects. You need to modify all your classes to know how to serialize/de-serialize themselves.

That’s a lot of work for a small game. So, we won’t be using that.

We’ll write our own functions to convert the Player object information to XML, and back from XML into a Player object.

By the way, there are several types of serialization. You may have also heard of JSON (JavaScript Object Notation), which is used to transfer object information in many web sites and web apps. It uses a different format for its data, but the concept is similar to XML.

OK, enough talk. Time to write some code.

Saving and reloading player information

Step 1: Open the SuperAdventure solution in Visual Studio and select the Player class to modify.

Step 2: At the top of the Player class, add this line to the “using” statement section, so we have access to the XML functions.

using System.Xml;

Step 3: Add this new ToXMLString() function to the Player class. This will take the Player information and create an XML string with all the Player’s current data.

public string ToXmlString()
{
    XmlDocument playerData = new XmlDocument();
    // Create the top-level XML node
    XmlNode player = playerData.CreateElement("Player");
    playerData.AppendChild(player);
    // Create the "Stats" child node to hold the other player statistics nodes
    XmlNode stats = playerData.CreateElement("Stats");
    player.AppendChild(stats);
    // Create the child nodes for the "Stats" node
    XmlNode currentHitPoints = playerData.CreateElement("CurrentHitPoints");
    currentHitPoints.AppendChild(playerData.CreateTextNode(this.CurrentHitPoints.ToString()));
    stats.AppendChild(currentHitPoints);
    XmlNode maximumHitPoints = playerData.CreateElement("MaximumHitPoints");
    maximumHitPoints.AppendChild(playerData.CreateTextNode(this.MaximumHitPoints.ToString()));
    stats.AppendChild(maximumHitPoints);
    XmlNode gold = playerData.CreateElement("Gold");
    gold.AppendChild(playerData.CreateTextNode(this.Gold.ToString()));
    stats.AppendChild(gold);
    XmlNode experiencePoints = playerData.CreateElement("ExperiencePoints");
    experiencePoints.AppendChild(playerData.CreateTextNode(this.ExperiencePoints.ToString()));
    stats.AppendChild(experiencePoints);
    XmlNode currentLocation = playerData.CreateElement("CurrentLocation");
    currentLocation.AppendChild(playerData.CreateTextNode(this.CurrentLocation.ID.ToString()));
    stats.AppendChild(currentLocation);
    // Create the "InventoryItems" child node to hold each InventoryItem node
    XmlNode inventoryItems = playerData.CreateElement("InventoryItems");
    player.AppendChild(inventoryItems);
    // Create an "InventoryItem" node for each item in the player's inventory
    foreach(InventoryItem item in this.Inventory)
    {
        XmlNode inventoryItem = playerData.CreateElement("InventoryItem");
        XmlAttribute idAttribute = playerData.CreateAttribute("ID");
        idAttribute.Value = item.Details.ID.ToString();
        inventoryItem.Attributes.Append(idAttribute);
        XmlAttribute quantityAttribute = playerData.CreateAttribute("Quantity");
        quantityAttribute.Value = item.Quantity.ToString();
        inventoryItem.Attributes.Append(quantityAttribute);
        inventoryItems.AppendChild(inventoryItem);
    }
    // Create the "PlayerQuests" child node to hold each PlayerQuest node
    XmlNode playerQuests = playerData.CreateElement("PlayerQuests");
    player.AppendChild(playerQuests);
    // Create a "PlayerQuest" node for each quest the player has acquired
    foreach(PlayerQuest quest in this.Quests)
    {
        XmlNode playerQuest = playerData.CreateElement("PlayerQuest");
        XmlAttribute idAttribute = playerData.CreateAttribute("ID");
        idAttribute.Value = quest.Details.ID.ToString();
        playerQuest.Attributes.Append(idAttribute);
        XmlAttribute isCompletedAttribute = playerData.CreateAttribute("IsCompleted");
        isCompletedAttribute.Value = quest.IsCompleted.ToString();
        playerQuest.Attributes.Append(isCompletedAttribute);
        playerQuests.AppendChild(playerQuest);
    }
    return playerData.InnerXml; // The XML document, as a string, so we can save the data to disk
}

At the start of this function, we create the playerData XmlDocument. This object lets us add nodes in a safe way, so we can’t break the most common XML formatting rules.

Now that we have the XmlDocument, we’ll populate it with our player data.

First, we create the “Player” XmlNode and add it to the document.

Next, we create the “Stats” XmlNode and add it as a child node to the Player node. That means it will start, and end, between the start and end of the Player node tags <Player> and </Player>.

Then we create nodes for the CurrentHitPoints, MaximumHitPoints, Gold, ExperiencePoints, and CurrentLocation. These nodes hold data, so their only child nodes are the values added to them with the CreateTextNode function.

Notice that we don’t have a node to store the Level value. That’s because Level is always calculated from the ExperiencePoints.

These nodes are all child nodes of “Stats”. So, when we finish creating them, we use the AppendChild method on the Stats node.

Then we add the “InventoryItems” node, and “InventoryItem” nodes for all the items in the player’s inventory.

Notice that we are using the CreateAttribute method to add the values to the nodes. After creating the attribute, we set its value.

Finally, we add the “PlayerQuests” node and its “PlayerQuest” child nodes (if any exist)

Since we are writing the XML value to a file, we return the InnerXml property of the XmlDocument, which is all the XML as a string.

This is probably a good time to rebuild your solution, and see if there are any errors, before we go to the next step.

Step 4: The next step is to make a new constructor for the Player class that takes the XML data and creates a new Player object, with the values from it.

This is where we’ll use the “Factory” design pattern.

A design pattern is basically a general method, or technique, to do something. It’s good to learn the common ones, especially if you work with other programmers. Then, instead of giving a long explanation of what you’re doing, you can just say, “It’s a Singleton,” or, “Use a Decorator.” Then the other programmer will know what you’re doing.

So far, in this program, whenever we want an object, we use the constructor to create an instance of the class. We’re going to change that for the Player class. We’re going to use a factory to create the object for us.

Replace the constructor for the Player class with the code below (and add in the two new functions).

private Player(int currentHitPoints, int maximumHitPoints, int gold, int experiencePoints) : base(currentHitPoints, maximumHitPoints)
{
    Gold = gold;
    ExperiencePoints = experiencePoints;
    Inventory = new List<InventoryItem>();
    Quests = new List<PlayerQuest>();
}
public static Player CreateDefaultPlayer()
{
    Player player = new Player(10, 10, 20, 0);
    player.Inventory.Add(new InventoryItem(World.ItemByID(World.ITEM_ID_RUSTY_SWORD), 1));
    player.CurrentLocation = World.LocationByID(World.LOCATION_ID_HOME);
    return player;
}
public static Player CreatePlayerFromXmlString(string xmlPlayerData)
{
    try
    {
        XmlDocument playerData = new XmlDocument();
        playerData.LoadXml(xmlPlayerData);
        int currentHitPoints = Convert.ToInt32(playerData.SelectSingleNode("/Player/Stats/CurrentHitPoints").InnerText);
        int maximumHitPoints = Convert.ToInt32(playerData.SelectSingleNode("/Player/Stats/MaximumHitPoints").InnerText);
        int gold = Convert.ToInt32(playerData.SelectSingleNode("/Player/Stats/Gold").InnerText);
        int experiencePoints = Convert.ToInt32(playerData.SelectSingleNode("/Player/Stats/ExperiencePoints").InnerText);
        Player player = new Player(currentHitPoints, maximumHitPoints, gold, experiencePoints);
        int currentLocationID = Convert.ToInt32(playerData.SelectSingleNode("/Player/Stats/CurrentLocation").InnerText);
        player.CurrentLocation = World.LocationByID(currentLocationID);
        foreach(XmlNode node in playerData.SelectNodes("/Player/InventoryItems/InventoryItem"))
        {
            int id = Convert.ToInt32(node.Attributes["ID"].Value);
            int quantity = Convert.ToInt32(node.Attributes["Quantity"].Value);
            for(int i = 0; i < quantity; i++)
            {
                player.AddItemToInventory(World.ItemByID(id));
            }
        }
        foreach(XmlNode node in playerData.SelectNodes("/Player/PlayerQuests/PlayerQuest"))
        {
            int id = Convert.ToInt32(node.Attributes["ID"].Value);
            bool isCompleted = Convert.ToBoolean(node.Attributes["IsCompleted"].Value);
            PlayerQuest playerQuest = new PlayerQuest(World.QuestByID(id));
            playerQuest.IsCompleted = isCompleted;
            player.Quests.Add(playerQuest);
        }
        return player;
    }
    catch
    {
        // If there was an error with the XML data, return a default player object
        return Player.CreateDefaultPlayer();
    }
}

Notice that the constructor is now private. That means it can only be called by another function inside the Player class. We didn’t need to do this. However, since we are only going to use the other two methods to create a Player object, I made it private.

So now, if you want to create a new Player object, you need to either call the CreateDefaultPlayer function or the CreatePlayerFromXmlString function. These methods are public. So they can be accessed by the rest of the solution. Since they are static, you can call them directly from the class, without an object (you’ll see to how to do that in a minute).

The CreateDefaultPlayer function should look familiar. It’s basically the same thing that the SuperAdventure page does when it creates a new player.

The CreatePlayerFromXmlString function is where we take the XML string with the game’s data, read the values in it, and create a player object with the values from the saved game.

First, we load the string into an XmlDocument object.

To get the data that only has a single value, we use the SelectSingleNode function on the XmlDocument. We give it the XPath of the data (like “/Player/Stats/CurrentHitPoints”). The “InnerText” says to get the value. InnerText always returns a string, so we need to wrap all that with Convert.ToInt32, to get the number.

Think of XPath, and child nodes, kind of like directories/folders, with sub-directories/folders, on your hard disk.

For the nodes that can have multiple items (inventory items and player quests), we use the SelectNodes function on the XmlDocument. This gets every node that matches the XPath. For each node, we create an InventoryItem, or PlayerQuest, object, set its values, and add it to the player object.

Notice that this function has a “try” and a “catch” section. This is known as a “try catch block”. What happens here is that the program tries to run everything in the “try” section. If there is an error, it does whatever is in the “catch” section.

We have this here in case there is ever a problem with the file (like, if someone tries to modify it, and messes it up). Instead of the user seeing an error, the program will execute the “catch” block and create the default player for the game.

Try catch blocks are a very powerful tool in professional programming. Instead of having your program crash, you can have it deal with problems more gracefully.

Don’t try building your program now. Since we made the Player constructor private, we need to make a couple changes before we can build without errors.

Step 5: Next, we need to have the program write the player’s information to disk when they exit the program.

We’re going to do this by adding code to the “FormClosing” event of the program. Whenever the program is being closed (stopped), this function will run. It will take the player’s current information, using the new ToXMLString() method of the Player class, and write it to the disk, in a file named “PlayerData.XML”

Select the SuperAdventure.cs file, and open it in design mode (so you see the screen). In the lower-right corner of Visual Studio, in the Properties box, click on the lightning symbol.

Now you see all the events that this form has. Scroll to the “FormClosing” event, and double-click on it.

That should have taken you to the code for the SuperAdventure form and created a function named “SuperAdventure_FormClosing”. This is the function that will be run when you close the program.

NOTE: It is important to create the function this way. This method adds a line of code to another file that connects the function to the FormClosing event. If you only copy/paste the new SuperAdventure.cs code into your program, that line will not be created, and this function will not ever run.

Before we add the code for this function, we need to include a reference to the library that lets us write to, and read from, the disk. Go to the top of the page and add this line to the section with the other “using” statements:

using System.IO;

Scroll down to the section where we define our class-level variables _player and _currentMonster (this should be around line 20). Add this new line as class-level constant:

private const string PLAYER_DATA_FILE_NAME = "PlayerData.xml";

That is the file name where we will save the player’s data. We made it a constant, because it doesn’t change. And it’s a class-level variable, so we can use it in the function that creates the file and the function that loads the file. We need it visible in both places.

Go back to the SuperAdventure_FormClosing function and change it to this:

private void SuperAdventure_FormClosing(object sender, FormClosingEventArgs e)
{
    File.WriteAllText(PLAYER_DATA_FILE_NAME, _player.ToXmlString());
}

Now, when the program is closing, it will write the player’s data, in our XML format, to the PlayerData.xml file.

Step 6: Finally, when the game starts, we want to look for the PlayerData.xml file.

If it exists, we’ll read it and create the player object from its values. If it doesn’t exist, we’ll assume we are starting a new game and use the normal Player constructor to create a new Player object.

Change the “public SuperAdventure” function to this:

public SuperAdventure()
{
    InitializeComponent();
    if(File.Exists(PLAYER_DATA_FILE_NAME))
    {
        _player = Player.CreatePlayerFromXmlString(File.ReadAllText(PLAYER_DATA_FILE_NAME));
    }
    else
    {
        _player = Player.CreateDefaultPlayer();
    }
    MoveTo(_player.CurrentLocation);
    UpdatePlayerStats();
}

When the game starts, it will look for the PlayerData.xml file.

If the file exists, it will read it and create the Player object with the values in the file. If it doesn’t find the file, it will create the default Player object.

Now you can build the solution.

Try moving the player to a new location, then exit the game and restart it. You should see that the game starts with the player in the new location.

If you ever want to have the player start over, you can manually delete the PlayerData.xml file (it will be in the same directory as SuperAdventure.exe). If you want to get fancy, you could add a menu to the game and let the play save and restore multiple games, with different file names.

But, I’m going to stop for now. We’re already way over 2000 words in this lesson.

Check your work

Build the solution and make sure there are no errors in the “output” box at the bottom of Visual Studio. If you see any problems, double-check the changes you made in this lesson.

Summary

This was a big lesson, with some new concepts.

If you want to become a professional programmer, read about design patterns and learn about good practices to use with try catch blocks.

Source code for this lesson

Source code on GitHub

Source code on Dropbox

Next lesson: Lesson 19.5 – Changing dropdown default values

Previous lesson: Lesson 19.3 – Clean up the source code by converting foreach to LINQ

All lessons: Learn C# by Building a Simple RPG Index