Difference between revisions of "NPCs"

From LugdunonWiki
Jump to: navigation, search
(Created page with "==Introduction== ==Behavior Overview== ==BaseBehavior== ==IdleBehavior== ==PathBehavior== ==AggroBehavior==")
 
 
(13 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
{{rewrite|Missing important information}}
 +
 +
{{engine}}
 +
 
==Introduction==
 
==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==
 
==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:
 +
 +
 +
<syntaxhighlight lang="java" line start="100" highlight="5" enclose="div">
 +
public Object getBehaviorContextVariable(String id)
 +
 +
public void setBehaviorContextVariable(String id, Object value)
 +
</syntaxhighlight>
  
 
==BaseBehavior==
 
==BaseBehavior==
  
 +
 +
 +
All behaviors must extend the '''''net.lugdunon.state.character.behavior.BaseBehavior''''' class. This class embodies common code shared by all behaviors:
 +
 +
 +
 +
<syntaxhighlight lang="java" line start="100" highlight="5" enclose="div">
 +
/**
 +
* The constructor used when instantiating a subclass of BaseBehavior.
 +
*
 +
* @param {NonPlayerCharacter} npc A reference to the NPC that this behavior belongs to.
 +
*/
 +
public BaseBehavior(NonPlayerCharacter npc)
 +
 +
/**
 +
* Called on initialization to set a parameter pulled from the definition JSON.
 +
*
 +
* @param {String} name the name or id of the parameter.
 +
* @param {Object} value the value of the parameter.
 +
*/
 +
public void setParameter(String name, Object value)
 +
 +
/**
 +
* Returns true if this behavior is triggered by the passed in state.
 +
*
 +
* @param state {int} The state to check
 +
*
 +
* @return true if the behavior is triggered by the state passed in, or false if it is not triggered.
 +
*/
 +
public boolean isTriggeredByState(int state)
 +
</syntaxhighlight>
 +
 +
 +
 +
Extending '''''net.lugdunon.state.character.behavior.BaseBehavior''''' will require implementing several abstract methods:
 +
 +
 +
 +
<syntaxhighlight lang="java" line start="100" highlight="5" enclose="div">
 +
/**
 +
* Returns an array of strings that represent the state names that will cause this behavior to trigger.
 +
* This is called from the BaseBehavior(NonPlayerCharacter npc) contructor.
 +
*
 +
* @return {String[]} the array of state names that can trigger this behavior.
 +
*/
 +
protected abstract String[] getTriggerStates();
 +
 +
/**
 +
* Returns the display name of this behavior.
 +
*
 +
* @return {String} the name of this behavior.
 +
*/
 +
public abstract String getName();
 +
 +
/**
 +
* Returns the description of this behavior.
 +
*
 +
* @return {String} the description of this behavior.
 +
*/
 +
public abstract String getDescription();
 +
 +
/**
 +
* This method is called if isTriggeredByState(state) returns true. It passes in the
 +
* delta since the last update, and expects a state value to be returned.
 +
*
 +
* @param delta The amount of time (in milliseconds) since the last update pass.
 +
*
 +
* @return the state that the NPC is in after this behavior is handled. To find the integer
 +
* value of a given state, use the State.instance().getWorld().getBehaviorState(String state)
 +
* method.
 +
*/
 +
public abstract int handle(long delta);
 +
</syntaxhighlight>
 +
 +
 +
 +
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:
 +
 +
 +
 +
<syntaxhighlight lang="javascript" line start="100" highlight="5" enclose="div">
 +
{
 +
    "type"  :"behaviorTypeId",
 +
    "params":
 +
    {
 +
        "paramKey":paramValueObject
 +
    }
 +
}
 +
</syntaxhighlight>
 +
 +
 +
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==
 
==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:
 +
 +
{| class="wikitable"
 +
!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==
 
==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:
 +
 +
{| class="wikitable"
 +
!Property
 +
!Type
 +
!Description
 +
 +
|-
 +
|“endState”
 +
|String
 +
|The state that is triggered at the completion if the idle state. Defaults to “CORE.IDLE”.
 +
 +
|}
  
 
==AggroBehavior==
 
==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:
 +
 +
{| class="wikitable"
 +
!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.
 +
 +
|}

Latest revision as of 15:57, 15 February 2015

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.

Contents

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:


  1. public Object getBehaviorContextVariable(String id)
  2.  
  3. 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:


  1. /**
  2.  * The constructor used when instantiating a subclass of BaseBehavior.
  3.  *
  4.  * @param {NonPlayerCharacter} npc A reference to the NPC that this behavior belongs to.
  5.  */
  6. public BaseBehavior(NonPlayerCharacter npc)
  7.  
  8. /**
  9.  * Called on initialization to set a parameter pulled from the definition JSON.
  10.  *
  11.  * @param {String} name the name or id of the parameter.
  12.  * @param {Object} value the value of the parameter.
  13.  */
  14. public void setParameter(String name, Object value)
  15.  
  16. /**
  17.  * Returns true if this behavior is triggered by the passed in state.
  18.  *
  19.  * @param state {int} The state to check
  20.  *
  21.  * @return true if the behavior is triggered by the state passed in, or false if it is not triggered.
  22.  */
  23. public boolean isTriggeredByState(int state)


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


  1. /**
  2.  * Returns an array of strings that represent the state names that will cause this behavior to trigger.
  3.  * This is called from the BaseBehavior(NonPlayerCharacter npc) contructor.
  4.  *
  5.  * @return {String[]} the array of state names that can trigger this behavior.
  6.  */
  7. protected abstract String[] getTriggerStates();
  8.  
  9. /**
  10.  * Returns the display name of this behavior.
  11.  *
  12.  * @return {String} the name of this behavior.
  13.  */
  14. public abstract String getName();
  15.  
  16. /**
  17.  * Returns the description of this behavior.
  18.  *
  19.  * @return {String} the description of this behavior.
  20.  */
  21. public abstract String getDescription();
  22.  
  23. /**
  24.  * This method is called if isTriggeredByState(state) returns true. It passes in the
  25.  * delta since the last update, and expects a state value to be returned.
  26.  *
  27.  * @param delta The amount of time (in milliseconds) since the last update pass.
  28.  *
  29.  * @return the state that the NPC is in after this behavior is handled. To find the integer
  30.  * value of a given state, use the State.instance().getWorld().getBehaviorState(String state)
  31.  * method.
  32.  */
  33. 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:


  1. {
  2.     "type"  :"behaviorTypeId",
  3.     "params":
  4.     {
  5.         "paramKey":paramValueObject
  6.     }
  7. }


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.
Retrieved from "http://wiki.lugdunon.net/w/index.php?title=NPCs&oldid=860"