Whilst our title comparison suggests that actors are simply sprites with brains they have the potential to be much more.<\/p>\n
Going back to comparison in the scene introduction section, actors play a pivotal role in our scenes, each actor having its own unique role and visual appearance. Actors are the building block of the game, they provide the actual unique\u00a0functionality and visuals that make up the game as a whole. They can provide any type of functionality from a simple bullet fleeting across the screen to something as complex as a dynamic machine that modifies its behaviour and appearance based upon data streamed from a web server.<\/p>\n
A CIwGameActor is a very generic object that provides quite a lot of functionality out of the box. The idea is for developers to create their own actor types from the base CIwGameActor class then implement their own custom functionality within its Update() method. The basic functionality provided by CIwGameActor includes:<\/p>\n
Note that any changes made to the actor will automatically be applied to the actors visual.<\/p>\n
As IwGame progresses more actor types with additional functionality will be created to create more out of the box style game objects (plug-in actors if you will). For the moment the following actors have been created for you:<\/p>\n
CIwGameActorImage \u2013 This object represents a basic image based actor which has an associated image and animation.
\nCIwGameActorText \u2013 This object represents a basic text based actor which has an associated font and animation.
\nCIwGameActorParticles \u2013 This object represents a complex particle based actor system consists of manypatricles that move independently and have varying life spans.<\/p>\n
A word of warning, do not forget to call the based classes Init(), Reset(), Update(), UpdateVisual() methods from your own derived classes or the underlying functionality will not be provided.<\/p>\n
Creating an actor is very simple as the following code shows:<\/p>\n
\t\/\/ Create player actor<\/span>\r\n\tMyActor* actor = new MyActor();\r\n\tif (actor == NULL)\r\n\t\treturn NULL;\r\n\r\n\tactor->Init();\r\n\tactor->setName(\"Player1\");\r\n\tactor->setPosition(x, y);\r\n\r\n\t\/\/ Add player actor to the scene<\/span>\r\n\tscene->addActor(actor);<\/pre>\nIn the above code we create a a basic MyActor object, which is a class that I created derived from CIwGameActor giving us the base CIwGameActor functionality. However, adding this code into a game wouldn’t actually see anything as we\u00a0have not assigned a visual element to the actor. CIwGameActor does not handle the creation of a visual for you, instead it handles the rendering and update of a visual and its animations.<\/p>\n
To get developers started with actors we included the CIwGameActorImage that will create a basic image based actor that supports animation.<\/p>\n
If you require your actor to support Box2D physics then you should either define the Box2DMaterial and Shape in XOML or if creating manually then call:<\/p>\n
\tInitBody(Scene, shape, material, &Position, Angle, com.x, com.y);<\/pre>\nThis can be called before or after CIwGameActor::Init()<\/p>\n
Creating a CIwGameActorImage<\/h2>\n
Creating an image based actor is a little more complicated, lets take a look at some example code:<\/p>\n
\t\/\/ Create a new instance<\/span>\r\n\tActorPlayer* actor = new ActorPlayer();\r\n\tif (actor == NULL)\r\n\t\treturn NULL;\r\n\r\n\t\/\/ Create player actor<\/span>\r\n\tactor->setScene(scene);\r\n\tactor->Init(image, 36, 40);\r\n\tactor->setPosition(x, y);\r\n\r\n\t\/\/ Add player actor to the scene<\/span>\r\n\tscene->addActor(actor);<\/pre>\nCreation is very similar to creating a basic CIwGameActor with the additional complication of having to pass an image to the actors Init() method.<\/p>\n
Looking at the above code we create an ActorPlayer, which is a class that I created derived from CIwGameActorImage as we want some basic image functionality.<\/p>\n
We then call the actors its Init() method to set up actor internals. We give the actor a name so that we can find it later then set its world position to the centre of the scene. Finally we add the actor to the scene.<\/p>\n
You will notice that ActorPlayer’s Init() method has quite a a few parameters. When we call Init(….) we are actually calling CIwGameActorImage::Init(….) and passing along all the details shown in the code above which includes an\u00a0image that will represent our actor (or more usually an image atlas), and the width and height of the visual on screen (in virtual canvas coordinates). Internally CIwGameActorImage will create a sprite to display our actor.<\/p>\n
The end product of the above code is an actor that can be seen, moved around, scaled, rotated etc..<\/p>\n
Now lets take a look at a slightly more complicated ezmple that creates an image based actor that uses an animation time line (more details on time line’s later):<\/p>\n
\t\/\/ Create a new instance<\/span>\r\n\tActorPlayer* actor = new ActorPlayer();\r\n\tif (actor == NULL)\r\n\t\treturn NULL;\r\n\r\n\t\/\/ Create an animation timeline to hold our image animation<\/span>\r\n\tCIwGameAnimTimeline* timeline = new CIwGameAnimTimeline();\r\n\r\n\t\/\/ Create and set up our face animation<\/span>\r\n\tCIwGameAnimInstance* face_anim = new CIwGameAnimInstance();\r\n\tface_anim->setAnimation(anim);\r\n\tface_anim->setTarget(actor, \"SrcRect\");\r\n\ttimeline->addAnimation(face_anim);\r\n\ttimeline->play();\r\n\r\n\t\/\/ Create player actor<\/span>\r\n\tactor->setScene(scene);\r\n\tactor->Init(image, 36, 40);\r\n\tactor->setTimeline(timeline);\r\n\tactor->setPosition(x, y);\r\n\r\n\t\/\/ Add player actor to the scene<\/span>\r\n\tscene->addActor(actor);<\/pre>\nI have marked the changes from the previous example.<\/p>\n
The first set of changes deals with creating a time line object then creating the instance of an animation and adding that to the time line. This process allows the actor to track and update its own animations<\/p>\n
In the last change we simply assign the time line to the actor, the actor will now take care of playing the animation and updating the actors visual with animation changes.<\/p>\n
Text Based Actors<\/h2>\n
Text based actors enable you to instantiate text into the scene with very little effort from code or more easily from XOML. Thse text objects can be use very much in the same way as image based actors in that they can be moved around,\u00a0scaled, rotated, hit tested or even have physics and collision applied to them.<\/p>\n
Lets firstly take a look at creating a text based actor in code:<\/p>\n
\t\/\/ Find our preloaded font<\/span>\r\n\tCIwGameFont* font = (CIwGameFont*)IW_GAME_GLOBAL_RESOURCES->getResourceManager()->findResource(\"font1\", CIwGameXomlNames::Font_Hash);\r\n\r\n\t\/\/ Create a text actor<\/span>\r\n\tCIwGameActorText* text_actor = new CIwGameActorText();\r\n\ttext_actor->Init(font);\r\n\ttext_actor->setText(\"Hello World!\");\r\n\ttext_actor->setRect(CIwRect(-100, -100, 200, 200));\r\n\ttext_actor->setColour(0, 0, 0, 255);\r\n\ttext_actor->setPosition(0, 0);\r\n\ttext_actor->setAngle(45);\r\n\r\n\t\/\/ Add to the scene<\/span>\r\n\tCIwGameScene* scene = findScene(\"Scene1\");\r\n\tscene->addActor(text_actor);<\/pre>\nIn the above code we firstly locate our font (which we have already preloaded into the resource system) then we create a text based actor from CIwGameActorText initialising it with the font. We then set the text, rect and some other\u00a0parameters.<\/p>\n
We now search for the scene we want to place the actor in and it to the scene.<\/p>\n
Now lets take a look at how to instantiate a text based actor in XOML:<\/p>\n
<ActorText<\/span> Position=”0, 0″ Rect=”-100, -100, 200, 200″ Angle=”45″ Font=”font1″ Text=”Hello World!” Colour=”0, 0, 0, 255″ \/><\/p>\nAs you can see the XOML definition is much more compact and readable.<\/p>\n
Particle System Actors<\/h2>\n
From v.030 of IwGame the new particle system based actor is available. This actor is special in that it is optimised for creating, displaying and updating a complete system of sprites (kind of like its own sprite manager). The advantage\u00a0of this actor is that it does not have to deal with each particle as a separate actor object. The CIwGameActorParticles actor supports both manual and auto generation of particles. Auto generation can be controlled using a number of a\u00a0control parameters.<\/p>\n
Particles have a number of properties that can be adjusted:<\/p>\n
\n- Visual<\/li>\n
- Position<\/li>\n
- Velocity<\/li>\n
- Velocity Damping<\/li>\n
- Gravity<\/li>\n
- Scale<\/li>\n
- Scale Velocity<\/li>\n
- Scale Velocity Damping<\/li>\n
- Angle<\/li>\n
- Angle Velocity<\/li>\n
- Angle Velocity Damping<\/li>\n
- Colour<\/li>\n
- Colour Velocity<\/li>\n
- Colour Velocity Damping<\/li>\n
- Depth<\/li>\n
- Depth Velocity<\/li>\n
- Depth Velocity Damping<\/li>\n
- Active state<\/li>\n
- Visible state<\/li>\n
- Lifespan \u2013 Duration of particle in seconds<\/li>\n
- SpawnDelay \u2013 The amount of time to wait before spawning for the first time<\/li>\n
- Lives \u2013 Number of times the particle will re-spawn (-1 for infinite)<\/li>\n<\/ul>\n
The CIwGameActorParticles class contains two methods for generating random particles:<\/p>\n
void GenerateRandomParticles(int count, CIwRect& src_rect, CIwFVec4& colour, CIwFVec4& colour_velocity, float duration, int repeat_count, float spawn_delay_change, float gravity)\r\nvoid GenerateRandomParticles(int count, CIwGameActorParticle* particle, CIwRect& src_rect, float duration, int repeat_count, float spawn_delay_change)<\/pre>\nBoth of these methods will generate a number of particles based on a set of limits.<\/p>\n
To determine which particle parameters are generated randomly the CIwGameActorParticles class supports the following methods:<\/p>\n
void\tsetPositionMode(eParticleMode mode)\r\nvoid\tsetAngleMode(eParticleMode mode)\r\nvoid\tsetScaleMode(eParticleMode mode)\r\nvoid\tsetVelocityMode(eParticleMode mode)\r\nvoid\tsetAngVelocityMode(eParticleMode mode)\r\nvoid\tsetScaleVelocityMode(eParticleMode mode)\r\nvoid\tsetDepthMode(eParticleMode mode)\r\nvoid\tsetDepthVelocityMode(eParticleMode mode)<\/pre>\nBy setting the mode to PAM_Random the specified parameters will be generated randomly.<\/p>\n
When parameters are generated the following methods specify limits to the random formulas used to generate the parameters:<\/p>\n
void\tsetPositionRange(CIwFVec2& range)\r\nvoid\tsetAngleRange(CIwFVec2& range)\r\nvoid\tsetScaleRange(CIwFVec2& range)\r\nvoid\tsetDepthRange(CIwFVec2& range)\r\nvoid\tsetVelocityRange(CIwFVec4& range)\r\nvoid\tsetAngVelocityRange(CIwFVec2& range)\r\nvoid\tsetScaleVelocityRange(CIwFVec2& range)\r\nvoid\tsetDepthVelocityRange(CIwFVec2& range)<\/pre>\nLets take a look at some code that generates an explosion type particle system:<\/p>\n
CIwGameActorParticles* GameScene::AddExplosion(int num_particles, float x, float y, float scale, float depth, int layer, float gravity)\r\n{\r\n\t\/\/ Create explosion particle actor<\/span>\r\n\tCIwGameActorParticles* actor = new CIwGameActorParticles();\r\n\taddActor(actor);\r\n\tactor->Init(num_particles);\r\n\tactor->setImage((CIwGameImage*)ResourceManager->findResource(\"sprites1\", CIwGameXomlNames::Image_Hash));\r\n\tactor->setPosition(x, y);\r\n\r\n\t\/\/ Set random <\/span>parameters<\/span>\r\n\tactor->setScaleMode(CIwGameActorParticles::PAM_Random);\r\n\tactor->setAngVelocityMode(CIwGameActorParticles::PAM_Random);\r\n\tactor->setVelocityMode(CIwGameActorParticles::PAM_Random);\r\n\r\n\t\/\/ Set paramater limits<\/span>\r\n\tCIwFVec2 scale_range(scale, scale + scale \/ 2);\r\n\tactor->setScaleRange(scale_range);\r\n\tCIwFVec2 angle_range(-5, 5);\r\n\tactor->setAngleRange(angle_range);\r\n\tCIwFVec4 vel_range(-5, 5, -5, 5);\r\n\tactor->setVelocityRange(vel_range);\r\n\tCIwRect src_rect(908, 440, 100, 100);\r\n\tCIwFVec4 colour(255, 255, 255, 255);\r\n\tCIwFVec4 colour_vel(0, 0, 0, -5);\r\n\r\n\t\/\/ Generate the particles<\/span>\r\n\tactor->GenerateRandomParticles(num_particles, src_rect, colour, colour_vel, 2, 1, 0, gravity);\r\n\r\n\treturn actor;\r\n}<\/pre>\nHere we create a particle actor, set up the which parameters should be randomised then set the random limits. Finally we tell the actor to generate random particles<\/p>\n
Now lets take a quick look at generating particles manually in code:<\/p>\n
CIwGameActorParticles* GameScene::AddStream(int num_particles, float x, float y, float scale, float depth, int layer, float gravity)\r\n{\r\n\t\/\/ Create stream particle actor<\/span>\r\n\tCIwGameActorParticles* actor = new CIwGameActorParticles();\r\n\taddActor(actor);\r\n\tactor->Init(num_particles);\r\n\tactor->setImage((CIwGameImage*)ResourceManager->findResource(\"sprites1\", CIwGameXomlNames::Image_Hash));\r\n\tactor->setPosition(x, y);\r\n\tCIwRect src_rect(800, 291, 68, 65);\r\n\tCIwFVec4 colour(255, 255, 255, 128);\r\n\tCIwFVec4 colour_vel(0, 0, 0, -3);\r\n\r\n\t\/\/ Create and add particles<\/span>\r\n\tfloat spawn_delay = 0;\r\n\tfor (int t = 0; t < num_particles; t++)\r\n\t{\r\n\t\tCIwGameActorParticle* p = new CIwGameActorParticle();\r\n\t\tp->LifeSpan = 1;\r\n\t\tp->Lives = -1;\r\n\t\tp->SpawnDelay = spawn_delay;\r\n\t\tp->Gravity = gravity;\r\n\t\tp->Colour = colour;\r\n\t\tp->ColourVelocity = colour_vel;\r\n\t\tp->DepthVelocity = -0.01f;\r\n\r\n\t\tactor->addParticle(p, src_rect);\r\n\t\tspawn_delay += (float)1.0f \/ num_particles;\r\n\t}\r\n\r\n\treturn actor;\r\n}<\/pre>\nThis method creates a particle actor then manually creates a stream of particles that spawn at slightly different times to create a stream type particle system.<\/p>\n
Particle actors can also be created in XOML. Lets take a quick look at an example:<\/p>\n
<ActorParticles<\/span> Name=\"StreamParticles\" Image=\"sprites1\" Position=\"0, 0\" Scale=\"1.0\" Depth=\"1.0\" Layer=\"1\" VelAngMode=\"random\" VelMode=\"random\" AngMode=\"random\" ScaleMode=\"random\" PositionRange=\"100, 100\" AngleRange=\"0, 360\" AngVelRange=\"-5, 5\" ScaleRange=\"0.25, 0.5\" DepthRange=\"0.5, 1.0\" VelRange=\"-2, 2, -2, 2\" ScaleVelRange=\"0, -0.1\" DepthVelRange=\"0, 0\">\r\n <Particle<\/span> Count=\"10\" Position=\"0, 0\" VelocityDamping=\"0.95, 0.95\"\r\n\t\tSrcRect=\"908, 440, 100, 100\" ColourVelocity=\"0, 0, 0, -4\" Duration=\"2\"\r\n\t\tRepeat=\"-1\" SpawnDelay=\"0\" \/>\r\n <Particle<\/span> Position=\"0, 0\" VelocityDamping=\"0.95, 0.95\" SrcRect=\"908, 440, 100, 100\"\r\n\t\tColourVelocity=\"0, 0, 0, -4\" Duration=\"2\" Repeat=\"-1\" SpawnDelay=\"0\" \/>\r\n <Particle<\/span> Position=\"0, 0\" VelocityDamping=\"0.95, 0.95\" SrcRect=\"908, 440, 100, 100\"\r\n\t\tColourVelocity=\"0, 0, 0, -4\" Duration=\"2\" Repeat=\"-1\" SpawnDelay=\"0.4\" \/>\r\n <Particle<\/span> Position=\"0, 0\" VelocityDamping=\"0.95, 0.95\" SrcRect=\"908, 440, 100, 100\"\r\n\t\tColourVelocity=\"0, 0, 0, -4\" Duration=\"2\" Repeat=\"-1\" SpawnDelay=\"0.8\" \/>\r\n <Particle<\/span> Position=\"0, 0\" VelocityDamping=\"0.95, 0.95\" SrcRect=\"908, 440, 100, 100\"\r\n\t\tColourVelocity=\"0, 0, 0, -4\" Duration=\"2\" Repeat=\"-1\" SpawnDelay=\"1.2\" \/>\r\n <Particle<\/span> Position=\"0, 0\" VelocityDamping=\"0.95, 0.95\" SrcRect=\"908, 440, 100, 100\"\r\n\t\tColourVelocity=\"0, 0, 0, -4\" Duration=\"2\" Repeat=\"-1\" SpawnDelay=\"1.6\" \/>\r\n <\/ActorParticles<\/span>><\/pre>\nThe above XOML firstly generates 10 random particles at time 0, followed by 4 additional particles at times 0.4, 0.8, 1.2 and 1.6 seconds.<\/p>\n
If you would like finer grained control over particle actors then you can simply derive your own version from CIwGameActorParticles<\/p>\n
Actor Lifetimes<\/h2>\n
Actors will persist within the scene until a) the scene is deleted b) you explicitly remove them or the recommended method c) they remove themselves. An actor can easily remove and delete itself from the scene by returning false from its\u00a0Update() method. Here’s an example:<\/p>\n
bool ActorPlayer::Update(float dt)\r\n{\r\n\t\/\/ If fade timer has timed out then delete this actor<\/span>\r\n\tif (FadeTimer.HasTimedOut())\r\n\t{\r\n\t\treturn false;\t\/\/ returning false tells the scene that we no need to be removed<\/span>\r\n\t}\r\n\r\n\t\/\/ Calculate our opacity from time left on fade timer<\/span>\r\n\tint opacity = FadeTimer.GetTimeLeft() \/ 2;\r\n\tif (opacity > 255) opacity = 255;\r\n\tColour.a = opacity;\r\n\r\n\treturn CIwGameActorImage::Update(dt);\r\n}<\/pre>\nActor Naming and Finding Actors<\/h2>\n
As mention previously for scenes, actors also named objects, each instance of an object that you wish to query should have its own unique name (per scene) so that it can be located and modified at a later date.<\/p>\n
You can find an actor in a particular scene using:<\/p>\n
\tCIwGameActor* actor = scene->findActor(\u201cPlayer1\u201d);\r\n\tif (actor != NULL)\r\n\t{\r\n\t\t\/\/ Do somethinig with the actor<\/span>\r\n\t}<\/pre>\nThere are three ways to locate actors within a scene:<\/p>\n
\tCIwGameActor*\t\tfindActor(const char* name);\r\n\tCIwGameActor*\t\tfindActor(unsigned int name_hash);\r\n\tCIwGameActor*\t\tfindActor(int type);<\/pre>\nThese allow you to search for actor by string, hash or type. Note that searching by type will return the first and only the first instance of that particular actor type. This is very useful if you want to find a unique actor type, for example the player.<\/p>\n
Actor Types<\/h2>\n
When developing games I find it incredibly useful to assign different types of actors different type ID’s, this allows me to optimise many area of my code such as collision checks. Carrying a type ID for each actor also comes in handy\u00a0when you want to know the types of actor that you are interacting with.<\/p>\n
You can set and get the actors type ID using:<\/p>\n
\tvoid\t\tsetType(int type)\r\n\tint\t\tgetType() const<\/pre>\nMoving, Rotating and Spinning Actors<\/h2>\n
Actors come with a very basic physics system that allows movement via velocity and angular velocity, actors can also be scaled. CIwGameActor provides the following basic functionality to handle these features:<\/p>\n
\tvoid\t\t\t\tsetPosition(float x, float y)\r\n\tCIwFVec2\t\t\tgetPosition()\r\n\tvoid\t\t\t\tsetAngle(float angle)\r\n\tfloat\t\t\t\tgetAngle()\r\n\tvoid\t\t\t\tsetVelocity(float x, float y)\r\n\tCIwFVec2\t\t\tgetVelocity()\r\n \tvoid\t\t\t\tsetVelocityDamping(float x, float y)\r\n\tvoid\t\t\t\tsetAngularVelocity(float velocity)\r\n\tfloat\t\t\t\tgetAngularVelocity() const\r\n\tvoid\t\t\t\tsetAngularVelocityDamping(float damping)\r\n\tvoid\t\t\t\tsetScale(float scale)\r\n\tfloat\t\t\t\tgetScale() const<\/pre>\nNote that velocity and angular velocity damping is a reduction factor that is applied each game frame to slow down objects linear and angular velocities. Their default values are 1.0f which provides no damping, setting this value to less\u00a0than 1.0f will dampen velocity whilst setting it to a value greater than 1.0f will enhance velocity.<\/p>\n
Also note that changing position or angle will not effect velocity.<\/p>\n
If the actor was created with Box2D physics enabled then you can also use the supplied force application methods.<\/p>\n
Attaching a Visual and an Animation Timeline<\/h2>\n
For our actor to become visible on screen we need to assign it a visual component. If you are rolling your own actor and don’t go the CIwGameActorImage route then you will need to create and assign your own visual component to the actor.<\/p>\n
To assign a visual to an actor you would call:<\/p>\n
\tvoid\t\tsetVisual(CIwGameSprite* visual)<\/pre>\nNow when the scene renders the actor it will attenot to render the visual. I want to mention at this pont that as far as IwGame is concerned a visual is an object type that derived from a CIwGameSprite (we will cover this later), but for\u00a0now we will just say that a sprite as far as IwGame is concerned is anything that can be displayed, be it a simple image or a complex piece of SVG.<\/p>\n
And where you find visuals you will usually find some kind of animation. The actor class supports attachment of CIwGameAnimTimeline which is basically a collection of animations (we will cover this in more depth later). To assign a time\u00a0line we call:<\/p>\n
\tvoid\t\tsetTimeline(CIwGameAnimTimeline* timeline) { Timeline = timeline; }<\/pre>\nChanging an Actors Colour<\/h2>\n
Each actor has its own independent colour (including opacity). All actors are set to a default colour of white and full opacity. To change the colour of an actor you can call:<\/p>\n
\tvoid\t\tsetColour(CIwColour& colour)<\/pre>\nNote that an actors colour will be combined with its parents base colour.<\/p>\n
Obeying Scene Extents<\/h2>\n
By default an actor would merrily travel across the game scene and beyond its extents into oblivion and out of range coordinates, this can cause a bit of a mess for the underlying math and rendering routines. To prevent actors from\u00a0going off into oblivion we can tell them to wrap around to the other side of the scene if they hit its extents boundary. To force actors to wrap around at the boundaries of the scene we call setWrapPosition(true):<\/p>\n
\tvoid\t\tsetWrapPosition(bool enable)\r\n\tbool\t\tgetWrapPosition() const\t\t\t\t\t{<\/pre>\nActor Layering<\/h2>\n
We touched on layering earlier when we talking about layering in scenes. All actors within a scene exist (visually) on a layer. The layer determines the order in which the actors are rendered with lower layers appearing below higher\u00a0layers. The maximum layer that an actor can exist on is determined by the scene that it lives in. To change the layer that an actor appears on and to retrieve its current layer we use:<\/p>\n
\tvoid\t\tsetLayer(int layer)\r\n\tint\t\tgetLayer() const<\/pre>\nScene Visibility and Active State<\/h2>\n
You can query an actors visibility state and set its visibility state using:<\/p>\n
\tvoid\t\tsetVisible(bool visible)\r\n\tbool\t\tisVisible() const<\/pre>\nYou can query an actors active state and set its active state using:<\/p>\n
\tvoid\t\tsetActive(bool active)\r\n\tbool\t\tisActive() const<\/pre>\nNote that when an actor is made inactive it will also become invisible. However making an actor invisible will not make it inactive.<\/p>\n
Resetting Actors<\/h2>\n
Because actors can be part of an object pooling system and may not get re-initialised when re-used, we provide the functionality to reset them to a default state. This allows developers to re-use objects and not worry about the previous\u00a0state of the object. Just remember to call the underlying CIwGameActor::Reset() method from your own Reset() method to ensure that the actor is completely reset.<\/p>\n
Collision Checking<\/h2>\n
Right now IwGame does not carry out collision checks for you, instead it calls back each actor in the scene after the scene has been updated to give each possible colliding object a chance to check and respond to collisions. To take\u00a0advantage of this functionality you need to implement the following handler in your derived actor class:<\/p>\n
\tvirtual void\tResolveCollisions() = 0;<\/pre>\nA basic actor to actor collision method is included in CIwGameActor to allow actors to test for overlap based on the size set by setCollisionRect();<\/p>\n
When a collision does take place, actors can notify each other by calling:<\/p>\n
\tvirtual void\tNotifyCollision(CIwGameActor* other) = 0;<\/pre>\nHere’s a quick example showing how to use the system:<\/p>\n
void ActorPlayer::ResolveCollisions()\r\n{\r\n\t\/\/ Walk the scenes actors<\/span>\r\n\tfor (CIwGameScene::_Iterator it = Scene->begin(); it != Scene->end(); ++it)\r\n\t{\r\n\t\t\/\/ Only test collision against ball type actors<\/span>\r\n\t\tif ((*it)->getType() == ActorType_Ball)\r\n\t\t{\r\n\t\t\t\/\/ Check for physical collision<\/span>\r\n\t\t\tif (CheckCollision(*it))\r\n\t\t\t{\r\n\t\t\t\t\/\/ Notify ourselves that we collided with ball actor<\/span>\r\n\t\t\t\tNotifyCollision(*it);\r\n\t\t\t\t\/\/ Notify ball actor that we collided with it<\/span>\r\n\t\t\t\t(*it)->NotifyCollision(this);\r\n\t\t\t}\r\n\t\t}\r\n\t}\r\n}<\/pre>\nNote that if you are using integrated Box2D then you safely bypass this collision check system.<\/pre>\nCreating an Actor from XOML<\/h2>\n
Actors can be created declaratively using XOML mark-up, making actor creation much easier and more intuitive. Below shows an example of an actor declared using XOML:<\/p>\n
<MyActor<\/span> Name=\"Player1\" Position=\"0, 0\" Size=\"100, 100\" Angle=\"45\" SrcRect=\"0, 0, 36, 40\" Image=\"Sprites\" Timeline=\"Player1Intro2\" \/><\/pre>\nThe basic actor tag supports many different attributes that determine how an actor is created and how it behaves. A description of these tags are listed below:<\/p>\n
\n- Name \u2013 Name of the scene (string)<\/li>\n
- Style \u2013 Style that should be applied to this actor. If a properties that exists in the style is added to the definition then it replaces the property found in the style<\/li>\n
- Type \u2013 A numerical type that can be used to identify the type of this actor (integer)<\/li>\n
- Position\u2013 Position in the scene (x, y 2d vector)<\/li>\n
- Origin\u2013 Origin in the scene, moves the point around which the actor will rotate and scale (x, y 2d vector)<\/li>\n
- Depth \u2013 Depth of the actor in 3D (float \u2013 larger values move the sprite further away)<\/li>\n
- Velocity \u2013 Initial velocity of the actor (x, y 2d vector)<\/li>\n
- VelocityDamping \u2013 The amount to dampen velocity each frame (x, y 2d vector)<\/li>\n
- Angle \u2013 The orientation of the actor (float)<\/li>\n
- AngularVelocity \u2013 The rate at which the orientation of the actor changes (float)<\/li>\n
- AngularVelocityDamping \u2013 The amount of rotational velocity damping to apply each frame (float)<\/li>\n
- Scale, ScaleX, ScaleY \u2013 The scale of the actor (float)<\/li>\n
- Colour \u2013 The initial colour of the actor (r, g, b, a colour)<\/li>\n
- Layer \u2013 The scenes visible layer that the actor should appear on (integer)<\/li>\n
- Active \u2013 Initial actor active state (boolean)<\/li>\n
- Visible \u2013 Initial actor visible state (boolean)<\/li>\n
- HitTest \u2013 If true then this actor will receive touch events<\/li>\n
- Collidable \u2013 Collidable state of actor (boolean)<\/li>\n
- CollisionSize \u2013 The circular size of the actor (float)<\/li>\n
- CollisionRect \u2013 The rectangular collision area that the actor covers (x, y, w, h rect)<\/li>\n
- WrapPosition \u2013 If true then the actor will wrap at the edges of the canvas (boolean)<\/li>\n
- Timeline \u2013 The time line that should be used to animate the actor<\/li>\n
- Box2dMaterial \u2013 Sets the physical material type used by the Box2D actor<\/li>\n
- Shape \u2013 Box2D fixture shape for the Box2D actor<\/li>\n
- COM \u2013 Centre of mass of Box2D body (x, y 2d vector)<\/li>\n
- Sensor \u2013 Can be used to set the Box2D actor as a sensor (boolean)<\/li>\n
- CollisionFlags \u2013 The Box2D body collision flags (category, mask and group)<\/li>\n
- OnTapped \u2013 Tapped event handler<\/li>\n
- OnBeginTouch \u2013 Event handler that specifies an actions list to call when the user begins to touch the actor<\/li>\n
- OnEndTouch \u2013 Event handler that specifies an actions list to call when the user stops to touching the actor<\/li>\n
- OnTapped \u2013 Event handler that specifies an actions list to call when the user taps the actor<\/li>\n
- OnCreate \u2013 Event handler that specifies an actions list to call when this actor is created<\/li>\n
- OnDestroy \u2013 Event handler that specifies an actions list to call when this actor is destroyed<\/li>\n
- LinkedTo \u2013 Name of actor that this actor links to (string)<\/li>\n<\/ul>\n
For actors that are derived from CIwGameActorImage we have the following additional properties:<\/p>\n
\n- Image \u2013 The image that is to be used as the actors visual (string)<\/li>\n
- Size \u2013 The on screen visible size of the actor (x, y 2d vector)<\/li>\n
- SrcRect \u2013 The position and source of the source rectangle in the image atlas (x, y, w, h rect). Used for panning the portion of a sprite atlas shown allowing frame based animation.<\/li>\n
- FlipX \u2013 Horizontal flipped state (boolean)<\/li>\n
- FlipY \u2013 Vertical flipped state (boolean)<\/li>\n<\/ul>\n
For actors that are derived from CIwGameActorText we have the following additional properties:<\/p>\n
\n- Font \u2013 Name of font to use to draw the text (string)<\/li>\n
- Rect \u2013 The area thuat the text should be drawn inside of (x, y, w, h rect)<\/li>\n
- Text \u2013 String to display (string)<\/li>\n
- AlignH \u2013 Horizontal alignment (centre, left and right)<\/li>\n
- AlignV \u2013 Verticalalignment (middle, top and bottom)<\/li>\n
- Wrap \u2013 If true then text is wrapped onto next line if to long (boolean)<\/li>\n<\/ul>\n
Note that unlike scenes you cannot create an Actor or ActorImage directly as their corresponding CIwGameActor and CIwGameActorImage classes are abstract, so you must derive your own actor class. More on this later.<\/p>\n
In addition, actors must be declared inside a scene tag element as they must have a parent scene and cannot be declared as resources.<\/p>\n
Animating Actor Components<\/h2>\n
Actors allow an animation time line to be attached to them that animates various properties of the actor. The following properties are currently supported:<\/p>\n
\n- Position \u2013 Actors current position<\/li>\n
- Depth \u2013 Actors 3D depth<\/li>\n
- Origin \u2013 Actors transform origin<\/li>\n
- Velocity \u2013 Actors current velocity<\/li>\n
- Angle \u2013 Actors current angle<\/li>\n
- AngularVelocity \u2013 Actors current angular velocity<\/li>\n
- Scale, ScaleX, ScaleY \u2013 Actors current scale<\/li>\n
- Colour \/ Color \u2013 Scenes current colour<\/li>\n
- Layer \u2013 Actors current visible layer<\/li>\n
- Visible \u2013 Actors current visible state<\/li>\n
- HitTest \u2013 Determines if the actor can be tapped<\/li>\n
- Timeline \u2013 The currently playing timeline<\/li>\n<\/ul>\n
For actors that are derived from CIwGameActorImage we have the following additional properties:<\/p>\n
\n- SrcRect \u2013 Actors currebt bitmapped visual source rectangle<\/li>\n
- Size \u2013 Actors visible size on screen<\/li>\n<\/ul>\n
Any of these properties can be set as an animation target<\/p>\n
Creating a Custom Actor<\/h2>\n
Whilst CIwGameScene can be instantiated and used as-is, CIwGameActor and CIwGameActorImage are abstract and cannot. The actor system is designed this way as the developer is meant to create their own custom actor types that provide\u00a0bespoke functionality that is specific to their game.<\/p>\n
You begin the creation of a custom actor by deriving your own actor class from either CIwGameActor or CIwGameActorImage then overloading the following methods to provide implementation:<\/p>\n
\tvirtual void\t\tInit();\r\n\tvirtual bool\t\tUpdate(float dt);\r\n\tvirtual bool\t\tUpdateVisual();\r\n\tvirtual void\t\tResolveCollisions() = 0;\r\n\tvirtual void\t\tNotifyCollision(CIwGameActor* other) = 0;<\/pre>\nHere’s a quick example:<\/p>\n
class MyActor : public CIwGameActor\r\n{\r\npublic:\r\n\tMyActor() : CIwGameActor() {}\r\n\t~MyActor() {}\r\n\r\n\tvoid\t\tInit()\r\n\t{\r\n\t\tCIwGameActor::Init();\r\n\t}\r\n\r\n\tbool\t\tUpdate(float dt)\r\n\t{\r\n\t\tif (!CIwGameActor::Update(dt))\r\n\t\t\treturn false;\r\n\r\n\t\t\/\/ Here we put our actor specific implementation<\/span>\r\n\r\n\t\treturn true;\r\n\t}\r\n\r\n\tbool\t\tUpdateVisual()\r\n\t{\r\n\t\tif (!CIwGameActor::UpdateVisual())\r\n\t\t\treturn false;\r\n\r\n\t\t\/\/ Here we put our actor specific rendering code (if any is needed)<\/span>\r\n\r\n\t\treturn true;\r\n\t}\r\n\r\n\tvoid\t\tResolveCollisions() {}\r\n\tvoid\t\tNotifyCollision(CIwGameActor* other) {}\r\n};<\/pre>\nWe have provided a very basic implementation of Init(), Update() and UpdateVisual() which call the base CIwGameActor class methods so we keep its functionality in-tact.<\/p>\n
We also provide a none functional implementation of ResolveCollisions() and NotifyCollision() as these are required methods<\/p>\n
You can take the implementation one step further by implementing both the IIwGameXomlResource and IIwGameAnimTarget interfaces to allow instantiation of your custom actor class from XOML and to allow your class to be a target for\u00a0animation time lines.<\/p>\n
Firstly lets take a look at XOML enabling your custom actor class. To get IwGame to recognise your class whilst parsing XOML files you need to do a few things:<\/p>\n
\n- Derive your class from IIwGameXomlResource and implement the LoadFromXoml method<\/li>\n
- Create a class creator that creates an instance of your class then add this to the XOML engine<\/li>\n<\/ul>\n
Lets start by taking a look at step 1.<\/p>\n
Because we have derived our class from CIwGameActor we already have the support for step 1. However we would like to insert our own custom attribute tags so we need to make a few changes.<\/p>\n
Lets take a look at our new class with thiose changes:<\/p>\n
class MyActor : public CIwGameActor\r\n{\r\npublic:\r\n\t\/\/ Properties<\/span>\r\nprotected:\r\n\tint\t\tNumberOfEyes;\r\npublic:\r\n\tvoid\t\tsetNumberOfEyes(int num_eyes)\t{ NumberOfEyes = num_eyes; }\r\n\tfloat\t\tgetNumberOfEyes() const\t\t{ return NumberOfEyes; }\r\n\t\/\/ Properties End<\/span>\r\npublic:\r\n\tMyActor() : CIwGameActor() {}\r\n\t~MyActor() {}\r\n\r\n\tvoid\t\tInit()\r\n\t{\r\n\t\tCIwGameActor::Init();\r\n\t}\r\n\r\n\tbool\t\tUpdate(float dt)\r\n\t{\r\n\t\tif (!CIwGameActor::Update(dt))\r\n\t\t\treturn false;\r\n\r\n\t\t\/\/ Here we put our actor specific implementation<\/span>\r\n\r\n\t\treturn true;\r\n\t}\r\n\r\n\tbool\t\tUpdateVisual()\r\n\t{\r\n\t\tif (!CIwGameActor::UpdateVisual())\r\n\t\t\treturn false;\r\n\r\n\t\t\/\/ Here we put our actor specific rendering code (if any is needed)<\/span>\r\n\r\n\t\treturn true;\r\n\t}\r\n\r\n\tvoid\t\tResolveCollisions() {}\r\n\tvoid\t\tNotifyCollision(CIwGameActor* other) {}\r\n\r\n\t\/\/ Implementation of IIwGameXomlResource interface\r\n\tbool\t\tLoadFromXoml(IIwGameXomlResource* parent, bool load_children, CIwGameXmlNode* node)\r\n\t{\r\n\t\tif (!CIwGameActor::LoadFromXoml(parent, load_children, node))\r\n\t\t\treturn false;\r\n\r\n\t\t\/\/ Add our own custom attribute parsing<\/span>\r\n\t\tfor (CIwGameXmlNode::_AttribIterator it = node->attribs_begin(); it != node->attribs_end(); it++)\r\n\t\t{\r\n\t\t\tunsigned int name_hash = (*it)->getName().getHash();\r\n\r\n\t\t\tif (name_hash == CIwGameString::CalculateHash(\"NumberOfEyes\"))\r\n\t\t\t{\r\n\t\t\t\tsetNumberOfEyes((*it)->GetValueAsInt());\r\n\t\t\t}\r\n\t\t}\r\n\r\n\t\treturn true;\r\n\t}\r\n};<\/pre>\nOur new class now basically supports a new NumberOfEyes attribute that we will eventually be able to set in XOML using something like:<\/p>\n
<MyActor<\/span> Name=\"AlienCritter\" Position=\"100, 100\" Size=\"100, 100\" NumberOfYes=\"3\" \/><\/pre>\nHowever, before we can do that we need to let the XOML system know about our new type of class (MyActor), so it can be instantiated when the XOML parser comes across it. To do this we need to create a XOML class creator:<\/p>\n
class MyActorCreator : public IIwGameXomlClassCreator\r\n{\r\npublic:\r\n\tMyActorCreator()\r\n\t{\r\n\t\tsetClassName(\"MyActor\");\r\n\t}\r\n\tIIwGameXomlResource* CreateInstance(IIwGameXomlResource* parent) { return new MyActor();\t}\r\n};<\/pre>\nThe creator basically defines the tag name “MyActor” and returns an instance of the MyActor class when CreateInstance() is called.<\/p>\n
To get the XOML system to recognise our new creator we need to add it to the XOML parsing system using:<\/p>\n
\t\/\/ Add custom MyActor to XOML system\r\n\tIW_GAME_XOML->addClass(new MyActorCreator());<\/pre>\nNow XOML integration is out of the way, lets take a quick look at enabling our class as an animation target.<\/p>\n
To enable a class as an animation target we derive it from IIwGameAnimTarget and implement the UpdateFromAnimation() method. Luckily we derived our MyActor class from the CIwGameActor class which already provides this functionality.<\/p>\n
Lets take a quick look at how we extend the animation update method to account for animating our NumberOfEyes variable.<\/p>\n
\tbool\tUpdateFromAnimation(CIwGameAnimInstance *animation)\r\n\t{\r\n\t\tif (CIwGameActor::UpdateFromAnimation(animation))\r\n\t\t\treturn true;\r\n\r\n\t\t\/\/ Add our own custom animating property<\/span>\r\n\t\tunsigned int element_name = animation->getTargetPropertyHash();\r\n\r\n\t\tif (element_name == CIwGameString::CalculateHash(\"NumberOfEyes\"))\r\n\t\t{\r\n\t\t\tCIwGameAnimFrameFloat* frame = (CIwGameAnimFrameFloat*)animation->getCurrentData();\r\n\t\t\tsetNumberOfEyes((int)frame->data);\r\n\t\t\treturn true;\r\n\t\t}\r\n\r\n\t\treturn false;\r\n\t}<\/pre>\nWe added the above code to our MyActor class definition. We begin by calling the base UpdateFromAnimation() method so we can keep the existing animation properties of the actor. We then add our own custom check for the NumberOfEyes\u00a0variable. If the animation property matches NumberOfEyes then we set the number of eyes to the provided interpolated value.<\/p>\n
<\/p>\n
<\/p>\n","protected":false},"excerpt":{"rendered":"
CIwGameActor Object \u2013 Sprites With Brains Introduction Whilst our title comparison suggests that actors are simply sprites with brains they have the potential to be much more. Going back to comparison in the scene introduction section, actors play a pivotal role in our scenes, each actor having its own unique role and visual appearance. Actors […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[13,43,118,44,42,181,148,3,45],"tags":[182,364],"class_list":["post-1301","post","type-post","status-publish","format-standard","hentry","category-android-app-development","category-blackberry-playbook-app-development","category-c-programming","category-game-and-app-development","category-ios-app-development","category-iwgame-engine","category-pocketeers-limited","category-programming","category-samsung-bada-development","tag-actors","tag-iwgame-engine-tutorial"],"_links":{"self":[{"href":"http:\/\/www.drmop.com\/index.php\/wp-json\/wp\/v2\/posts\/1301","targetHints":{"allow":["GET"]}}],"collection":[{"href":"http:\/\/www.drmop.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"http:\/\/www.drmop.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"http:\/\/www.drmop.com\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"http:\/\/www.drmop.com\/index.php\/wp-json\/wp\/v2\/comments?post=1301"}],"version-history":[{"count":7,"href":"http:\/\/www.drmop.com\/index.php\/wp-json\/wp\/v2\/posts\/1301\/revisions"}],"predecessor-version":[{"id":1309,"href":"http:\/\/www.drmop.com\/index.php\/wp-json\/wp\/v2\/posts\/1301\/revisions\/1309"}],"wp:attachment":[{"href":"http:\/\/www.drmop.com\/index.php\/wp-json\/wp\/v2\/media?parent=1301"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"http:\/\/www.drmop.com\/index.php\/wp-json\/wp\/v2\/categories?post=1301"},{"taxonomy":"post_tag","embeddable":true,"href":"http:\/\/www.drmop.com\/index.php\/wp-json\/wp\/v2\/tags?post=1301"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}