Client Programming Guide

paths.xml is an XML file which the engine will look for on startup and contains a list of resource paths. The client will first try to open paths.xml in the current working directory. If it cannot be found in the current directory, then it will try to open paths.xml in the same folder as the client executable. The schema of paths.xml looks like this:

<root>
    <Paths>
        <Path>../../my_game/res</Path>
        <Path>../../bigworld/res</Path>
    </Paths>
</root>

By default the client will look for the paths.xml illustrated above. However, this can be overridden via the command line using the --res switch. Multiple paths are semi-colon separated. For example,

"bwclient.exe" --res ../../../my_game/res;../../../bigworld/res

This file defines game-specific resources that are needed by the client engine to run.

The entries in resources.xml are read from the various entries in the resources folders list (or <res>), in the order in which they are listed. Only missing entries will have their values read in subsequent folders.

A default file exists under folder bigworld/res, and any of its resources may be overridden by creating your own file <res>/resources.xml.

The example below illustrates this mechanism:

Precedence of your game's resources.xml file over BigWorld's ones

For a complete list of the resources and values used by BigWorld, refer to the resources.xml file provided with the distribution.

The XML file <engine_config>.xml lists several engine configuration options.

The actual name and location of this file is defined by the resources.xml's <engineConfigXML> tag. The location of the resources.xml file is always defined relative to one of the entries in the resources directories list (or <res>), which will be searched in the order in which they are listed.

An example follows below:

Locating <engineConfigXML>'s file

Under the main section of the XML file, a personality tag must be included, naming the personality script to use.

Several other tags are used by BigWorld to customise the way the client runs. For a complete list of the supported tags and a description of their functions, refer to the engine_config.xml file provided with the distribution. Additional information can also be found in the Client Python API.

The data contained in this file is passed to the personality script as the second argument to the init method (for details, see init), in the form of a DataSection object.

The XML file <scripts_config>.xml can be used to configure the game scripts. It has no fixed grammar, and its form can be freely defined by the script programmer.

The actual name and location of this file is defined by the resources.xml's scriptsConfigXML tag — its location is always defined relative to one of the entries in the resources folders list (or <res>), which will be searched in the order in which they are listed.

Locating scriptsConfigXML's file

The data contained in this file is passed to the personality script as the first argument to the init method (for details, see init), in the form of a DataSection object.

The XML file <preferences>.xml is used to save user preferences for video and graphics settings, with a pre-defined grammar.

The file also embeds a data section (called scriptsPreference) that can be used by scripts to persist game preferences — there is no fixed grammar for this section.

The actual name and location of this file is defined in file specified by resources.xml's engineConfigXML tag, in the preferences tag.

Locating engineConfigXML's preferences' file

By default the preferences XML file is relative to the client executable location, but this can be changed to a number of other base paths by specifying a pathBase subtag (e.g. it can be defined to be relative to the user's My Documents directory). The base path can be defined as an optional sub-tag of the preferences tag. The available path bases for <preferences>.xml are:

The data contained in the scriptsPreference of this file is passed to the personality script as the third argument to the init method (for details, see init), in the form of a DataSection object.

The current user preferences can be saved back into the file (including changes to the DataSection that represents the script preferences) by calling BigWorld.savePreferences. For details, see the Client Python API .

If a KeyEvent is generated by the keyboard, it may have a character attached to it. The character generated by a particular key is determined by the currently set locale and input language in the operating system, and is represented by the KeyEvent.character member (a Unicode string).

Dead character keys are supported (e.g. in Spanish, a user can type the letter é by first pressing the apostrophe key followed by the e key). In this case the first key press will not have a character associated with it, and the second key press will have the final character.

The BigWorld client supports advanced Input Method Editors (IME). See Input Method Editors (IME) for details on using an IME in your game.

The keyboard will generate auto-repeat events when keys are held down, based on the user's operating system settings (e.g. repeat delay). The mouse and joystick do not generate auto-repeat events.

Auto-repeat events are sent as additional key-down events, however scripts that do not want to handle repeat events can call the KeyEvent.isRepeatedEvent method to determine whther or not it is an auto-repeat event.

When the user presses a button (keyboard, mouse or joystick), the sequence of events are:

The output from the user input module is processed by a number of other modules, which take it in turn to examine events and either consume or ignore them. If an event is not consumed by any module then it is discarded. The order of modules that get a turn at the events is as follows:

The BigWorld client performs event matching to ensure consistent module behaviour. If a key-down event is consumed by a module, that module's identifier is recorded as the sink of the event's key number. When the corresponding auto-repeat and key-up event arrives, it is delivered directly to that module. For example, if a chat console is brought up (and inserted into the list) while the player is running, and the user subsequently releases the run key, then the player script will still get the key-up event for that key, and be able to stop the run action.

In some cases it may be desired to temporarily block certain key events from being passed into the scripts. For example, the GUI scripts may handle a key down event by removing the current GUI screen and replacing it with a new GUI screen. By default, since the new GUI screen has become the active screen by the time handleKeyEvent returns, any associated auto-repeat and key-up events will be posted to the new GUI screen creating possibly unwanted behaviour.

The BigWorld.sinkKeyEvents function can be used to stop all key events for the given key-code from reaching the scripts until (and including) the next key-up. See the Python API guide for details.

It is often a requirement to know where the mouse was when a key event occured (i.e. rather than where the mouse is at the time of handling the event), especially when processing mouse button events. Therefore, the mouse cursor position is available via the KeyEvent.cursorPosition property, and should be used instead of GUI.mcursor().position where ever possible.

High resolution mouse movement events are sent to the scripts as a MouseEvent. This object exposes three direction deltas.

Similar to the KeyEvent object, the mouse cursor position for when the event occured is available as a member of the MouseEvent object.

Mouse buttons are sent as a KeyEvent, however they do not generate auto-repeat events. See Key events for details.

When axis events occur, they will be sent to the scripts as an AxisEvent object via the handleAxisEvent personality script function.

Joystick buttons are sent as a KeyEvent, however they do not generate auto-repeat events. See Key events for details.

The C++ engine will automatically pass axis events to the active cursor, so the direction cursor can be joystick controlled by setting it as the active cursor using BigWorld.setCursor. The direction cursor will process any events generated by the right axis.

The C++ engine will also give the physics subsystem a chance to handle axis events. The physics treats axis input as a special case and will scale movement speed by how far the user as pushed the joystick forward.

In order to enable joystick support on movement physics, set the Physics.joystickEnabled property to True and be sure to set joystickFwdSpeed and joystickBackSpeed properties to values appropriate for your game.

The advanced terrain engine uses a height map split up into blocks of 100 by 100 metres. Each block consists of height and texture information, normals, a hole map and LOD information.

Texturing is done by blending multiple textures layers together, each texture layer has its own projection angle and blend values for blending with other texture layers. The resolution of the blend values is configurable per space and the layers themselves are stored per chunk. The textures are assumed to be rgba with the alpha channel used for the specular value.

The lighting of the advanced terrain is performed per pixel. A normal map is stored per block, which is used in the lighting calculations, this is combined with the blended texture to output the final colour. The terrain allows up to 8 diffuse and 6 specular lights per block. For details of how the specular lighting is calculated see Terrain specular lighting

The terrain uses a horizon shadow map for shadowing, this map stores two angles (east-west) between which there is an unobstructed view of the sky from the terrain. In the terrain shader, these angles are checked against the sun angle and the sun light is only applied if the sun angle falls between the horizon angles.

The purpose of the LOD system is to reduce the amount of cpu and gpu time spent rendering terrain and to reduce the memory footprint of the terrain. The terrain LOD system achieves this by reducing geometric and texture detail in the distance and loading/unloading high resolution resources as they are needed. The LODing is broken up by resource so that texture and geometric detail can be streamed separately. The LOD distances are configurable in the space.settings file, please see terrain section in space.settings for more information.

Since the advanced terrain allows for a number of configuration options the memory footprint of the terrain depends on the options selected.

In the Fantasydemo example provided, the terrain overhead is as follows (this information was captured using the resource counters in the Fantasydemo client, the graphics settings were set to high and the far plane was set to 1500 metres):

(this includes the textures used by the texture layers, which may also be used by other assets)

Terrain memory usage

A terrain2 section is contained in a chunk's .cdata file. It contains all the resources for the terrain in a chunk. The different types of terrain data are described in BNF format in the following chapter.

<heightMap> ::= <header><heightData>
<header> ::= <magic><width><height><compression><version><minHeight><maxHeight><padding>

<textureLayer> ::= <header><textureName><blendData>
<header> ::= <magic><width><height><bpp><uProjection><vProjection><version><padding>
<textureName> ::= <length><string>

<normals> ::= <header><data>
<header> ::= <magic><version><padding>

<holes> ::= <header><data>
<header> ::= <magic><width><height><version>

<shadows> ::= <header><data>
<header> ::= <magic><width><height><bpp><version><padding>

<dominant> ::=<header><texNames><data>
<header> ::= <magic><version><numTextures><texNameSize><width><height><padding>

The terrain section in the space.settings file contains the configuration options for the terrain. The values in the lodInfo and server sections can be modified, but the root level values should only be modified by the World Editor.

    <version> 200 (int) </version>
    <heightMapSize> uint </heightMapSize>
    <normalMapSize> uint </normalMapSize>
    <holeMapSize> uint </holeMapSize>
    <shadowMapSize> uint </shadowMapSize>
    <blendMapSize> uint </blendMapSize>
    <lodInfo>
      <startBias> float </startBias>
      <endBias> float </endBias>
      <lodTextureStart> float </lodTextureStart>
      <lodTextureDistance> float </lodTextureDistance>
      <blendPreloadDistance> float </blendPreloadDistance>
      <lodNormalStart> float </lodNormalStart>
      <lodNormalDistance> float </lodNormalDistance>
      <normalPreloadDistance> float </normalPreloadDistance>
      <defaultHeightMapLod> uint </defaultHeightMapLod>
      <detailHeightMapDistance> float </detailHeightMapDistance>
      <lodDistances>
        +<distance?> float </distance?>
      </lodDistances>
      <server>
        <heightMapLod> uint </heightMapLod>
      </server>
    </lodInfo>    

The terrain is a huge height map defined by a regular grid of height poles, every 4x4 metres. Terrain is organised into terrain blocks of 100x100 metres. Each of these blocks can have up to four textures, which are blended on a per-vertex (i.e., per-pole) basis. The terrain also is self-shadowing, and allows holes to be cut out of it, for things like cave openings. The terrain also contains detail information, so that the detail objects can be matched to the terrain type.

The terrain integrates properly with the chunking: each terrain block is 100x100 metres, which is the size of the outside chunks. The terrain blocks are stored in separate files, so that they can be opened as needed.

Each terrain block covers one chunk, each with dimension of 100x100 metres. It contains 28x28 height, blend, shadow, and detail values (there are two extra rows and one column to allow for boundary interpolation). Each terrain block also stores 25x25 hole values, one for each 4x4m tile.

The table below display the terrain cost per chunk.

Terrain cost per chunk

For example, for a 15x15 km world the total disk size of the terrain would be: 10,017 x 150 x 150 ~ 215MB.

With a field of view of 500m, and each terrain block covering 100x100 metres, a typical scene would require roughly 160 terrain blocks in memory at any one time.

The memory usage of this much terrain is about 2MB, plus data management overheads.

The TerrainTextureSpacing tag included in the environment section of file <res>/resources.xml (for details on the precedence of entries in the various copies of file resources.xml, see File resources.xml) determines the size (in metres) to which texture map will be stretched/shrunk when applied to the terrain.

This value determines both the length and height of the texture tile.

Includes are transparent after being loaded (to client, server, and scripts). Label clashes are handled by appending '_n' to labels, where N is the number of objects with that label already.

Includes are expanded inline where they are encountered, and do not need to have a bounding box for the purposes of the client or server.

The World Editor does not generate includes.

Material overrides and animation declarations remain the domain of model files. For more details, see Models.

Only entities that are implicitly instantiated need to have their ID field filled in. If it is zero or is missing, then the entity is assigned a unique ID from either the client's pool (if it is a client-instantiated entity) or the creating cell's pool (if it is a server-instantiated entity).

If an entity needs a label, it must include the label as a property in its formal type definition.

The special chunk identifier heaven may be used if only the sky (gradient, clouds, sun, moon, stars, etc...) is to be drawn there. Similarly with earth, if the terrain ought to be drawn. Therefore, outside chunks will have six sides, with the heaven chunk on the top and the earth chunk on the bottom.

The absence of a chunk reference in a portal means it is unconnected and that nothing will be drawn there.

If a chunk is included inside another, then its boundary planes are ignored — only things like its includes, models, lights, and sounds are used.

An internal portal means that the specified boundary is not an actual boundary, but instead that the space occupied by the chunk it connects to (and all chunks that that chunk connects to) should be logically subtracted from the space owned by this chunk, as defined by its non-internal boundaries. This was originally intended only for 'outside' chunks to connect to 'inside' chunks, but it may be readily adapted for 'interior portals', the complement to 'boundary portals'.

In a portal definition, the vAxis for the 2D polygon points is found by the cross product of the normal with uAxis.

In boundary definitions, the normals should point inward.

Everything in the chunk except the bounding box is interpreted in the local space of the chunk (as specified in the top-level transform section).

The following items can also exist in chunks:

A hull tree is a kind of binary-space partitioning tree for convex hulls. It can handle hulls that overlap. It can do point tests and proper line traversals.

The hull tree is formed from the boundaries of all the chunks that overlap the column. From this tree, the chunk that any given point lies in can be quickly determined. (e.g., the location of the camera)

The quad tree is made up of the bounding boxes (or, potentially, any other bounding convex hull) of all the obstacles that overlap the column. This tree is used for collision scene tests. Chunk items are responsible for adding and implementing obstacles. Currently only model and terrain chunk items add any obstacles.

If a chunk or obstacle is in more than one column, it is added to the trees of both columns.

When the client starts up, it will query each entity Python module for a function named preload. Resource names returned by this function will be loaded on client startup and kept in memory for the entire life-time of the client (i.e. it will be instantly available for use at any time). This is useful for commonly used assets to avoid potentially loading and re-loading at a later time. The tradeoff, however, is that the client will take longer to start and will use more memory (if the resource isn't actually being used at some point).

To use the preloads mechanism, create a global function called preload in the relevant entity module. It must take a single parameter which is a Python list containing resource to preload. Modify this list in place (e.g. using list.append or list concatenation), inserting the string names of each resource to be preloaded by the client.

For example,

# Door.py
import BigWorld

class Door( BigWorld.Entity ):
    def __init__( self ):
        ...

def preload( list ):
    list.append( "doors/models/generic_door.model" )
    list.append( "doors/maps/door_highlight.tga" )
    ... 

The type of resources which can be preloaded are,

When an entity is about to appear in the world on the client, the engine will execute a callback on the entity script called prerequisites. This allows entity scripts to return a list of resources that must be loaded before the entity may enter the world. These resources are loaded by the loading thread, so as to not interrupt the rendering pipeline.

It is recommended practice for an entity to expose its required resources as pre-requisites, and load them in the method onEnterWorld. Unlike using preloads, prerequisites do not leak a reference, so when the entity leaves the world, it will free its resources.

The Entity Manager calls Entity::checkPrerequisites before allowing an entity to enter the world. This method checks whether the pre-requisites for this entity entering the world are satisfied. If they are not, then it starts the process of satisfying them (if not yet started).

Note that when the prerequisites method is called on the entity, its script has already been initialised and its properties have been set up. The entity thus may specialise its pre-requisites list based on the specific instance of that entity. For example:

def Door( BigWorld.Entity ):
    ...
    def prerequisites( self ):
        return [ DoorResources[ self.modelType ].modelName ]
    ...

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.

In order to avoid the need for an intermediate step, there needs to be an explicit pairing between character hard points and item hard points. Every item needs a hard point for every specific way that it can be held.

As an example, listed below are the hard points for a human character and a gun.

The (client-side) Entity class provides a list of hard points, but only if asked by the specializing class. For example, when a model is loaded, it will find all nodes prefixed with (for instance) 'HP_'. These are then stored in a hardPoint list that is owned by the model.

When an item is equipped, the entity/game arbiter will be asked to match up the item with the correct hard point. For example, if the 'next weapon' button is pressed, the next weapon in the inventory can be attached to the right hand hard point.

The syntax for using hard points from Python is elegant and powerful. To attach model gun to model avatar on hard point hand, use the following syntax:

avatar.hand = gun

A model is checked when it is attached to ensure that it is not attached elsewhere. To retrieve the model attached to avatar's hand, simply use:

model = avatar.hand

If no model is attached, then None is returned.

The model is attached by reference, not by copy, so anything that can be done to the original model reference can be done to the reference retrieved from a hard point.

For example, gun.Shoot() and avatar.hand.Shoot() have the same effect.

A model definition is an XML file specifying:

The Model Editor tool is used to create a .model file that links an object's geometry to its animations and defines the sets of animations/actions that are possible to play on this object.

As with all resource files in the BigWorld framework, .model files are in XML format. They are hierarchical and inherit data from their parent(s), in this way basic animations that apply to a large set of characters can be isolated from more character-specific animations without having to be duplicated.

The example below defines a very simple model:

<jogger.model>

  <nodefullVisual>  jogger  </nodefullVisual>
  <parent>          biped   </parent>

  <animation>
    <name>      jog         </name>
    <frameRate> 30.0        </frameRate>
    <nodes>     jogAnim     </nodes>
    <alpha>
      <Torso>   0.0  </Torso>
      <Pelvis>  1.0  </Pelvis>
    </alpha>
  </animation>

  <action>
    <name>          BIPED_JOG  </name>
    <animation>     jog        </animation>
    <blendInTime>   0.300000   </blendInTime>
    <blendOutTime>  0.300000   </blendOutTime>
    <filler>        false      </filler>
    <blended>       false      </blended>
    <isMovement>    true       </isMovement>
    <isCoordinated> false      </isCoordinated>
    <isImpacting>   true       </isImpacting>
    <match>
      <trigger>
        <minEntitySpeed> 1.0  </minEntitySpeed>
        <maxEntitySpeed> 3.0  </maxEntitySpeed>
        <capsOn>         16   </capsOn>
      </trigger>
    </match>
  </action>
<jogger.model>

Example of .model file

This file describes a character (jogger) which has a geometry defined by the visual file jogger and has a standard set of biped actions via the <parent> tag, which may include walk, run, and jump animations, but also specifies a jog animation.

The animation section includes:

The <action> section describes the action name that is used to play this action from the Python code.

There are model files, with the .model extension, but there are no explicit SuperModel files.

There is the SuperModel class, which holds together and controls the animation and rendering of a number of models. A SuperModel is created based on information in chunk and model files (these are instance-like classes — there is nothing analogous to PyModelInfo.).

Using LOD ratios, the SuperModel class can manage the transition between, say, an avatar being rendered at a high LOD using three separate models, to it being rendered at a low LOD using just one.

Animations are accumulated on the same inheritance hierarchy, and the animation most appropriate to the current LOD level is used. All the animations for all the LOD levels are interpreted and selected from a flat namespace. Attempting to play an animation that does not exist (or does not exist at the current LOD level) selects an infinite length animation of the model's initial pose. Care must be taken to ensure that multi-model SuperModels do not waste time animating unnecessarily (e.g., when all the small parts have an animation overriding the whole part's animation, it would be a waste of time to apply the whole part's animation).

The mesh files themselves specify how a part is connected to others for multi-part supermodels.

The SuperModel class implements the basic functionality of the BigWorld model definition, using the objects provided by Moo. It combines a number of the .model files created by Model Editor (but usually just one) into one conceptual model, managing any animations and level-of-detail chains. The SuperModel class is detailed in SuperModel.

Two classes currently use SuperModels in the BigWorld client, for two different needs:

Both are described in the following subsections.

Running the process_defs executable with the --help switch will give you general options as well as a list of module-specific options supported by the selected Python module.

$ ./process_defs -m GenerateCPlusPlus --help
usage: process_defs [OPTION] scriptArgs

This program parses the BigWorld entity definition files. A Python object is
then created representing the entity descriptions. This is passed to a Python
callback moduleName.functionName. By default, this is ProcessDefs.process.

This module (ProcessDefs.py) should be placed in modulePath. This is the
current working directory by default.

Options:
  -r             directory     Specifies a resource path. Can be used
                               multiple times, in order of deccreasing
                               priority.
  -f, --function funcName      The Python function to call. "process" by
                               default.
  -m, --module   moduleName    The Python module to load. "ProcessDefs"
                               by default.
  -p, --path     directory     The directory to find the module. Current 
                               working directory by default.
  -v, --verbose                Displays more verbose output.
  -h, --help                   Displays this message.

Script Options:
  -h, --help            show this help message and exit
  -o FILE, --output=FILE
                        Directory to output generated files. Defaults to
                        "GeneratedCPlusPlus".
  --base-class-header=CLASS_NAME_INCLUDE_PATH
                        Path to a header file containing the declaration for
                        the base class for generated entity classes. Defaults
                        to "connection/bw_entity.hpp".
  -b CLASS_NAME, --base-class=CLASS_NAME
                        The base class for generated entity classes. Defaults
                        to "BWEntity".
  --generated-header-path=HEADERPATH
                        This indicates the directory of where to find the
                        generated sources, and is used for generating the
                        #include lines for generated headers. Defaults to
                        "GeneratedEntities".
  --entity-header-path=HEADERPATH
                        This indicates the directory of where to find your
                        entity class header files, and is used for generating
                        the #include lines for entity header files. Defaults
                        to "Entities"
  --entity-template-source-extension=EXT
                        Specifies the extension suffix given to generated
                        entity stub and template C++ source files. Defaults to
                        "cpp".

ProcessDefs requires the location of the resource directories be specified as command line options, so it can find the relevant entity definition files to parse. The resource directories can be specified by using the -r option, followed by the path to the resource directory. To specify multiple directories, the option can be used multiple times, specifying resource paths in descending order of priority. Typically, the bigworld/res directory is specified as the last resource path.

Typically, the generated sources are compiled as part of a larger project, and are placed in their own directory within the project directory structure. You can use the ProcessDefs tool to compile straight to their target directory by using the -o / --output command line option.

Once the sources are in place, you will also need to include them into your project using a common include line path prefix. The generated source files will also include other generated header files, and so it is necessary to also add this common include line path prefix in the generated source files themselves. This prefix is specified using the --generated-header-path option, and is usually determined by where the output directory is in relation to your project source directories.

Concrete entity implementations will typically be in their own directory. Since the generated source files require the inclusion of those entity class header files in order to construct them in the entity factory, the location of the entity class header files needs to be specified using the --entity-header-path option.

It can be useful to also modify the file extension of the entity class template source files that are generated. For example, Objective-C++ requires its source files to have a .mm extension.This can be specified using the --entity-template-source-extension option.

As an example, the ios client project directory (located at bigworld/src/examples/client_integration/c_plus_plus/ios) contains a Classes directory, which in turn contains an Entities directory, which in turn contains a GeneratedSource directory. The Classes directory contains source files for general game Objective-C and Objective-C++ classes, including the general FDEntity class which is used as the entity super-class, which implements functionality common to all entity classes. FDEntity itself derives from BWEntity.

The Entities directory contains the implementation source files of the concrete entity classes. These classes derive directly from their corresponding stub classes, so for example, Avatar derives from Avatar_Stub.

The GeneratedSource directory contains all the generated sources output from ProcessDefs. It contains the non-entity-specific source files, for example, the sources for generated FIXED_DICT types, as well as each entity type's stub class and the server-side entity classes.

With these requirements in mind, we use the following command as part of the build process in XCode:

./process_defs.macosx \
        -r "${SRCROOT}/../../../../fantasydemo/res" \
        -r "${SRCROOT}/../../../res" \
        --module "GenerateCPlusPlus" \
        --output "${SRCROOT}/Classes/Entities/GeneratedSource" \
        --base-class "FDEntity" \
        --base-class-header "FDEntity.h" \
        --entity-header-path "Classes/Entities" \
        --generated-header-path "Classes/Entities/GeneratedSource" \
        --entity-template-source-extension "mm"

The GenerateCPlusPlus module takes the entity definitions descriptor object and writes out several generated files that can be used for connecting to a server that runs those same entity definitions.

For each entity type, the GenerateCPlusPlus module will generate a stub class which incorporates the entity type name in the class name. This stub class implements the entity property streaming and client-side method dispatch.

The GenerateCPlusPlus module will also generate, if needed, remote entity classes used for calling remote methods on the server side, if they are defined in that entity type's definition file.

The files generated are:

The GenerateCPlusPlus module will also output several general source files as listed below:

The GenerateCPlusPlus module uses the supplied jinja2 Python templating library to generate the code. The jinja templates are located inside the module directory under the directory called templates. The templates used are:

For ultimate control over the code generation process, a new processing module can be used with ProcessDefs.

Each ProcessDefs processing module implements a function that is passed a data structure that describes the entity definitions that are parsed by ProcessDefs. The function is called process() by default; a command line option on ProcessDefs can change which module function is called.

The data structure passed to the processing function is a Python dictionary with the following keys:

Each method description dictionary object contains the following keys:

Each property description dictionary object contains the following keys:

The connection_model library depends on:

This class represents a connection to the server. The BWConnection class's simple interface allows applications to connect to a server and populate BWEntity objects with position and direction data, property updates and handling of remote method calls.

static const char g_publicKeyString[] = "-----BEGIN PUBLIC KEY-----\n" \
"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7/MNyWDdFpXhpFTO9LHz\n" \
"CUQPYv2YP5rqJjUoxAFa3uKiPKbRvVFjUQ9lGHyjCmtixBbBqCTvDWu6Zh9Imu3x\n" \
"KgCJh6NPSkddH3l+C+51FNtu3dGntbSLWuwi6Au1ErNpySpdx+Le7YEcFviY/ClZ\n" \
"ayvVdA0tcb5NVJ4Axu13NvsuOUMqHxzCZRXCe6nyp6phFP2dQQZj8QZp0VsMFvhh\n" \
"MsZ4srdFLG0sd8qliYzSqIyEQkwO8TQleHzfYYZ90wPTCOvMnMe5+zCH0iPJMisP\n" \
"YB60u6lK9cvDEeuhPH95TPpzLNUFgmQIu9FU8PkcKA53bj0LWZR7v86Oco6vFg6V\n" \
"sQIDAQAB\n"
"-----END PUBLIC KEY-----\n"

BWConnection connection( ... );

connection.setLoginAppPublicKeyString( g_publicKeyString );

#include "GeneratedSource/DefsDigest.hpp"

#include "connection/bw_connection.hpp"

...

    BWConnection * pConnection = new Connection( *pEntityFactory, DefsDigest::constants() );

std::string serverAddress = "10.1.1.1";
std::sttring username = "MyUser";
std::string password = "pass";

pConnection->logOnTo( serverAddress, username, password );

MyConnectionHandler handler;
pConnection->setHandler( &handler );

The BWEntity class is the superclass of all entity classes. Instances of the BWEntity class are created using the BWEntityFactory instance registered with the BWConnection at construction time.

MyEntity::MyEntity() :
...
{
    ...
    this->pFilter( new AvatarFilter( environment ) );

Subclasses of the BWEntityFactory interface class are responsible for creating instances of BWEntity that are appropriate to the entity type ID given to the creation method.

Generated code will include a concrete class that implements BWEntityFactory, called EntityFactory, which creates the appropriate concrete BWEntity class that has the same name as the entity type name.

A BWEntityFactory instance is required to construct a BWConnection instance.

When the player is inside a space, entities in that space will enter and leave the client's area of interest, and the server will inform the client when this occurs. It is useful to catch when this happens, and so BWConnection allows for a BWEntitiesListener object to be registered which receives entity enter and leave events.

A BWEntitiesListener subclass implements the following methods:

Server discovery is used during development to find a locally running server on the same LAN segment and get details for starting a connection. It is not intended to be used for production clients.

A subclass of the abstract ServerFinder class is used for this purpose. By implementing a new concrete subclasss of ServerFinder, instantiating it and passing it to BWConnection's findServers() method, a search for locally running servers will be performed. The timeout parameter in findServers() can be used to set the time-out duration for searches; it defaults to 10 seconds.

Virtual method callbacks are called when servers are found, when the search is completed or has timed out. ServerFinder subclasses should implement the following methods:

This example client is a barebone application that connects to a BigWorld server, and illustrates a minimal amount of effort required to connect to the server and send player movement, and how to apply property updates to Python-based entities.

This example is compilable under Linux and Windows.

The SDL example is a simple client that provides a top-down GUI using the Simple Directmedia Library library (http://www.libsdl.org) to connect to a FantasyDemo server.

It uses the ProcessDefs tool to generate entity code.

This example is compilable under Linux and Mac OS X. It requires the SDL and SDL_image libraries.

Under CentOS Linux, these libraries can be installed by installing the SDL-devel and SDL_image-devel packages.

Mac OS X framework libraries for SDL and SDL_image and instructions on how to install them can be found at on the SDL site.

In order to run the example, the resource paths for FantasyDemo need to be specified on the command line as well as the server address, for example:

$ ./client_integration -r ../../../../fantasydemo/res -r ../../../res -s localhost

When running under Xcode, you will need to set these command line arguments in the client_integration scheme Run → Arguments → Arguments Passed On Launch.

This example is a simple iOS client that connects to a FantasyDemo server, and offers a top-down GUI to visualise the client-side area of interest.

The project file is located in bigworld/src/examples/client_integration/c_plus_plus/ios/FantasyDemo.xcodeproj. It requires XCode 4.3 and above, and the installation of the optional XCode Command Line Tools. To install, go to Preferences → Downloads → Components, and install the Command Line Tools component.

Source actions can create particles over regular periods of time, on demand, or even be sensitive to the movement of the model to which it is attached. The size, colour, velocity, position, and even age of the particles can be specified upon creation. The key behind vector descriptions of particles is the Vector Generation subsystem.

Each source action requires three vector generators. A vector generator is a class of objects that randomly create vectors within a given space; the space is usually defined by the type of generator and the parameters given to it. For example, a sphere generator may accept a point in 3D space and a radius value, while a line generator may accept two points in 3D space.

The three generators are used to find the initial position, velocity, and colour of the particle when created. When calculating position and velocity, the local space of the model is taken into account, but only for the creation of the particle. What this means is that a cube described by two points, (-0.5, -0.5, -0.5) to (0.5, 0.5, 0.5) is roughly the bounding box of the particle in position.

Movement actions act on every particle in the system. There is a variety of movements that can be applied to a particle. Examples would be force, stream, barrier, and jitter.

Basic movement of particles due to velocity is calculated automatically within the particle system, taking wind also into account.

Particles can also undergo full scene collision — e.g., spent bullets tumbling down steps.

Sink actions remove particles from the system, whether it is due to age or for moving beyond a specified boundary. Examples of sink actions are sink, barrier, and splat.

It is important to note that without sink actions, particles once created will never leave the system, eventually forcing it to hit its particle limit.

Alteration actions affect the appearance of the particles. They can modify the shading, alpha level, and size of the particle over time. They are typically used in smoke effects, gentle fading in and out, and glowing effects. Particle textures can be animated if the texture specified is an animated texture.

Because of the multitude of objects involved, it is impractical to place detail objects by hand. Instead, BigWorld has Ecotypes.

Ecotypes define objects that are automatically placed within the world, guided by terrain texture. They are defined in XML, and have the following properties:

For example, a grass ecotype could contain two separate meshes: one for low-height grass, and another for mid-height grass.

The set of ecotypes currently active is managed by the Flora class, which also manages the individual active detail objects, allocating and de-allocating them as required.

Each terrain block can have four textures, and each of these textures can have one associated ecotype. This allows for four different ecotypes per terrain block. Hence, within the detail sphere (50-metre radius from the camera) up to 16 different ecotypes may be visible.

Detail objects are not placed precisely within the terrain blocks — this would create square regions of detail objects. Detail objects 'jitter' their position before querying the terrain for its detail mapping. This effectively antialiases the quantised detail map.

Flora is calculated and stored in terrain files by the World Editor. For more details, see the document Content Creation Manual (accessible in World Editor, Model Editor, and Particle Editor via the Help → Content Creation menu item, or by pressing F1).

Drawing detail objects is an extremely performance-critical area, as all routines are run thousands of times per frame.

Vertex buffers are the perfect solution. The detail objects are kept transformed in a large vertex buffer. Thus, 1,000 pieces of grass at 6 vertices each means a world-space vertex buffer of 6,000 vertices. This allows all grass to be drawn using one call to the video card, using one transform matrix. 3D accelerators are extremely fast performing this kind of batched rendering.

As the player moves around the world, he sees the detail objects in the immediate vicinity (50m). In reality, this means that the active set of detail objects must change according to the camera position. Detail objects that are just coming into view are faded in, using alpha blending.

The flora configuration XML file <flora>.xml (for details on this file's grammar, see the document File Grammar Guide's section <flora>.xml) can define the size of the vertex buffer either statically or as a set of options selectable by the user via the FLORA_DENSITY graphics setting. For details, see FLORA_DENSITY.

In a multi-thousand object system, frame coherency must be utilised aggressively. The obvious choice for frame coherency is the vertex transforms. Each detail object is kept transformed in a vertex buffer in world space, until its terrain tile (or 'flora block') leaves the detail radius, at which point another terrain tile will have moved into the detail radius. Then the new tile's detail objects will be transformed and placed in the freed up vertex buffer memory.

On average, detail objects have shown around 97% coherency between frames, making for a huge saving in transformation cost.

In order to create an immersive, living, breathing world, most things must animate.

Animating detail objects add greatly to the illusion of the world. The BigWorld client uses 3D Perlin noise based on (wx, wz, time) to create believable procedural animation to the detail objects. Perlin noise was chosen because it is a cheap way to create space-time coherent noise. The implementation performs the animation efficiently in the vertex shader.

When using simplified meshes (which is crucial in a multi-thousand object ornamentation system), lighting becomes challenging. Consider a criss-cross grass object rising vertically out of the terrain. If lit using standard procedures, the criss-cross objects would flare up in the evening sun.

In the BigWorld client, lighting for detail objects is performed using the light map calculated from the actual terrain. Thus, it picks up terrain shadows as well. This is a mostly correct solution, because the mesh-based terrain itself is really a simplified version of the millions of detail objects in existence.

The XML flora file defines among other things, the light map to be used, plus the ecotypes and noise generation functions. For details on this file's grammar, see the document File Grammar Guide's section <flora>.xml.

The Water::init method is used to initialise the graphics settings options menu link and the FX files, and is only called once. It will make available the following menu items:

A — Cells are sub-divisions of the water surface (for details, see Simulation).

The SimpleGUIComponent class is simply a textured rectangle. The derived class TextGUIComponent draws text, and the also derived class FrameGUIComponent draws a resizable frame using three bitmaps (corner, edge, background).

SimpleGUIComponent has many properties, mostly accessed from Python and XML files. For more details, see Python GUI support.

Components are hierarchical only in that parents draw their children; children do not inherit their parents' transform. WindowGUIComponent is an exception to this rule — children are automatically clipped and translated by their parent. Note that this is a feature of WindowGUIComponent, not the GUI system in general.

The GUIShader class alters the way that components are drawn, in an analogous form to vertex shaders (in fact, 99% of GUI shaders operate only on temporary variables instead of vertices, hardware TnL support).

Shaders are applied to all children — so use a MatrixGUIShader to implement windowing, and an AlphaGUIShader to fade in/out a whole tree of components.

This is the GUI root, and it is ticked and drawn at every frame.

Use SimpleGUI::addSimpleComponent() and SimpleGUI::removeSimpleComponent() to build your tree of GUI components. Note that you would normally never call these methods from C++, as they are mostly called by scripts.

The onLoad method is called just after the C++ load method has been called, the standard member variables have been setup, and the associated script has already been constructed.

The data section that the GUI component is being loaded from is passed into the method. This allows the definition of custom attributes, especially for loading custom data into the script object.

Note that the method is called before any children components or shaders have been loaded.

The onBound method is called after the load is complete.

The main difference between this method and onLoad is that by the time onBound is called, the whole GUI component tree has been created. Thus in the onBound method you can write custom script handling to manipulate child components. For example, you could invoke your own custom Layout Manager in this method.

The onSave method is called just after the C++ save method has saved all standard GUI component members, but before the shaders and children are saved.

Keyboard events are related to input from keyboard, mouse, and joystick buttons. They are reported to script objects through the handleKeyEvent method:

def handleKeyEvent( self, event )

The parameters are described below:

A return value of True means that the event has been consumed, thus effectively preventing it from being propagated to other components or game scripts. A return value of False allows further propagation.

To receive key events, a component must have the property focus set to True.

Note that mouse button events reported through the method handleKeyEvent differ from those reported through handleMouseButtonEvent in that the mouse cursor does not have to be inside the area defined by a component for that component to capture the event. The only requirements for the capture are to have the property focus set to True, and not having another component consuming the event earlier in the focus list.

Character events are attached to key events. Check the PyKeyEvent.character parameter, which will be a string containing the fully translated character. It will otherwise it will be None. Keep in mind that due to more complex input methods (e.g. dead-keys) the length of the character string can be greater than 1.

Axis events are related to joystick axis input. They are reported to script objects through the handleAxisEvent method:

def handleAxisEvent( self, axis, value, dTime )

The parameters are described below:

A return value of True means that the event has been consumed, effectively preventing it to be propagated to other components or game scripts. A return value of False allows further propagation.

To receive axis events, a component must have the property focus set to True.

Mouse events can be grouped into three categories:

Mouse events are propagated from the top-most component under the mouse cursor down to the bottom component until it is handled by a component (by returning True in one of its event handling methods).

The following sub-sections describe how to handle input from each category of mouse event.

Note that mouse events are only generated when the object MouseCursor is active. For more details, see Mouse cursor.

def handleMouseButtonEvent( self, comp, event )

def handleMouseClickEvent( self, comp, pos )

def handleMouseEnterEvent( self, comp, pos )

def handleMouseLeaveEvent( self, comp, pos )

def handleMouseEvent( self, comp, event )

SimpleGUI offers support for drag-and-drop functionality. Drag-and-drop events can be grouped into two categories:

The following sub-sections describe how to handle input from each category of drag-and-drop event.

Note that drag-and-drop events are only generated when the MouseCursor is active. For more details, see Mouse cursor.

def handleDragStartEvent( self, comp, pos )

def handleDragStopEvent( self, comp, pos )

def handleDragEnterEvent( self, comp, pos, dropped )

def handleDragLeaveEvent( self, comp, pos )

def handleDropEvent( self, comp, pos, dropped )

You might find it useful to build your own Python module with custom GUI components. To do that, the best starting point is the module PyGUI.

PyGUI is the informal Python module for basic GUI elements, created for an internal project, and defined in fantasydemo/res/scripts/client/Helpers/PyGUI.

Starting from the basic functionality offered by SimpleGUI native components, you can code your own GUI toolkit in Python. Below are some examples of widgets you can create:

Font Definition Files are an XML file describing the font itself, the size of the glyph cache and the details of any preloaded glyphs :

<example_font.font>
    <creation>
        <sourceFont> Arial </sourceFont>
        <sourceFontSize> 16 </sourceFontSize>
        <effectsMargin>   1 </effectsMargin>
        <textureMargin>   1 </textureMargin>
        <dropShadow>   true </dropShadow>
        <shadowAlpha>   192 </shadowAlpha>
        <bold>         true </bold>
    </creation>
</example_font.font>

Since fonts are generated on-the-fly and their glyphs cached at runtime, this is all you need to do to begin using a new font. If the specified source font name does not exist on the system, then Windows will automatically choose the nearest matching typeface. To avoid any potential problems, please make sure you license and install your desired true-type fonts on the end-users' system (e.g. as part of the installer scripts). If you do decide to choose only Windows fonts (and assume they exist on the end-users' machines) then be aware that there are large differences in the standard fonts used by Windows, depending on the region. For example, if Windows has been installed with the Asian font pack, it will have a significantly different standard font sets by default (even for English language fonts).

See .font for a detailed description of the .font definition format.

<example_font.font>
    <creation>
        <sourceFont> Arial </sourceFont>
        ...
        <secondary>
            <sourceFont>      SimSun          </sourceFont>
            <unicodeRange>    U+2F00-U+9FFF   </unicodeRange>
        </secondary>
    </creation>
</example_font.font>

For languages that have a limited number of glyphs, for example English, you may want to preload all the glyphs into the cache so the client doesn't have to do anything more at runtime. Additionally, for larger Asian languages, you may still want to preload the cache with some often-used glyphs and from then on let the cache deal with whichever less-frequently used glyphs are required at runtime. The glyph caching system will still be in effect, but the cache will contain these glyphs to begin with. Additionally, the preloaded glyphs will never leave the cache during the duration of client execution, even if they are not used.

To preload glyphs or a range of glyphs, add any combination of the following tags into your font definition file.

<startChar>    32    </startChar>
<endChar>     192    </endChar>

or

<unicodeChar>  U+3000  <unicodeChar>

and/or

<unicodeRange>  U+AC00-U+D7A3   </unicodeRange>

Font glyphs are cached into a texture and are positioned on a regular grid (i.e. each grid element is the same width and height). In order to determine the size of each grid element up front, the glyph cache must know the dimensions of the widest character. By default the letter 'W' is used to calculate this size but this may be inappropriate for some character sets (including Chinese). If the widest character is too narrow, then visual artifacts will occur (characters will be clipped and neighbouring characters may 'leak' into each other). If it is too wide, then texture space will be wasted.

The widest character can be set using the <widestChar> tag in the font definition file. For example:

<example_font.font>
    <creation>
        ...
        <widestChar>  U+FF1F  </widestChar>
        ...
    </creation>
</example_font.font>

Text GUI Components are the main way that fonts are used to display text on-screen. For full details on Text GUI Components and their python GUI.Text counterpart, please refer to the Python Client API guide, under the section GUI.Text. The GUI.Text class supports the "font" attribute, this specifies the name of the font definition file, relative from the font root (see File Grammar Guide / resources.xml to see how to choose or change the font root folder.)

Here is an example of how to use the above example font file, which for now we will assume was saved to $FONT_ROOT/example_font.font.

import GUI
t = GUI.Text( "Some Text" )
t.font = "example_font.font"
GUI.addRoot(t)

The python API contains a function, BigWorld.saveFontCacheMap, that outputs the contents of the font's glyph cache to a DDS file, and the details of the font metrics to the .font file. Once this snapshot is taken, the .font file contains a <generated> section, and the font will no longer use the glyph cache, or be able to generate any new glyphs at runtime. To revert this change, simply remove the <generated> section from the .font file, and delete the .dds file. The texture will be named $FONT_ROOT/$FONTNAME_font.dds

import BigWorld
BigWorld.saveFontCacheMap( "super_turbo.font" )
#this generates super_turbo.font.dds, super_turbo.font.generated, and super_turbo.font.grid.dds

Once a snapshot has been created, the generated font .dds file can be loaded into Photoshop (you may need to download and install a .dds file plugin, depending on the version of Photoshop you are using). The glyphs can then be modified freely, however care must be taken not to go outside of the designated bounds for each character. The grid reference bitmap describes the go and no-go areas, and its alpha-channel has a copy of the glyphs to provide shape information and to simply demonstrate which character goes where.

Once you have modified a font texture, simply save over the *.font.dds file, and make sure both it and the *.font.generated file is committed as part of your asset repository. The presence of these files on disk instructs the font system to use the generated map from now on, and never attempt to expand the glyph cache. If glyphs are encountered that do not exist as part of the generated glyph cache, a warning will be output to the debug window and a filler character will be used.

Below is a portion of a font.grid.dds file, duplicated 3 times in photoshop with various colour channels extracted. You can see the three colour channels, with the alpha channel overlayed in white.

Example extracted from a .font.grid.dds file

On the left, the red channel describes the raw glyph rectangle as given by GDI+. As you can see in the example, the W and / glyphs go outside of this region. This is because this particular font already has a drop-shadow applied. The drop shadow, as provided in-engine, is a copy of the glyph, with a single pixel offset. This is demonstrated by the green region below.

The green region describes the glyph region plus the effect margin, and is the rectangle that will be drawn by the engine. Any pixels outside of the green area will be clipped when drawing text to the screen. Note too that when glyphs are drawn together, creating a string or a sentence, the red regions (raw size) determine the spacing between characters, and any effects margin is overlapped by the next glyph, this ensures that adding effects like drop shadows do not increase the width of your strings.

The blue region describes the glyph region plus effect margin plus texture margin. The texture margin is used to pad the glyphs apart in the texture map, to avoid any filtering artifacts. The texture margin should never be drawn, and is pretty much wasted space. If you are sure that your font will only be drawn at a 1:1 ratio between pixels and texels (for example the text will never be shrunk, or drawn in 3D where it can be rotated and mip-maps come into play), then you can safely do away with any texture margin.

[Installing and Using Input Method Editors, MSDN - http://msdn.microsoft.com/en-us/library/bb174599%28VS.85%29.aspx]

[Using an Input Method Editor in a Game, MSDN - http://msdn.microsoft.com/en-us/library/bb206300%28VS.85%29.aspx]

Disabled by default, IME can be enabled and disabled from the Python script. Typically, an application would enable IME when a text-input interface comes into focus (e.g. an edit box), and disable it again once it has lost focus. The enabled property on the PyIME object controls the current state:

BigWorld.ime.enabled = enableBoolean

The internal state will be reset when IME is disabled.

Once the IME system is enabled, the engine will start posting events to the personality script.

The task of actually displaying the IME interface based on the current underlying state is a task for the Python script programmer. The complexity of the IME presentation scripts will be determined by how many languages need to be supported, as each language has their own standard way of presenting the IME.

Note that due to the number of different IME's available for a single language, and due to differences between Windows XP and Windows Vista, it is recommended to test across these different configurations as much as possible.

Generally, when constructing an IME interface, the scripts will do the following:

An in game web GUI component is a GUI component capable of displaying 2D web content and sending mouse and keyboard events to that web content. There is some experimental (not supported) code also allows building a game integrated with ActionScript and JavaScript components (see below).

An in game web screen is a 3D in game entity with similar capabilities and use cases as the previously explained Web GUI Component. The main difference between the Web GUI component and the in game web screen is that the Web Screen is part of the 3D game scene and not a 2D GUI component. This Web Screen is located in a specific world location and isn't available for gamers as part of their HUD.

The TextureProvider returned by the WebPageProvider can be used to build a TextureFeed (similar to the one used for the WebScreen entity above). A VideoScreen Entity allows simple usage of the TextureFeed to map the texture into 3D world objects with the correct material settings (same as the tints used above). The exhibition room in the Urban space contains a teapot example of mapping a web texture into a world object using a VideoScreen entity.