Behavior Operations

From PSwiki
Jump to navigation Jump to search

A “Behavior” in NPCClient is a script defined in the database (see npcbehave.xml) to run to make the npc behave a certain way. It is almost like a state, for AI designers used to state machine npcs. Example behaviors might include “guard patrol”, “wander in forest”, “fight attackers”, “smith an item”. Before we talk about how everything fits together we will go over what is possible in npcclient with these detailed behavior scripts. The following is a list and reference description of each behavior script operation or command you can use. They are put together in sequences called beaviors as will be described later in Behaviors_and_Reactions.


Assess Operation

(Net load: 1, CPU Load 1)

Parameter Type Default Description
physical string The prefix for the physical perception.
magical string The prefix for the magical perception.
overall string The perfix for the overall perception.

Each of the physical, magical, or overall will be assessed as; "extremely weaker", "much weaker", "weaker", "equal", "stronger", "much stronger" or "extremely stronger".


 Ex: <assess overall="$target overall" />

Typical reaction to catch the response to this would be as shown in the example below. $target is used here to make sure the correct assessment is matched to the same target. A npc will not react if the target has changed before the response is received.

 Ex: <react event="assess equal" type="$target overall" .../>
     <react event="assess weaker" type="$target overall" .../>

Auto Memorize Operation

(Net load: 1, CPU Load 1)

Parameter Type Default Description
types string Comma separated list of types. "all", can be used to memorize everything to all.
enable bool true Enables or disables the types.

Auto memorize is a way to turn on and off memorizing of perception. This will be memorize without actually needing to react to thees. Related to the Share Memories Operation.

 Ex: <auto_memorize types="all" />
     <auto_memorize types="Hunting Ground,Marked" />
     <auto_memorize types="Marked" enable="false" />
 

You can use a reaction without a behavior lists to enable the NPC to receive perceptions to be memorized if enabled.

 Ex: <react type="location sensed" />

Build Operation

(Net load: 1, CPU Load 1)

Parameter Type Default Description
pickupable boolean false If false the building deployed will not be pickupable by the players

Build a building as specified bye the NPC's current held building spot as set by the Tribe Scripting locateBuildingSpot function.


 Ex: <build />

Busy Operation

(Net load: 1, CPU Load 1)

Parameter Type Default Description

Mark a NPC as busy. This will cancle the Idle Operation


 Ex: <busy />

Cast Operation

(Net load: 1, CPU Load 1)

Parameter Type Default Description
spell string The name of the spell to cast.
k float 1.0 The kFactor to use when casting the spell.

Cast a spell on the current selected target.

 Ex: <cast spell="Flame Strike" k="3.0" />

Change Brain Operation

(Net load: 1, CPU Load 1)

Parameter Type Default Description
brain string The name of the brain to load.
brain reload Reload the standard NPC brain stored in the sc_npc_definition table.

Change the brain of the current selected target.

 Ex: <change_brain brain="Charmed" />

Chase Operation

(Net load: 3, CPU Load 3)

Parameter Type Default Description
anim string The animation to use for the chase.
adaptiv_vel_script string A NPCClient math script used to adjust the adaptivVelocityScale. Additional variables defined for this script is "Distance" to the target of the chase and "AdaptivVelScale" that is the value used to adjust velocity. 1.1 will increase the velocity by 10%.
type nearest_actor, nearest_npc, nearest_player, owner, target nearest_* is the nearest entity of that type. target is current target.
range float 2.0 The range to search for target of the chase.
chase_range float -1 The range at where the chase should give up and issue a "<target> out of chase" perception. -1 is default to disable the max range check.
offset float 0.5 The distance to stop before the target of the chase. NPC Variables will be replaced. Expressions will be resolved. See Offset for more details.
offset_angle float 0.0 Size of the arc used to distribute the chase when approaching the target. The angle is in degrees.
offset_relative_heading bool false Make the offset relative to the target heading. NPC Variables will be replaced. See Offset for more details.
vel float,$WALK,$RUN Default is to use the velocity from the behavior. The velocity to use when chasing.
ang_vel float 0 is to use the default from the behavior.
collision string collision The name of the perception to be used when a collision perception is to be fired.
out_of_bounds string out of bounds The name of the perception to be used when a out of bounds perception is to be fired.
in_bounds string in bounds The name of the perception to be used when a in bound perception is to be fired.


Chasing a player is one example where both turning and moving at the same time are required to give a realistic effect to the behavior. We have <move> and <rotate> but this one does them together and intelligently to follow a targeted player or entity. Normally, this will be used to get npc’s to chase after players if players run away during a fight.

 Ex: <chase type="target" anim="walk" range=”2” />

In this example, the npc will play the animation called “walk” while moving and turning as appropriate to reduce his range to his most hated enemy. Of course, he is limited by his speed and if the player can run faster than he can chase, he will never catch the player. An "<target> out of chase" perception will be fired in this case.

The “type” attribute of the operation can be either “enemy” as shown here, “owner” to follow the NPC’s owner around, or “nearest” to chase after the nearest player at the time the operation was initiated. This operation will continue until interrupted by another behavior or until the distance to the target from the npc is less than the range specified. (2 is the default if no range is specified.) This operation sends DR messages whenever it turns or changes course, plus the DR messages to start the forward motion and animation, and to stop them. The CPU load is somewhat heavy because CD must be performed as the npc is chasing, since his path is not predetermined.

Circle Operation

(Net load: 3, CPU Load: 2)

Parameter Type Default Description
anim string The animation to use for the operation.
radius float Mandatory, no default value Radius to move NPC around with.
angle float 2PI The angle to move. Calculated if 0 and duration not 0.
duration float 0 The duration to move in circle. Calculated if 0.
ang_vel float The angular velocity to use when moving in the circle. Calculated if 0.


Moving the NPC around in a circle. The following example will move the npc around using the velocity defined in the behavior in one complete circle in 10 sec.

 Ex: <circle anim="walk" radius=”2” duration="10" />

Control Operation

(Net load: 3, CPU Load: 2)

Parameter Type Default Description


Take control of an player an move with the player.

 Ex: <control />

Copy_Locate Operation

(Net load: 0, CPU Load: 1)

Parameter Type Default Description
source string Mandatory, no default value The source locate to copy from.
destination float Mandatory, no default value The destination locate to copy to.


Copy one locate from source to destination. Built in function like Wander and Navigate use the Active locate.

 Ex: <locate obj="some thing" destination="SpecialPlace" />
     <copy_locate source="SpecialPlace" destination="Active" />

Debug Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description
level int Mandatory The level of debug to turn on for current NPC.
exclusive string Will set on exclusive logging for this NPC.

Turn on and of debug printouts on the server console. Used for debuging of script operations. Level 1-4 Only the biggest events, 5-9 Medium number of events, 10-15 and more is maximum output.

 Ex: <debug level=”2” />

Dequip Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description
slot string Mandatory The slot to dequip an move back into inventory.

Dequip an item held by the NPC in the given slot.

 Ex: <dequip slot="righthand" />

Drop Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description
slot string Mandatory The slot from which the item is to be dropped.

This operation allows an NPC to drop an item he has in inventory on the ground.

 Ex: <drop slot="lefthand" />

Eat Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description
resource string,tribe:wealth Mandatory The resource to reward the tribe when eating.

Simple simulation that the tribe would gain things like flesh from eating at a dead entity withing a range of 1.0. The tribe wealth resource would be read from the wealt_resource_name field in the tribes table.

 Ex: <eat resource="tribe:wealth" />
     <eat resource="Flesh" />

Emote Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description
cmd string The emote cmd to be used as defined in the emote.xml file. Including leading /.

This operation allows an NPC to do an emotion.

 Ex: <emote cmd="/greet" />

Equip Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description
item string Mandatory The name of the item to equip
slot string Mandatory The sloot to dquip the item in
count int 1 The number of items to equip. Will be forced to at least 1.

Equip one item from inventory into the given slot.

 Ex: <equip item="Sword" slot="righthand" count="1" />

Hate List Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description
delta float Add delta to hate list.
absolute float Set the hate value.
max float Hate should have a max value
min float Hate should have a min value
perception bool false Use perception instead of target to find target.

Adjust the hate list for an npc. The current target or perception target is the target entry for the adjustment.

 Ex: <hate_list delta="0.5" max="10.0" />
 Ex: <locate obj="perception" />
     <hate_list absolute="5.0" />
 
     Is equvivalent with:
 
     <hate_list perception="yes" absolute="5.0" />

Idle Operation

(Net load: 1, CPU Load 1)

Parameter Type Default Description

Mark a NPC as idle. This operation cancle the Busy operation.


 Ex: <idle />

Invisible Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description

No parameters.

This operation makes the NPC invisible through the toggle visibility command. See Visible Operation.

 Ex: <invisible />

Locate Operation

(Net load: 0, CPU Load 0)

Parameter Type Default Description
obj See table below. Mandatory The object to locate. NPC Variables will be replaced.
failure string A perception to fire if fails to locate the given obj.
static boolean false For location the search could be made static. Se description for more details.
range float -1 The maximum range to locate within. -1 represents infinite.
random boolean false If true a random return within the radius will be made. Otherwise the nearest entry will be returned.
outside_region boolean false Set this to true if the locate operation should consider entities outside region as well if a region is defined. NPC Variables will be replaced.
invisible boolean false Set this to true if the locate operation should consider invisible objects
invincible boolean false Set this to true if the locate operation should consider invincible objects.
destination string Active Set the destination NPC locate location. NPC Variables will be replaced.

Obj can be one of the following:

obj Description
<string> Locate a location. This is the default if none of the following obj types is matched.
actor Located nearest actor
building_spot Locate a building spot from the npc's building spot.
dead Nearest dead actor
entity:name:<name> Entity with given name
entity:pid:<pid> Entity with given pid
friend Nearest visible friend (NPC)
local_region Locate region in current sector.
ownbuffer Locate the own buffer.
owner Locate the owner, if this NPC is owned (Pets and stuff)
perception The location of the last received perception.
player Nearest player
point Random point
region Locate a random point within the region of the NPC.
self Locate your self
spawn Spawn location of the npc.
target Locate a target. The target will be the most hated from the NPC hate list.
tribe:home Locate the npcs tribe home place.
tribe:memory:string Locate something from the Tribes memory. See the ShareMemories and Memorize operation.
tribe:resource Locate a resource location from the memory of the tribe.
tribe:target Locate the most hated target for this tribe. The target will be the most hated from all the NPCs hate list in the tribe.
waypoint Will locate a waypoint.
waypoint:group:string Locate a waypoint from a given group
waypoint:name:string Locate a waypoint by name.

This operation is one of the more flexible and crucial operations in npc scripting. It allows the scripter to have his npc “find” a certain thing or type of thing, and remember that location for other scripting commands later such as turning, moving or attacking. The operation will store the position found in the NPCs as active postion and calcualte the neares waypoint and store that in the active_waypoint. For location it is possible to make the first search a static search. So that the first time the npc do this operation it could search for a "Baker" location. The next time the operation is used it will use the results of the first time even if there might be Bakers closer at that time.

 Ex: <locate obj="perception" />
     <locate obj="target" />
     <locate obj="furnace" range="50" />
     <locate obj="waypoint" failure="no waypoint found" />

Example 1 finds the last perception received by the current npc and sets the active target location to the location of that perception. This allows npcs who receive “Talk” perceptions to turn to face the person talking to them. It allows npcs who have a spell cast on them to turn to face the caster, and so on.

Example 2 finds the location of the currently active “enemy” of the NPC, which is the entity with the highest score on the NPC’s hate list, and sets that location as the active target location for other operations. This allows NPCs to turn to face the person they are attacking, chase attackers who are retreating, etc.

Example 3 uses predefined lists of named location types to find the closest one to the npc and sets the active target location to the coordinates specified there. This is the most subtle of the 3, and in some ways the most powerful so it deserves more discussion. Consider the following pictures:

npc_pic1.png

Here we have two blacksmith shops with similar items but different layouts. They might be side by side or they might be in entirely different cities. LocTypes specify a list of Anvil locations, or a list of Furnace locations, as marked by the stars on these pictures. When Example 3 says to locate the nearest furnace, an NPC in smithy #1 will find his furnace while the NPC in smithy #2 will find his own furnace. They will be able to share one script for moving between these points and acting like a real blacksmith in their own location, even though they are in totally different smithy shops.

This will become even more important when we implement player housing and player shops. It will be possible with the scripts we have already today for a player to build the blacksmith shop of his own design and for him to hire an npc smith to come work in that shop. The Smith NPC he hired will be able to “know” how to get around the player’s shop magically.

Something intended to be supported here but not actually implemented yet was the ability to locate named objects or entities as well, so an NPC could locate a sword someone dropped on the ground and things like this. Better integration with the entity system and perhaps integration with data from the maps themselves rather than externally generated lists of points could make this even more powerful.

The Locate Operation does NOT move the NPC.

To have the NPC move you need to have a navigate or move operation after, this can be done with subsequent

  <locate obj="something" destination="Move" />
  <navigate  />

If you want to trigger a separate behaviour you can use a perception (this is the actual version we use in PlaneShift, using the Move Behaviour)

  <locate obj="something" destination="Move" />
  <percept event="move" />


Loop Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description
iterations int 0 Number of iterations to do in this loop. No iterations attribute or a value of -1 is loop forever.

This operation allows you to loop a section of your script a certain number of times. This is mostly useful for city npcs such as smiths and tavern barkeeps. Behaviors in general will loop if not replaced by another behavior, but if you want subloops within the script, this is an easy way to do it.

Ex:

 <loop iterations="20">
   <locate obj="fire" range="10" />
   <navigate anim="walk" />
   <wait anim="stand" duration="30" />
   <locate obj="anvil" range="10" />
   <navigate anim="walk" />
   <wait anim="hammer" duration="20" />
 </loop>

In this example, the blacksmith is scripted to walk back and forth between his fire and his anvil 20 times before moving on to the next operation in his script to act like a blacksmith.

This operation does not affect the network at all and does not have CPU overhead.

Melee Operation

(Net load: 1, CPU Load: 2)

Parameter Type Default Description
seek_range float 0.0 The range to search for new targets in melee
melee_range float[0.5-3.0] 3.0 The range where melee can be done. Max 3.0 to prevent npc/server conflicts.
attack_type string default The name of a special attack defined in the 'attacks' table. If this attribute is not set an ordinary attack will be queued. NPC Variables will be replaced.
stance string normal The stance to use when attacking. NPC Variables will be replaced.
tribe boolean false When set to true the tribe hate list will be used to select target. If true and NPC not member of a tribe the NPC hate list will be used as a fall back. NPC Variables will be replaced.
outside_region boolean false Set to true to fight even outside region if a region is defined. NPC Variables will be replaced.
invisible boolean false Will melee operation fight invisible entities
invincible boolean false Will melee operation fight invincible entities.

The <melee> operation handles starting and ending fights for the NPC. It finds the most hated enemy in range and tells the server to attack him. If there is no enemy in range, it finds the nearest enemy that it does hate and prepares to chase him.

 Ex: <melee seek_range="10" melee_range="3" />

The “melee_range” attribute specifies how far away the enemies can be while still fighting without the npc needing to move. 3 meters is the maximum of how far away a player can be to hit the npc also, so in most cases this is a good value. The “seek_range” specifies how far around himself the npc should look for other enemies if none are found within the melee_range. If there are no enemies within the seek_range, the npc starts to calm down and his current behavior (making his ‘melee’ operation active) is lowered in priority. If an enemy is found within the seek_range, the NPC’s active enemy is set to this found person so the <chase type=”enemy”> operation can run after him.

This operation’s only network load is informing the server of its melee target and attack mode, and switching these occasionally as people die, etc. The CPU load is in periodically (2x per second) checking the hate list for the NPC to make sure the most hated person is being fought. If no one on the hate list is within the melee range, a more expensive operation is done to find any hated people within the seek_range, but this operation isn’t performed very often.

See the NPC hate list for further details about the hate list.

Memorize Operation

(Net load: 0, CPU Load: 0)

Tribe operation.

Parameter Type Default Description

No Parameters.

This is an operation that only will have effect for tribe members. The NPC will memorize the current perception as a private memory. See the Share Memories Operation for how to make the memories known to other members of the tribe.

 Ex: <memorize />

Move Operation

(Net load: 0, CPU Load: 5)

Parameter Type Default Description
anim string The animation to use when moving.
duration float 0.0 The duration this move should have. The default is probably no good.
vel float,$WALK,$RUN Default is to use the velocity from the behavior. The velocity to use when moving.
ang_vel float 0.0 By defining a ang_vel the movement will be much like the Circle Operation.
collision string collision The name of the perception to be used when a collision perception is to be fired.
out_of_bounds string out of bounds The name of the perception to be used when a out of bounds perception is to be fired.
in_bounds string in bounds The name of the perception to be used when a in bound perception is to be fired.

The most basic behavior operation in npcclient is <move>. It simply tells the npc to move forward at a certain speed in the direction he is currently pointing, and to play a named animation while doing so.

 Ex: <move vel="1" anim="walk" />
     <move anim="walk" vel="$WALK" out_of_bounds="move_outside_region" />

This operation has no preset end or duration, so it will go until the behavior is preempted by another higher priority behavior such as the one to turn, triggered by a collision perception. (See the next section for a more detailed explanation of how behaviors pre-empt each other and change priorities.)

This operation has low networking overhead since all it does is trigger a single Dead Reckoning (DR) update to start the forward motion. It does have CPU overhead during the entire duration of it running though, since there is no way for npcclient to know what it might hit along this path. Every 500msec this operation wakes up and checks its latest movement for collisions, generating a perception called “collision” for the behavior script to react to. Also at each 500msec checkpoint, it checks the owner NPC’s region setting (such as “sunny meadow” in the example above), and if there is a region specifed, the operation checks its current position to make sure the NPC is still “in bounds”. If the NPC has made it outside the region in the last half second, it fires a perception called “out of bounds”. It will not fire another “out of bounds” perception until an “in bounds” perception has been detected.

MovePath Operation

(Net load: 2, CPU Load: 3)

Parameter Type Default Description
path string Mandatory The name of the path to use for the movement.
anim string The name of the animation to use for this movement
direction FORWARD,REVERSE FORWARD The direction to move along the path

This operation tell the NPC to move in a predefined path. The path is a named entity in the path network. From a start waypoint to and end waypoint with any number of path points in between. The path will either be followed in the forward or reverse direction. Upon start of this the npc will be forced to the start position of the path. The following example will move the NPC the reverse path to the clock tower.

 Ex: <movepath path="Clock Tower" direction="REVERSE" />
 Ex: <behavior "Ring the Clock">
       <movepath path="Clock Tower" />
       <wait anim="Ring the Clock" />
       <movepath path="Clock Tower" direction="REVERSE" />
     </behavior>

Current implementation will extrapolate on the server and send updates to the client.

The following old description isn't quite in line with current implementation. Sure it should be possible to send the path to the client and do the math there. Suggest to include that as a option to the current implementation. With today implementation the movement could be interrupted and it will stop when finished with the path. To get the looping behavior either the behavior should be set to looping or a loop should be created.

--Start old description:

This operation is another very easy one: <movepath>. It tells the npc to set its preset path to a 3d spline specified in another file by name. Each client will take care of playing the right animations along the spline as the npc progresses. The intent of this operation was really simply for birds to be able to fly through the air as decoration rather than any gameplay reason. Aside from birds, most creatures do not follow 3d spline paths in their normal behaviors.

 Ex: <movepath path="bird1" />

This operation has no present end or duration, and will actually loop if not stopped by another behavior.

This operation has almost no network overhead, as the packed bytes of the spline are sent 1 time across the network to anyone needing to see this npc, and no other network activity happens until the <movepath> operation is interrupted.

This operation also has almost zero CPU overhead, because there is no collision detection and no bounds checking on this type of movement. The reasoning is that since predefined paths are being followed, it is up to the designer/scripter to ensure that the path goes where they want it to and does not hit anything along the way.

--End old description

MoveTo Operation

(Net load: 0, CPU Load: 3)

Parameter Type Default Description
x float 0.0 X-coordinate to move to
y float 0.0 Y-coordinate to move to
z float 0.0 Z-coordinate to move to
vel float,$WALK,$RUN Default is to use the velocity from the behavior. The velocity to use when moving.
anim string The name of the animation to use

This operation tells the npc to turn and face a certain point in 3d space, then move in a straight line to that location at a certain speed. The turn is not animated, so if you want an animated turn, you need a <rotate> op in front of this (see below). <moveto> also specifies an animation name to play while performing this move.

 Ex: <moveto x="-38" y="0" z="-169" anim="walk" />

When this operation is executed, the angle necessary to point in the right direction towards this 3d coordinate is calculated and the DR message to start the anim, start the movement and set the rotation angle so it will look correct is sent. Then the operation calculates the time it will take to traverse the distance at the specified speed and suspends itself for that length of time before waking up and completing. Thus, this operation has zero processing during these ½ second update opportunities. No CD checking is done and no bounds checking is done.

When the operation wakes up a few seconds later, the <moveto> is considered complete, and npcclient sends another DR message to stop the movement.

While this operation is very cheap, it is also not very flexible because the coordinates are in the NPCType and not in the NPC. Thus any NPC using this NPC Type with this command in it is going to have to be willing to move to this exact 3d coordinate.

Navigate Operation

(Net load: 1, CPU Load 1)

Parameter Type Default Description
anim string The animation to use in the navigation.
failure string The perception to fire if the operation fails.


The <navigate> operation is a placeholder right now and is simpler than it will be in the future. It is designed to work with <locate> and it moves the NPC in a straight line to the target location found by the <locate> operation.

 Ex: <navigate anim="walk" />

The only thing the operation specifies is the animation to play while moving. It works much like <moveto> but uses the locate target destination instead of a single fixed location. The only network overhead are the Start and Stop DR messages, and the only CPU overhead is calculating how long to sleep between starting and stopping.

For more complex movement the Wander Operation should be used that will use the path network to navigate. Though if there are no path directly to the location to where the NPC should go a combination of Wander and Navigate could be used. Like this example where wander is used to navigate using waypoints and navigate is used navigate into the exact position of the tavern.

 Ex <locate obj="tavern" static="yes" random="yes" range="800" > 
    <wander /> 
    <navigate />

NOP Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description

This is a no operation operation. It does absolutely nothing, though each behavior needs to have a set of operations, if nothing else insert this nop operation.

 Ex: <nop />

Percept Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description
event string The name of the perception event to fire. NPC Variables will be replaced.
target self,tribe,all,target self The recipient of this perception
type string (null) The perception type. NPC Variables will be replaced.
range float 0.0 If set to something greater than 0.0 this perception will only be delivered if within that range.
condition string A NPCClient math script that if set will be evaluated and any non zero return value will cause the perception event to be fired.
failed_event string The event to percept if the condition fail. NPC Variables will be replaced.
delayed float 0.0 The amount of time to delay before the perception is fired. NPC Variables will be replaced.

This operation allows an NPC to fire a custom perception to himself.

 Ex: <percept event="done wandering" />
     <percept event="need help" target="tribe" range="50" />
     <percept event="GoToSleep" condition="DiurnalNight" delayed="10" />

Pickup Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description
obj string,perception perception The object to pick up. (Only perception implemented)
count int 1 Number of objects to pick up
equip slot name of slot to equip the item in (Not implemented)

This operation allows an NPC to pickup an item he finds on the ground, and optionally equip(Not implemented) it if he can use it. Only objects that are pickable will be picked up.

 Ex: <pickup obj="perception" count="2" />
     <pickup obj="perception" equip="righthand" /> (Not Implemented)

Release Control Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description

Release the control of a player.

 Ex: <release_control />

Reproduce Operation

(Net load: 0, CPU Load: 0)

Tribe operation.

Parameter Type Default Description
type string The tribe member type for this. NPC Variables will be replaced.

The reproduce operation will spawn the target with the type given. Tribes will use this to create different types of members (See: Select statement in Tribe Scripting).

 Ex: <reproduce type="Warrior" />

To make make a copy of your self

 Ex: <locate obj="self" />
     <reproduce />

Resurrect Operation

(Net load: 0, CPU Load: 0)

Tribe operation.

Parameter Type Default Description

No Parameters.

This operation will resurrect a tribe member within the radius of tribe home.

 Ex: <resurrect />

This operation should be placed in an behavior that will be executed for dead NPCs. The reaction should as well have the when_dead flag set.

 Ex: <behavior name="Resurrect" completion_decay="200" growth="0" initial="0" when_dead="yes">
        <resurrect/>
     </behavior>
     <react event="tribe:resurrect"    behavior="Resurrect"     inactive_only="yes" when_dead="yes" />

Reward Operation

(Net load: 0, CPU Load: 0)

Tribe operation.

Parameter Type Default Description
resource string,tribe:wealth Mandatory The resource to reward to the tribe. NPC Variables will be replaced.
count int 1 The number of resource to reward.

Will reward a tribe with a resource. Using the special tribe:wealth keyword will result in a lockup in the tribe for whats the wealth resource.

 Ex: <reward resource="Gold Ore" count="2" />
     <reward resource="tribe:wealth" />

Rotate Operation

(Net load: 1, CPU Load: 0)

Parameter Type Default Description
type See table below. Mandatory The type of rotation operation to perform.
ang_vel float 0.0 Angular velocity in degree. If 0 the NPC default angular velocity will be used.
anim string The animation to use for the rotation operation
max float 0.0 For inregion and random a range can be defined.
min float 0.0 For inregion and radom a range can be defined.
value float 0.0 For absolute and relative a value to add in degrees should be given.
Type Description
inregion
random
absolute
relative
locatedest Face in the direciton of the last located position.
locaterotation Face in the direction of the last located rotation angle.
target

This operation <rotate> can be used to turn to a certain angle, to turn a relative amount, to turn a random amount or to turn to face a previously located object. This turn is animated, to give a more realistic look.

 Ex: <rotate type="random" min="90" max="270" anim="walk" vel="30" />
     <rotate type="locatedest" anim="walk" vel="90" />

The first example here is a random turn of between 90 and 270 degrees from the current heading, with an angular velocity of 30 degrees per second, while playing the “walk” animation. 30 degrees per second means that the maximum turn of 270 degrees will take the npc 9 seconds.

In the second example, we have already used our <locate> operation to find a point of interest near us, and we want to turn to point directly at it. Here a different (faster) angular velocity is specified but other angles aren’t necessary because they are implied by the current position of the NPC and the located special destination.

This operation requires a DR update to start and stop the rotation, as the only networking overhead. CPU overhead is also minimal since npcclient calculates the time required to turn the full amount and puts this script to sleep for that many msec until the turn is done, then stops it.

Script Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description
name string Mandatory The name of the script

Run a Progression Event script. Target and Actor env is set for the script at the server.

 Ex: <script name="my_script" />

Sequence Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description
name string Mandatory The name of the sequence to control
cmd start,stop,loop Mandatory The control of the sequence to issue.
count int 1 The number of times to loop the sequence.

Sequences are defined in the map file. They can be started, stopped, or played a number of time with the loop command. This allow the NPC to interact with large animation of world objects. This could be a winch that should run only when manned, a folding bridge or door that open and close etc.

 Ex: <sequence name="winch_up" cmd="start" />

Set Buffer Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description
buffer string Mandatory The name of the buffer.
value string Mandatory The value to set for the buffer.
type npc,tribe npc The type of buffer to set.

Set either a NPC or a Tribe buffer. NPC Variables $NBUFFER[Buffer] (NPC Buffer) and $TBUFFER[Buffer] (Tribe Buffer) are replaced multiple places with the value of the buffer.

 Ex: <set_buffer buffer="Building" value="Small Tent" />

Share Memories Operation

(Net load: 0, CPU Load: 0)

Tribe operation.

Parameter Type Default Description

No parameters

This operation will share all private memories of the NPC with the tribe. Private memories is created with the Memorize Operation. They can be retrived by the Locate Operation using tribe:memory:"memory name". Memories can also be crated using the Auto Memorize Operation.

 Ex: <share_memories />

Sit Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description

No parameters.

Sit tells the npc to sit down. Use standup operation to stand up again.

 Ex: <sit />

Standup Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description

No parameters.

Standup tells the npc to stand up. Use sit operation to sit down again.

 Ex: <standup />

Talk Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description
target boolean true Talk to current target
text string The string to send
public boolean true Should this talk go to everyone in range, or only the target if public=false.
type say,me,my,narrate say The type of talk.
command string A perception to send to target if it is a NPC. NPC Variables will be replaced.

If target is false, this will queue a talk command to the server from the NPC. If target is true and a target exists the same talk command will be sent to the server but a "command" perception will be sent to the target as well. The target will than be able to react to this perception.

 Ex: <talk target="true" text="Kneel in front of me." command="kneel" />
     <talk type="me" text="is angry" />
     <talk target="true" text="This message is only for you" public="false" />

Teleport Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description

Teleport the NPC to the current active location.

 Ex: <teleport />

Transfer Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description
item string,tribe:wealth Mandatory The name of the item to transfer. NPC Variables will be replaced.
target tribe Mandatory The target for this transfer.
count int
Number of items to transfer. -1 is all items.

Transfere a number of item from one NPC to the target.

 Ex: <transfer item="tribe:wealth" target="tribe" />

This example will transfer all of the tribe wealth from the NPC to the tribe.

Tribe Home Operation

(Net load: 0, CPU Load: 0)

Tribe operation.

Parameter Type Default Description

No Parameters.

Move the tribe home to the last active position of the NPC. This operation will issue a "tribe:home moved" perception to all members of the tribe.

 Ex: <tribe_home />

Tribe Type Operation

(Net load: 0, CPU Load: 0)

Tribe operation.

Parameter Type Default Description
type string Change tribe member type.

No Parameters.

Change the Tribe Member type of the current NPC to the new type.

 Ex: <tribe_type type="Queen" />

Unbuild Operation

(Net load: 0, CPU Load: 0)

Tribe operation.

Parameter Type Default Description

Unbuild a building. The building has to be targeted.

 Ex: <unbild />

Visible Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description

No Parameters.

This operation makes the NPC visible if it where invisible. See Invisible Operation.

 Ex: <visible />

Wait Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description
duration float Mandatory The duration to wait. NPC Variables will be replaced.
random float 0.0 The random duration to wait. NPC Variables will be replaced.
anim string The animation to play while waiting.

This operation makes the NPC wait a specified length of time before progressing to the next operation. It will loop an animation during this time also for you, so you can use it for crafting actions, guard monitoring, or whatever you need that is a timed animated activity.

 Ex: <wait duration="30" anim="stand" />
     <wait duration="$NBUFFER[Sit_Duration]" anim="sit" />

This example tells the NPC to play the “stand” animation and do nothing for 30 seconds. This requires a network DR message with the specified animation, and another to stop the animation when the duration is over. There is almost no CPU required because the script goes to sleep for the duration and is woken up automatically at the end.

As with any other scripted operation, this operation can be interrupted if another behavior preempts this one from completing. So if an npc is playing the above operation, and just standing there for 30 seconds, and is attacked by someone, presumably an attack behavior would become top priority and the npc would stop waiting and attack back.

This concludes the section on the detailed operations possible with npc scripting today. Now we will discuss how these operations work together to define behaviors and how behaviors interact with each other.

Wander Operation

(Net load: 2, CPU Load 1)

Parameter Type Default Description
anim string The animation to play while wandering.
vel float
random boolean false Turn on never ending random wandering.
underground boolean invalid If not set ignore underground, set true only wander underground, if set false never wander underground waypoints
underwater boolean invalid If not set ignore underwater, set true only wander underwater, if set false never wander underwater waypoints
private boolean invalid If not set ignore private, set true only wander private, if set false never wander private waypoints
public boolean invalid If not set ignore public, set true only wander public, if set false never wander public waypoints.
city boolean invalid If not set ignore city, set true only wander city, if set false never wander city waypoints.
indoor boolean invalid If not set ignore indoor, set true only wander indoor, set false never wander indoor waypoints.

Using random <move> and <rotate> operations works well for creating randomized wandering behaviors in open, outdoor spaces and scripters should be using that approach there. However, in tighter, indoor areas like the hydlaa sewers or the dungeon, a more specific type of randomness is required.

The <wander> operation makes the npc in question walk between an independently defined set of “waypoints”. Each waypoint is a 3d coordinate and a tolerance radius. The radius adds a ‘fuzzy’ factor so that multiple npcs sharing the same set of waypoints will not all walk to the exact same centimeter location. Even in tight locations, a tolerance radius of .5-1m will be a lot better than 0m. Waypoints will be created with the path system available as GM commands.

 Ex: <wander anim="walk" />

As you see, the only thing specified by the wander operation is the animation to play while wandering. The NPC starts by walking to the nearest waypoint to its current location, then follows the waypoint choices to decide where to go next. This operation will take the NPC to the current active waypoint as selected by the last Locate Operation.

Each waypoint have a set off properties. It can be marked as indoor,underground,underwater,private,public, or city. If the wander operations in specified with the indoor flag set to true only waypoints with the indoor attribute set to true will be used when wandering. Changing waypoint attributes can be done by the GM command /path (TBD, Not impemented yet, has to be done in DB for now).'

Each waypoint is connected with a path. The path has a set of properites like TELEPORT, NO_WANDER, ONEWAY.

This operation is very light on the network because it is all straight-line navigation between known, preset points. There is 1 DR update per point hit by the npc. It is also quite light on CPU power requirements because the points are known, which means no collision detection has to be done.

One tricky thing about this is that normally non-horizontal walking is accomplished on the client with collision detection with the ground/stairs. In order to get the most accurate-looking result on the client, the client DOES do collision detection on these npcs. However, npcclient does simple linear interpolation between the starting and ending y-coordinates of the 2 waypoints as an approximation. Thus the server and client will not have the identical y-coordinate in all cases. This should almost never be noticeable, though.

Watch Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description
type nearest_actor,nearest_npc,nearest_player,owner,target Mandatory The type of watch to do.
range float 0.0 The watch range. A perception will be generated when watched entity move out of range.
invisible boolean false Set to true to watch invisible entities.
invincible boolean false Set to true to watch invincible entities.
search_range float 2.0 When watching nearest, this range set the limit for how fare that entity can be.

Watch over nearby entities. The "nearest out of range","owner out of range", or "target out of range" perception will be generated when the watched entity move out of range.

 Ex: <behavior name="Watch">
       <watch type="owner" range="3.0" />
     </behavior>
     <react event="owner out of range"   behavior="follow_chase"  />

In this example the NPC will watch the owner. If the owner move out of the watch range 3.0 the "owner out of range" perception will be fired and the new follow_chase behavior will start.

Work Operation

(Net load: 0, CPU Load: 0)

Parameter Type Default Description
type dig,fish,harvest Mandatory The type of work to do
resource string,tribe:wealth Mandatory Resource to work for or by using the keyword tribe:wealth look up in the tribe to find the resource.

Order an NPC to start digging for a resource. The keyword "tribe:wealth" will cause the resource to be looked up in the wealth_resource_nic field in the tribes table if the NPC is part of a tribe.

 Ex: <work type="dig" resource="tribe:wealth" />
     <work type="dig" resource="Gold Ore" />