5. Les Acteurs [WME Resource Center]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 5. Les Acteurs ======

Le chapitre qui suit couvre les acteurs en général et traite aussi des détails de la création 2D - du sprite de l'acteur. Pour ceux qui sont intéressé par les acteurs 3D un chapitre appelé “Going 2.5D” y sera dédié, alors patience, nous y arriverons aussi.

Nous avons déjà vu quelques méthodes associé aux acteurs - Nous avons vu comment charger un acteur dans le jeu ou la scene courante, nous connaissons comment faire que notre acteur marche, parle, se position dans la direction à laquelle il fait face, etc... Mais regardons, à quoi ressemble Molly. Ouvrez le fichier data\actors\molly\molly.actor et de voir immédiatement que ce n'est pas un fichier de script - C'est un fichier de définition.

Divisons le en petits morceaux et expliquons l'ensemble du fichier:

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

Normalement dans les fichiers de définition de WME les lignes commençant par ; sont commentées. Notez que dans les commentaires de script :

<code script>
(// or /* */) ne sont pas supportés dans les fichiers de définition et provoque des erreurs! 
</code>

Mais cette ligne est spéciale et elle dis à WME à quel niveau nous sommes dans la structure de dossier ou en d'autres mots où est la racine du projet. Ceci est très important plus tard dans les fichiers de scene (si vous déplacez les scènes plus profondément dans les structure de dossiers, vous devrez modifier cette valeur ou votre scène ne fonctionnera pas).

Important: Les lignes dans les fichiers de définition ne se termine pas par des point-virgules!

<code script>
ACTOR
{
</code>

Notre bloc de données définissant un acteur commence par:
<code script>
  NAME = "molly"
  CAPTION=""
  SCALABLE = TRUE
  INTERACTIVE = FALSE
  X = 400
  Y = 460
  SCRIPT="actors\molly\molly.script"

  FONT = "fonts\outline_red.font"
</code>

**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, idle, turnleft, turnright). 

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).

<code script>
  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"
  }
</code>

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 **idle**.

<code script>
  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"
  }  
</code>

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

Next two sprite sets are called **turnleft** and **turnright** 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 **turnleft**.
<code script>
  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"
  }
</code>

Last set is the **talk** animation.  
<code script>
  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"
  }
</code>

We can define more than one **talk** blocks though! If we do, WME then randomly plays the talk animations while talking which makes it more alive. In addition to that we can define a **Talk stances** which will be invoked through the special parameter in the Talk command.

If we created a special animation and name it for example **eyeroll**, we could then for a special line invoke the eyeroll. 

So let's recap - by default if we call **actor.Talk(“Hello, how is it goin? Blah blah blah”);** all animations named **talk** are randomly played. 

Full method 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,"eyroll");** which would make actor perform an eyeroll on this line.

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

<code script>
global Peter; 
global Sally;
</code>

in **game.script** use our 

<code script>
Peter = Scene.LoadActor("path_to_peter.actor file");
Sally = Scene.LoadActor("path_to_sally.actor file");

Peter.GoTo(100,100);
Sally.Talk("blahblahblah");
</code>

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.

Lastly you can override the default animations (for example run, swim or fly animation to replace "walk") and switch them using the **actor.TalkAnimName**, **actor.IdleAnimName**, **actor.WalkAnimName**, **actor.TurnLeftAnimName** and **actor.TurnRightAnimName**.

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//