Table of Contents
This document is a technical design overview for the Client Engine for 3d engine Technology. It is part of a larger set of documentation describing the whole system. It only includes references to the BigWorld Server in order to provide context. Readers interested only in the workings of the BigWorld Client may ignore the server information.
The intended audience is technical-typically MMOG developers and designers.
For API-level information, please refer to the online documentation.
Note
For details on BigWorld terminology, see the document Glossary of Terms.
The BigWorld Client provides the end-user experience of the BigWorld client/server architecture. In a BigWorld client/server implementation, the client connects to the server using UDP/IP over the Internet.
The BigWorld Client presents the user with a realistic and immersive 3D environment. The contents of that environment are a combination of static data stored with the client, and dynamic data sent from the server. The user interacts with the world through an avatar (character) that he or she controls. The movement and actions of that avatar are relayed to the server. The avatars controlled by other connected users are part of the dynamic data sent from the server.
Client perspective of BigWorld system. Note that the BigWorld server is not just one machine, although the client can treat it as such.
Developers may choose to integrate the client with their own server technology, but if they do, they will have to address problems already tackled by the BigWorld architecture, like:
-
Uniform collision scene (used on client and server).
-
Uniform client/server scripting (used on client and server).
-
Tools that produce server and client content.
-
Optimised low bandwidth communication protocol.
The client initialises itself, connects to the server, and then runs in its main thread a standard game loop (each iteration of which is known as a frame):
-
Receive input
-
Update world
-
Draw world
Each step of the frame is described below:
-
Input
Input is received from attached input devices using DirectInput. In a BigWorld client/server implementation, input is also received over the network from the server using WinSock 2.
-
Update
The world is updated to account for the time that has passed since the last update.
-
Draw
The world is drawn with the 3D engine Moo, which uses Direct3D (version 9c). For details, see 3D Engine (Moo).
A number of other objects also fall into the world's 'update then draw' system. These include a dozen related to the weather and atmospheric effects (rain, stars, fog, clouds, etc.), various script assistance systems (targeting, combat), pools of water, footprints, and shadows.
There are other threads for background scene loading and other asynchronous tasks.
The BigWorld client is a generic executable that is fully configurable via the game specific resources. The location of these resources must be supplied to the client so that it can initialise correctly.
Typically, at least two resource paths need to be specified - your project specific resource path and the BigWorld resource path (which supplies common resources such as standard shaders, fonts, scripts, etc). For example, if your game was located in "my_game", the two resource paths you would define are:
-
my_game/res -
bigworld/res
When the engine tries to access a resource, it will look in each
resource tree in the order that they are given to the engine. As an
example, if the client scripts request the resource named
sets/models/foo.model it tries the following
locations:
-
my_game/res/sets/models/foo.model -
bigworld/res/sets/models/foo.model
The search will stop at the first valid file found. As such, it is
possible to override resources specified in bigworld/res by
placing it in the same location within my_game/res.
There are two ways search paths can be specified:
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>
Note
Paths are defined relative to the location of
paths.xml.
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
Note
These paths must be defined relative to the executable location, not the current working directory.
Configuration files are defined relatively to one of the entries in
the resources folders list (or
<res>). For details on
how BigWorld compiles this list, see Resource search paths
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:
-
EXE_PATH— The preferences XML file will be stored relative to the location of the client executable. This is the default location if none is supplied. -
CWD— The preferences XML file will be stored relative to the current working directory. Note that if the working directory changes during runtime, it will save in the new working directory. -
ROAMING_APP_DATA— The preferences XML file will be stored relative to the current user's roaming AppData directory. In other words, if the user is on a domain the data will be syncronised with the domain controller when the user logs in and out of Windows. -
LOCAL_APP_DATA— The preferences XML file will be stored relative to the current user's local AppData directory. -
APP_DATA— This is the same asROAMING_APP_DATA. -
MY_DOCS— The preferences XML file will be stored relative to the current user's My Documents directory. -
MY_PICTURES— The preferences XML file will be stored relative to the current user's My Pictures directory. -
RES_TREE— The preferences XML file will be stored relative to the first resource path found inpaths.xml.
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 .
BigWorld uses a left-handed coordinate system. The x-axis points "left", the y-axis points "up" and the z-axis points "forward".
yaw is rotation around the y-axis. Positive is to the right, negative is to the left.
pitch is rotation around the x-axis. Positive is nose pointing down, negative is nose pointing up.
roll is rotation around the z-axis. Positive is to the left, negative is to the right.