IwGame Engine Tutorial – Basic introduction

Posted on by drmop

What is the IwGame Engine?

Welcome to the home of IwGame, the free open source cross platform mobile 2D game engine for smart phones, tablets and emerging technologies developed by Pocketeers Limited. IwGame is designed and written on top of the Marmalade SDK the ultimate  cross platform SDK for smart phones tablets and emerging technologies. In order to use the IwGame game engine you will need to download and install the Marmalade SDK.
IwGame supports the following platforms:

  • iPhone, iPod and iPad
  • Android phones and tablets (1.5+ including Ice Cream Sandwich)
  • Samsung Bada 1.0 / 2.0
  • Blackberry BBX (Playbook)
  • Symbian
  • WebOS
  • Windows Mobile
  • Mobile Linux
  • LG-TV
  • Windows Desktop
  • Mac OSX

IwGame is free to use at your own discretion and the code base is open source . You do not need to submit bug fixes or improvements, but we would be very happy if you did.

You can find out more and download the IwGame Engine from the IwGame Engine home

The IwGame engine has been in development since November 2011 and has had 14 releases to date

The original IwGame concept set out to achieve the following:

  • Create a game layer on top of the Marmalade SDK allowing developers to get game code up and running incredibly quickly without having to learn the ins and outs of the Marmalade SDK
  • Create a solid feature rich gaming SDK that does not rely on the underlying platform
  • Enable developers and designers to create content without writing any code

In around 6 months time we achieved all three of the above aims and more:

  • IwGame now supports a wealth of features that enable developers to create 2D games quickly and efficiently
  • IwGame boasts a vast array of features, including all the basic game development features such as scenes, sprites, actors, animation, audio, input, mark-up language. IwGame also supports advanced features such as HTTP communications, unified Ads API, Facebook API and unified in-app purchasing.
  • We wanted to put the IwGame engine into the hands of designers as well as programmers. We also wanted a way to separate game and UI layout design from code. We accomplished both of these aims by introducing the XOML mark-up language into the IwGame engine, allowing programmers and designers to not only design the layout and general interaction of games and apps but also define animations, resources, variables, conditions, events and actions. We also made the whole system extensible allowing developers to extend the language to fit whatever needs they may have.

Platform Independence

The IwGame engine strives to provide platform independence, so the developer has to deal less with the differences that separate platform from platform and spend more time dealing with creating a game. Because IwGame is built atop of the Marmalade SDK, this platform independence is mostly catered for, although there are a number of areas where the Marmalade SDK falls short:

  • Screen size independence – IwGame uses a virtual canvas system, allowing each scene to specify a working resolution that the developer can rely on not changing from device to device. The scene will scale all its content to fit the target display resolution with no extra effort on the developers part
  • Frame rate independence – Regardless of the target platform speed, all transient variables within a game are scaled by time to ensure that animations and movement etc do not suffere slow down or speed up on different platforms
  • In-app purchasing – IwGame allows the developer to set-up and utilise in-app purchasing in a platform independent manner
  • Unified Ads – IwGame provides a mediated unified Ad API that allows the developer to serve ads to their apps regardless of platform and from a number of different ad providers

Scene / Actor Concept

The most important concept behind the IwGame engine is the Scene / Actor system. IwGame uses scenes to hold collections of Actors. A game can be made up of a single scene or more usually a collection of scenes. For example, your main game can be built up of the following scenes:

  • Game world background scene
  • Game world foreground scene
  • In-game HUD scene
  • In-game menu scene
  • End of level dialog

Actors represent the game objects that live and work in your gaming world. An actor has logical, visual and physical components associated with them. The logical component is the game logic that gives the actor its purpose in the game world, the visual component is how the actor will appear on screen, usually some kind of sprite and finally the physical component tells the system how the actor will behave under physics (this component is optional). Actors can be defined hierarchically, allowing the developer to create complex objects that consist of multiple actors that are all connected with each actor having its own independent logic and visual but sharing the parents visual transform. Actors also support functionality components that can be stacked allowing the creation of vastly complex game objects from many smaller independent modules.

Scenes can be hidden, moved and animated, all actors contained within a scene will obey the scenes visibility, colour and transforms.

Creating a game is a case of creating scenes that represent the different components of a game then creating and adding actors that define the games behaviour.

Resource Management

IwGame supports resource management on a local per scene and a global basis. The resource management system will take care of cleaning up resources at the correct time. For example, all resources that are local to a scene will be destroyed when the scene has been destroyed. Global resources will remain present throughout the duration of the game, unless removed manually. The resource manager handles many different types of resources including images, animations, timelines, shapes, materials, fonts etc..

Animation

IwGame supports a very powerful key frame based animation system supports the following features:

  • Time based frame and interpolated named animations
  • Delayed and looped animations
  • Support for boolean, float, vectors (2d, 3d and 4d), rect (for image frames), string and custom frame data types
  • Resource manager that tracks and manages sets of animations (scene local and global)
  • Animation data re-use using animation instances
  • Animation time lines to support multiple simultaneous animations that can target object specific properties such as the colour of a scene or the position of an actor
  • Time line manager that tracks and manages sets of animation time lines
  • Callback notifications for animation instance started, stopped and looped events
  • Animations and animation time lines can be defined and attached to actors and scenes using XOML
  • Support for OnStart, OnEnd and OnRepeat events in code and in XOML
  • Linear, quadratic, quartic and cubic in and out easing

Scenes and actors can contain an animation timeline that will be applied to the scene or actors properties. For example, you may set up a timeline that contains animations that target position, scale, rotation and colour then attach that to a group of actors. The group of actors will all take on the animation properties of the timeline.

XOML Mark-up Language

By far the best feature of the IwGame engine is its built-in XML mark-up language (can be thought of as HTML for game development). XOML enables designers and developers to both create interactive content. XOML is a little more than a simple mark-up language as it allows the definition of variables, conditions, actions and events. Its entirely possible to create a complete interactive presentation, app or game using XOML. XOML also contains features to help create styled content using styles and templates.

Lets take a look at a typical piece of XOML:

<!-- Create a scene to contain our logo actors -->
<Scene Name="IntroScene" Style="GenericSceneStyle" Camera="IntroCam" Timeline="camera_zoom" Current="true" OnGainedFocus="GainedFocus" Batch="false">

    <Actions Name="GainedFocus">
        <Action Method="SetBGColour" Param1="64, 128, 200, 255" />
    </Actions>

    <!-- End of logo actions -->
    <Actions Name="NextScene">
        <Action Method="LoadXOML" Param1="Menu.xml" />
        <Action Method="KillScene" Param1="IntroScene" />
    </Actions>

    <!-- Create a camera-->
    <Camera Name="IntroCam" Position="0, 0" Angle="0" Scale="1.0" />

    <!-- Create delayed fade out animation -->
    <Animation Name="fade_out" Type="vec4" Duration="5" >
        <Frame Value="255, 255, 255, 255" Time="3" />
        <Frame Value="64, 128, 200, 0"  Time="5"/>
    </Animation>

    <!-- Create a zoom animation for the camera -->
    <Animation Name="camera_zoom" Type="float" Duration="5" >
        <Frame Value="2"  Time="0.0" Easing="quadout" />
        <Frame Value="0.75" Time="2.0" />
    </Animation>
    <Timeline Name="camera_zoom" AutoPlay="true">
        <Animation Anim="camera_zoom" Target="Scale" Repeat="1" StartAtTime="0" OnEnd="NextScene" />
        <Animation Anim="fade_out" Target="Colour" Repeat="1" StartAtTime="0" />
    </Timeline>

    <!-- Define logo image -->
    <Image Name="logo" Location="logo.png" Preload="true" />

    <!-- Create animations for the logo pieces -->
    <Animation Name="x_axis" Type="vec2" Duration="4" >
        <Frame Value="500, 0"  Time="0.0" Easing="quadout" />
        <Frame Value="0, 0" Time="2.0" />
    </Animation>
    <Animation Name="x_axis2" Type="vec2" Duration="4" >
        <Frame Value="600, 0"  Time="0.0" Easing="quadout" />
        <Frame Value="0, 0" Time="2.25" />
    </Animation>
    <Animation Name="scale_axis" Type="float" Duration="4" >
        <Frame Value="1"  Time="0.0" Easing="quadout" />
        <Frame Value="1.25" Time="2.0" />
    </Animation>
    <Animation Name="spin_axis" Type="float" Duration="4" >
        <Frame Value="180"  Time="0.0" Easing="quadin" />
        <Frame Value="90"  Time="1.0" Easing="quadout" />
        <Frame Value="0" Time="2.0" />
    </Animation>
    <Timeline Name="orbit1" AutoPlay="true">
        <Animation Anim="x_axis" Target="Position" Repeat="1" />
        <Animation Anim="scale_axis" Target="ScaleY" Repeat="1" />
    </Timeline>
    <Timeline Name="orbit2" AutoPlay="true">
        <Animation Anim="x_axis" Target="Position" Repeat="1" />
        <Animation Anim="scale_axis" Target="ScaleY" Repeat="1" />
        <Animation Anim="spin_axis" Target="Angle" Repeat="1" />
    </Timeline>
    <Timeline Name="orbit3" AutoPlay="true">
        <Animation Anim="x_axis2" Target="Position" Repeat="1" />
        <Animation Anim="scale_axis" Target="ScaleY" Repeat="1" />
    </Timeline>

    <!-- Define the logo actors -->
    <InertActor Name="logo" Position="0, 0" Size="1024, 300" Angle="0" SrcRect="0, 0, 1024, 300" Image="logo" Timeline="orbit1" />
    <InertActor Name="logo" Position="0, 0" Size="1024, 300" Angle="0" SrcRect="0, 0, 1024, 300" Image="logo" Timeline="orbit2" Colour="255, 255, 255, 128" />
    <InertActor Name="logo" Position="0, 0" Size="1024, 300" Angle="0" SrcRect="0, 0, 1024, 300" Image="logo" Timeline="orbit3" Colour="255, 255, 255, 64" />

    <ActorText Name="Text1" Position="0, -260" Rect="-400, -50, 800, 100" Angle="0" Font="trebuchet_12" AngularVelocity="0" Text="Developed By Pocketeers Limited" Colour="255, 255, 255, 255" Scale="1.5" />
    <ActorText Name="Text2" Position="0, 250" Rect="-200, -50, 400, 100" Angle="0" Font="trebuchet_12" AngularVelocity="0" Text="www.drmop.com" Colour="255, 255, 255, 255" Italic="true" Scale="1.5" />

</Scene>

This XOML defines the complete animation sequence that can be seen in the Puzzle Friends / cOnnecticOns game. Three logos spin onto the screen and 2 lines of text zoom into place.

XOML also now supports data binding, which allows developers to bind variables to properties of actors or scenes. Any changes to bound variables will be reflected in object that they are bound to.

Lastly, XOML is extensible allowing the developer to extend the language to support their own needs.

Input and Audio

IwGame provides access to the various input devices on the device including:

  • Single and multi-touch input
  • Button and key states (including support for Android back and menu)
  • On screen keyboard input
  • Accelerometer
  • Compass

Actors handle events that deal directly with touch events, including OnTapped, OnBeginTouch and EndTouch. These events can be handled directly in code or actions can be attached in XOML.

Scenes also handle menu and back button presses using the OnBackKey and OnMenuKey events

IwGame provides an API that provides access to the devices audio playback systems

  • Compressed WAV software sound effect playback
  • MP3 playback via the devices media engine
  • Support for multiple simultaneous sound effects
  • Control over volume and pitch

Music and sound effects can be played directly in XOML via actions, allowing the developer to tie music and sound effect playback to specific events declaratively.

Physics

The Box2D physics engine is integrated into the IwGame engine allowing physics to be attached to any actor. IwGame supports shapes, joints (distance, revolute, prismatic, pulley and wheel) and physics materials that can be defined and attached to actors, putting them under control of the Box2D physics system. Actors will also receive collision events from the Box2D collision system, allowing the actor to respond to collisions.

Gravity and world scale can be set on a per scene basis.

Facebook API

IwGame currently supports basic Facebook interaction providing log-in and allowing the developer to post information to the users wall stream.

Unified In-App Purchasing

IwGame provides unified in-app purchasing for both iOS and Android. A single easy to set-up API can be used to track products and purchase them regardless of platform.

Unified Ads API

IwGame provides a platform independent ad collection, display and processing system called IwGameAds. The whole system is automated and once set-up will collect ads from a variety of ad providers using ad mediation and display them using a slick animation system. The system also handles ad clicks directing the user to the target URL.

The following ad providers are currently supported:

  • Inner-active
  • AdFonic
  • Vserv – Also provides support for InMobi, BuzzCity, JumpTap, ZestAdz / Komli Mobile and Inner-active
  • Mojiva
  • Millennial Media – Also provides support for AdMob, Amobee, JumpTap and Mojiva

So why use IwGame Engine?

IwGame was designed by game developers for game developers. IwGame is built on many years of game development experience, using tried and tested game development techniques. IwGame provides a mass of out-of-the-box features that would take many months to develop and test from scratch. Above all else, using XOML enables the developer to create games insanely quickly (our recent game cOnnecticOns took just 3 days to create from scratch). Lastly, using separation of coding and game layout / design, XOML encourages easy and smart game development, where designers can take care of the design / layouts and programmers can take of the gaming logic.

Leave a Reply