Referencing a Character

You can reference a particular character by using the Item property or the Character method. In fact, you can omit both keywords and simply specify the name of the character that you wish to use. The first three statements in the following code all perform the same function. In the last three statements, I declare a variable as type Object and create an object reference to it. This provides the quickest way of all to reference the character.

Agent1.Characters.Character(“Genie”).Speak “Hello Chris.”
Agent1.Characters.Item(“Genie”).Speak “Hello Chris.”
Agent1.Characters(“Genie”).Speak “Hello Chris.”
Dim MyAgent as Object
Set MyAgent = Agent1.Characters.Character(“Genie”)
MyAgent.Speak “Hello Chris.”

Using Character Files

There are three types of character files:

• The .AAF file contains the character animation information.

• The .ACF file contains the character data.

• The .ACS file contains both the character animations and the character data.

The three types of files are optimized for different situations. The .AAF and .ACF files are designed to let users download just enough data over the Internet to perform their immediate task. You use the Character object’s Get method to retrieve the pieces of information you need. The .ACS file is designed for use on your local hard disk, when the amount of information you want to access is not a problem.

Assigning Properties to the Character Object

Table 14.5 lists the Character object’s properties. By changing the values of Height and Width, you can change the size of the character. By changing the Top and Left properties, you can change the character’s location on the screen. All four of these properties use measurements in pixels, not twips.

Table 14.5: Selected Character Object Properties

Some of these properties, such as the character’s Name, Description, and ExtraData, are set when the character is created using the Agent Character Editor. Both the Description and the ExtraData properties contain optional information that may not be available in all characters.

Setting the IdleOn property to True will let the Agent server automatically provide animations when the character hasn’t been referenced in a while. The SoundEffectsOn property controls whether or not the character’s sound effects will be played. Of the characters shipped with Microsoft Agent 1.5, only the MerlinSfx character contains sound effects, so this property won’t make much of a difference with any of the other characters. The Pitch and Speed properties reflect the options set by the user in the Microsoft Agent Properties dialog box.

Since a particular character may be controlled by multiple applications, several of the properties are available to coordinate multiple access. You can see if you have exclusive use of the character by checking the HasOtherClients. You can find out who or what last moved the character with the MoveCause property, and you can check who last changed the Visible property with the VisibilityCause property.

Using Character Object Methods

When working with Agents, most of the functions involve requests that you will pass to an individual character to perform. These functions include speaking, gesturing, playing animations, and moving around on the screen. To perform these functions, you use the methods listed in Table 14.6.

Table 14.6: Character Object Methods

Because many of the actions that a character will perform take a relatively long period of time, most of the methods issue a command to the Agent server and then return control to your program. The Agent server maintains a queue with these commands and will execute them in the order that they were submitted to the server, unless you take explicit action to change what is happening.

Displaying and Hiding Characters

Once you have used the Load method to load a character into the Characters object, you can use the Show method to display the character on the screen. Normally, the character will play a short animation rather than simply appearing on the screen. For instance, the Robby the Robot animation will begin by showing a door opening on your screen and then walking through the door, as you can see in Figure 14.9. You have the option to skip this animation and have the character appear immediately on the screen.

Figure 14.9: Robby the Robot’s Show animation

The opposite of the Show method is the Hide method. Normally, the Hide method will play a short animation rather than having the character simply vanish. However, you can specify that the character should skip this animation, which will cause the character to disappear immediately.

Moving Characters

You can move your character around the screen by using the MoveTo method. This method requires an x, y location (in pixels) to specify where you want to move the character and a value to indicate the speed at which the character should be moved. An animation will be played while the character is moving. If you specify a value of 0 for speed, the character will immediately jump to the new location without any animation.

TIP: Jump before you show: You can use the MoveTo method before you use the Show method to display the character if you set the MoveTo speed to 0. Otherwise, using the MoveTo method before the Show method will cause an error.

The animation consists of two parts: the normal animation and the return animation. The normal animation takes the character from the neutral position to the desired position. The return animation takes the character back to the neutral state.

Making Characters Point 

The GestureAt method also plays an animation. This animation is used to point at a location specified by an x, y coordinate on the screen. Figure 14.10 shows an example. The routine is smart enough to pick the appropriate animation to point in the correct direction relative to the character’s current location.

Figure 14.10: Merlin’s gesture

Playing with Your Characters  

All of the other animations are handled by the Play method. This method adds the animation to the end of the queue at the Agent server. Each animation will be played in turn, unless a Stop, StopAll, or Interrupt method is used. Table 14.7 lists some of the animations handled by the Play method.

Table 14.7: Selected Play Method Animations for Genie, Merlin, and Robby

If an animation doesn’t leave the character in a neutral state, and the next animation starts with the character in the neutral state, then the return animation associated with the last animation will be played automatically. For example, when you tell Merlin to play the Wave animation, Merlin finishes with his hand up. Then when you play the Surprised animation, the WaveReturn animation will be played automatically before the Surprised animation is started.

Making Animations Speak

The Speak method uses the text-to-speech engine to convert the string of words into audible speech. The words will also be displayed in the character’s balloon as they are spoken. In addition, this method includes a number of speech tags that can be used to modify how the speech sounds Table 14.8 lists the available speech tags and what they do.

Table 14.8: Speech Tags Used with the Speak Method

Synchronizing Characters 

If you have a program with more than one Agent, you will need a way to synchronize the various characters. Synchronization can be accomplished by using the Wait and Activate methods. Each of the methods we’ve discussed here (GestureAt, Hide, MoveTo, Play, Show, and Speak) can return a Request object. The Wait method uses the Request object and will delay one character’s action until the action of another character has been completed.

WARNING: Wait not, want not: You can’t use the Wait method on the same character that created the Request object. Doing so will cause an error.

The Activate method is also important because it allows you to make a different character input-active. Without this method, you would need to play an animation or speak some words to switch the input-active state from one character to another.

Stopping Animations

To cancel the current animation and the rest of the animations in the queue, use the Stop method. You can also use the Stop method to cancel the animation associated with a particular Request object. The StopAll method can cancel all animations or other requests by request type. The Interrupt method is used to cancel the current animation and begin processing the next animation in sequence. All of these methods are not queued and take effect immediately.

Handling Characters over the Internet

The Get method is used primarily in Internet applications where character information and animations are loaded from a web server. This method allows you to retrieve three types of information: an animation, a state date, or a wave file. The requests are sent to the Agent server, which will get the information from the specified location if needed. By using the Get method, you will only download those animations you need, thus minimizing download time.

WARNING: You can’t play what you don’t have: You must use the Get method to retrieve character information and animation information before you use it. For example, before you use the Show method, you must download the Show animation. Of course, if you are using character data from your local hard disk, this warning doesn’t apply.

© 1998 SYBEX Inc. All rights reserved.