IwGame Engine – Using Templates Tutorial

New here? What’s IwGame? IwGame is an open source free to use cross platform game engine for iPhone, iPad, Android, Bada, Playbook, Symbian, Windows Mobile, LG-TV, Windows and Mac, built on top of the Marmalade SDK.

A forum poster asked a question recently that made me realise that XOML Templates can quite easily be overlooked as a means for creating re-usable actors and such, so I thought to help make Templates more visible that I would create a very quick tutorial showing how to use them.

To begin with, lets take a look at what a template actually is and does. A template is a XOML tag that allows you to define generic XOML that is not instantiated immediately, yuo can think of a Template as a blue print for something that you will later instantiate into your game or app world. A template also takes any number of parameters that can be passed when you instantiate the template.

When creating items inside a Template, template parameters are defined using a template parameter name that is enclosed inside double dollar signs ($$), for example $position$. When you later instantiate the items within the template the parameters within the template will be replaced by values that are passed to the template.

Lets take a quick look at creating an actor / child actor with a template

[sourcecode language=”xml”]
<Template Name="TankTemp">
<TankActor Name="$name$" Style="TankActorStyle" Position="$pos$″ >
<TankActor Name="$name$_sel" Style="TankActorSelectedStyle" Position="0, 0″ />
</TankActor>
</Template>
[/sourcecode]

Here we create a template called TankTemp that defined an actor with a name of $name$ and a position of $pos$. Note that because these two parameters are enclosed in $$ they are classed as template parameters.

Now to instantiate this elements within this template in XOML we use the following:

[sourcecode language=”xml”]
<FromTemplate Template="TankTemp" name="Tank" pos="310, -120" />
[/sourcecode]

The above code will instantiate the following code:

[sourcecode language=”xml”]
<TankActor Name="Tank" Style="TankActorStyle" Position="310, -120″ >
<TankActor Name="Tank_sel" Style="TankActorSelectedStyle" Position="0, 0″ />
</TankActor>
[/sourcecode]

To instantiate a template from C++, we firstly need to find the template, build the parameters then instantiate the template passing in the parameters:

[sourcecode language=”cpp”]
// Find the tank template
CIwGameTemplate* temp = (CIwGameTemplate*)scene->getResourceManager()->findResource("TankTemp", "template");
if (temp != NULL)
{
// Create a set of XML attributes that will replace the template parameters
CIwGameXmlNode* replacements = new CIwGameXmlNode();
replacements->Managed = false;
CIwGameXmlAttribute* attrib;

// Set name template parameter
attrib = new CIwGameXmlAttribute();
attrib->Managed = false;
attrib->setName("name");
attrib->setValue("Tank");
replacements->AddAttribute(attrib);

// Set position template parameter
attrib = new CIwGameXmlAttribute();
attrib->Managed = false;
attrib->setName("pos");
attrib->setValue("310, -120");
replacements->AddAttribute(attrib);

// Instantiate the Tank template
temp->Instantiate(scene, replacements);

// Clean up replacement attributes
delete replacements;
}
[/sourcecode]