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.
This tutorial is a basic overview of the image, brush, animation and timeline systems.
Images
Art work definition in XOML is separated into images, each image represents a single image file in PNG, JPEG, BMP, GIF or TGA format
To create an image in XOML the following tag is used:
[sourcecode language=”xml”]
<Image Name="ui_image" Location="ui.png" Preload="false" Blocking="true" Format="RGBA_8888" Filter="true" Tag="Level1" Condition="variable" />
[/sourcecode]
Parameters are:
- Name – Name of the image
- Location – filename, local or web based
- Preload – If true then the image will be preloaded, if false then the image will be loaded when first used (optional)
- Blocking – If true then execution will be paused until the image is fully loaded (optional)
- Format – Format to convert the image to when loaded, supported formats include RGBA_8888, RGB_565, RGBA_4444, RGBA_5551, RGB_888, RGBA_6666, RGB_332 (optional)
- Filter – When set to true filtering will be used when rendering sprites that utilise this image (optional)
- Tag – A resource tag name, allows resources to be grouped, so they can be removed in groups (optional)
- Condition – The name of a condition variable that must evaluate to true (false if !variable is specified) for this resource to be loaded (optional)
Brushes
An Image represents a single image file whilst an image brush represents a rectangular area within an image (used with sprite atlases). A 9patch image brush represents a special type of image that preserves the edges of an image whilst scaling its inner features.
To create an brush in XIOML the following tag is used:
[sourcecode language=”xml”]
<Brush Name="Button1Brush" Image="ui_image" SrcRect="320, 70, 200, 70" Type="9patch" ScaleArea="7, 8, 186, 54" Tag="Level1" Condition="variable" />
[/sourcecode]
Parameters are:
- Name – Name of the brush
- Image – Image to use for this brush
- SrcRect – A rectangular area in the image that will be used to limit the part of the image drawn (x, y, w, h)
- Type – The type of brush (image or 9patch currently supported)
- ScaleAea – The scalable area of a 9patch brush (optional)
- Tag – A resource tag name, allows resources to be grouped, so they can be removed in groups (optional)
- Condition – The name of a condition variable that must evaluate to true (false if !variable is specified) for this resource to be created (optional)
Animation
XOML supports a versatile and complex animation system that allows animation of all types of data. However for the purpose of image animation we can narrow it down to just rect animations. Here is an example of creation of rect animation:
[sourcecode language=”xml”]
<Animation Name="PlayerImageAnim" Type="rect" Duration="0.8" Tag="Level1" >
<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>
[/sourcecode]
Here we enclose a number of Frame tags inside an Animation tag, each frame specifies a rectangular area within the sprite atlas, whilst Animation defines the actual animation that will be available.to the user.
Animation parameters are:
- Name – Name of the animation
- Type – Type of animation data (bool, float, vec2, vec3, vec4, rect and string) – Images animation use rect
- Duration – The length of the animation in seconds
- Tag – A resource tag name, allows resources to be grouped, so they can be removed in groups (optional)
Frame parameters are:
- Value – The value for this frame, in the case of a rect this value is x, y, w, h
- Time – The time at which this frame will be used
- Easing – The easing method used (linear, quadin,quadout, cubicin, cubicout, quarticin, quarticout)
An Animation tag can also contain another tag called Atlas that is used to automatically generate a number of frames of type rect:
[sourcecode language=”xml”]
<Animation Name="PlayerImageAnim" Type="rect" Duration="0.8" Tag="Level1" >
<Atlas Count="8" Size="36, 40" Position="0, 0" Pitch="1024, 40" Width="1024" Duration="0.1"/>
</Animation>
[/sourcecode]
Atlas parameters are:
- Count – number of frames to generate
- Size – The size of each frame (w. h)
- Position – Position where to start creating frames (x. y)
- Pitch – The amount to step to move to the next line of sprites within the image (x, y)
- Width – The width of the source image
- Duration – The amount of time to assign to each frame
An Atlas tag can be mixed in with normal frames, although such an action would be rare. Atlas tag is useful for sprite atlases where all frames are of equal size and are also spaced equally across and down the image.
Timelines
The Timeline system is a system that allows the user to group together collections of animations and play them all back simultaneously on demand. A timeline can contain any number of animations that can target different properties of actors and scenes.
Below is an example of a timeline that can target an actors SrcRect, allowing sprite atlas bitmap animations to be applied to an actors sprite
[sourcecode language=”xml”]
<Timeline Name="Player1Intro" AutoPlay="true" Tag="Level1">
<Animation Anim="PlayerImageAnim" Target="SrcRect" Repeat="0" StartAtTime="0" Delta="false" Interpolate="true" OnEnd="AnimEnded" OnStart="AnimStarted" OnRepeat="AnimRepeated" />
</Timeline>
[/sourcecode]
The Timeline tag enclosed a set of animations that have previously been defined with the Animation tag.
Timeline parameters are:
- Name – Name of the timeline
- AutoPlay – If set to true then the animation will automatically play when assigned to an actor or scene< (optional)/li>
- Tag – A resource tag name, allows resources to be grouped, so they can be removed in groups (optional)
The inner Animation tags define which animations to play and which properties of the target actor or scene to modify, as well as actions that can be called when certain animation events occur.
Timeline Animation parameters are:
- Anim – The animation to play
- Target – The target property of the actor or scene to modify (in this case SrcRect modifies the actors sprite source rectangle which defined which portion of the sprite atlas to display)
- Repeat – Number of times to repeat the animation (0 for infinite)
- StartAtTime – The number of seconds to delay starting the animation playback (optional)
- Delta – When set to true animation frames will be added to the objects existing property rather than overwriting it (optional)
- Interpolate – When set to false frames will be interpolated< (optional)/li>
- OnEnd, OnStart and OnRepeat are actions that will be called when an animation ends, starts or repeats< (optional)/li>
Hello Mat,
I’ve been through all your tutorials on Marmalade SDK and IwGame Engine. The first lessons were quite easy, but since “Turorial 14 – Turning IwGame into a real game engine” the complexity grows expotentialy, and now with controlling almost everything with XOML I’m totaly confused. I tried going through your code, and have read most of the documentation, but what I lack now is real life tutorials on the IwGame engine. The descriptions of tags with their parameters will be much more useful when I undestand their purpose as by now I can’t figure out how they work. Sometimes they are values for a constructor () and other times they are constructors themselves (), some are placed inside tags, some are outside. When I switch places they crash the app … I get totally confused. The code you provided in Examples is excellent, but it is also extremely complex to figure out what comes from where 🙁 I’ve been trying to figure out what is what for a couple of days now, and I feel I am more lost then when I started learning Marmalade SDK.
Mat, would it be possible for you to write a tutorial on creating a game using IwGame Engine which goes like this:
1. There is a “Score” on the top (like you did with the water drops game).
2. When I press the screen spinning actor (animated image) gets created at this point.
3. The actor falls on the ground.
4. If the actor reaches the ground it bounces and fades out.
5. If the actor is pressed it fades out and then dies.
6. If you pinch or stretch the screen (multitouch) it zooms in or out.
If you created such app and described the files you create (at least Game.cpp, ActorPlayer.cpp, and Scene.xml), you’d be my hero forever! :)) Really, I think I’m not the only one who’d LOVE to see such tutorial. Later on when I understand everything in the code, I’m sure I’ll get back to the above tutorials as a great reference for additional parameters, but now I’m totaly lost and ask you kindly for help.
Best regards,
B.
Hi Beny,
We have plans to create new documentation relating to XOML and how to use it, along with new fresh tutorials and examples. I will see if I can get a simple game tutorial together some time this coming week, although I cannot 100% promise as I have a very busy schedule.
Mat
Thank you! I’d really appreciate that. Meantime I’ll keep studying.
Best regards!
Hi!
First of all thank you for your tutorials and engine – looking great.
I’ve discovered some render error during writing animation test application:
– when actor is moving and has animation it renders with some “offset” on atlas, thus showing you stripes of pixels from “neighborhood” frames. This behavior can be reproduced in your tutorial “Creating an Extensible Animation System”. This error is really frustrating – can you suggest some decision to resolve it (of course we I’m talking about not just create frames with transparent offset =) )?
You can check the image capturing this behavior here: http://imageshack.us/a/img713/8700/iwgamespriteanimationar.png
P.S.: I also left similar message on the page with extensible animation system tutorial. Thanks.
Br, Michael.