Character Behave Commands

Jump to: navigation, search


BEHAVE <nodeid|0> <behavior string>


Id of the node that you wish to display the behavior, 0 has a special behavior of defaulting to your currently controlled character/npc node.
<behavior string> 
1...n additional words that specify the behavior to assume, see tables below for valid behavior strings.


The Character Behavior system changes animations based on commands that are given to it. These commands are not queued, but simply activated at the time that they are received.

In other words, animations are loaded "on demand," as they are needed. This may cause a small delay the first time that they load, but works effectively when the same animation is used in multiple Areas. It is important to note though, that if an animation is not in a user's local cache, that it will start downloading if a related "spec" comes in (such as a new creature)."

Animations are handled by applying the necessary inputs via an Animation Agent script, which applies the changes to each frame of animation. The AAS determines how to select animations per channel based on its logic (the wiring), inputs, priorities, hold times, etc.

The animation mixer can play one or two animations at the same time on a given channel. When playing two, it mixes them based on the blend ramp asked for. If a third animation comes in, it is not ignored. Instead it causes a strange visual problem where the character snaps to "root pose" for a brief moment. This happens because the older of the two animations is discarded and then it is blending the previous new one with the new new one... but the previous new one wasn't at 100% yet so you get some root mixed in. Anyway, nothing is ignored.

The PlayerBehavior2 character controller responds to behave commands. These commands influence the Animation Agent, character controller settings, collision settings and more. The commands are text-based, and can be sent to a character through its Behave property. The CLI command BEHAVE can be used in the Console Window to issue behaves to specific characters by GUID, or this can be accomplished via a client-side script, or by setting the Behave property directly in the Properties panel.

Debugging Utilities

These can all be used via the BEHAVE command.

This displays debugging information on that character for what behavior commands are happening. Useful here is seeing what inputs are being set when.

debugmixer true|false

This shows details about what the animation mixer is doing, to see what animations are being selected based on the AAS and how the inputs were set. Remember that hold times and priorities come into play.


This will show you the value of all inputs in the AAS, to get a better idea of what is going wrong.


Macros are stored per-character. In this way you might use string substitution to dynamically alter the nature of behave commands submitted by scripts or animation notes. Each character can keep track of a set of string substitution macros for behave command processing. Macros are very useful because you can issue behave commands from an animation track or a script, and you may want some of the arguments to those commands to be set at a different time or unique per character.

Setting Macro values

Establish a macro like this:

 behave 0 macro MyMacro audioloop.(file extension)

This sets the macro "MyMacro" to the value of "audioloop.(file extension)". If your macro value needs spaces, use quotes like this:

 behave 0 macro MyMacro "this is a macro value with spaces"

Here two macros are set on a character:

 behave 0 macro MyMacro audioloop.(file extension)
 behave 0 macro AnotherMacro 200

Showing Macro Values

To list all macros on the character, enter the macro behave command with no additional parameters. The output will be in the console window:

 behave 0 macro
   [AnotherMacro] = [200]
   [MyMacro] = [audioloop.wav]

To see a value of a particular macro in the console window:

 behave 0 macro MyMacro
  [MyMacro] = [audioloop.wav]

Note that macro names ARE case-sensitive, so this would generate an error to spell "MyMacro" with a lowercase 'm':

 behave 0 macro Mymacro
   Macro [Mymacro] not defined.

Using a Macro

Anywhere in a behave command string, simply use the macro name preceded by a $ character. For example, if the macro AudioQueue was set to "bashsound.wav" then it could be used like this:

 behave 0 audio "bip01" $AudioQueue

This would substitute $AudioQueue with "bashsound.wav".

So what good are macros anyway?

Most behave commands are issued to characters from either HSL script or from animation notes. Let's use an example where we have a note track on a sword swing animation that issues an audio behave command to a character to do the "sword swish" sound. This would be in the swing weapon animation.

The note track might issue a behave like this: audio "righthand" "sounds/swordswish.wav"

This works well, the sword makes a swish sound whenever it plays, at the right time in the swing and at the right spot in 3D space (the "righthand" bone).

But later, the designers introduce a new weapon... say a whip. The same animation works fine for the whip weapon, except the sound is completely wrong! One way to fix this is to use a macro. First, change the animation note to issue a behave command that expects a macro: audio "righthand" $WeaponSwingSound

Next, a script will set the WeaponSwingSound macro to the approprite value based on the weapon that character is wielding. Say "swordswishl.wav" or "whipcrack.wav" as the case may be.

This example illustrates how macros can be used to provide parameterization of the behave commands.

Animation Agent

The Animation Agent Script can be manipulated by various behave commands.


The anim command overrides the Animation Agent playing sequence. It has the following format:

 behave 0 anim {channel} {sequence} [set|force|always [{priority} [[{holdtime} [seconds] [recycle]] [{align} [{looping} [{blend} [{freeze}]]]]]]]

{channnel} = name of channel (* = AnimAllBody)
{sequence} = name of sequence
{priority} = value, default 1
set = play if priority is higher than current
force = play if priority is equal to or higher than current
always = play regardless of current priority(default)
{holdtime} = (0..1) percent of animation length to hold (default 1)
seconds = hold time is specified in seconds instead of a percentage
recycle = animation will recycle at end of loop (so random elements can vary)
{align} = true | false (default false)
{looping} = true | false (default false)
{blend} = 0..1 | (default .1)
{freeze} = true | false (default false) if to freeze last playing sequence


The animpriority command sets the priority of the currently playing sequence on a given animation mixer channel:

 behave 0 animpriority AnimAllBody  0

This would set priority of the currently playing sequence on the AnimAllBody channel to 0.


The hold command causes a character to attach an instance to one of its bones with an offset position and rotation from that bone. This is typically used to "hold" a sword or place the sword "sheathed" across the back or on the hip.

 behave characterID hold InstanceID "Bone Name" positionalOffset rotationalOffset


 behave 0 hold 2312100045 "Bip01 Hand" (0,0,0) (0,45,0)


The killanim command sets the priority of the playing sequence on the <codeAnimAllBody</code> to 0. It is a short-cut for an animpriority on the special "AnimAllBody" channel being set to 0.


The input command sets an Animation Agent input to a specific value. The value must be valid for that input. Example:

 behave 0 input BaseMode Combat

This would set the Animation Agent's input named BaseMode to its value of Combat (presuming that Combat is valid value for that input, and that an input of that name exists on the current Animation Agent Script).


The following will list all inputs of the Animation Agent and their currentl values:


This can be useful for debugging.


The following will list all transitions of the Animation Agent:


This can be useful for debugging.

Behave Commands


Behave Description
audio Used to create a sound node at a particular bone of the character. Issue the audio command with no additional arguments to get a detailed listing of the options in the console window.
input {name} {value} Sets the Animation Agent Script input to a new value.
Fall Character plays their falldown animation and ends with the last frame looping. (many but not all rigs have this)
collide Character will now honor collide
nocollide Character will not honor collide
snap (boolean) Character snaps (or does not snap) to follow terrain
snaptoground (boolean) Character falling/grounding are prevented with the behavior "snaptoground false".
listen (boolean) True by default, if false incoming remote movement packets are ignored.
debugmixer (boolean) Debugging for the choices the mixer is making.
dumpinputs Displays the values currently stored in the character's inputs.
move navpoint (x,y,z) Attempts to navigate a character to a specified point, no attempt to path is made and a timeout occurs after 10 seconds.
heading face (degrees) For remote characters, movement packets will break out of this mode. For local characters, set behave to "heading face camera" to return to normal control. More performance probes in renderer.
heading fly true When using BipedDriver, the character behavior "heading fly true" now tracks along the Y axis.
heading node id It works like heading face, except it turns the character to face a node. There's a callback when the turn animation is done, but if the target node is moving it could continue to turn for a while. When this behavior is set, if the character is server-driven it automatically snaps to its target position. Non driven NPCs now have a valid facing, and are not always looking in the same direction.
fknob) ~knobName value Set the specified knob to value.
animcallbacks (boolean) Turns on the OnAnimationNote callback for animations the character does
setposition <vector> character snaps to the position and its navpoint is set there as well so it doesn't run off
visibleeverywhere [true false] Flags a character to be visible from all rooms, even if the room it is in isn't visible.


  meNode as noderef = playerutils:getmychar(me)   // Get your own character node
  meNode["Behave"] = "input BaseMode Combat"

In the next example, the server calls the client ability script telling it to play the ability for a particular character. The client ability script then verifies the actor node exists, and sets two behave commands:

actor["Behave"] = "input BaseMode Combat"        // Note that this is an HJ-only mode
actor["Behave"] = "input MoveType Swim"          // This mode is available in Clean Engine

After this, other steps could be taken such as calling the effects system to play some associated effects with the ability.

Note: In the current implementation, the effects system does not wait for the animation to begin, so if for some reason the animation fails to play, the effects will still continue.

CLI syntax:

: behave 75622220003 snap false
: behave 76622220004 input MoveType Swim

Behave 0 has a special behavior that defaults to the currently controlled character/npc.

: behave 0 input MoveType Normal

Tutorial Exercise

See also

Personal tools