5. Actors

The following chapter covers actors in general and also deals with the details of the 2D – sprite actor – creation. For those who are interested in 3D actors is then dedicated the chapter called “Going 2.5d” so have patience, we’ll get to it too.

We’ve already seen a few methods associated with actor – we’ve seen how to load actor to game or to the current scene, we know how to make our actor walk, talk, set direction he is facing etc. But let’s see, how does Molly look. Open the file data\actors\molly\molly.actor and immediately see that it’s not a script file - it’s a definition file.

Let’s split it by little chunks and explain the whole file:

; $EDITOR_PROJECT_ROOT_DIR$ ..\..\..\

Normally in the WME definition files lines starting with ; are commented out. Note that the script comments (// or /* */) are not supported in definition files and will cause an error!

But this line is special and it tells WME how deep we’re in the folder structure or in other words where is the root of the project. This is very important later on in scene files, where (if you move scenes around into deeper directory structures, you should adjust this value or your scene won’t work).

Important: Lines in definition files don’t end with a semicolon!

ACTOR 
{

Our datablock defining an actor starts.

  NAME = "molly" 
  CAPTION="" 
  SCALABLE = TRUE 
  INTERACTIVE = FALSE 
  X = 400 
  Y = 460 
  SCRIPT="actors\molly\molly.script" 
 
  FONT = "fonts\outline_red.font"

NAME is the internal name of an actor. CAPTION is the label which can be used for example in game_loop.script to display the caption in the same way as with the Nodes. SCALABLE can be true or false and defines if actor is affected by Scene scale levels or by manually scaling it through internal method. In addition we can have:

ROTATABLE = TRUE/FALSE which would make our character affected by the scene rotation levels which we’ve seen already in the Scene Edit.
INTERACTIVE means that the actor is sensitive to mouse. If you run our game now and put mouse cursor over Molly, game doesn’t react because the INTERACTIVE is set to false. If you changed this to TRUE you’d see that Molly is an interactive part of the scene as well.
X and Y are the initial coordinates of an actor on screen.
SCRIPT is a script filename which will be automatically attached to the actor upon loading. You can have multiple script lines there. FONT is the font file used for actor.Talk method we’ve used already.

And there are two more:

SOUND_PANNING = TRUE/FALSE which if set to true would automatically pan the sound from left to the right according to actor’s onscreen position.
COLORABLE = TRUE/FALSE which if set to true would make the actor affected by the decoration regions.

Now before we go on, let’s have a little bit of theory. To have a successful 2D actor in our scene, we need to define five basic sets of animations.

WALK, TALK, STAND, TURN_LEFT and TURN_RIGHT

WME documentation clearly states that: “…remember the actor is able to walk into eight directions, therefore you will need eight versions of each animation type for different directions. If you have only four directions created for your character, you can use one animation for multiple directions, but the actor definition file must always define all 8 directions. For example if you have a "character walking left" animation, you can assign it to both "walk left" and "walk up left" directions.“

But let’s look at our first animation set called WALK - note that the behavior changed in new WME (before it was SPRITESET).

ANIMATION 
{ 
  NAME       = "walk" 
   
  LEFT       = "actors\molly\ll\walk.sprite" 
  RIGHT      = "actors\molly\rr\walk.sprite" 
  UP         = "actors\molly\uu\walk.sprite" 
  DOWN       = "actors\molly\dd\walk.sprite" 

  UP_LEFT    = "actors\molly\ul\walk.sprite" 
  UP_RIGHT   = "actors\molly\ur\walk.sprite" 
  DOWN_LEFT  = "actors\molly\dl\walk.sprite" 
  DOWN_RIGHT = "actors\molly\dr\walk.sprite" 
} 

ANIMATION 
{ 
  NAME       = "idle" 
   
  LEFT       = "actors\molly\ll\stand.sprite" 
  RIGHT      = "actors\molly\rr\stand.sprite" 
  UP         = "actors\molly\uu\stand.sprite" 
  DOWN       = "actors\molly\dd\stand.sprite" 

  UP_LEFT    = "actors\molly\ul\stand.sprite" 
  UP_RIGHT   = "actors\molly\ur\stand.sprite" 
  DOWN_LEFT  = "actors\molly\dl\stand.sprite" 
  DOWN_RIGHT = "actors\molly\dr\stand.sprite" 
}   

ANIMATION 
{ 
  NAME       = "talk" 
   
  LEFT       = "actors\molly\ll\talk.sprite" 
  RIGHT      = "actors\molly\rr\talk.sprite" 
  UP         = "actors\molly\uu\talk.sprite" 
  DOWN       = "actors\molly\dd\talk.sprite" 

  UP_LEFT    = "actors\molly\ul\talk.sprite" 
  UP_RIGHT   = "actors\molly\ur\talk.sprite" 
  DOWN_LEFT  = "actors\molly\dl\talk.sprite" 
  DOWN_RIGHT = "actors\molly\dr\talk.sprite" 
} 

ANIMATION 
{ 
  NAME       = "turnleft" 
   
  LEFT       = "actors\molly\ll\turn.sprite" 
  RIGHT      = "actors\molly\rr\turn.sprite" 
  UP         = "actors\molly\uu\turn.sprite" 
  DOWN       = "actors\molly\dd\turn.sprite" 

  UP_LEFT    = "actors\molly\ul\turn.sprite" 
  UP_RIGHT   = "actors\molly\ur\turn.sprite" 
  DOWN_LEFT  = "actors\molly\dl\turn.sprite" 
  DOWN_RIGHT = "actors\molly\dr\turn.sprite" 
} 
 
ANIMATION 
{ 
  NAME       = "turnright" 
   
  LEFT       = "actors\molly\ll\turn.sprite" 
  RIGHT      = "actors\molly\rr\turn.sprite" 
  UP         = "actors\molly\uu\turn.sprite" 
  DOWN       = "actors\molly\dd\turn.sprite" 

  UP_LEFT    = "actors\molly\ul\turn.sprite" 
  UP_RIGHT   = "actors\molly\ur\turn.sprite" 
  DOWN_LEFT  = "actors\molly\dl\turn.sprite" 
  DOWN_RIGHT = "actors\molly\dr\turn.sprite" 
}   

}

WALK
{

  SPRITESET 
  { 
    LEFT       = "actors\molly\ll\walk.sprite" 
    RIGHT      = "actors\molly\rr\walk.sprite" 
    UP         = "actors\molly\uu\walk.sprite" 
    DOWN       = "actors\molly\dd\walk.sprite" 

    UP_LEFT    = "actors\molly\ul\walk.sprite" 
    UP_RIGHT   = "actors\molly\ur\walk.sprite" 
    DOWN_LEFT  = "actors\molly\dl\walk.sprite" 
    DOWN_RIGHT = "actors\molly\dr\walk.sprite" 
  } 

}
As you see you assign different sprite for each of the eight possible directions and that’s about it. There’s one special thing about walking animations though – when you construct your actor’s animation in the Sprite Edit, you have to set the “Move by” parameter for each frame as we discussed before. This will define how fast the character moves on the screen.

Next sprite set is called STAND.

STAND

{ 
  SPRITESET 
  { 
    LEFT       = "actors\molly\ll\stand.sprite" 
    RIGHT      = "actors\molly\rr\stand.sprite" 
    UP         = "actors\molly\uu\stand.sprite" 
    DOWN       = "actors\molly\dd\stand.sprite" 

    UP_LEFT    = "actors\molly\ul\stand.sprite" 
    UP_RIGHT   = "actors\molly\ur\stand.sprite" 
    DOWN_LEFT  = "actors\molly\dl\stand.sprite" 
    DOWN_RIGHT = "actors\molly\dr\stand.sprite" 
  } 
} 

There’s nothing special about standing. You can add some neat effect like breathing, shuffling feet or scratching nose.

Next two sprite sets are called TURN_LEFT and TURN_RIGHT and via them can be achieved realistic turning of actor. Default is just a flip which we know from older games. They look identical so I’ll include only TURN_LEFT.

TURN_LEFT 
{ 
  SPRITESET 
  { 
    LEFT       = "actors\molly\ll\turn.sprite" 
    RIGHT      = "actors\molly\rr\turn.sprite" 
    UP         = "actors\molly\uu\turn.sprite" 
    DOWN       = "actors\molly\dd\turn.sprite" 

    UP_LEFT    = "actors\molly\ul\turn.sprite" 
    UP_RIGHT   = "actors\molly\ur\turn.sprite" 
    DOWN_LEFT  = "actors\molly\dl\turn.sprite" 
    DOWN_RIGHT = "actors\molly\dr\turn.sprite" 
  } 
} 

Last set is the TALK animation.

TALK
{

  SPRITESET 
  { 
    LEFT       = "actors\molly\ll\talk.sprite" 
    RIGHT      = "actors\molly\rr\talk.sprite" 
    UP         = "actors\molly\uu\talk.sprite" 
    DOWN       = "actors\molly\dd\talk.sprite" 

    UP_LEFT    = "actors\molly\ul\talk.sprite" 
    UP_RIGHT   = "actors\molly\ur\talk.sprite" 
    DOWN_LEFT  = "actors\molly\dl\talk.sprite" 
    DOWN_RIGHT = "actors\molly\dr\talk.sprite" 
  } 

}

Now TALK is special, because you can have more than one Talk block. This way you can achieve something which is called Talk stances. Talk stances are animations which can be used for gestures and other poses, making your game characters more alive.

If you want to include multiple talk blocks, you have to name them in the sprite sets. Let’s look at an example.

TALK
{

  SPRITESET 
  { 
    NAME = “basic” 
    LEFT       = "actors\molly\ll\talk.sprite" 
    RIGHT      = "actors\molly\rr\talk.sprite" 
    UP         = "actors\molly\uu\talk.sprite" 
    DOWN       = "actors\molly\dd\talk.sprite" 

    UP_LEFT    = "actors\molly\ul\talk.sprite" 
    UP_RIGHT   = "actors\molly\ur\talk.sprite" 
    DOWN_LEFT  = "actors\molly\dl\talk.sprite" 
    DOWN_RIGHT = "actors\molly\dr\talk.sprite" 
  } 

}

TALK
{

  SPRITESET 
  { 
    NAME = “eyeroll” 
    LEFT       = "actors\molly\ll\talk2.sprite" 
    RIGHT      = "actors\molly\rr\talk2.sprite" 
    UP         = "actors\molly\uu\talk2.sprite" 
    DOWN       = "actors\molly\dd\talk2.sprite" 

    UP_LEFT    = "actors\molly\ul\talk2.sprite" 
    UP_RIGHT   = "actors\molly\ur\talk2.sprite" 
    DOWN_LEFT  = "actors\molly\dl\talk2.sprite" 
    DOWN_RIGHT = "actors\molly\dr\talk2.sprite" 
  } 

}

We’ve created two separate animations for talking and named them basic and eyeroll. By default if we call actor.Talk(“Hello, how is it goin? Blah blah blah”); those animations are played in random order until the talk line ends. But there is more to talk than meets the eye. You can actually supply more parameters to it! The full function prototype is:

actor.Talk(Text, SoundFilename, Duration, TalkStances, TextAlignment)

Text – is the written line. So far we always used solely this parameter.
SoundFilename – this is in a way an obsolete parameter. We’ll see why when we get to the localization chapter, because in the latest engine versions, WME automatically chooses a correct filename to play according to string tab file. So if you’re going to use voiceovers, simply put null in there.
Duration is normally not used as well. Text is automatically synchronized to speech file. You can use null again.
TalkStances – here you can specify the order and stances, which are used for the speech. If this parameter is supplied you can choose only a subset of stances.
TextAlignment – defines the alignment of the written lines.

So our modified call could look like for example:

actor.Talk(“Hello.”,null,null,”basic,eyroll”); which would be exactly the same like calling it without parameters, because WME would play those stances nonetheless. But if you have for example 6 stances defined, then it would be different story because WME would play only two instead of six.

But what should we do if we want to have a stance which should be played only very rarely? WME thinks about that as well and comes with a special block called appropriately TALK_SPECIAL. It’s the very same structure as talk, but it is never picked up by Talk unless specified in the stances parameter.

As a side note - we’ve used always only variable actor for actor interaction, but it’s only a variable. So if I wanted to break this stereotype I can easily do the following:

in base.inc declare

global Peter;
global Sally;

in game.script use our

Peter.LoadActor(“path_to_peter.actor file”);
Sally.LoadActor(“path_to_sally.actor file”);

Peter.GoTo(100,100);
Sally.Talk(“blahblahblah”);

I think you’ve got my point here. But back to animations.

You can of course create also sprites for nonstandard animations (pickup, push, pull etc.) which will be then referenced from the scripts.

So we see that it’s not hard to create a brand new 2D actor, together with animations, provided we have a corresponding graphics. And now it’s time to discover some more usable methods for actors.

actor.PlayAnim(path_to_sprite) – plays an animation as defined in sprite file and wait until the animation is finished.
actor.PlayAnimAsync(path_to_sprite) – plays an animation as defined in actor file and immediately continue.
actor.Reset() – cancel current action actor is performing (talking, walking)
actor.TurnTo(object or direction) – makes actor turn either to an object’s direction as defined in Scene Edit or to directional constant.

This book doesn’t surrogate WME documentation. There are other methods and attributes which can be used for our actors. So as I promised in the first chapter, I’ll include on closing relevant sections in WME documentation, where you can see the complete object description.

Contents→ Inside a game→ Actors - for the general description of actor
Contents → Scripting in WME → Script language reference → Actor object – for methods and attributes which can be used with the actor