The Entity class (entity.cpp) is the C++ container that brings together whatever components are in use for a particular entity. It is derived from Python object and intercepts certain accesses, and passes those it does not understand on to the user script. This allows scripts to call C++ functions on themselves (and other entities) transparently, using the 'self' reference. The same technique of integration has been used in the cell and base components of the server.

This class handles any housekeeping or glue required by the component classes — it is the public face of an entity as far as other C++ modules are concerned.

The data members of this class include id, type, and position.

This is the instance of the user-supplied script class. The type of the entity selects the class. It stores type-specific data defined in the XML description of the entity type, as well as any other internally used data that the script wishes to store.

When field data is sent from the server, this class has its fields automatically updated (and it is notified of the change). When messages are received from the server (or another script on the client), the message handlers are called automatically. The entity class performs this automation — it appears to be automatic from the script's point of view.

A model is BigWorld's term for a mesh, plus the animations and actions used on it.

The model management component allows an entity to manage the models that are drawn and animated at its position. Models can be attached to each other at well-defined attachment points (hard points), or they can exist independently. A model is not automatically added to the scene when it is loaded — it must be explicitly put in it.

An entity may use any number of independent (disconnected) models, but most will use zero or one. Those that use more require special filters to behave sensibly. For details, see Filters.

The best way to understand models is t`o be acquainted to their Python interface, which is described in the Client Python API's entry Main → Client → BigWorld → Classes → PyModel. For more details, see Models.

Filters take time-stamped position updates and interpolate them to produce the position for an entity at an arbitrary time.

BigWorld provides only the Filter base class. The game developer would derive game-specific filters from this. Each entity can then select one type of filter for itself from the variations available. It can dynamically change its filter if it so desires.

Whenever a movement update comes from the server, it is handed over to the selected filter, along with the time that the (existing) game time reconstruction logic calculated for that event.

The filter can also be provided with gaps in time and transform, i.e., 'at game-time x there was a forward movement of y metres and a rotation of z radians lasting t seconds'. The filter (if it is smart enough) can then incorporate this into its interpolation.

The filter can also execute script callbacks at a given time in the stream.

Filters are fully accessible from Python.

BigWorld provides access to some navigation methods by the client scripts. BigWorld.navigatePathPoints() will return a list of points along the path between the given source and destination points, and BigWorld.findRandomNeighbourPoint() and the related BigWorld.findRandomNeighbourPointWithRange() will return a random point in a connected navmesh, which will be navigable from the given point.

These methods are provided for the client in order to allow some processing to be moved away from the server, and to allow movement to be more responsive, removing the need to wait for the server to provide a path.

For more details about navigation in BigWorld, refer to the Server Programming Guide's section Navigation System.

<clientNavigation>
    <enable>  true  </enable>
</clientNavigation>

navigatePathPoints( src, dst, maxSearchDistance, girth )

BigWorld.navigatePathPoints( (100, 10, 200), (150, 20, 50), 300, 4 )

[(100,10,200), (121,3,148), (133,9,87), (144,8,61), (150,20,50)]

findRandomNeighbourPoint( position, radius, girth )

BigWorld.findRandomNeighbourPoint( (100, 10, 200), 300, 0.5 )

findRandomNeighbourPoint( position, minRadius, maxRadius, girth )

BigWorld.findRandomNeighbourPoint( (150, 20, 50), 200, 400, 4 )

The action queue is the structure within the BigWorld Technology framework that controls the queue of actions in effect on a model (actions are wrapped by ActionQueuer objects that are contained by the action queue).

The ActionQueue deals with the combining of layers and also applying the appropriate blend in and blend out times.

The ActionQueue also deals with any scripted callback functions that are linked to the playing of an action, like for example calling sound-playing callbacks at particular frames in an action.

An action is described in XML as illustrated the example .model file below (model files are located in any of the various sub-folders under the resource tree <res> , such as for example, <res>/environments, <res>/flora, <res>/sets/vehicles, etc...):

<action>
   <name>          ACTION_NAME     </name>
  ?<animation>     ANIMATION_NAME  </animation>
  ?<blendInTime>   float           </blendInTime>
  ?<blendOutTime>  float           </blendOutTime>
  ?<filler>        [true|false]    </filler>
  ?<track>         int             </track>
  ?<isMovement>    [true|false]    </isMovement>
  ?<isCoordinated> [true|false]    </isCoordinated>
  ?<isImpacting>   [true|false]    </isImpacting>
  ?<match>
    ?<trigger>
      ?<minEntitySpeed> float  </minEntitySpeed>
      ?<maxEntitySpeed> float  </maxEntitySpeed>
      ?<minEntityAux1>  float  </minEntityAux1>
      ?<maxEntityAux1>  float  </maxEntityAux1>
      ?<minModelYaw>    float  </minModelYaw>
      ?<maxModelYaw>    float  </maxModelYaw>Coor
      ?<capsOn>  capabilities  </capsOn>
      ?<capsOff> capabilities  </capsOff>
     </trigger>
    ?<cancel>
      ?<minEntitySpeed> float  </minEntitySpeed>
      ?<maxEntitySpeed> float  </maxEntitySpeed>
      ?<minEntityAux1>  float  </minEntityAux1>
      ?<maxEntityAux1>  float  </maxEntityAux1>
      ?<minModelYaw>    float  </minModelYaw>
      ?<maxModelYaw>    float  </maxModelYaw>Coor
      ?<capsOn>  capabilities  </capsOn>
      ?<capsOff> capabilities  </capsOff>
     </cancel>
    ?<scalePlaybackSpeed>  [true|false] </scalePlaybackSpeed>
    ?<feetFollowDirection> [true|false] </feetFollowDirection>
    ?<oneShot>             [true|false] </oneShot>En
    ?<promoteMotion>       [true|false] </promoteMotion>
   </match>
</action>

Example .model file describing action

The list below describes some of the tags in the XML file:

The Python interface to a model's action queue allows actions to be played directly on that model, or a set of actions to be queued and played in sequence. Callback functions can be defined and played when actions are finished.

In Python, a model can be easily created and an action played on it, as illustrated in the example below:

class Jogger( BigWorld.Entity ):
  ....
def __init__( self ):
  self.model = BigWorld.Model( "jogger.model" )

def warmUp( self ):
  self.model.action( "StretchLegs" )()
...

Model creation in Python

9.1.6.1. Debugging animations

If a model is not being animated as it is supposed to, it is useful to display the Action Queue graph in the Python console.

This is can be done by calling BigWorld.debugAQ() method, which can receive two kinds of arguments:

• PyModel

  Displays the graph for the specified model, with the blend weight of each action. Each action is represented in a different, arbitrarily chosen, colour.

• None

  Switches off the graph display.

Python console displaying Action Queue's debugging graph

The graph in the picture above displays the execution on the TurnLeft animation (in green) and the Idle one (in red). We can determine the animations that were being played in each labelled point in the graph:

• A — 100% of the Idle animation is being played.

• Between A and B — Idle animation is being blended in with TurnLeft animation.

• B — 50% of the Idle animation is being played, and 50% of the TurnLeft animation is being played.

• C — 100% of the TurnLeft animation is being played.

For more details, see the Client Python API.

Note

Model Editor offers the same functionality for the model. For details, see the document Content Tools Reference Guide's section Model Editor → Panel summary → Actions panel.

Given a model, an action queue, and a set of actions, all behaviour of a game object/character can be specified by event-driven calls on the Action Queuer. This ends up with a heavy overhead, as many changes in object state need to directly call the object and solve which animation should be played.

The solution to this problem is to internalise most of the behaviour of a character in a system called the Action Matcher, which automatically updates an object's motion based on the object's state. It is a simple pattern matcher, picking an animation based on model's attributes such as speed, direction, etc.

State parameters such as speed, rotation, or power are exposed to the Action Matcher, which then selects the action that best maps to these parameters. This frees the game from having to handle many aspects of animation, allowing it to only have to update state parameters, such as position.

When there are no (unblended) actions in the Action Queue for a model (within the player's AoI), the Action Matcher takes over and plays an 'idle' action. It triggers these 'idle' animations to give the game world more life, since real living things are not still. It can also be used to automate menial animation tasks.

This class looks at all the actions that have a match section (see XML example in section Action Queue, whose constraints are satisfied for the Action Matcher object controlling the model.

Scriptable constraints are tested against the capabilities bit fields capsOn and capsOff. The Action Matcher for a model has a set of capability bits, which value is controlled by script. An action will only be matched if all the capsOn bits are on and all the capsOff bits are off in the Action Matcher's set.

It then looks at the change in pose (position and orientation — as set by the filter) and selects the first action that matches this change for the time over which the change occurred. The trigger constraints are used to test most actions. The cancel constraints are used if the action that matched last frame is encountered. This feature is intended primarily to reduce action hysteresis.

The update function of an action-matched object takes the previous updated position of the object, chooses the best matched action from its matched action list, then plays the animation back at the correct speed to smoothly link action with speed. As a game character starts moving faster, the Action Matcher may choose a faster running cycle to play back and increase its playback speed to precisely match speed so no foot sliding is seen.

This method allows an AI system to define behaviour with respect to a few variables such as orientation, speed, and aiming direction, and the Action Matcher will convert these updated parameters into a smoothly moving character.

In a client/server architecture where position and orientation are updated over a network, the Action Matcher (combined with a filter) can automatically compensate for position jumps caused by network lag by having characters realistically run faster to the latest updated position.

When an action is loaded, its data is augmented with the effect on pose that performing the action would have on the root node. This information is used for the matching described above.

Now that an action has been selected, it is passed to the Action Queue. If the action supplied is the same as the previous action, it continues to be played in the normal fashion (i.e., frame += fps*deltaTime). Otherwise, it is blended in over a few frames while the other is blended out.

class AngryMan( BigWorld.Entity ):
  ....
def onEnterWorld( self, prereqs ):
  self.am = BigWorld.ActionMatcher( self )

def enterAngryMode( self ):
  self.am.matchCaps = self.am.matchCaps + [1]
...

A tracker applies inverse kinematics to nodes in the entity's model so that they appear to point to a position defined by a given 'target' entity. An entity may have any number of trackers.

To add a tracker to an entity, use a script call like this:

tracker = BigWorld.Tracker()
tracker.dirProvider = DiffDirProvider( 
  self.focalMatrix, target.focalMatrix )
tracker.nodeInfo = BigWorld.TrackerNodeInfo(
  model,
  primaryNode, 
  secondaryNodeList, 
  pointingNodeName,
  minPitch, maxPitch,
  minYaw, maxYaw,
  angularVelocity )
self.model.tracker = tracker

Adding tracker in Python

The parameters for the BigWorld.TrackerNodeInfo method are described below:

These are generic helper services provided to entity scripts.

A script can set timers to have itself called-back at a certain time, as illustrated in the example below:

BigWorld.callback( afterTime, fn )

Traps use a slightly different interface:

trapRef = self.addTrap( radius, function )

A trap goes off if any entity wanders within the given radius of the entity it is created on, and can be cancelled with the self.delTrap method.

There are two other types of trap, optimised for their specific need, as discussed in the following sections.

potHandle = BigWorld.addPot( trapMatrix, radius, callback )

matHandle = BigWorld.addMat( sourceMatrix, callback, destMatrix )

The callback has the following syntax:

init(scriptsConfig, engineConfig, preferences, loadingScreenGUI = None)

The script is called once, when the engine initialises, and receives the arguments below:

The available read functions are listed below:

To read data from PyDataSection, call the read function that relates to the data type, passing in the section name as the first argument, and the default value as the second argument. The plural read functions (ending in 's') read the contents of all matching subsections of the specified section, and return the results as tuple of values. You can refer to sub-sections by using the forward slash.

For example:

username = userPreferences.readString("login/username", "guest")

You can also reference to subsections of a PyDataSection by calling the section name prefixed with an underscore.

For example:

username = userPreferences._login._username.asString

The callback has the following syntax:

fini()

This is script is called when the client engine shuts down. It is used to do any cleanup required before the client exits. This is a good place to perform a logout procedure on the player to logout gracefully.

For example:

# note: you must set up a logOff method as a base method in the
# def file of the class that the player is using.
def fini():
  try:
    BigWorld.player().base.logOff()
  except:
    pass

Example of fini() implementation

The callback has the following syntax:

handleKeyEvent( event )

The event argument is a PyKeyEvent which contains information about the key event. See the Python Client API document for details.

Generally, several systems can process keyboard input, so the arguments are passed to a handleKeyEvent method on each system in turn, until one returns a Boolean value of True, indicating that it has processed the key event.

For example:

def handleKeyEvent( event ):
  global rds

  # give the chat console a go first
  if rds.chat.editing:
    if rds.chat.handleKeyEvent( event ):
      return True
  # try the gui
  if GUI.handleKeyEvent( event ):
    return 1
  # now do our custom keys
  if not event.isKeyDown(): return False # we are not interested in key releases
  if event.key == KEY_RETURN and event.modifiers == 0:
    rds.chat.edit( True )  # bring up the chat console
    return True

  # return False because the key event has not been handled
  return False

Example of handleKeyEvent() implementation

Note that the engine also calls the handleKeyEvent method on the entity that the player is controlling. All keys related to player control are handled there.

The callback has the following syntax:

handleMouseEvent( event )

This script is called whenever the mouse moves, and is given an instance of PyMouseEvent. It operates similarly to handleKeyEvent.

For example:

def handleMouseEvent( event ):

  # try the gui
  if GUI.handleMouseEvent( event ):
    return True

  # return False because the mouse event has not been handled
  return False

Example of handleMouseEvent() implementation

The callback has the following syntax:

handleAxisEvent( event )

This script is called whenever a joystick axis event occurs, and is given an instance of PyAxisEvent.

For example:

def handleAxisEvent( event ):

  # try the GUI
  if GUI.handleAxisEvent( event ):
    return True

  # return False because the axis event has not been handled
  return False

Example of handleAxisEvent() implementation

The callback has the following syntax:

handleIMEEvent( event )

This is called when an Input Method Editor (IME) related event occurs and is used to update the GUI respectively, and is given a PyIMEEvent object as it's first parameter. See Input Method Editors (IME) for details on IME support.

The callback has the following syntax:

handleLangChangeEvent()

This event occurs whenever the current input language has been changed by the user. It is useful for tasks such as updating language indicators on GUI edit fields.

The callback has the following syntax:

onChangeEnvironments( inside )

This script is a callback acknowledging the environment type the player is currently in.

Currently there are only inside and outside environment types. The argument is a Boolean value indicating whether the player is inside or not. This may be useful for modifying the behaviour of the camera in third person mode.

For example:

def onChangeEnvironments( inside ):
  global sd
  sd.inside = inside
  sd.updatePivotDist()

The callback has the following syntax:

onGeometryMapped(spaceID, spacePath)

This callback method tells the player entity about changes to the geometry in a space. It is called when geometry is mapped into any of the currently existing spaces on the client. The space ID and the name of the space geometry are passed as parameters.

The first parameter is the ID of the space the geometry is being mapped in to. The second parameter is the name describing the space's geometry.

The callback has the following syntax:

onRecreateDevice ()

This script is a callback alerting the scripts that the Direct3D device has been recreated. This often occurs when the screen resolution is changed.

This callback was introduced primarily so that scripts can re-layout their GUI component scripts, but it is also useful for recreating any static PyModelRenderer textures (since these do not automatically update, unless they are dynamic).

For example:

def onRecreateDevice():
  (width,height) = GUI.screenResolution()
  myGuiController.doLayout( width, height )
  myRenderers.recreateTextures()

The callback has the following syntax:

onTimeOfDayLocalChange( gameTime, secondsPerGameHour )

This script is a callback to allow scripts to be notified of changes in the game time.

It is passed two floats as arguments: the first one is the game time in seconds, and the second is the number of real-time seconds per game hour.

The callback has the following syntax:

start()

This script is called after the engine has initialised, and used to start the game. It may be used to bring up a start menu, or login screen.