IwGame Engine v0.27 Released – Powerful Animation and XOML Support

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. You can find out more and download the SDK from our IwGame Engine page.

After much bashing with hammers and sawing with saws IwGame version 0.27 is now available for download, including updated documentation. Some of you may get a little upset as we have completely replaced the old animation system with a brand new more powerful system. Sorry for that, but thought better to change it sooner rather than later.

Lets take a quick look at the changed for v0.27:

  • Added new customisable mark-up language XOML that allows you to declare most IwGame obects declaratively, including scenes, custom actors, images, resource groups, animations, animation timelines
  • CIwGameAnimManager has been removed and replaced with the much more powerful CIwGameAnimTimeline, paving the way for very powerful actor and scene animations
  • Animation system has been completely changed to use a proper key frame interpolation system
  • Support for animation targets to automate update of object properties
  • CIwGameActorImage initialisation no longer requires a scene or an animtion. CIwGameActorImage initial image source rectangle now matches the initial size of the actor
  • setCollisionSize() added to CIwGameActor to allow setting of collision size from a radius
  • CIwGameDataInput and CIwGameDataOutput stream classes added
  • Simple, fast pooled memory XML parser added (CIwGameXml)
  • CIwGameResourceGroup system added to encapsulate Marmalade resource groups
  • Global and scene local resoure systems added
  • CIwGameImage can now be instantiated 3 ways, from memory buffer, from file or from web file
  • CiwGameImage initialisation from memory buffer no longer requires specification of the is_jpeg flag
  • Blocking parameter can now be passed to CIwGameImage::Load()
  • CIwGameScene scenes can now be assigned a colour. All contained actors will be scaled by the colour, allowing flash and fade effects
  • CIwGameBitmapSprite::setSrcRect() now takes a CIwRect
  • FRAME_SPEED_LOCK_MS now added to set frame rate cap
  • CIwGame::Init() changed to CIwGame::Init(bool enable_http), passing true will boot up the HTTP manager and allow you to use it in-game
  • Bug Fix – CIwGameHttp crashed if a request came back after the object was shut down
  • Bug fix – CIwGameActor::setCollisionRect() bug fixed
  • Bug fix – All actors were being treated as though they were collidable
  • Bug fix – Sprites no lnoger try to render themselves if their associated image is not yet loaded

Yes, I know that’s a lot of changes! Lets take a look at some of these new changes in more depth

What’s this new XOML Mark-up Language stuff all about?

Ok, time for the old copy and past. After working two days flat on updating documentation I feel less obliged to write fresh content :)

I like to make code that is extensible but I also like to make life easier for myself without sacrificing too much versatility, so my coding style constantly strives towards balancing ease of use and extensibility. I’ve done a lot of Silverlight / WPF coding in the past which is where I came across Microsoft’s XAML mark-up language. I later came across Adobe Flex’s MXML mark-up language and decided that mark-up language was the way to go with game and app development. Being able to define my whole UI, game scenes, animations and even game logic using simple readable XML seemed like the best way to go.

IwGame adds some of the great functionality found in XAML / MXML allowing you to declare much of what will appear in your game using XOML (XML Object Modelling Language).

The major advantages of using XOL include:

  • Saves a whole bunch of typing
  • Design and layout scenes and actors using mark-up
  • Design resource groups and images using mark-up
  • Design complex animations and time line animations
  • No recompiling required to test changes
  • Add new content without resubmitting to the app stores
  • Add content that is streamed from a server

As you can see, we have some pretty neat advantages to switching over to using a mark-up language

Lets take a quick look at an example XOML file:

<?xml version="1.0"?> <xml> <ResourceGroup Name="Audio" GroupFile="Audio.group" Preload="true" /> <ResourceGroup Name="Level1" GroupFile="Level1.group" Preload="true" /> <Image Name="Sprites" Location="Level1" Preload="true" /> <Image Name="Buddy" Location="http://www.battleballz.com/bb_icon.gif" Preload="true" Blocking="false" /> <Animation Name="PlayerImageAnim" Type="rect" Duration="0.8" > <Frame Value="0, 0, 36, 40" Time="0.0" /> <Frame Value="0, 40, 36, 40" Time="0.1" /> <Frame Value="0, 80, 36, 40" Time="0.2" /> <Frame Value="0, 120, 36, 40" Time="0.3" /> <Frame Value="0, 160, 36, 40" Time="0.4" /> <Frame Value="0, 200, 36, 40" Time="0.5" /> <Frame Value="0, 240, 36, 40" Time="0.6" /> <Frame Value="0, 280, 36, 40" Time="0.7" /> </Animation> <Animation Name="SpinAnim1" Type="float" Duration="8" > <Frame Value="0" Time="0.0" /> <Frame Value="90" Time="2.0" /> <Frame Value="180" Time="4.0" /> <Frame Value="270" Time="6.0" /> <Frame Value="360" Time="8.0" /> </Animation> <Animation Name="ScaleAnim1" Type="float" Duration="4" > <Frame Value="0.1" Time="0.0" /> <Frame Value="1.0" Time="1.0" /> <Frame Value="1.5" Time="2.0" /> <Frame Value="1.6" Time="3.0" /> <Frame Value="1.65" Time="4.0" /> </Animation> <Animation Name="ColourAnim1" Type="vec4" Duration="4" > <Frame Value="255, 255, 255, 0" Time="0.0" /> <Frame Value="255, 255, 255, 200" Time="1.0" /> <Frame Value="255, 255, 255, 255" Time="2.0" /> <Frame Value="255, 255, 255, 200" Time="3.0" /> <Frame Value="255, 255, 255, 0" Time="4.0" /> </Animation> <Animation Name="PlayerStates" Type="string"> <Frame Value="State1" Time="0" /> <Frame Value="State2" Time="0.5" /> <Frame Value="State3" Time="1.0" /> <Frame Value="State4" Time="1.5" /> </Animation> <Timeline Name="Scene1Anim" AutoPlay="true"> <Animation Anim="SpinAnim1" Target="Angle" Repeat="1" StartAtTime="0"/> <Animation Anim="ScaleAnim1" Target="Scale" Repeat="1" StartAtTime="0"/> </Timeline> <Scene Name="GameScene" CanvasSize="320, 480" FixAspect="true" LockWidth="false" Current="true" Colour="128, 128, 128, 255" Timeline="Scene1Anim"> <Timeline Name="Player1Intro" AutoPlay="true"> <Animation Anim="PlayerImageAnim" Target="SrcRect" Repeat="0" StartAtTime="0"/> <Animation Anim="SpinAnim1" Target="Angle" Repeat="4" StartAtTime="10"/> <Animation Anim="ColourAnim1" Target="Colour" Repeat="10" StartAtTime="2"/> </Timeline> <TestActor Name="Player1" Position="-100, 0" Size="100, 100" Angle="45" SrcRect="0, 0, 36, 40" Image="Sprites" Timeline="Player1Intro" /> <TestActor Name="Player2" Position="0, 0" Size="100, 100" Angle="-45" SrcRect="0, 0, 36, 40" Image="Sprites" /> <TestActor Name="Player3" Position="0, 100" Size="100, 100" Angle="0" SrcRect="0, 0, 64, 64" Image="Buddy" /> </Scene> <Scene Name="GameScene2" CanvasSize="320, 480" FixAspect="true" LockWidth="false" Colour="0, 0, 255, 255" AllowSuspend="false"> <Timeline Name="Player1Intro2" AutoPlay="true"> <Animation Anim="PlayerImageAnim" Target="SrcRect" Repeat="0" StartAtTime="1"/> <Animation Anim="SpinAnim1" Target="Angle" Repeat="4" StartAtTime="10"/> </Timeline> <TestActor Name="Player1" Position="0, 0" Size="100, 100" Angle="45" SrcRect="0, 0, 36, 40" Image="Sprites" Timeline="Player1Intro2" /> <TestActor Name="Player2" Position="100, 0" Size="100, 100" Angle="-45" SrcRect="0, 0, 36, 40" Image="Sprites" /> <TestActor Name="Player3" Position="100, 100" Size="100, 100" Angle="0" SrcRect="0, 0, 64, 64" Image="Buddy" /> </Scene> </xml>

It may look like quite a bit of XML but the above would take many hundreds of lines of code to instantiate all of these classes and set up their data.

XOML is also extensible in that you can provide your own custom tags, allowing you to extend the syntax.

How to work with XOML files?

How is XOML meant to be used? Well that’s up to you, I’m pretty sure you already have hundreds of cool ideas bouncing around your mind right now. That said we do have some recommended usage and work flow ideas.

The idea is to define all of your different types of actors and / or scenes derived from IwGame base scenes and actors then add the creators to the XOML system. This allows you to declare them in XOML.

You should have very few if not a single global resource XOML file that contains all of your global resources. This gets loaded first when you boot the game.

You then create separate XOML files that contain either single scenes or scenes grouped by functionality.

Try to keep scene specific resources within scenes so they can be freed up when the scene is no longer needed, but try to balance resource group loading times with resource re-use.

The animation system provided by XOML is very powerful so try to use it wherever appropriate.

Start looking at your game as being driven by XOML rather than XOML being a simple data format.

How to load a XOML File

Loading a XOML file is incredibly simple:

// Load a test XOML file IW_GAME_XOML->Process(this, "Scene1.xml");

The first parameter to the Process() method represents the parent class that you want to load all of the XOML data into. For example, if you load a XOML file that contains scenes then you should pass the CIwGame derived game object so that the created scenes will be added to the main game object. On the other hand if the XOML file contains a simple list of global resources then you can pass NULL. This kind of versatility allows you to split your game definitions across multiple files.

Its worth noting at this point that you need to ensure that IwGame::Init() has been called before using the XOML system as IwGame::Init() sets up important systems that are used by the XOML system.

What’s the future of XOML?

XOML was initially designed to simplify the mundane and time consuming tasks involved in creating scene layouts and animations etc, but luckily it turned into something much more. Over time XOML will evolve into even more with future with plans for the following addictions:

  • Data binding
  • Declartion of user interfaces
  • Declartion of physics materials and scenes
  • Support for styling
  • More IwGame class support such as support for video, data files, camera streaming, audio time lines and more..

New Animation System

Now XOML (the biggest addition to IwGame) is out the way, lets look at the new animations system. The new animation system supports proper key frame interpolation where key frames can be spaced apart in time in a none linear fashion. The new animation system also has support for animation timeline’s and more types of animation data.

Timeline animations are collection of animations that are played simultaneously on some kind of animation target. An animation can be anything such as an actor or a scene. In fact, any class that is derived from the IIwGameAnimTarget interface.

Animation target and animation target properties allows the animation system to automatically updated properties of target objects with their interpolated animation values.

The new animation system has support for boolean, floating point, 2d, 3d and 4d vector, image frames and string based frame data.

XML parser and Streams

Stream input and output classes and XML parser utilities have been added. The XML parser is basic but quick and uses tag / node pooling to reduce memory fragmentation.

Marmalade Resource Group Wrapping and Global Resources

Marmalades resource groups have been wrapped into CIwGameResourceGroup to enable then to be integrated into XOML and facilitate auto loading / destruction in scenes and the global resource syste,

A new global resource system has been added (use IW_GAME_GLOBAL_RESOURCES to access) which the XOML system uses to store application global resources. Scenes also support a local resource system for resources that should only exist during the scenes lifetime.

Other Bits and Bobs

Images can now be created directly from a web resource (no need to go through the file system)
Game scenes now have a colour and opacity that can be animated. Note that the colour and opacity will be applied to any contained actors (good for flashes and fades)

CIwGame can now initiate and take care of update and clean-up of the HTTP manager, so you no longer need to handle this from outside CIwGame.

In closing

Well that’s it for this update of the IwGame engine, our next update will include Box2D integration into the actor and scene system, maybe even into the XOML system too, we will just have to see.

The latest version of IwGame can be downloaded FREE from the IwGame Engine page.

Happy coding!

7 thoughts on “IwGame Engine v0.27 Released – Powerful Animation and XOML Support

  1. Thomas says:

    Hey Dr. Mop!

    Thanks for updating animations with a new system. I’m excited to download this tonight and have a go at it – since I still couldn’t get the animations to work previously.

    I had question regarding the Visual variable for actors. Is there a way to change the visual component of an actor, which would replace the old one? I tried doing this by using setVisual() but the old image still remained after setting the visual to another sprite. So the end result was the rendering of both images on top of each other.

    Here is the code I used to try replace the visual:

    CIwGameBitmapSprite* TestSprite= new CIwGameBitmapSprite();
    TestSprite->setSrcDest(0, 0, 300, 300);

    Basically the initial Level1_Scene has rectangle images and I wanted to replace the actor’s visual image to squares for the current scene. The result of this code shows the rectangle image behind the square image.

    Anyways thanks for your great work with IwGame and I look forward to your next update with Box2D!!!

    Best Regards,


  2. drmop says:

    Hi Thomas,

    When a CIwGameActorImage derived actor is created and the Init() method is called the actor will create a sprite and add it to the scenes sprite manager where it will remain until deleted. At the moment setVisual() simply changes the visual that the actor is using so the previous sprite visual remains in the sprite manager. The best thing to do would be to firstly remove the actors existing visual from the sprite manager and then set your new visual. I’ve just added a new method to CIwGameActor which will do this for you:

    void CIwGameActor::removeVisual()
    if (Visual != NULL)
    Visual = NULL;

    The change will appear in v0.28 hopefully next week.


  3. pugmartin says:


    Consider me excited :)

  4. Thomas says:

    Thanks for the update! I’ve been trying to update a lot of my code with xml files. I am a bit confused on how to allocate a specific image in a resource group to an actor using xml. From your manual and testbed it looks like you created an image that was associated with a resource group. Then you attached that image to an actor in xml. However, how would I specify which image (in my case a png file in the resource group) that the actor should have, since each resource group file has more than one image. Thanks for your help!

  5. drmop says:

    Fiirstly we declare our Marmalage resource group using:

    <ResourceGroup Name=”Level1″ GroupFile=”Level1.group” Preload=”true” />

    Lets now say that we have 2 images in that resource group that are named PlayerImage and AlienImage, you would declare them in XOML using:

    <Image Name=”PlayerImage” Location=”Level1″ Preload=”true” />

    <Image Name=”AlienImage” Location=”Level1″ Preload=”true” />

    The image Name defined in the image tag is the name of the image in the Marmalade resource file.

    Now when you declare your actor you set Image=”PlayerImage” to assign the player image to that actor or Image=”AlienImage” to assign the actor the alien image

  6. Thomas says:

    Hey Dr. Mop,

    Thanks for the reply. Yea I got things working with the images and the resource manager. The only thing that confused me was that you used “Sprite” when your image in the resource group was named “sprite”, so I thought you were creating a name for the image not calling out the name from the resource group.

    I tried using the setTimeline function yesterday for an actor, in a scene with multiple timelines. I tried using scene->getTimelineManager()->findTimeline(“timeline”) and setting the timeline to the actor. However nothing happens to the actor when I set it. I assume I am calling the timeline in the scenes incorrectly.

    Sorry for asking so many questions and thanks for your help :) .

  7. drmop says:

    We considered adding a separate name for images when references a resource group but it seemed like doubling up on attributes.

    setTimeline should work as long as the animations within the tiimeline target the actor / scene specific properties. Note that everything is case sensitive in XOML at the moment. we will be fixing this in the next version.

Leave a Reply