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

    <Template Name="TankTemp">
        <TankActor Name="$name$" Style="TankActorStyle" Position="$pos$″ >
            <TankActor Name="$name$_sel" Style="TankActorSelectedStyle" Position="0, 0″ />
        </TankActor>
    </Template>

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:

        <FromTemplate Template="TankTemp" name="Tank" pos="310, -120" />

The above code will instantiate the following code:

    <TankActor Name="Tank" Style="TankActorStyle" Position="310, -120″ >
        <TankActor Name="Tank_sel" Style="TankActorSelectedStyle" Position="0, 0″ />
    </TankActor>

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

// 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;
}