Documentation › Modules › NPC.em

File: NPC.em

Functions for manipulating non-player character mobiles. All (most?) these functions are limited to use in an NPC context (meaning an AI script).

Last modified: 08/31/2015

File Constants

// Constants for texttype flags in the Say() function
const SAY_TEXTTYPE_DEFAULT := "default";
const SAY_TEXTTYPE_WHISPER := "whisper";
const SAY_TEXTTYPE_YELL := "yell";
 
// Constant for Unicode Language flag in the SayUC() function
const SAY_LANG := "ENU";
 
// Constants for doevent flag in Say() function
const SAY_DOEVENT_DISABLE := 0x0;
const SAY_DOEVENT_ENABLE := 0x1;
 
const FACE_NORMAL := 0x0;
const FACE_FORCE := 0x1;

CanMove( direction )#

Parameters

direction String, one of N, S, E, W, NW, NE, SW, SE

Explanation

Given current position and direction, would it be possible to move there?

Return values

0 on invalid parameter, or illegal move. 1 on legal move

Related

Face( direction, flags := FACE_NORMAL )#

Parameters

direction Integer (0 - 7) or String, one of N, S, E, W, NW, NE, SW, SE
flags Integer

Explanation

Sets Facing to given direction. If FACE_FORCE is set frozen/paralysed is not checked.
const FACE_NORMAL := 0x0;
const FACE_FORCE := 0x1;

Return values

0 on invalid parameter, illegal direction, or failed to face. New direction on success.

Related

GetProperty( propertyname )#

Parameters

propertyname String

Explanation

Deprecated. Equivalent to GetObjProperty( Self(), propertyname )

Return values

An unpacked object. See GetObjProperty in UO.EM

Errors

  • "Property not found"
  • "Invalid parameter type"

Related

IsLegalMove( move, boundingbox )#

Parameters

move String, one of N, S, E, W, NW, NE, SW, SE
boundingbox Bounding box, from CreateBoundingBox

Explanation

Given your position, and a tentative move, would it fall within a bounding box. This function ignores facing. It checks explicity for moving in a given direction, regardless of facing.

Return values

0 on invalid parameter, or illegal move. 1 on legal move

Related

MakeBoundingBox( areastring )#

Parameters

areastring String, see explanation

Explanation

Make a bounding box from an area string. An area string is a number of 'x1 y1 x2 y2' world coordinate entries.
"1 1 4 4 2 5 3 7" would create a walk area something like this:
   XXXX
   XXXXXXX
   XXXXXXX
   XXXX
Used with Move() and IsLegalMove() functions

Return values

boundingbox on success, empty string on invalid param (ick). Careful, not much error checking!

Move( direction )#

Parameters

direction Direction String, Facing Integer, or Bounding Box

Explanation

A Direction String is one of: N, S, E, W, NW, NE, SW, SE
A Facing Integer is 0 through 7 where 0 is North, 1 is NorthEast, etc.
See MakeBoundingBox for info on the bounding box.

Return values

Boolean for move success, or Direction String if bounding box was used

Errors

  • none, returns 0 on failures

Related

RunAwayFrom( object )#

Parameters

object UObject

Explanation

Runs away from object one tile. Puts the script to sleep for a period of time proportional to the NPC's run_speed (or dexterity if not defined).
Note also, walking in range of your opponent may cause you to attack.
See the NPC members run_speed and use_adjustments. If use_adjustments is 1 the NPC will adjust the direction of the move to attempt to avoid small obsticles. Also, this function will always return true as a result. If it is 0, the NPC will not attempt to adjust the move, and the function will return false.
The success of this function is affected by the NPC's anchor point. See SetAnchor().
In the future, this function will activate a pathfinding system.
servspecopt.cfg NpcMinimumMovementDelay setting controls the maximum speed of NPC.

Return values

Boolean for move success

Errors

  • "Invalid parameter type"
  • "Mobile specified cannot be seen" if object is a character and invisible

Related

Related config

RunAwayFromLocation( x, y )#

Parameters

x Integer World Coordinate
y Integer World Coordinate

Explanation

Runs away from the given coordinates one tile. Puts the script to sleep for a period of time proportional to the NPC's run_speed (or dexterity if not defined).
Note also, walking in range of your opponent may cause you to attack.
See the NPC members run_speed and use_adjustments. If use_adjustments is 1 the NPC will adjust the direction of the move to attempt to avoid small obsticles. Also, this function will always return true as a result. If it is 0, the NPC will not attempt to adjust the move, and the function will return false.
The success of this function is affected by the NPC's anchor point. See SetAnchor().
In the future, this function will activate a pathfinding system.
servspecopt.cfg NpcMinimumMovementDelay setting controls the maximum speed of NPC.

Return values

Boolean for move success

Errors

  • "Invalid parameter type"
  • "Invalid Coordinates for Realm"

Related

Related config

RunToward( object )#

Parameters

object UObject

Explanation

Runs toward object one tile. Puts the script to sleep for a period of time proportional to the NPC's run_speed (or dexterity if not defined).
Note also, walking in range of your opponent may cause you to attack.
See the NPC members run_speed and use_adjustments. If use_adjustments is 1 the NPC will adjust the direction of the move to attempt to avoid small obsticles. Also, this function will always return true as a result. If it is 0, the NPC will not attempt to adjust the move, and the function will return false.
The success of this function is affected by the NPC's anchor point. See SetAnchor().
In the future, this function will activate a pathfinding system.
servspecopt.cfg NpcMinimumMovementDelay setting controls the maximum speed of NPC.

Return values

Boolean for move success

Errors

  • "Invalid parameter type"
  • "Mobile specified cannot be seen" if object is a character and invisible

Related

Related config

RunTowardLocation( x, y )#

Parameters

x Integer World Coordinate
y Integer World Coordinate

Explanation

Runs toward the given coordinates one tile. Puts the script to sleep for a period of time proportional to the NPC's run_speed (or dexterity if not defined).
Note also, walking in range of your opponent may cause you to attack.
See the NPC members run_speed and use_adjustments. If use_adjustments is 1 the NPC will adjust the direction of the move to attempt to avoid small obsticles. Also, this function will always return true as a result. If it is 0, the NPC will not attempt to adjust the move, and the function will return false.
The success of this function is affected by the NPC's anchor point. See SetAnchor().
In the future, this function will activate a pathfinding system.
servspecopt.cfg NpcMinimumMovementDelay setting controls the maximum speed of NPC.

Return values

Boolean for move success

Errors

  • "Invalid parameter type"
  • "Invalid Coordinates for Realm"

Related

Related config

Say( text, text_type:=SAY_TEXTTYPE_DEFAULT, do_event:=SAY_DOEVENT_DISABLE )#

Parameters

text String
text_type Integer
do_event Integer

Explanation

Makes the NPC print text above its head. Uses the NPC member speech_font and speech_color.
If do_event is enabled with SAY_DOEVENT_ENABLE, it will send a speech event to nearby npcs.
Note npc.em constant for this function:
// Constants for texttype flags in the Say() function
const SAY_TEXTTYPE_DEFAULT := "default";
const SAY_TEXTTYPE_WHISPER := "whisper";
const SAY_TEXTTYPE_YELL := "yell";

// Constants for doevent flag in Say() function
const SAY_DOEVENT_DISABLE := 0x0;
const SAY_DOEVENT_ENABLE := 0x1;

Return values

0

Errors

  • "NPC is squelched"
  • "texttype string param must be either 'default', 'whisper', or 'yell'"

Related

SayUC( uc_text, text_type:=SAY_TEXTTYPE_DEFAULT, langcode:=SAY_LANG, do_event:=SAY_DOEVENT_DISABLE )#

Parameters

uc_text Array of 2-byte integers, where each integer is a Unicode character
text_type Integer
langcode 3-character 'Originating Language' string code e.g. ENU, CHT, DEU, RUS, KOR, etc.
do_event Integer

Explanation

Makes the NPC print text above its head. Uses the NPC member speech_font and speech_color.
If do_event is enabled with SAY_DOEVENT_ENABLE, it will send a speech event to nearby npcs.
uc_text MUST be an array of integers representing unicode characters.
Integers must be "Big Endian" (0x1234) and not "Little Endian" (0x3412).
Integers will be clipped internally to 2-bytes (value masked with 0xFFFF)
The Array must be terminated with zero. (0x0000)

Return values

0

Errors

  • "A parameter was invalid"
  • "NPC is squelched"
  • "texttype string param must be either 'default', 'whisper', or 'yell'"
  • "Unicode array exceeds maximum size."
  • "langcode must be a 3-character code."
  • "Invalid value in Unicode array."

Related

Self()#

Explanation

return a mobileref to self

Return values

A Character Reference to this NPC

Related

SetAnchor( centerx, centery, distance_start, percent_subtract )#

Parameters

centerx Integer world coordinate
centery Integer world coordinate
distance_start Integer
percent_subtract Integer

Explanation

Sets the NPC's 'anchor' point. The NPC will have difficulty moving far away from this coordinate, and will generally stay near it.
centerx and centery define the anchor point.
distance_start is the distance away from the anchor point at which the npc may not be able to move beyond. Under this distance there is a 100% chance the move will succeed. If 0, it disables the anchor point.
percent_subtract is how much to subtract from the normal 100% chance for each move beyond the distance_start boundary. So if this value is "20", the first move beyond the distance_start range (and away from the anchor point) will only have an 80% chance of succeeding. The next one will have a 60% chance. So the NPC will tend to move back toward its anchor point.
The anchor point has no effect as long as the NPC is in war mode.

Return values

1 on success

Errors

  • "Invalid parameter type"
  • "Invalid Coordinates for Realm"

Related

SetOpponent( character )#

Parameters

character CharacterRef

Explanation

Set your opponent. If you are in range (or are carrying a projectile weapon and have LOS), you will attack. If a player character is connected, the NPC will highlight.
Implicitly sets war mode.
pass 0 to clear the opponent.

Return values

0 on invalid param or clear, 1 on successful set

Related

SetProperty( propertyname, propertyvalue )#

Parameters

propertyname String
propertyvalue Packable script object (int, string, array, etc)

Explanation

Deprecated. Equivalent to SetObjProperty( Self(), propertyname, propertyvalue )

Return values

1. See SetObjProperty in UO.EM

Errors

  • "Invalid parameter type"

Related

SetWarMode( warmode )#

Parameters

warmode Integer 1/0

Explanation

Usually used to leave warmode, but can be used to enter warmode independently of setting an opponent.
Setting war mode to 0 clears your opponent.

Return values

1 on success, 0 on invalid param or clear

Related

TurnAwayFrom( object, flags := FACE_NORMAL )#

Parameters

object UObject
flags Integer

Explanation

Adjust facing to turn away from object. Puts the script to sleep for a period of time proportional to the NPC's run_speed (or dexterity if not defined).
See Face() for flags explanation
const FACE_NORMAL := 0x0;
const FACE_FORCE := 0x1;

Return values

Boolean for move success

Errors

  • "Invalid parameter type"
  • "Mobile specified cannot be seen" if object is a character and invisible

Related

Related config

TurnAwayFromLocation( x, y, flags := FACE_NORMAL )#

Parameters

x Integer World Coordinate
y Integer World Coordinate
flags Integer

Explanation

Adjust facing to turn away from given coordinates one tile. Puts the script to sleep for a period of time proportional to the NPC's run_speed (or dexterity if not defined).
See Face() for flags explanation
const FACE_NORMAL := 0x0;
const FACE_FORCE := 0x1;

Return values

Boolean for move success

Errors

  • "Invalid parameter type"
  • "Invalid Coordinates for Realm"

Related

TurnToward( object, flags := FACE_NORMAL )#

Parameters

object UObject
flags Integer

Explanation

Adjust facing to turn toward object. Puts the script to sleep for a period of time proportional to the NPC's run_speed (or dexterity if not defined).
See Face() for flags explanation
const FACE_NORMAL := 0x0;
const FACE_FORCE := 0x1;

Return values

Boolean for move success

Errors

  • "Invalid parameter type"
  • "Mobile specified cannot be seen" if object is a character and invisible

Related

Related config

TurnTowardLocation( x, y, flags := FACE_NORMAL )#

Parameters

x Integer World Coordinate
y Integer World Coordinate
flags Integer

Explanation

Adjust facing to turn toward given coordinates one tile. Puts the script to sleep for a period of time proportional to the NPC's run_speed (or dexterity if not defined).
See Face() for flags explanation
const FACE_NORMAL := 0x0;
const FACE_FORCE := 0x1;

Return values

Boolean for move success

Errors

  • "Invalid parameter type"
  • "Invalid Coordinates for Realm"

Related

WalkAwayFrom( object )#

Parameters

object UObject

Explanation

Walk away from object one tile. Puts the script to sleep for a period of time proportional to the NPC's run_speed (or dexterity if not defined).
Note also, walking in range of your opponent may cause you to attack.
See the NPC members run_speed and use_adjustments. If use_adjustments is 1 the NPC will adjust the direction of the move to attempt to avoid small obsticles. Also, this function will always return true as a result. If it is 0, the NPC will not attempt to adjust the move, and the function will return false.
The success of this function is affected by the NPC's anchor point. See SetAnchor().
In the future, this function will activate a pathfinding system.
servspecopt.cfg NpcMinimumMovementDelay setting controls the maximum speed of NPC.

Return values

Boolean for move success

Errors

  • "Invalid parameter type"
  • "Mobile specified cannot be seen" if object is a character and invisible

Related

Related config

WalkAwayFromLocation( x, y )#

Parameters

x Integer World Coordinate
y Integer World Coordinate

Explanation

Walk away from the given coordinates one tile. Puts the script to sleep for a period of time proportional to the NPC's run_speed (or dexterity if not defined).
Note also, walking in range of your opponent may cause you to attack.
See the NPC members run_speed and use_adjustments. If use_adjustments is 1 the NPC will adjust the direction of the move to attempt to avoid small obsticles. Also, this function will always return true as a result. If it is 0, the NPC will not attempt to adjust the move, and the function will return false.
The success of this function is affected by the NPC's anchor point. See SetAnchor().
In the future, this function will activate a pathfinding system.
servspecopt.cfg NpcMinimumMovementDelay setting controls the maximum speed of NPC.

Return values

Boolean for move success

Errors

  • "Invalid parameter type"
  • "Invalid Coordinates for Realm"

Related

Related config

WalkToward( object )#

Parameters

object UObject

Explanation

Walk toward object one tile. Puts the script to sleep for a period of time proportional to the NPC's run_speed (or dexterity if not defined).
Note also, walking in range of your opponent may cause you to attack.
See the NPC members run_speed and use_adjustments. If use_adjustments is 1 the NPC will adjust the direction of the move to attempt to avoid small obsticles. Also, this function will always return true as a result. If it is 0, the NPC will not attempt to adjust the move, and the function will return false.
The success of this function is affected by the NPC's anchor point. See SetAnchor().
In the future, this function will activate a pathfinding system.
servspecopt.cfg NpcMinimumMovementDelay setting controls the maximum speed of NPC.

Return values

Boolean for move success

Errors

  • "Invalid parameter type"
  • "Mobile specified cannot be seen" if object is a character and invisible

Related

Related config

WalkTowardLocation( x, y )#

Parameters

x Integer World Coordinate
y Integer World Coordinate

Explanation

Walk toward the given coordinates one tile. Puts the script to sleep for a period of time proportional to the NPC's run_speed (or dexterity if not defined).
Note also, walking in range of your opponent may cause you to attack.
See the NPC members run_speed and use_adjustments. If use_adjustments is 1 the NPC will adjust the direction of the move to attempt to avoid small obsticles. Also, this function will always return true as a result. If it is 0, the NPC will not attempt to adjust the move, and the function will return false.
The success of this function is affected by the NPC's anchor point. See SetAnchor().
In the future, this function will activate a pathfinding system.
servspecopt.cfg NpcMinimumMovementDelay setting controls the maximum speed of NPC.

Return values

Boolean for move success

Errors

  • "Invalid parameter type"
  • "Invalid Coordinates for Realm"

Related

Related config

Wander()#

Explanation

walk, usually forward, sometimes turning

Return values

1 if the move succeeded, 0 if it failed

Related