NPCs

It has been suggested that this page/section be rewritten. Reason: "Missing important information"

Engine Content: This information applies to the engine and therefore to all servers.

Introduction

Non-Player Characters (NPCs) share a large part of their code with player characters (PCs). The only real exceptions are the account related and locational awareness (for client-side rendering) properties of PCs and parent definition, spawner id, and behavior related properties of NPCs. This document will focus mainly on the configuration and definition of behaviors, as that is currently the core concept for modifying an NPC.

Behavior Overview

Behaviors are what define the actions of an NPC. They are discrete chunks of logic that inhabit a priority queue. Behaviors towards the front of this queue are deemed ‘more important’ to the NPC and will be evaluated before those behaviors further down the queue. Another factor that drives decision making is the NPCs behavior state. These state values are defined in etc/behaviorStates.json. At runtime, these state values are sorted and then an int value is assigned to each one. To discover the integer value of a given state, use the State.instance().getWorld().getBehaviorState(String state) method. Individual behaviors, or in some cases outside factors, may set that state and thus change the response of a particular behavior. One final piece is the presence of certain properties in the NPC’s behavior context. The existence of this context allows different behaviors to persist and share state.

The properties within the NPC’s behavior context can be accessed using the following convenience methods on the net.lugdunon.state.character.NonPlayerCharacter class:

100. public Object getBehaviorContextVariable(String id)
101.  
102. public void setBehaviorContextVariable(String id, Object value)

BaseBehavior

All behaviors must extend the net.lugdunon.state.character.behavior.BaseBehavior class. This class embodies common code shared by all behaviors:

100. /**
101.  * The constructor used when instantiating a subclass of BaseBehavior.
102.  *
103.  * @param {NonPlayerCharacter} npc A reference to the NPC that this behavior belongs to.
104.  */
105. public BaseBehavior(NonPlayerCharacter npc)
106.  
107. /**
108.  * Called on initialization to set a parameter pulled from the definition JSON.
109.  *
110.  * @param {String} name the name or id of the parameter.
111.  * @param {Object} value the value of the parameter.
112.  */
113. public void setParameter(String name, Object value)
114.  
115. /**
116.  * Returns true if this behavior is triggered by the passed in state.
117.  *
118.  * @param state {int} The state to check
119.  *
120.  * @return true if the behavior is triggered by the state passed in, or false if it is not triggered.
121.  */
122. public boolean isTriggeredByState(int state)

Extending net.lugdunon.state.character.behavior.BaseBehavior will require implementing several abstract methods:

100. /**
101.  * Returns an array of strings that represent the state names that will cause this behavior to trigger.
102.  * This is called from the BaseBehavior(NonPlayerCharacter npc) contructor.
103.  *
104.  * @return {String[]} the array of state names that can trigger this behavior.
105.  */
106. protected abstract String[] getTriggerStates();
107.  
108. /**
109.  * Returns the display name of this behavior.
110.  *
111.  * @return {String} the name of this behavior.
112.  */
113. public abstract String getName();
114.  
115. /**
116.  * Returns the description of this behavior.
117.  *
118.  * @return {String} the description of this behavior.
119.  */
120. public abstract String getDescription();
121.  
122. /**
123.  * This method is called if isTriggeredByState(state) returns true. It passes in the
124.  * delta since the last update, and expects a state value to be returned.
125.  *
126.  * @param delta The amount of time (in milliseconds) since the last update pass.
127.  *
128.  * @return the state that the NPC is in after this behavior is handled. To find the integer
129.  * value of a given state, use the State.instance().getWorld().getBehaviorState(String state)
130.  * method.
131.  */
132. public abstract int handle(long delta);

The definition, or configuration, for a particular behavior resides in a JSONArray contained within the NPC definition. The structure of a behavior definition JSONObject is as follows:

100. {
101.     "type"  :"behaviorTypeId",
102.     "params":
103.     {
104.         "paramKey":paramValueObject
105.     }
106. }

The value of the type property is the key of the behavior mapping as defined in etc/behaviors.json, and ultimately is what resolves the implementing class for the particular behavior. The params property holds all configuration properties that are set with the setParameter(name,value) method mentioned earlier. In the following topics, we will explore the specific parameters defined for each subclass of net.lugdunon.state.character.behavior.BaseBehavior.

IdleBehavior

The net.lugdunon.state.character.behavior.core.IdleBehavior behavior is used to make an NPC ‘idle’. This is intended to be sort of a default state, where the NPC waits either for a predefined time period of for some external stimulus. Once the state is triggered by either the timer or outside influence, the NPC transitions to a new state. The states that trigger this behavior are:

• CORE.IDLE

The available configuration parameters are:

Property	Type	Description
“duration”	long	The amount of time (in milliseconds) to remain in an idle state before transitioning to “endState”.
“endState”	String	The state that is triggered at the completion if the idle state.

PathBehavior

The net.lugdunon.state.character.behavior.core.PathBehavior behavior triggers an NPC to begin pathing to a random point within a small radius (10 tiles) of either the NPC’s current location, or if the NPC is tied to a spawner, the spawner’s location.

The states that trigger this behavior are:

• CORE.WALKING

The available configuration parameters are:

Property	Type	Description
“endState”	String	The state that is triggered at the completion if the idle state. Defaults to “CORE.IDLE”.

AggroBehavior

The net.lugdunon.state.character.behavior.core.AggroBehavior behavior can trigger an NPC to attack players and other NPCs. This behavior can be triggered regardless of the current state, and is usually placed at the fore of the behavior priority queue.

The states that trigger this behavior are:

• all states can trigger

The available configuration parameters are:

Property	Type	Description
“aggroRadius”	integer	The radius (in tiles) that the NPC can aggro.
“attackNPCs”	String[]	An array of NPC defintion ids that this NPC will regard as hostile and attack on sight.
“dropRadius”	integer	If the aggro target exceeds this distance (in tiles) from the NPC, then aggro will be dropped.
“leash”	integer	If the NPC travels past this radius (in tiles) from the initial point of aggro, the NPC will drop aggro.
“provoked”	boolean	If set to true, the NPC will not aggro unless provoked (attacked).
“returnToOrigin”	boolean	If set to true, the NPC will attempt to return to the point of initial aggro.
“weaponActionIndex”	integer	The index (in the play action bar) of the item to use as a weapon.