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!