How to load a cocos2d-x plist (configuration file) from C++

by on Jan.14, 2013, under Cocos2d-x

In this post I will try to explain how to use this cocos2d-x functionality from our C++ code.

Sometimes we might need to load a configuration file with some information for our game. For instance, let’s imagine that we need to load the level background image file name, width and height. Of course we always can use a constant, local class var, … etc to store this information. But as your project grows, it will be difficult to remember where you have stored this var, or the name of it. To avoid it, a solution could be to store this information into a text file. Cocos2d-x provides a functionality for loading a XML “like” text file.

Let’s try to make a simple example to use this functionality from our C++ Code. I’m going to be using the following text/xml file:

< ?xml version="1.0" encoding="UTF-8"?>
< !DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>BACKGROUND_01</key>
	<string>background1.png</string>
	<key>WIDTH_01</key>;
	<string>800</string>
	<key>HEIGHT</key>
	<string>600</string>
</dict>
</plist>

As you can see above, it is just a plan xml file with the following elements:

  • <plist version=”1.0″></plist>This mark this file as a plist file, recognaized by Cocos2d
  • <dict></dict> Everything contained inside this element will be contained by a CCDictinonaryΒ element in Cocos2d. We will see below how to load it.
  • <key>some_key_name</key> Inside this element we will store the keys name. It is like a variable name, we will use it inside our code in order to get the value for this key. Be aware that the key names must be unique inside our dictionary
  • <string>some_key_value</string> Inside this element we will add the value for the key we just defined above. In our example the value for the key “BACKGROUND_01” will be “background1.png”

Now that we understand how it works a plist file, let’s see how we will load this information from C++ using Cocos2d. For this example, we can use the following code:

	
	CCDictionary *pConfInfo;
	// create this dictionary object within the content of our plist configuration file
	pConfInfo = CCDictionary::createWithContentsOfFile("configuration.plist");

	CCString * bgFile;
	int width, height;

	// Get data for the given key. As you can see below, you can get this data within the format you expect (string, int, float....)
	pBackgroundFile = pConfInfo->valueForKey(keyValue)->getCString()()
	width = pConfInfo->valueForKey("WIDTH_01")->intValue();
	height =pConfInfo->valueForKey("HEIGHT_01")->intValue();

As you can see in the code snippet above, first of all you have to create a CCDictionary object. In order to initialize it, you might use the static method “createWithContentsOfFile” passing the configuration file name(there are other ways to initialize this object). In our example I have saved the XML file above with the name “configuration.plist”. After this, just use the method “valueForKey(keyValue)” of your CCDictionary object. As you can see in the code above, you might have to convert the result of this function to a type (int, float, string, ….).

So this is it. As simple as that, we have loaded our plist file into our Cocos2d-x C++ project. I hope this will help to understand how this configuration files works, and how to load them into our projects. Do not hesitate to ask if you have any doubt !!! πŸ™‚


4 Comments for this entry

Leave a Reply