From Blue Mars Developer Guidebook

Jump to: navigation, search

XML files can be loaded as Lua tables, and Lua tables can be written as XML files.

ARLoadXML(definitionFile, dataFile)
load an XML file into a Lua table

ARSaveXML(definitionFile, dataFile, dataTable)
writes an Lua table to an XML file

This process requires a definition file (for those familiar with XML, this is a simplified version of an XML Document Type Definition file or schema file), which specifies how data is converted between the two formats.

Definition Files

A definition file is also an XML file. It instructs ARLoadXML what nodes and attributes to expect in the XML file it's reading and how to convert values to Lua, and likewise tells ARSaveXML how to write out a Lua table into a particular XML format.

The definition file always starts with the definition of the root node tag in the XML data file, with a list of the properties (XML tag attributes) expected for that tag. After that, the subnodes of the root node can each be a Table or Array, each with an optional set of Property specifications that correspond to tag attributes. Array is like Table but with an expected number of subnodes each using the tag specified in the Array elementName attribute.

Each property specifies the property name and Lua type it should be converted to: int, float, or string. A leaf-node (i.e. containing no child nodes) with content (the data between the tag begin and end) can also be interpreted as a Property.

Tables, arrays and properties can be specified as optional.

As an example, if we have this definition file:

<?xml version="1.0"?>

<Definition root="player">

 <Property name="age" type="int" />
 <Property name="name" type="string" />
 <Property name="weight" type="float" />

  <Array name="nicknames" elementName="alias">
	<Property name="firstname" type="string"/>
	<Property name="lastname" type="string" optional="1"/>

	<Table name="address">
	<Property name="city" type="string"/>
	<Property name="planet" type="string"/>


and we have an entity script with a matching Lua table:

MyXML = {
   data = {
      nicknames = {
	 {firstname="fugu", lastname="neumann"},
      address = {city="Beach City", planet="Blue Mars"},


then calling ARSaveXML with the template and table like this:


results in this XML file saved in the user's Blue Mars directory:

<player age="5" name="phil" weight="160.10001">
  <alias firstname="bubba"/>
  <alias firstname="fugu" lastname="neumann"/>
 <address city="Beach City" planet="Blue Mars"/>

And if we load the resulting XML file using ARLoadXML, again specifying the definition file, into a Lua table and dump the table to the log file:

 local result = ARLoadXML("Levels/MyCity/Common/Libs/XMLSampleDef.xml","mysample.xml")

we see the contents of the table match what we started with

<Lua> $2  $6name$1=$8"phil"
<Lua> $2  $6weight$1=$8160.1
<Lua>   $4address$1= {
<Lua> $2    $6city$1=$8"Beach City"
<Lua> $2    $6planet$1=$8"Blue Mars"
<Lua>   $1}
<Lua> $2  $6age$1=$85
<Lua>   $4nicknames$1= {
<Lua>     $41$1= {
<Lua> $2      $6firstname$1=$8"bubba"
<Lua>     $1}
<Lua>     $42$1= {
<Lua> $2      $6firstname$1=$8"fugu"
<Lua> $2      $6lastname$1=$8"neumann"
<Lua>     $1}
<Lua>   $1}

Remember, leaf-node tags with content can also be read as properties, so we'll get the same table if we edit the result XML file like this:

<player age="5" name="phil" weight="160.10001">
  <alias firstname="bubba"/>
  <alias firstname="fugu" lastname="neumann"/>
	<city>Beach City</city>
	<planet>Blue Mars</planet>

More examples are used in the High Score Server example.

Problems with this wiki page? Contact us either by: Support Email or Support Ticket System

Blue Mars Guidebook Privacy Policy
Blue Mars Guidebook Community Guidelines

Personal tools