XNA Serialization to XML tutorial

Introduction

What is serialization?

Serialization is a semi-automatic process where XNA gets a class that has been marked as [Serializable] and stores/loads it from xml. An awesome idea in theory but with a few shortcomings.

Why these tutorials?

While trying to add serialization to one of my games, I’ve come to notice that there is a very real lack of documentation on XML serialization if you want to do anything more complex than serializing a struct with a few value members inside. When you get to serializing derived classes, dictionaries, trees,… and in general the normal stuff any game needs, there are a lot of hidden pitfalls to be aware of.
It’s a big list of things to go work, but I’m going to share my experiments with serialization and hopefully it will help someone else.

Windows only

This tutorial is aimed only at the windows platform, simply because it’s the only one I’ve got. I promise that if anyone likes them enough to send me a WP7 or an Xbox, I’ll make sure they are compatible. :D

Note*: Check the comments to see the small change to make it work in WP7 and XBox

Serialization example

A look at MSDN serialization

This tutorial is based on the simplest of all options, the default MSDN tutorial for serializing xml, to be found at MSDN: Serialization. The version provided in the download of that article is aimed for the Xbox, which makes it kind of confusing on the windows platform as it uses classes that are not needed, such as the Guide class. If you are working on the Xbox and have doubts, have a look in the book: "XNA Game Studio 4.0 Programming".

My main objection to the example at MSDN: Serialization is that it does NOT tell you where it gets the "device" object, and if you download the code to find out, it uses the "Guide" to get the device in a rather confusing way.

Searching around on how to make it work I found another 3 ways to get the storage device here MSDN : Get StorageDevice. Note that even though they are ALMOST the same as in the MSDN: Serialization example code, the function call varies, not much, but enough to drive one crazy. God bless IntelliSense. If you’ve got more interest, there is a theoretical explanation on how to get a storage device at MSDN : User Storage.

Steps

For both saving and loading the steps are almost the same. Notice most of the work goes into getting the actual file we are going to save to. The function calls to achieve this vary slightly from platform to platform, but we’re going to stick with windows, as the code download at the MSDN: Serialization tutorial has a Xbox version.

1. User requests to Save / Load
2. Get the StorageDevice.
1. Request StorageDevice
2. Receive StorageDevice
3. Get a StorageContainer from the device.
1. Request StorageContainer
2. Receive StorageContainer
4. Get the Stream of the file we want to use from the container.
5. Serialize / Deserialize.
6. Cleanup.

Code

With that out of the way, let’s head over to the code!
We will be using a very simple data class to serialize in this first tutorial.

Code Snippet

1. /// <summary>
2. /// Data class with some basic data
3. /// for testing.
4. /// </summary>
5. [Serializable]
6. public class Data1
7. {
8. public int age;
10. public string name = "Chuel";
12. /// <summary>
13. /// Initializes a new instance of
14. /// the Data1 class.
15. /// Required default constructor for
16. /// serialization.
17. /// </summary>
18. public Data1()
19. {
20. this.age = 0;
21. }
23. /// <summary>
24. /// Initializes a new instance of
25. /// the Data1 class.
26. /// </summary>
27. /// <param name="age">Age of the chuel.</param>
28. public Data1(int age)
29. {
30. this.age = age;
31. }
33. public void Draw(SpriteBatch spriteBatch, SpriteFont font)
34. {
35. string text = "Name: " + this.name +
36. " Age: " + this.age;
38. spriteBatch.DrawString(
39. font, text,
40. new Vector2(10, 10),
41. Color.White);
42. }
43. }

First thing to notice here is that you need to mark with the [Serializable] attribute the class you want to serialize (Not necessary for serializing to XML, check r2d2rigo's comment), there are more options to explore with related attributes and you can find it here. Second, that it’s a public class, as the object you serialize must be public. Third, only public properties or fields will be serialized (age and name).

And here is how we load / save the data.

Code Snippet

1. /// <summary>
2. /// This is a game component that
3. /// implements IUpdateable.
4. /// It serializes data in a simple way,
5. /// no preprocesing or special content.
6. /// No blocking when doing the async. calls.
7. /// </summary>
8. public class Mode2 :
9. Microsoft.Xna.Framework.DrawableGameComponent
10. {
11. public Data1 data1;
12. private SpriteBatch spriteBatch;
14. // Keyboard polling helpers
15. private KeyboardState currentState;
16. private KeyboardState previousState;
18. // Action to do
19. private enum State {
20. Innactive, RequestDevice,
21. GetDevice, GetContainer,
22. SaveLoad };
23. private State state;
24. private enum Action { None, Save, Load };
25. private Action action;
27. // Needed variables
28. IAsyncResult result = null;
29. StorageDevice device = null;
30. StorageContainer container = null;
32. public Mode2(Game game)
33. : base(game)
34. {
35. state = State.Innactive;
36. action = Action.None;
37. }
39. public override void Initialize()
40. {
41. base.Initialize();
42. this.spriteBatch =
43. new SpriteBatch(Game.GraphicsDevice);
44. this.data1 = new Data1();
45. }
48. public override void Update(GameTime gameTime)
49. {
50. // Key checking
51. previousState = currentState;
52. currentState = Keyboard.GetState();
54. // STEP 1: User requests save / load
55. // When we press the "s" key
56. if (currentState.IsKeyUp(Keys.S) &&
57. previousState.IsKeyDown(Keys.S))
58. {
59. // Request to save
60. if (state == State.Innactive &&
61. action == Action.None)
62. {
63. this.state = State.RequestDevice;
64. this.action = Action.Save;
65. }
66. }
68. // When we press the "l" key
69. if (currentState.IsKeyUp(Keys.L) &&
70. previousState.IsKeyDown(Keys.L))
71. {
72. // Request to save
73. if (state == State.Innactive &&
74. action == Action.None)
75. {
76. this.state = State.RequestDevice;
77. this.action = Action.Load;
78. }
79. }
81. // Do the actual save or load
82. if (this.action == Action.Save &&
83. this.state != State.Innactive)
84. {
85. this.Save();
86. }
87. if (this.action == Action.Load &&
88. this.state != State.Innactive)
89. {
90. this.Load();
91. }
93. // Make the age change so we can see
94. // stuff change with the save / load
95. if (Mouse.GetState().LeftButton ==
96. ButtonState.Pressed)
97. {
98. this.data1.age += 1;
99. }
101. base.Update(gameTime);
102. }
104. /// <summary>
105. /// Function where we do all the saving
106. /// </summary>
107. private void Save()
108. {
109. switch (this.state)
110. {
111. case State.RequestDevice:
112. {
113. // STEP 2.a: Request the device
114. result =
115. StorageDevice.BeginShowSelector(
116. PlayerIndex.One,
117. null,
118. null);
119. this.state = State.GetDevice;
120. }
121. break;
122. case State.GetDevice:
123. {
124. // If the device is ready
125. if (result.IsCompleted)
126. {
127. // STEP 2.b: Recieve the device
128. device =
129. StorageDevice.EndShowSelector(result);
131. // STEP 3.a: Request the container
132. result.AsyncWaitHandle.Close();
133. result = null;
134. result = device.BeginOpenContainer(
135. "StorageDemo",
136. null,
137. null);
138. this.state = State.GetContainer;
139. }
140. }
141. break;
142. case State.GetContainer:
143. {
144. // If the container is ready
145. if (result.IsCompleted)
146. {
147. // STEP 3.b: Recieve the container
148. container = device.EndOpenContainer(result);
149. result.AsyncWaitHandle.Close();
150. this.state = State.SaveLoad;
151. }
152. }
153. break;
154. case State.SaveLoad:
155. {
156. string filename = "savegame.sav";
158. // Check to see whether
159. // the file exists.
160. if (container.FileExists(filename))
161. {
162. // Delete it so that we
163. // can create one fresh.
164. container.DeleteFile(filename);
165. }
167. // Create the file.
168. Stream stream =
169. container.CreateFile(filename);
171. // Convert the object to XML data
172. // and put it in the stream.
173. XmlSerializer serializer =
174. new XmlSerializer(typeof(Data1));
176. serializer.Serialize(stream, data1);
178. // Close the file.
179. stream.Close();
181. // Dispose the container, to
182. // commit changes.
183. container.Dispose();
184. state = State.Innactive;
185. action = Action.None;
186. }
187. break;
188. }
189. }
191. /// <summary>
192. /// Function where we do all the loading
193. /// </summary>
194. private void Load()
195. {
196. switch (this.state)
197. {
198. case State.RequestDevice:
199. {
200. // STEP 2.a: Request the device
201. result =
202. StorageDevice.BeginShowSelector(
203. PlayerIndex.One,
204. null,
205. null);
206. this.state = State.GetDevice;
207. }
208. break;
209. case State.GetDevice:
210. {
211. // If the device is ready
212. if (result.IsCompleted)
213. {
214. // STEP 2.b: Recieve the device
215. device =
216. StorageDevice.EndShowSelector(result);
218. // STEP 3.a: Request the container
219. result.AsyncWaitHandle.Close();
220. result = null;
221. result =
222. device.BeginOpenContainer(
223. "StorageDemo",
224. null,
225. null);
226. this.state = State.GetContainer;
227. }
228. }
229. break;
230. case State.GetContainer:
231. {
232. // If the container is ready
233. if (result.IsCompleted)
234. {
235. // STEP 3.b: Recieve the container
236. container =
237. device.EndOpenContainer(result);
238. result.AsyncWaitHandle.Close();
239. this.state = State.SaveLoad;
240. }
241. }
242. break;
243. case State.SaveLoad:
244. {
245. string filename = "savegame.sav";
247. // Check to see whether the save exists.
248. if (!container.FileExists(filename))
249. {
250. // If not, dispose of the
251. // container and return.
252. container.Dispose();
253. return;
254. }
256. // Create the file.
257. Stream stream =
258. container.OpenFile(
259. filename,
260. FileMode.Open);
262. // Convert the object to XML
263. // data and put it in the stream.
264. XmlSerializer serializer =
265. new XmlSerializer(typeof(Data1));
267. data1 =
268. (Data1)serializer.Deserialize(stream);
270. // Close the file.
271. stream.Close();
273. // Dispose the container, to commit changes.
274. container.Dispose();
275. state = State.Innactive;
276. action = Action.None;
277. }
278. break;
279. }
280. }
282. public override void Draw(GameTime gameTime)
283. {
284. base.Draw(gameTime);
286. this.spriteBatch.Begin();
287. this.data1.Draw(
288. this.spriteBatch,
289. Game.Content.Load<SpriteFont>("Font"));
290. this.spriteBatch.End();
291. }
292. }

We need to get 2 objects with asynchronous calls, the device and the container. This means we need to be careful not to block the game while we wait for the calls to return, and that’s why the code looks like a magical rainbow of cases, because the Update() function might be called lots of times while we wait and we don’t want strange stuff to happen.

We create a data object with just a name and an age, when we press the left button of the mouse the age increments, press “s” to save and “l” to load the last saved data.

Following the comments in the code should give a pretty clear idea of what is going on, but we’ll go over it none the less, I’ll ignore the support code not directly related with serialization, but if there are any doubts just ask in the comments. There is some redundant code but I haven’t shortened to make it as simple as possible to follow the logic.

Both save and load work very similar. First thing we need to do is get a storage device. This requires using an asynchronous call, so we request it (2.a) by calling BeginShowSelector and when it’s ready result.IsCompleted will return true. Notice that in windows we pass PlayerIndex.One as the parameter.

We then receive the device (2.b) and request the container from the device (3.a) with BeginContainer, where we pass the name of the “container” to use, in this case, the folder StorageDemo.

We finally we receive the container (3.b) and we’re ready to go! No more magical asynchronous stuff.

The last part is where the actual serializing takes place. For saving we get ourselves a file to write on (4) and a serializer for the type of data we want to serialize (Data1 in this case), and then just serialize it into the file (5) and tidy up (6). For loading we check the file exists (4) and then open it and deserialize into our data object (5) and clean up (6).

The generated XML looks like this:

Code Snippet

1. <?xml version="1.0"?>
2. <Data1 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
3. <age>43</age>
4. <name>Chuel</name>
5. </Data1>

A last note on how the system is set up. The Mode2 class is a DrawableGameComponent so that the XNA framework takes care of everything (updating and drawing and so on), and in our game class we only need to add one line. Has nothing to do with serializing.

Code Snippet

1. public Game1()
2. {
3. graphics = new GraphicsDeviceManager(this);
4. Content.RootDirectory = "Content";
6. this.Components.Add(new Mode2(this));
7. }

Notes

Data that XNA serializes

XNA doesn’t serialize everything that there is in the class, but the documentation is not too specific on what’s game besides “public properties and fields”. So I went ahead a did a little testing. Here are the results of testing, plus what I found searching around the net.

• Serializes public properties, not private or protected.
• Serializes public fields with both get and set, not partially implemented fields.
• Arrays of values or of objects work fine.
• Lists<> of values or of objects work fine. Tough not generic List<T>
• Cannot serialize ArrayList.
• Cannot serialize an enumeration of unsigned long with any value larger than 9,223,372,036,854,775,807.
• Typical XNA classes like Rectangle or Vector work just fine with the serialization.
• On serializing references, I found this bit from the MSDN forum:
  
  “It will serialize references, but always as a copy. Basically what this means is that each time the serializer hits an object that has a reference to another serializable object exposed as a public property or field, it will write out the all of the public properties/fields of the object that reference points to. This is a problem if you have the same object referenced multiple times by something you're serializing. For instance...say you had two MeleeAttack's referencing the same PhysicsObject. After deserialization, you'd end up with your MeleeAttack's having references to different PhysicsObject's with identical properties. I used to get around this by giving certain types of objects a unique integer ID, and then having the objects serialize the ID rather than the reference. Then after deserialization I'd have another initialization step where I'd use the ID to look up the corresponding object and grab a reference.”
• From textures it only saves the name.

Leads for more complex serialization magic

For elements that we read from Xml that are not in the object, we can use the XmlAnyElementAttribute and XmlAnyAttributeAttribute attributes. Useful for compatibility with older versions of our code. Check it here.

To ignore a field we can use the XmlIgnoreAttribute. Check it here.

You can override the serialization of any set of objects by creating one of the appropriate attributes and adding it to an instance of the XmlAttributes class. More complex stuff that can be used to serialize things that come from dlls, or to control how to serialize your own data. Check it here.

You can use the IXmlSerializable interface to provide custom formatting for Xml serialization and deserialization. Check it here.

4 Quick rules

To end, 4 quick reference rules to keep in mind for serializing:

• Note #1: You need to mark the class you want to serialize with the [Serializable] attribute.
• Note #2: Serialized classes must have a default constructor.
• Note #3: Serialization only converts the public properties and fields
• Note #3: The actual object you serialize must be public.

Conclusion

The serialization mechanism is awesome as in it’s automatic for the classes marked, but it’s lack of handling references correctly makes it useless for saving a big “chunk” of game data (like a whole level) as it doesn’t avoid the work of having to set up a ID system to take care of the references. It is best suited for things as saving the player preferences, or the control settings or similar.