Developer Guide (Version 1.11)

Using the Lua XML Loader

CryLua is deprecated and will be removed in a future version of Lumberyard.

There is a generic interface for parsing and translating XML files into Lua files. This interface uses an XML file as a definition format that declares what kind of XML is included in a file and what kind of Lua to create from the XML. The format includes some simple validation methods to ensure that the data received is what is expected.

XML Data

The XML loader can distinguish between three kinds of data: properties, arrays, and tables.


This table represents a Lua-based table:

letters = { a="a", b="b", c="c" }

In an XML data file, this table would look like this:

<letters a="a" b="b" c="c"/>

The XML definition file would look like this:

<Table name="letters"> <Property name="a" type="string"/> <Property name="b" type="string"/> <Property name="c" type="string"/> </Table>

Each element can be marked as optional in the definition file using the attribute optional="1".


There are two possible types of arrays. The first type is a simple group of elements, shown in Lua like this:

numbers = {0,1,2,3,4,5,6,7,8,9}

In the XML data file, the array would look like this:

<numbers> <number value="0"/> <number value="1"/> <number value="2"/> <number value="3"/> <number value="4"/> <number value="5"/> <number value="6"/> <number value="7"/> <number value="8"/> <number value="9"/> </numbers>

The data definition file would look like this:

<Array name="numbers" type="int" elementName="number"/>

The second array type is an array of tables. In Lua:

wheels = { {size=3, weight=10}, {size=2, weight=1}, {size=4, weight=20}, }

In the XML data file:

<wheels> <wheel size="3" weight="10"/> <wheel size="2" weight="1"/> <wheel size="4" weight="20"/> </wheels>

The XML definition file:

<Array name="wheels" elementName="wheel"> <!-- note no type is attached --> <Property name="size" type="float"/> <Property name="weight" type="int"/> </Array>

Loading and Saving a Table from Lua

To load and initialize a Lua table:

someTable = CryAction.LoadXML( definitionFileName, dataFileName )

When storing XML files for scripts, the recommended practice is to keep the definition files with the scripts that use them, but store the data files in a directory outside the Scripts directory.

To save a table from Lua:

CryAction.SaveXML( definitionFileName, dataFileName, table )

Data Types

The following data types are available, and can be set wherever a "type" attribute is present in the definition file.

  • float – Floating point number.

  • int – Integer.

  • string – String.

  • bool – Boolean value.

  • Vec3 – Floating point vectors with three components. Values of this type are expressed as follows:

    • XML – "1,2,3"

    • Lua – {x=1,y=2,z=3}


For string type properties, an optional <Enum> definition can be used. Property values will be validated against the enum.


<Property name="view" type="string"> <Enum> <Value>GhostView</Value> <Value>ThirdPerson</Value> <Value>BlackScreen</Value> </Enum> </Property>

Enum support for other data types can be added, if necessary.


XML definition file:

<Definition root="Data"> <Property name="version" type="string"/> <Table name="test"> <Property name="a" type="string"/> <Property name="b" type="int" optional="1"/> <Array name="c" type="string" elementName="Val"/> <Array name="d" elementName="Value"> <Property name="da" type="float"/> <Property name="db" type="Vec3"/> </Array> <Property name="e" type="int"/> </Table> </Definition>

Corresponding XML data file:

<Data version="Blag 1.0"> <test a="blag" e="3"> <c> <Val value="blag"/> <Val value="foo"/> </c> <d> <Value da="3.0" db="2.1,2.2,2.3"/> <Value da="3.1" db="2.1,2.2,2.3"/> <Value da="3.2" db="3.1,3.2,2.3"/> </d> </test> </Data>