How does Unity3D do XML?

Well, Unity3D uses the Mono implementation of the .net XML processor. Honestly I didn’t really want to know this, I just wanted to process XML. [did I mention that I am both needy AND demanding?].

In Unity3D (for 2.5 and 2.6 at least) it turns out that XML is best processed through C#.

What you need to do

• Write file open functions in C#
• Write XML read and write functions in C#
• write a function to read  the XML and process the results
• write a function to write game data in XML
• Optional: Read and write lists

The instructions are a bit confusing, you may just want to Skip them and, just read source code: Read and Write XML from Unity3D.

Calling C# from JavaScript in Unity3D

My project is coded in JavaScript, because it is the most productive. But, even though calling the .net functions can be done from JavaScript, it is still a bit of a mystery.  Processing XML is most natural through C#. So now I will have a project that uses both C# and JavaScript.

Fiddly bit of Unity3D magic

The first thing you have to know is that the C# files have to be “built” first, so the class names can be known to the JavaScript compiler.  The Unity3D documentation mentions that files in the Plugins or Editor folders get built before JavaScript.

1. Create a C# file, place it in the Plugins directory

I’ll cover how to call the C# stuff from JavaScript later.

Stuff you need to include for C# into Unity3D

using UnityEngine;
using System.Collections.Generic;
using System.Xml;
using System.Xml.Serialization;
using System.IO;
using System.Text;

Unfortunately this (currently) causes a cascade of includes, and you will notice the size of your plugin BLOAT bigtime.

Opening the file

It turns out that you will want to open your save file one way for read, and another way for write.

Most of the howtos on the web show reading and writing an XML file by opening a Stream. I found it is MUCH easier to open a stream to write, and open a “TextReader” for read.

but first, your C# class needs to be defined:

public class GameXML : MonoBehaviour
{
 string _FileLocation,_FileName;
 StreamWriter _writer;
 TextReader _reader;

Then you can open the file. I created one function for read and another for write.

public void OpenSaveFileForWrite()
 {
 FileInfo t = new FileInfo(_FileLocation+"\\"+ _FileName);
 if(!t.Exists)
 {
 _writer = t.CreateText();
 }
 else
 {
 t.Delete();
 _writer = t.CreateText();
 }
 }

 public void OpenSaveFileForRead()
 {
 FileInfo t = new FileInfo(_FileLocation+"\\"+ _FileName);
 if(t.Exists)
 {
 _reader = t.OpenText();
 }
 else
 {
 Debug.Log("SaveFile NotFound");
 }
 }

Yeah Ok, so I am not taking time to figure out indenting. You can check out formatted code in the included sourcecode.

Using Unity3D to write XML, it really is just two function calls

Well, you need a class that describes your games’ save data, but once you have that, all you need to do is turn it into a single text string (Serialization) then write the file out. Also once the data has been serialized, it can be written out using debug routines or printf or whatever, it’s just a big text string.

public void WriteGameDataAndTurnSequence(GameSaveGame SGDat )
 {
 string _data = SerializeGame(SGDat);
 Debug.Log("Game Sequence looks like:" + _data); 

 _writer.Write(_data);
 }

That’s it…Well sort of. The GameSaveGame class needs a little esplination. The function above is called from JavaScript. You can pass a reference to a class back and forth between JavaScript and C#. As long as that class has all the data you need then your good. BUT the tricky bit is building a class structure that describes all the data you need. For most games you’ll have structured data and lists that need to be read and written. This can get a little messy.

Templates, and sequences classes, Oh My

Your Serialize function will serialize ONE instance of a class. So in order to read and write complex data, you need to create a russian doll set of class constructs. Lists of class elements held by a “top level” class.

Ok, this gets messy. I want to write out a list of turns. the .net serialization can serialize a templated List. This is powerful, it means I can write out a list of arbitrary structure.What you need to know is that you will likely want to define 3 classes:

That One class can contain a Sequence(and tons and tons of other stuff). The Sequence is a class that contains a list of class instances. Your sequence is essentially defined as  a List<ListElementClass>. The Class definition the Sequence, actually sequences is the class definition that holds your actual game data.

Confused? I sure was.

Bottom line, create 3 class definitions in your C# file.

1. One “top level” class that defines the top level structure of your game
2. One (or more) “Sequence” classes that hold lists of data
3. One “List Element” class that describes the data in each list element

Top Level

So my “top level” class just needs to really define two members, one for “settings” and one for the game’s turn list.

public class GameSaveGame
{
 public GameData GameSettings;
 public GameSequence Turns;

 public GameSaveGame()
 {
 GameSettings = new GameData();
 Turns = new GameGameSequence();
 }

 public GameSaveGame(GameData pData, GameSequence pGS)
 {
 GameSettings = pData;
 Turns = pGS;
 }
}

Sequence

my Sequence  GameSequence class so that it would be easy to add elements and stuff like that.

public class GameSequence
{
 public List<TurnData> TurnList = new List<TurnData>();
 private int Sequence = 0; 

 public GameSequence () { }

Thee are more convenience functions in the source code, but you get the Idea. Finally, the sequence is a sequence of “TurnData” structures. The “TurnData” class actually describes what a turn is.

List Element

Finally, the inner most nugget. A simple class that describes the data in each turn.

public class TurnData
{
 public TurnData (){ Unconditional = false; SequenceNum = 0;}
 public TurnData ( int x, int y, int z, int PID, bool cond, int seq)
 {
 X = x;
 Y = y;
 Z = z;
 PlayerID = PID;
 Unconditional = cond;
 SequenceNum = seq;
 }

Reading XML with Unity3D

Reading is just as easy as writing, but I recommend using a different type of stream to read and parse the XML. Extracting XML into game data is just two steps

1. Open the file for read
2. De-serialize

Open the file for read….

public void OpenSaveFileForRead()
 {
 FileInfo t = new FileInfo(_FileLocation+"\\"+ _FileName);
 if(t.Exists)
 {
 _reader = t.OpenText();
 }
 else
 {
 Debug.Log("SaveFile NotFound");
 }
 }

Reading XML with Unity3D: a little magic

Here we actually “do something with XML”. XmlSerializer is the function that parses the formatted xml data and fills in all those classes you defined.

GameSaveGame DeserializeGame(TextReader file)
 {
 XmlSerializer xdsg = new XmlSerializer(typeof(GameSaveGame));
 GameSaveGame newGame;
 newGame = (GameSaveGame)xdsg.Deserialize(_reader);
 _reader.Close();
 return newGame;
 }

within Unity3D Calling C# from JavaScript

So, one last thing. How to call the C# functions from Javascript.

1. Declare a variable using the name of the C# file (becomes the class name)
2. Get the instance of that class
3. Fill a data structure with your game save data
4. call your unity3D save/load function

It looks something like this

private var SaveLogic : RnWXML; // note I put my CSharp files in the Plugins directory
SaveLogic = GameRootClass.GetComponent(RnWXML);
var NewGame : SaveGame = SaveLogic.ReadSaveGame(); // the SaveGame class is defined in SaveLogic C#

I hope this help someone. There are a lot of twiddly bits of magic that need to be strung together in order to read and write XML. What I have NOT done yet is read and write XML from a URL, which will mean opening up a stream reader and writer to an HTTP connection.

That will be interesting, facebook might be a good source of XML….

And if you missed the source code link at the beginning of this post: Read and Write XML from Unity

How to do that in Unity3d? well the unity 3d web forums gave me a hint.

Bottom line is to use the Coroutine function yeild, and the Lerp function off of Vector3D.

what I do is instantiate an object from a prefab, then call a function called growObj.

Here is my GrowObj function (NOTE: I leave off the type of the first parameter so it could be called with any object that contains a .transform member)

/* groObj function, grow an object fom nothing  to some destination size over a period of time
    go is an object to grow
    toScale is the destination scale preferably the object's original local scale
*/
function growObj( go, toScale: Vector3)
{
	var i = 0.0;
	var rate = 1.0 / GrowTime;
	var StartScale = Vector3.zero;
	while ( i <= 1.0)
	{
		i += Time.deltaTime * rate;
		go.transform.localScale = Vector3.Lerp(StartScale, toScale, i);
		yield;
	}
}

Objects grow one at a time

	 for (var z = zStart ; z < zEnd; z++ ){
	    var pos = Vector3 (0, 0, z) * 4;
	    var clone;
	    clone = Instantiate(prefab, pos, Quaternion.identity);
	    var DestScale : Vector3 = clone.transform.localScale; // capture the original size of the object
	    yield growObj(clone,DestScale);
	}

all objects appear and grow together

	 for (var z = zStart ; z < zEnd; z++ ){
	    var pos = Vector3 (0, 0, z) * 4;
	    var clone;
	    clone = Instantiate(prefab, pos, Quaternion.identity);
	    var DestScale : Vector3 = clone.transform.localScale; // capture the original size of the object
	    growObj(clone,DestScale);
	}

Yup the only difference in the two loops is the yield statement in front of growObj.

That’s all for now. I hope to make a “bubble” grow function some time, where the object will overshoot destination scale once, then undershoot the destination scale once

When you build a project in Unity3d, select the web build, and pick a seporate folder for unity to put the output file into.

In Wordpress, in Site Admin, click the media link, and upload new media, browse to directory you told unity to dump the files. Select and upload the “.unity3d” file

When you downloaded the Wordpress plugin from the Unity support site there is a readme file. That readme file contains examples on the tags you need to place in your blog posts.

here are the instructions from the readme.txt file that comes with the plugin

=== Usage Instructions ===

With the plugin installed and activated as part of your WordPress blog you can start embedding Unity Web Player content in your posts. Embedding content within your post is done by using a simple tag structure:

Please view the full post to see the Unity content.

The outer tag declares the existence of Unity Web Player content, the name/value pairs you provide then determine what content is displayed and how. There is only one required parameter, the src URL for the content to be displayed, all other parameters are optional and if not provided default values will be used instead.

When adding any of the optional parameters please note that the order you list them is not important. Simply provide each parameter in name=”value” format, there should be no spaces before or after the equals sign and the value provided should always be wrapped in double-quotes (the ” character). Additionally you need to separate each of the name/value pairs with an empty space. For example, here is a tag set where the src, height and width are all specified:

Please view the full post to see the Unity content.

=== Usage Instructions ===

With the plugin installed and activated as part of your WordPress blog you can start embedding Unity Web Player content in your posts. Embedding content within your post is done by using a simple tag structure:

\[WP_UnityObject src="http://www.yourdomain.com/yourfile.unity3d" \/\]

The outer tag declares the existence of Unity Web Player content, the name/value pairs you provide then determine what content is displayed and how. There is only one required parameter, the src URL for the content to be displayed, all other parameters are optional and if not provided default values will be used instead.

When adding any of the optional parameters please note that the order you list them is not important. Simply provide each parameter in name=”value” format, there should be no spaces before or after the equals sign and the value provided should always be wrapped in double-quotes (the ” character). Additionally you need to separate each of the name/value pairs with an empty space.

When you upload content into the WordPress Media library, it will give you the URL to your content.

Soo…. let’s see how it works

Please view the full post to see the Unity content.

Did it work?

Well, unfortunately more often than not you’ll get an error downloading the file.
Reading the developer’s  unity 3d blog it seems some people have had success others may be having the same problem as here.

Sure it has it’s bugs, and problems like any software, but they are few and far between.

One huge advantage Unity has is the sheer number of blogs and posts and information for developers. I have to say Will Goldstone’s posts at LearnMeSilly.com are some of the best “Zero to Hero” tutorials I have ever seen. He is writing a book about Unity I hope he is able to make a comfortable living doing what he has been doing. I know the unity community owes him a lot.

I was able to learn everything I needed to know about Unity in 3 days to start development on a game. What was amazing to me, is that I started this project with a sketch and a plan. and after 15 days. I had a playable game that acutally looked a lot like my sketch.

Part was because Unity is so easy to use, and in my mind that makes it powerful, but also in part due to the sheer amount of content that can be absorbed and used by unity.

But now I need to figure out how to get a unity build to display in a wordpress post. Stay Tuned