IwGame Engine v0.25 Released – Documentation Added

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.

Well I feel quite shell-shocked, I’ve been working flat out and its taken a few days but I finally got the first draft of the documentation done for IwGame.

The documentation consists of an 81 page document in PDF, Word and OpenOffice formats and is located in the Docs folder in the IwGame distribution. Its a first draft so please expect lots of mistakes including quite probably some quite embarrassing auto correction mistakes.

As I was producing the documentation I found a number of holes that needed to be plugged, hence an update along with the documentation:

Here are the changes for IwGame v0.250:

  • Added first draft of IwGame engine manual in PDF, Word 97 and OpenOffice formats.
  • Added CIwGame::BringSceneToFont() to allow bringing of scenes to the top of the scene stack
  • Added naming to animations in CIwGameAnim
  • Added ne findAnimation() methods to CIwGameAnimManager
  • CIwGameSound SetVolume and SetPitch() now taking floating point values
  • Added support for active and visibility to CIwGameScene scenes
  • Fixed some string comparison issues
  • Can now stop auto ad requests using CIwGameAdsView::setNewAdInterval(0)
  • Fixed issue where bad ad requests were not timing out in CIwGameAdsView

Now its time get back on with my life πŸ™‚

30 thoughts on “IwGame Engine v0.25 Released – Documentation Added

  1. Roman says:

    Buddy, I have no words to say how great you are!

    It is amazing that you care about docs so much!

  2. Dan says:

    Wow! Just wow… open source projects usuall have no documentation much less 81 pages of docs.

    Anyway I am trying to port a project ( it’s the tipical basic game http://www.raywenderlich.com/352/how-to-make-a-simple-iphone-game-with-cocos2d-tutorial) using your engine, but I am running into a bit of problem with the following code:
    CIwResGroup* Level1Group = IwGetResManager()->GetGroupNamed(“Level1”);
    game_scene->getImageManager()->addImage(“sprites”, Level1Group);
    game_scene->getImageManager()->addImage(“player”, Level1Group,true);
    game_scene->getImageManager()->addImage(“projectile”, Level1Group);
    game_scene->getImageManager()->addImage(“target”, Level1Group);

    // Create an image from the downloaded gif file
    CIwGameImage* pimage = new CIwGameImage();
    pimage = game_scene->getImageManager()->findImage(“player”);

    // Create a test sprite to display our downloaded gif
    CIwGameBitmapSprite* test_sprite = new CIwGameBitmapSprite();
    test_sprite->setDestSize(pimage->getWidth(), pimage->getHeight());
    test_sprite->setSrcRect(0, 0, pimage->getWidth(), pimage->getHeight());
    test_sprite->setPosition(20 + pimage->getWidth() / 2, 20 + pimage->getHeight() / 2);


    If I comment out the scale I get an image, but with scale I have no image on screen.

    Am I using this properly? Also, the emulator crashes wend I exit… is the sprite manager released automatically or do I have to call it to release the sprite?

    I am hoping to have the game done by the weekend, but I am running into a bit of trouble getting beyond the basic sprite functionality to work. Ill try to load images from memory to see if it fixes by bypassing the manager.

    Cheers and once again amazing work!

  3. Dan says:

    Also I think there is a bug in the sound code. If the background sound is not loaded the first time you click there is no gunfire sound only at the second click does it play.

  4. drmop says:

    Hi Dan,

    Sprites are low level so they used fixed point numbers for scale and rotation (unlike the higher level actor system which uses floats). You need to change your scale to use fixed point using:

    test_sprite->setScale(2.0f * IW_GEOM_ONE);

    Although I’ve just added methods to allow you to set the angle and scale using floats (will include that in the next update).

    Also, you have a memory leak. You create an image then write over it:

    CIwGameImage* pimage = new CIwGameImage();
    pimage = game_scene->getImageManager()->findImage(β€œplayer”);

    You should change this to:
    CIwGameImage* pimage = game_scene->getImageManager()->findImage(β€œplayer”);

    Good luck with your game.

    Will take a look at the audio.

  5. Dan says:

    Hi Mat,

    Thanks for the catch. Ill try it that way then.
    Yeah I think I will write my own Actor but it seemed overhead since the only thing my sprites have to do is move, they are not animated. I tried to create an acotr with a null animation but that is a No No.

    I created the image that way but there was no image shown so that is why I did it using new… now that I think that may have been because there was the scale issue.

    Thanks! Ill post it online as soon as it is done.

  6. Hey DrMop!

    Thanks a million for your library! I used to use Marmalade back when it was AirPlay. After several months of just setting up my game’s framework, I gave up on the SDK.

    Your game framework is just tremendous and I’m quickly replacing months worth of frustration in a matter of days.

    Quick suggestion:

    CIwGameBitmapSprite* sprite = new CIwGameBitmapSprite();

    sprite->setDestSize(backgroundImage->getWidth(), backgroundImage->getHeight());
    sprite->setSrcRect( 0, 0, backgroundImage->getWidth(), backgroundImage->getHeight() );

    How about having ‘setImage’ default the destination and srcRect size?

  7. drmop says:

    Hi Philip,

    Great to hear that you are finding IwGame useful.

    setDestRect() is defined in the CIwGameSprite class, which doesn’t have a concept of source image areas as it doesn’t know about image based sprites.

    Your idea is good though, so I have just added a new method to CIwGameBitmapSprite:

    void setSrcDest(int x, int y, int width, int height)
    Width = width;
    Height = height;
    SrcX = x;
    SrcY = y;
    SrcWidth = width;
    SrcHeight = height;

    This will set both the src and dest for you, saving having to set them up separately. I will include this in the next update, some time next week.

    Good luck with the engine, keep me posted on how you get on.


  8. Dan says:


    Is there a simple way to stop a sprite on a frame or jumpandStop to a frame… Also is there a way to make an actorPlayer without an animation.

    Tried to overload Create and Init methods and remove AnimManager code but had some issues with that. I think I will have to write my own ActorStatic for static images should I use GameBitmapSprite as base class or GameActor?

    Funny that you can have an animated actor out of the box, but I am having a trouble getting to make a static player, well there is the GameBitmapSprite

    //// TEST SPRITE ////
    //// – Setup CIwGameImage from image manager ////
    //// – Create CIwGameBitmapSprite and setup proprieties ////
    //// – Add to Scene spriteManager ////

    CIwGameImage* pimage = game_scene->getImageManager()->findImage(“player”);
    int iwith = pimage->getWidth();
    int iheight = pimage->getHeight();

    CIwGameBitmapSprite* test_sprite = new CIwGameBitmapSprite();

    test_sprite->setDestSize(pimage->getWidth(), pimage->getHeight());
    test_sprite->setSrcRect(0, 0, pimage->getWidth(), pimage->getHeight());

    int swidth = game_scene->getScreenSize().x;
    int sheight = game_scene->getScreenSize().y;

    test_sprite->setPosition((-swidth/2) + (iwith/2), 0);


    But I have no way to setup position, or speed so I need to create StaticActors… sorry for such basic questions, but before I run I have to walk…

    How do I control animation playback on my ActorPlayer? Do i have to call my animManager and control playback thru that?

    Also how do I setup Timer to create new instances of my Actor Class on a 3 second interval? I have to pool them in Game update right?


  9. Dan says:

    OK created my own class ActorStatic derived from IwGameActor after I read the documentation with a bit more care, all works well now… guess Ill start adding some methods… moveTo(), etc… the more I get used to it, the more I like it πŸ˜‰

  10. Dan says:

    One last question, Is it possible to change the coordinate system to 0,0 as the bottom some calculations are harder to do with a middle of the screen coordinate system.

    bool ActorStatic::Update(float dt)
    //Having the coordinates on the middle does not help to compare stuff, need to use abs
    if(this->getPosition().x > this->getScene()->getScreenSize().x;){
    return false;

    return CIwGameActor::Update(dt);

    Basically what I am trying to do here is if the Actor is no longer visible then it gets deleted or Reset to be reused.

  11. drmop says:

    Hi Dan,

    To move the origin to the top left hand corner of the screen you can change the following lines in CIwGameScene::setVirtualTransform():

    // Cantre scene in middle of screen
    VirtualTransform.t.x = screen_width / 2;
    VirtualTransform.t.y = screen_height / 2;


    // Cantre scene to top left hand of screen
    VirtualTransform.t.x = 0;
    VirtualTransform.t.y = 0;

    Although to keep in with the way the system is designed I would set up the scenes extents and then check the actor against the scenes extents inside its Update() method. if the actor is outside the scenes extents then you can then reset or re-use it.

    To control an actors animation you would need to get a handle to the animation manager using:

    CIwGameAnimManager* manager = actor->getVisualAnimManager();
    CIwGameAnim* anim = manager->getAnimation(0);

    Jumping to a frame can be done with:


    You can then stop the animation by calling:


  12. Dan says:

    Thanks for the quick reply.

    Yep I got most of the code done, doing the Collision checks and deletion now.

    Is there a simpler built-in way to get the Screen Extents than to use


    Should I use the macros VIRTUAL_SCREEN_WIDTH instead? I am still a bit unsure how marmalade scales… since my screen at HVGA is actually much larger than 800*460.

  13. drmop says:

    Ah, great news.

    Best way is to set the scene extents when you create the scene using:

    void setExtents(int x, int y, int w, int h) { Extents.x = x; Extents.y = y; Extents.w = w; Extents.h = h; }

    Then later retrieve them and do your bounds check using:

    CIwRect getExtents() const { return Extents; }

    Note that scene extents are in virtual canvas coords, the same as actor positions so you do not need to scale anything.

  14. Dan says:

    Thanks again.

    The game is now running fine, but I am having a hard time getting rid of self-collisions… if I do two quick clicks it collides against itself… also it appears that it collides with origin player right away.

    Also is there any recommended data structure to create arrays of Characters? On cocos2D i would use CCMutableArray is there a similar concept native to CIwGameEngine or the marmalade SDK API or should I just use the STL? I want to reuse my objects instead of delete and recreate.

    Anyway I hope that once it is done you can review it and package it as a sample application. I only need to get the collision code to work properly.

  15. drmop says:

    Hi Dan,

    Great to hear that the game is running, nice one.

    When you test for collision, to stop testing against self you can skip actors / sprites that are == this (this being the actor / sprites this pointer).

    Marmalade supports CIwArray and CIwList

    Yes, I’m definitely interested in including your game as a sample


  16. Dan says:

    I think I found the issue… I am not setting up collision rectangle and that is causing the issue.

    I thought they would be initialized automatically but they are not: http://i.imgur.com/oFkWU.png

  17. drmop says:

    Thanks for finding that, I’ve now added code to CIwGameActor::Reset() to reset the collision rect to all zeros.

  18. Dan says:


    Ok I am back. I have a couple of questions. I think I am probably doing this in the wrong way.

    I setup my Bonding boxes in my Init

    bool ActorStatic::Init(CIwGameScene* scene, CIwGameImage* image, int width, int height)

    Scene = scene;

    // Create sprite
    if (image != NULL)
    CIwGameBitmapSprite* sprite = new CIwGameBitmapSprite();
    if (sprite == NULL)
    return false;

    // Set sprite image
    sprite->setDestSize(width, height);
    sprite->setSrcRect(0, 0, width, height);

    // Set sprite as visual
    Visual = sprite;

    // Add sprite to the sprite manager so it can be managed and drawn

    //Setup Collision Box
    CIwRect* colBox = new CIwRect(0, 0, width, height);

    return true;

    But I think I am misunderstanding how the box is setup, is the CollisionRect setup using relative to the sprite coordinates… or is it setup using scene coordinates…

    should I pass it
    (this->getPosition().x, this->getPosition().y, width, height);

    What I mean is that I am passing (0,0,..) where I think 0,0 is the center of the sprite… Also why do we need a Rect to be defined?

    Also my sprites move on the screen, I am not sure where my boundingbox is being updated… do I need to manually update it?

    Thanks again!

  19. Dan says:

    Sorry I think I did not explain myself properly… I think that the GameActor has all the proprieties necessary to setup a bounding box, so we should not have to set it up or update it, simply enable it for collidable objects.

  20. Dan says:

    Hum… still not working. Also it collides even with
    IsCollidable false bool
    so these objects should not be collidable, but they are tested for collisions.

    Mat, did you have the time to test the collision system?

    I think I will take a better look tomorrow, it is the one thing that is missing right now… If I can’t figure it out I’ll try another approach.

    I know that you are busy adding the new features, but if you have some time can you cook up a little collision demo, it would be much appreciated.

    Thanks, have a nice night!

  21. Criss says:

    Hi Matt,

    What are the correct steps to take in order to remove the current scene from a game?

    My scenario is the following: In order to save memory, I decided to load my scenes only when its time to display them cause I noticed that if I load them all, I can’t load more than 5 and then the application quits on me. In order to achieve that, I loaded my first scene (“Scene1”) from whithin Game::Init() when the user flips to the second scene, I initialise Scene2 and add it to the game, then I go ahead and remove my scene by calling the following code:

    CIwGameScene* prevScene = findScene(“Scene1”);
    if (prevScene != NULL)

    The application is crashing as soon as reaches removeScene(prevScene);

    I feel as if it is trying to delete something that is still in use.

    Any Thoughts?


  22. drmop says:

    Hi Dan,

    Sorry for the delay, been very busy rolling out v0.26 of IwGame.

    You set up a collision rect and the collision size is auto calculated from that. I don’t auto set-up collision rect from the actors size because in most cased during game development, the size of the actor does not represent the collision area that yu want to collide with.

    The coordinates you specify for the collision rect are local to the centre of the actor, so if your collision size for your actor is 32×32 then the collision rect would be -16, -16, 32, 32

    To fix the issue with all actors being checked for collision change CIwGameScene::Update() from:

    // Resolve actor collisions
    for (_Iterator it = begin(); it != end(); ++it)


    // Resolve actor collisions
    for (_Iterator it = begin(); it != end(); ++it)
    if ((*it)->isCollidable())


  23. drmop says:

    Hi Criss,

    I’ve just fixed problems with scene removal in v0.26. Not sure why you cannot add more than 5 scenes though, there is no restriction within the engine itself.


  24. Criss says:

    Hi Mat,

    First, let me wish you a Merry Christmas.
    Second, let me thank you for the fix that you placed. It really made a difference but now the crash is happening somewhere else deeper in the code:

    for (_Iterator it = Animations.begin(); it != Animations.end(); ++it)
    delete *it;

    It’s on the level of the AnimManager, it seems that once the actors are being deleted one by one and when the destructors are being called for every class, an exception is thrown and I am seeing in my Stack:

    CIwGameScene::`scalar deleting destructor'()

    Is it because CIwGameScene is not managed? or am I doing something wrong?

    On another note, when I try to add one of the scenes that I removed, do I have to remove the added images from the resource group before adding it again? or should the removeScene() takes care of this? cause what is happeneing is that the iwResManager is complaining about having duplicated in its hash table.

    Regarding the limitation of the 5 scenes, well it is only happening on small devices only such as android and iPhone but i don’t have this issue on the playbook or the iPad, this is leading me to believe that it is a device specific and memory related problem. hence, the idea of removing the unused scenes came to my attention.

    Thanks a lot

  25. drmop says:

    Hi Criss,

    Thanks and a merry Christmas to you too.

    An actor contains and manages a CIwGameAnimManager, so it should get deleted when the actor is destroyed. Also scenes are managed by the main CIwGame class, so you don’t need to delete them or anything, you simply call removeScene() which adds the scene to a removal list. Any scenes in the removals list will be removed and destroyed after all scenes have been processed. When a scene is removed / destroyed all of its contained actors will also be destroyed.

    One thing to note is that managed objects such as scenes and actors are not reference counted so you cannot for example share the same instance of an actor across multiple scenes.

    I’m very curious about the 5 scene issue. Could you send me your code and I will take a look at it at this end?


  26. Criss says:

    Hi Mat,

    Thanks for your answer.
    When you said that managed objects cannot share the same instance of an actor in multiple scenes, this has given me an insight of what was the problem that prevented me from removing my scenes.
    I created some actors that shared the same CIwGameAnimImage cause I thought that this will allow my actors to animate at the same time the same way when only one is tapped and it worked beautifully until I decided to remove my scene where this caused some pain when the first actor in the series was deleted. Apparently, it deleted the CIwGameAnimImage object hence it was not available for the second actor in the series.

    Thanks a lot.
    PS: I will check again if I still have the problem of the 5 scenes and will get back to you.

    1. drmop says:

      Hi Criss,

      Unfortunately the engine doesn’t manage objects on a global level, although I could add this functionality at some point


  27. Criss says:

    Hi Mat,

    Happy New Year!

    Hope this coming year will be prosperous and full of sucess to you and your family.

    Now that I managed to remove the scenes I added some navigational functionality in order to navigate around my scenes. I have a problem when I return to one of the deleted scenes, I am instantiating the scene correctly but when I reach the code where I load the images and sounds from the resources using:


    I am getting the following error:

    “Message: Trying to add item (‘Scene1’) with hash 0x1b590264 to CIwManagedList,
    but item with that hash already exists in the list”

    Do I need to remove the groupe resources using :
    or is there a way to let the scene handle the resource removal automatically?

    This is been said: I tried to call DestroyGroup(), it game me a different error:
    IwAssert failure:
    Channel: CORE
    File: IwArray.h
    Line: 684
    Expression: qty>=0

    though I used the directive in the icf file:

    any ideas how to bypass that error?

    Thanks a lot

  28. drmop says:

    You mention that you are navigating around your scenes, but why are you deleting them? You could just hide the scene and then make it visible when the user switches to it?

    Marmalade’s resource manager does not auto clean-up groups, you need to destroy them yourself when you are done with them. You should also not try to load the same resource into the resource manager more than once.

    I will be putting a new version of IwGame out this week that contains support for auto clean-up of global resource groups in the game class as well as scene local resource groups which get cleaned up when a scene is deleted.

    Some other cool features include setting up scenes, actors, animations, images and resource groups using an XML based language that I’ve called XOML.

  29. Criss says:

    Hi Mat,

    I am deleting the scenes to release some memory, I tried hiding them but I am stuck with the memory limitations that only allows me to load few scenes at a time. My scenes are big, with lots of graphics, big backgrounds and a lot of sounds. Even though that I used the “derbh” library to compress my resources, this has only decreased the size of the deployed binary.
    Also, whenever I have a resource that has to show up in several scenes, I implemented it in the scene group as a child object so that it gets loaded when the parent is loaded.

    As per your suggestion a while ago, I will send you tomorrow my code to look at it. I will extract it and place it in a new project to make it lighter.

    Meanwhile I can’t wait to see your new changes that use the XOML and maybe managing the resources from whithin the IwGame instead of Marmalade will solve my problem.

    Thanks a lot

Leave a Reply