Tutorial

All files used in this tutorial are provided in the tutorial directory of your BigWorld package.

As shipped, the files represent the final state of the completed tutorial. If you are new to BigWorld development, then you probably want to see the minimal set of files required at each stage of the tutorial, instead of just diving into the completed tutorial (which while much simpler than FantasyDemo, still consists of a fair number of files). To help you with this, BigWorld provides a utility (tutorial/bw_generate_res_trees.py) that strips down the resource tree to the minimal state needed for a particular stage of the tutorial. If you run the utility with the symbolic name of a chapter (e.g., ./tutorial.py CLIENT_SERVER), then the stripped resources are extracted to an appropriately named <res> directory in the tutorial directory (e.g., tutorial/res_client_server). You can then alter the paths.xml^[1] and .bwmachined.conf^[2] settings to point to these stripped trees.

Even if you are doing the final stage of the tutorial, it may be helpful to run this stripping utility before looking through the source code, as it removes all inclusion/exclusion steps that we have inserted to facilitate the stripping process and makes the code easier to read.

There may be times while working through the tutorial that the client won't start due to some error in the scripts. In order to discover the cause of the error, use a program such as DebugView (available on the Microsoft website) which captures and displays debug output.

The FantasyDemo project is located in the fantasydemo directory in C:\BigWorld. Following that convention, we will start our new tutorial project in the same directory, by creating a new directory called tutorial in C:\BigWorld. All resources and scripts specific to this project will be located within this directory.

Please note that the tutorial project is shipped as part of your package. A skeleton project called my_game is also shipped as part of the Indie edition, in order to allow you to start a new project easily. Please review the Getting Started document for more details.

The BigWorld client is a generic executable, located at bigworld\bin\client\bwclient.exe. Since it is independent of the game resources it loads, it needs to be instructed as to where to find your project's resources.

The easiest way to go about this is to use the --res command line switch in conjunction with a batch file to provide a convenient way to start the client for your particular game. A benefit of doing it this way is that it also keeps the resource path configuration self contained within your project folder. Typically, you would create a batch file named run.bat and it would be located at the root level of your project folder (i.e. in my_game) and would look something like:

"..\bigworld\bin\client\bwclient.exe" --res %~dp0res;../../../bigworld/res

Keep in mind that paths are relative to the executable location, not the current working directory. The above example uses %~dp0 to grab the batch file's directory as an absolute path in order to keep the batch file generic.

Resource directories for BigWorld games are typically named res, therefore you can simply create a directory called res in the tutorial directory. This top-level resources directory will contain all game-specific scripts, assets, and configuration files.

Entities are game objects that have a position. Not every class that you write in your game must be an entity, but most objects that are part of the game mechanics will be. Examples of entities would be the player, NPCs, chat rooms, dropped items, etc.... Examples of objects that need not be entities might be helper classes that are only attached to/used by a single entity type.

<root>
   <ClientServerEntities>
      <Avatar/>
   </ClientServerEntities>
   <ServerOnlyEntities>
   </ServerOnlyEntities>
</root>

<root>
   <Volatile>
      <position/>
      <yaw/>
   </Volatile>
   <Properties>
      <playerName>
         <Type>   UNICODE_STRING       </Type>
         <Flags>  ALL_CLIENTS  </Flags>
      </playerName>
   </Properties>
   <ClientMethods>
   </ClientMethods>
   <CellMethods>
   </CellMethods>
   <BaseMethods>
   </BaseMethods>
</root>

tutorial
+-res
  +-scripts
    +-base
    +-cell
    +-client
    +-entity_defs

import BigWorld

# These are constants for identifying keypresses, mouse movement etc
import Keys

class Avatar( BigWorld.Entity ):

   def onEnterWorld( self, prereqs ):
      pass

class PlayerAvatar( Avatar ):

   def onEnterWorld( self, prereqs ):

      Avatar.onEnterWorld( self, prereqs )

      # Set the position/movement filter to correspond to an player avatar
      self.filter = BigWorld.PlayerAvatarFilter()

      # Setup the physics for the Avatar
      self.physics = BigWorld.STANDARD_PHYSICS
      self.physics.velocityMouse = "Direction"
      self.physics.collide = True
      self.physics.fall = True

   def handleKeyEvent( self, event ):

      # Get the current velocity
      v = self.physics.velocity

      # Update the velocity depending on the key input
      if event.key == Keys.KEY_W:
         v.z = event.isKeyDown() * 5.0
      elif event.key == Keys.KEY_S:
         v.z = event.isKeyDown() * -5.0
      elif event.key == Keys.KEY_A:
         v.x = event.isKeyDown() * -5.0
      elif event.key == Keys.KEY_D:
         v.x = event.isKeyDown() * 5.0

      # Save back the new velocity
      self.physics.velocity = v

The next required script for our basic client is the personality script. The easiest way to think of this script is as the bootstrap script for each component of a BigWorld system.

There should be one personality script in each script directory (i.e., for cell, base, and client) and they are used for defining callbacks to be called on startup and shutdown, as well as other global, non-entity-related functionality. On the client, this might include menu systems, user input management, camera control, etc...

For details on the client personality script, see the Client Programming Guide's section Scripting, in Personality script.

Save the basic personality script below as tutorial/res/scripts/client/BWPersonality.py:

# This is the client personality script for the BigWorld tutorial.  Think of
# it as the bootstrap script for the client.  It contains functions that
# are called on initialisation, shutdown, and handlers for various input
# events.
import BigWorld

# ----------------------------------------------------------------------------
# Section: Required callbacks
# ----------------------------------------------------------------------------
# The init function is called as part of the BigWorld initialisation process.
# It receives the BigWorld xml config files as arguments.  This is the best
# place to configure all the application-specific BigWorld components, like
# initial camera view, etc...
def init( scriptConfig, engineConfig, prefs ):

   initOffline( scriptConfig )

   # Hide the mouse cursor and restrict it to the client area of the window.
   GUI.mcursor().clipped = True
   GUI.mcursor().visible = False

# This is called immediately after init() finishes.  We're done with all our
# init code, so this is a no-op.
def start():
   pass

# This method is called just before the game shuts down.
def fini():
   pass

# This is called by BigWorld when player moves from an inside to an outside
# environment, or vice versa.  It should be used to adapt any personality
# related data (eg, camera position/nature, etc).
def onChangeEnvironments( inside ):
   pass

# This is called by the engine when a system generated message occurs.
def addChatMsg( msg ):
   print "addChatMsg:", msg

# Keyboard event handler
def handleKeyEvent( event ):
   return False

# Mouse event handler
def handleMouseEvent( event ):
    return False

# Joystick event handler
def handleAxisEvent( event ):
    return False

# ----------------------------------------------------------------------------
# Section: Helper methods
# ----------------------------------------------------------------------------
def initOffline( scriptConfig ):

   # Create a space for the client to inhabit
   spaceID = BigWorld.createSpace()

   # Load the space that is named in script_config.xml
   BigWorld.addSpaceGeometryMapping(
      spaceID, None, scriptConfig.readString( "space" ) )

   # Create the player entity, using positions from script_config.xml
   playerID = BigWorld.createEntity( scriptConfig.readString( "player/entityType" ),
                                     spaceID, 0,
                                     scriptConfig.readVector3( "player/startPosition" ),
                                     scriptConfig.readVector3( "player/startDirection" ),
                                     {} )

   BigWorld.player( BigWorld.entities[ playerID ] )

   # Use first person mode since we are not using models yet.
   BigWorld.camera().firstPerson = True

Example tutorial/res/scripts/client/BWPersonality.py

This personality script provides an initOffline method that contains enough code to get a basic client going, as well as stub implementations of all other required callbacks. The initialisation code expects various configuration files to be passed to it, and expects scriptConfig to contain particular settings, such as space, player/entityType, and so on.

The following sections describe how to set up those files, so they will be ready to be passed to the personality script on startup.

At a minimum, the BigWorld client expects three XML configuration files to be passed into the personality script at startup:

The <engine_config>.xml file is used for setting various configurable properties on the client engine, including the name of the game's personality. We will re-use the engine settings used for FantasyDemo by copying fantasydemo/res/engine_config.xml to tutorial/res/engine_config.xml, ensuring that we change the <personality> setting to BWPersonality. Notice that this corresponds to the file BWPersonality.py that we created in The personality script).

The <scripts_config>.xml file is used to define the settings that the personality script is expecting — save the following into tutorial/res/scripts_config.xml:

<scripts_config.xml>
   <!-- The contents of this file are passed to the personality script
        as the first argument in the init function (as a data section). Its
        grammar is solely defined by the personality script. -->
   <space> spaces/main </space>
   <player>
      <entityType> Avatar </entityType>
      <!-- This is the entity type of the player that will be created. You must implement
           a Player<class> type (e.g. PlayerAvatar) to use this type as a client proxy. The following options -->
      <startPosition>  0.0 1.25 0.0 </startPosition>
      <startDirection> 1.0 0.0  0.0 </startDirection>
      <!-- are used by the personality script to provide a start position and
           facing dir for players if there is no space specific spawn point. -->
    </player>
</scripts_config.xml>

Example tutorial/res/scripts_config.xml

At this stage, the values for the configuration settings expected by the personality script's init method have been provided. The only thing still missing for our basic client is the actual space data. The script configuration passes the string spaces/main into the personality script as the space in which the client entity will be created, so next we will create a basic space to walk around in.

Before starting World Editor, you will need to tell it where to find the resources for your particular project. To do this, open bigworld/tools/worldeditor/paths.xml and replace the reference to FantasyDemo to your own project. For example,

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

Example bigworld/worldeditor/paths.xml

To create a simple space that can be navigated, follow the steps below:

Having carried out the steps in the previous sections of this tutorial, you can now run the client . To do that, use the run.bat you created earlier. You should have a basic first-person player that can walk around a space using mouse-look and WASD controls.

A simple first-person client

Prior to progressing through this part of the tutorial it is necessary to install and configure the BigWorld server. If you haven't already done this please proceed to the Server Installation Guide

At this point it is also relevant to address the issue of sharing files between Linux and Windows machines. Since there are many files that are read by both the client and the server (tutorial/res/scripts/entity_defs/*, space data, etc), it is necessary to keep them all on a single file system that is shared between the client and server, rather than having to keep them synchronised manually. Please refer to the Client Programming Guide's section on Shared Development Environments for more information on this topic.

For the purposes of this tutorial, we will assume that you have mounted your Windows directory tree at $HOME/bigworld_windows_share on your Linux file system.

In BigWorld, spaces are separate coordinate systems. Each space can have one or more geometry mappings (as created in the World Editor). Cell entities are associated with a single space at any one time. These may be used to implement things like planets, mission instances, apartments or game sharding.

A new space is created by creating a cell entity in a new space. It is typical to have an entity type that is responsible for space creation.

<root>
   <ClientServerEntities>
      <Avatar/>
   </ClientServerEntities>
   <ServerOnlyEntities>
      <Space/>
   </ServerOnlyEntities>
</root>

<root>
   <Properties>
      <spaceDir>
         <Type>          STRING          </Type>
         <Flags>         BASE            </Flags>
      </spaceDir>
   </Properties>

   <ClientMethods>
   </ClientMethods>

   <CellMethods>
      <addGeometryMapping>
         <Arg>           STRING          </Arg>
      </addGeometryMapping>
   </CellMethods>

   <BaseMethods>
   </BaseMethods>
<root>

import BigWorld

class Space( BigWorld.Base ):

    def __init__( self ):
        
        BigWorld.Base.__init__( self )

        # Create this entity in a new space
        self.createInNewSpace()
        self.cell.addGeometryMapping( self.spaceDir )
    
        self.registerGlobally( "DefaultSpace", self.onRegistered )
    
    def onRegistered( self, succeeded ):
        if not succeeded:
            print "Failed to register space."
            self.destroyCellEntity()

    def onLoseCell( self ):

        # Once our cell entity is destroyed, it's safe to clean up the Proxy.
        # We can't just call self.destroy() in onClientDeath() above, as
        # destroyCellEntity() is asynchronous and the cell entity would still
        # exist at that point.
        self.destroy()

import BigWorld

class Space( BigWorld.Entity ):
        
    def __init__( self, nearbyEntity ):
        BigWorld.Entity.__init__( self )

        # This is the first entity created for the space
        assert( nearbyEntity is None )
        
    def onDestroy( self ):
        # Destroy the space and all entities in it
        self.destroySpace()

    def addGeometryMapping( self, geometryToMap ):
        # The base informs us what geometry to map.
        BigWorld.addSpaceGeometryMapping( self.spaceID, None, geometryToMap )

Just like the client, the server uses personality scripts to perform bootstrap functionality on each CellApp and BaseApp. For the moment, we are only interested in the onBaseAppReady callback in the BaseApp personality script, which we will use to create a space.

Our initial revision of tutorial/res/scripts/base/BWPersonality.py is displayed below:

# Base bootstrap script
import BigWorld

def onInit( isReload ):
   pass

def onBaseAppReady( isBootstrap, didAutoLoadEntitiesFromDB ):
   # Only on the first baseapp
   if isBootstrap:
     # Create a Space entity that will create a space with our geometry.
     BigWorld.createBaseLocally( "Space", spaceDir = "spaces/main" )

Example tutorial/res/scripts/base/BWPersonality.py

A Space entity is created with the spaceDir property set to "spaces/main".

Our initial revision of tutorial/res/scripts/cell/BWPersonality.py is displayed below:

# Base bootstrap script
import BigWorld

def onInit( isReload ):
   pass

def onCellAppReady( isFromDB ):
   pass

Example tutorial/res/scripts/cell/BWPersonality.py

Our implementation of the scripts is trivial and provides only stub implementations of callbacks that will be explained later.

For a complete list of the available personality script callbacks, see the documentation for the BWPersonality module in Client Python API, Client Python API, and Client Python API.

The next step is to define the server-side logic that goes with our Avatar class. Even if we did not want to define any server-side logic for our Avatar, we would still need to provide at least stub implementations of Avatar.py in the base and cell directories so that the base and cell parts of our Avatar entity can be created.

First we need to define the base part of the Avatar in tutorial/res/scripts/base/Avatar.py:

import BigWorld

# Must derive from BigWorld.Proxy instead of BigWorld.Base if this entity type
# is to be controlled by the player.
class Avatar( BigWorld.Proxy ):

   def __init__( self ):
      BigWorld.Proxy.__init__( self )

      # Set our spawn position.
      self.cellData[ "position" ] = (0,0,0)

      # Spawn in the default space.
      self.createCellEntity( BigWorld.globalBases[ "DefaultSpace" ].cell )

   def onClientDeath( self ):
      # We ensure our cell entity is destroyed when the client disconnects. 
      self.destroyCellEntity()

   def onLoseCell( self ):
      # Once our cell entity is destroyed, it is safe to clean up the Proxy. We cannot
      # just call self.destroy() in onClientDeath() above, as destroyCellEntity() 
      # is asynchronous and the cell entity would still exist at that point.
      self.destroy()

Example tutorial/res/scripts/base/Avatar.py

The constructor for the base entity creates the cell entity in our space created earlier. It was registered in BigWorld.globalBases as "DefaultSpace".

There is a little bit of housekeeping here too — we have provided implementations for the onClientDeath and onLoseCell callbacks, which clean up the cell and base parts of the entity when the client disconnects from the server.

At this stage we do not need to define any interesting logic on the cell entity, so we provide a stub implementation in tutorial/res/scripts/cell/Avatar.py:

import BigWorld

class Avatar( BigWorld.Entity ):
   def __init__( self, nearbyEntity ):
      BigWorld.Entity.__init__( self )

Example tutorial/res/scripts/cell/Avatar.py

We need to add code to our basic client to have it connect to a server. If you have used FantasyDemo, you will have experienced the various GUI-based methods that can be used to connect to a server. Since we are not writing GUI code yet, we will just enter the address of our server into tutorial/res/scripts_config.xml and have the personality script read it from there.

We will also add an entry to control whether the client should attempt to connect to a server, or just explore the space offline as in the previous stage of the tutorial.

The relevant changes to tutorial/res/scripts_config.xml are displayed below:

...
   <server>
      <online> true </online>
      <!-- Whether the client actually connects to the server. -->
      <host> 10.40.3.23 </host>
      <!-- The server to connect to. Ideally we would allow this to be entered via an in-game
           GUI (or leverage the server discovery stuff) but for now we'll just hardcode it. -->
   </server>
...

Example tutorial/res/scripts_config.xml

The next step is to implement the function call initOnline in the client personality script tutorial/res/scripts/client/BWPersonality.py and switch between calling it and calling initOffline based on the online option in tutorial/res/scripts_config.xml.

To achieve that, make the changes to tutorial/res/scripts/client/BWPersonality.py as illustrated below.

...
def init( scriptConfig, engineConfig, prefs ):
   if scriptConfig.readBool( "server/online" ):
      initOnline( scriptConfig )
   else:
      initOffline( scriptConfig )
...

def initOnline( scriptConfig ):
   class LoginParams( object ):
      pass

   def onConnect( stage, step, err = "" ):
      pass

   # Connect to the server with an empty username and password.  This works
   # because the server has been set up to allow logins for any user/pass.
   BigWorld.connect( scriptConfig.readString( "server/host" ),
                     LoginParams(), onConnect )

Example tutorial/res/scripts/client/BWPersonality.py

Notice that we no longer need to do client-side space creation, geometry mapping, or entity creation; these functions now happen on the server side. The client will automatically perform the necessary client-side actions based on the server-side game state.

The last line of initOffline in the personality script sets the camera to use first-person mode. We chose to do this in the first part of the tutorial because we wanted to get a client up and running as quickly and simply as possible, and using first-person mode allowed us to ignore the issue of rendering the player himself.

However, since we are now implementing a client-server game where multiple clients can log in and inhabit the same space, it will be helpful if they have models so that they can see each other!

We have provided a basic biped model in res/characters/bipedgirl.model, which we will use for all Avatars. Edit the enterWorld callback for the Avatar class in tutorial/res/scripts/client/Avatar.py as follows:

...
class Avatar( BigWorld.Entity ):

   def enterWorld( self ):

      # Set the position/movement filter to correspond to an avatar
      self.filter = BigWorld.AvatarFilter()

      # Load up the bipedgirl model
      self.model = BigWorld.Model( "characters/bipedgirl.model" )
...

Example tutorial/res/scripts/client/Avatar.py

The BigWorld server uses the file your_game/res/server/bw.xml for configuring options on the various server components. For a comprehensive list of configuration options along with a detailed description, see the Server Operations Guide's section Server Configuration with bw.xml.

Typically, the bw.xml file includes a BigWorld provided default configuration file which contains recommended default values for all the available configuration options. This is achived by using the <parentFile> tag as follows:

<root>
   ...
   <parentFile> server/development_defaults.xml </parentFile>

You will notice that in the example above, the included file is development_defaults.xml. This file provides good working defaults for a game development environment that will generate more warnings and intentionally crash the server in certain circumstances to ensure that critical issues are caught prior to the release of a game. The development defaults file however is only a small file that modifies a subset of values from the file bigworld/res/server/production_defaults.xml. The production defaults file aims to provide a comprehensive set of options and default values to be used for a game in a live production environment and can be used as a reference point when searching for a specific option.

While it is anticipated that the majority of configuration options will not need to be modified, if you need to change a value or are simply curious as to the purpose of an option, complete documentation for the BigWorld server configuration options can be found in the Server Operations Guide's section Server Configuration with bw.xml.

To get our basic game up and running, we need to set a few options to specify what entity type the player should be connected to once logged in, and to allow players to log in with unknown usernames (just for convenience while developing).

Save the following in tutorial/res/server/bw.xml:

<root>
   <parentFile> server/development_defaults.xml </parentFile>
   <billingSystem>
      <entityTypeForUnknownUsers>  Avatar </entityTypeForUnknownUsers>
      <shouldAcceptUnknownUsers>   true   </shouldAcceptUnknownUsers>
      <shouldRememberUnknownUsers> false  </shouldRememberUnknownUsers>
   </billingSystem>
</root>

Example tutorial/res/server/bw.xml

At this point of the tutorial, it is assumed that you have set up your Linux machine as described in the Server Installation Guide. In particular, this assumes you have installed BWMachined on your Linux machine and have installed the Web Console somewhere on the local network. For details on Web Console see the Server Operations Guide's section Cluster Administration Tools, in WebConsole).

Before we can start the server, we need to specify where the server should get its binaries and resources from. This is a concept similar to the paths.xml files used by the client and tools.

We firstly need to know the directory the game resources are located on the Linux machine. If you have been developing the game resources on your Windows machine and have shared them using the setup_win_dev script, the resources are most likely located in $HOME/bigworld_windows_share. Check the directory where you believe the resources are located actually contain the correct files. For example:

$ ls $HOME/bigworld_windows_share
bigworld  fantasydemo  my_game  readme.html  rpm  template  tutorial

We now run the bw_configure script providing the location of the game resources we wish to use. This will differ slightly depending on the BigWorld Edition you are using.

$ bw_configure
Game resource path [~/my_game/res]: ~/bigworld_windows_share/tutorial/res
Writing to /home/fred/.bwmachined.conf succeeded

Installation root : /opt/bigworld/current/server
BigWorld resources: /opt/bigworld/current/server/res
Game resources    : /home/fred/bigworld_windows_share/tutorial/res

# Generated by ./bw_configure
/opt/bigworld/current/server;/home/fred/bigworld_windows_share/tutorial/res:/opt/bigworld/current/server/res

$ bw_configure
Installation root [~/mf]: ~/mf
Game resource path [~/my_game/res]: ~/mf/tutorial/res
Writing to /home/fred/.bwmachined.conf succeeded

Installation root : /home/fred/mf
BigWorld resources: /home/fred/mf/bigworld/res
Game resources    : /home/fred/mf/tutorial/res

# Generated by ./bw_configure
/opt/bigworld/current/server;/home/fred/bigworld_windows_share/tutorial/res:/opt/bigworld/current/server/res

The chat console GUI needs to be able to display a few lines of text and be able to accept and display the player's input on a separate line, the edit line. It is implemented in tutorial/res/script/client/Helpers/ChatConsole.py.

That chat console displays through two GUI components. A window that darkens the background so the text is easier to read and a multiline text component which is a child of the window. These are both set up in the __init__() method.

import string
import BigWorld
import GUI
import Keys
import collections

class ChatConsole( object ):

    sInstance = None

    def __init__( self, numVisibleLines = 4 ):

		self.numVisibleLines = numVisibleLines
		self.lines = collections.deque()
		self.editString = ""

		self.box = GUI.Window( "system/maps/col_white.bmp" )
		self.box.position = ( -1, -1, 0 )
		self.box.verticalAnchor = "BOTTOM"
		self.box.horizontalAnchor = "LEFT"
		self.box.colour = ( 0, 0, 0, 128 )
		self.box.materialFX = "BLEND"
		self.box.width = 2
		self.box.script = self

		self.box.text = GUI.Text()
		self.box.text.verticalPositionMode = "CLIP"
		self.box.text.horizontalPositionMode = "CLIP"
		self.box.text.position = ( -1, -1, 0 )
		self.box.text.verticalAnchor = "BOTTOM"
		self.box.text.horizontalAnchor = "LEFT"
		self.box.text.colourFormatting = True
		self.box.text.multiline = True

		GUI.addRoot( self.box )

		self.active = True
		self.update()
		self.box.height = self.box.text.height * ( numVisibleLines + 1 )
		self.editing( False )
    

The Avatar and Personality scripts calls three of the chat console's methods:

    @classmethod
    def instance( cls ):
        """
        Static access to singleton instance.
        """

        if not cls.sInstance:
            cls.sInstance = ChatConsole()

        return cls.sInstance


    def editing( self, state = None ):

        if state is None:
            return self.active
        else:
            self.active = state
            self.box.visible = state


    def write( self, msg ):

        self.lines.append( msg )

        # Rotate out the oldest line if the ring is full
        if len( self.lines ) > self.numVisibleLines:
            self.lines.popleft()

        self.editing( True )
        self.update()

    

When the chat console is visible it also parses key events. Printable characters are added to the edit line and removed with the backspace. The return key sends the edit line to the server for propagation and puts it into the main display. This is done with the commitLine(). When the line is committed or anything else changes the update() method will correctly set the text field of the text component. Finally the escape key closes the chat console.

    def commitLine( self ):

        # Send the line of input as a chat message
        BigWorld.player().cell.say( unicode( self.editString ) )

        # Display it locally and clear it
        self.write( "You say: " + self.editString )
        self.editString = ""


    def update( self ):

        if self.active is False:
            return

        self.box.text.text = ""

        # Redraw all lines in the ring
        for line in self.lines:
            self.box.text.text = self.box.text.text + line + "\n"

        # Draw the edit line
        self.box.text.text = self.box.text.text + "\cffff00ff;" + self.editString + "_" + "\cffffffff;"


    def handleKeyEvent( self, event ):

        if event.isMouseButton():
            return False

        if self.active is False:
            return False

        if event.isKeyDown():
            if event.key == Keys.KEY_ESCAPE:
                self.editing( False )
            elif event.key == Keys.KEY_RETURN:
                self.commitLine()
            elif event.key == Keys.KEY_BACKSPACE:
                self.editString = self.editString[:len( self.editString ) - 1]
            elif event.character is not None:
                self.editString = self.editString + event.character

            self.update()
            return True

        return False
    

We need to implement methods on both the client and the server to make our chat system work:

Before implementing these methods, they need to be declared in tutorial/res/scripts/entity_defs/Avatar.def:

...
   <ClientMethods>
      <!-- Chat to people within 50 metres -->
      <say>
         <Arg> UNICODE_STRING </Arg> <!-- message -->
         <DetailDistance> 50     </DetailDistance>
      </say>
   </ClientMethods>
   <CellMethods>
      <!-- Cell part of the chat implementation -->
      <say>
         <Exposed/>
         <Arg>            UNICODE_STRING </Arg>
      </say>
   </CellMethods>
...

Example tutorial/res/scripts/entity_defs/Avatar.def

The step above adds the method definitions to the previously empty client and cell method sections. The cell method definition includes the <Exposed/> tag, which exposes the method to the client. Without this, the method cannot be called from the client. The definition file also uses BigWorld's method LODing feature, by declaring a <DetailDistance> of 50m, which means that referring to self.allClients or self.otherClients from within this method will not refer to all clients in that entity's AoI, just those within 50m.

Having declared these methods, we must now provide their implementations. In tutorial/res/scripts/cell/Avatar.py, add the following:

...
   def say( self, id, message ):
      if self.id == id:
         self.otherClients.say( message )

Example tutorial/res/scripts/cell/Avatar.py

Even though we prototyped the cell method to take only the message as an argument in the definition file, our implementation expects another argument (id) before the declared arguments. This is because this method was declared as <Exposed/>, and the ID passed as an argument is that of the client who called the exposed method. Please note that this may not be the client who is attached to this Avatar, so we add a check to make sure the calling client is in fact the owner of this entity.

Now we implement the client entity's say method in tutorial/res/scripts/client/Avatar.py:

class Avatar( BigWorld.Entity ):
   ...
   def say( self, msg ):
      ChatConsole.ChatConsole.instance().write( "%d says: %s" % (self.id, msg) )
	

Example tutorial/res/scripts/client/Avatar.py

Now you should have a basic usable chat system. Connect a couple of clients to a running server and test it out!

The EntityLoader class exists only on the base entity, and in this tutorial will be implemented in the same Python module file as the Space entity. The following operations are performed:

# scripts/base/Space.py

class Space( BigWorld.Base ):
    ...

    def onGetCell( self ):        
        print "Space.onGetCell loading entities from '%s'" % self.spaceDir
        BigWorld.fetchEntitiesFromChunks( self.spaceDir,
            EntityLoader( self ) )
    ...

class EntityLoader( object ):
    def __init__( self, spaceEntity ):
        self.spaceEntity = spaceEntity

    def onSection( self, entity, matrix ):
        entityType = entity.readString( "type" )
        properties = entity[ "properties" ]
        pos = matrix.applyToOrigin()

        # Create entity base
        BigWorld.createBaseAnywhere( entityType,
            properties,
            createOnCell = self.spaceEntity.cell,
            position = pos,
            direction = (matrix.roll, matrix.pitch, matrix.yaw) )

    def onFinish( self ):
        print "Finished loading entities for space", self.spaceEntity.spaceDir

Adjusted example tutorial/res/scripts/base/Space.py

Before creating an entity, we need to determine what functionality is required. For this tutorial we will to create an NPC which will greet a player when they get within a certain radius (think of a person who stands in a supermarket entrance greeting people).

Entity requirements:

We shall give this entity the class name Greeter.

For this tutorial, we have provided the 3D Studio Max source file to the Barbarian model (a fantasy themed human). The model needs to prepared for use by the engine and needs to be configured to satisfy the requirements of the Greeter entity. This section assumes the BigWorld exporters have already been installed (see the Content Tools Reference Guide).

Detailed documentation about the exporters and tools can be found in the Content Tools Reference Guide and the Content Creation Manual.

In order to insert the model as an entity into a space, we need to create the entity scripts. These are written in Python and perform game-specific logic and are split up into three parts: base, cell, and client.

Please refer to the Python API reference documents^[9] for detailed information on the API's mentioned here.

<root>
   <ClientServerEntities>
      <Avatar/>
      <Greeter/>
   </ClientServerEntities>
   <ServerOnlyEntities>
      <Space/>
   </ServerOnlyEntities>
</root>

<root>
    <Properties>
        <radius>
            <Type>          FLOAT
                <Widget>    RADIUS
                    <colour>    255 0 0 192   </colour>
                    <gizmoRadius>    2        </gizmoRadius>
                </Widget>
            </Type>
            <Flags>          CELL_PRIVATE    </Flags>
            <Default>        3.0             </Default>
            <Editable>       true            </Editable>
        </radius>
        
        <activated>
            <Type>           INT8            </Type>
            <Flags>          ALL_CLIENTS     </Flags>
            <Default>        1               </Default>
        </activated>

        <createOnCell>
             <Type>    MAILBOX        </Type>
             <Flags>   BASE           </Flags>
        </createOnCell>
    </Properties>

    <ClientMethods>
        <greet>
            <Arg> UINT32 </Arg> <!-- Entity ID of who we are greeting -->
            <Arg> STRING </Arg> <!-- Our greeting message -->
        </greet>
    </ClientMethods>

    <CellMethods>
        <toggleActive>
            <Exposed/>
        </toggleActive>
    </CellMethods>

    <BaseMethods>
    </BaseMethods>
</root>

import BigWorld

class Greeter( BigWorld.Base ):
    def __init__( self ):
        BigWorld.Base.__init__( self )
        self.createCellEntity( self.createOnCell )

    def onLoseCell( self ):
        self.destroy()

import BigWorld
import Avatar
import random

MESSAGES = [ "Hello BigWorld", "Have a nice day" ]

class Greeter( BigWorld.Entity ):

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

        # Setup the trap
        self.addProximity( self.radius, 0 )

    def onEnterTrap( self, entityEntering, range, controllerID ):
        # If we are not active, do nothing.
        if not self.activated:
            return

        # Filter by entity class type
        if not isinstance( entityEntering, Avatar.Avatar ):
            return

        # Notify clients.
        self.allClients.greet( entityEntering.id, random.choice(MESSAGES) )

    def toggleActive( self, sourceID ):
        # Get the entity who called us. If the entity can't be found then they
        # obviously not near by so just bail out.
        try:
            sourceEntity = BigWorld.entities[ sourceID ]
        except KeyError:
            return
            
        # Get the distance between ourself and the Avatar
        dist = sourceEntity.position.distTo( self.position )
        
        # Do a check to make sure they are close enough.
        if dist > self.radius:
            return
            
        # All good, toggle our state. The activated property will be automatically 
        # propagated to all clients once this server tick is complete.
        self.activated = not self.activated

# Greeter.py

import BigWorld
import GUI
import Math

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

GREETER_MODEL_NAME = "characters/barbarian.model"

class Greeter( BigWorld.Entity ):
    ....

    def prerequisites( self ):
        return [ GREETER_MODEL_NAME ]

class Greeter( BigWorld.Entity ):
    ....

    def onEnterWorld( self, prereqs ):
        # Setup our model.
        self.model = BigWorld.Model( GREETER_MODEL_NAME )

        # Setup an appropriate filter.
        self.filter = BigWorld.DumbFilter()

    def onLeaveWorld( self ):
        # Clean up.
        self.model = None
        self.filter = None

class Greeter( BigWorld.Entity ):
    ....

    def greet( self, targetID, msg ):
        # Grab the entity instance, if for some reason we don't have it just do nothing.
        try:
            targetEntity = BigWorld.entities[targetID]
        except KeyError:
            return
            
        # Try to play the Wave action. If it doesn't exist, print a warning.
        try:
            self.model.Wave()
        except AttributeError:
            print "WARNING: Greeter model missing Wave action (%s)" % self.model.sources
    
        # Display the greet message above our head.
        addressee = targetEntity.name        
        if targetID == BigWorld.player().id:
            addressee += "! Yes you"
            
        self._displayMessage( "Hey %s! '%s'!" % (addressee, msg) )

class Greeter( BigWorld.Entity ):
    ....

    def _displayMessage( self, msg ):
        # First make sure any previous message is cleared.
        self._clearMessage()
        
        # Create our text component. Since we want to display it in the world
        # we shall explicitly set our width and height in world units.
        text = GUI.Text( msg )
        text.explicitSize = True
        text.size = ( 0, 0.5 )             # Specifying 0 for x to auto-calculate aspect ratio.
        text.colour = (255, 0, 0, 255)     # Change the colour.
        text.filterType = "LINEAR"         # Don't use point filtering.
        text.verticalAnchor = "BOTTOM"     # Position relative to the bottom of the text.
        
        # The origin of our model is at our feet. To place the text above
        # our head, move it up on the Y by our model's height.
        text.position = (0, self.model.height + 0.1, 0)
        
        # Setup our GUI->World attachment. Tell it that we want the GUI 
        # component to always face the camera.
        atch = GUI.Attachment()
        atch.component = text
        atch.faceCamera = True
        
        # Attach to our model's root node.
        self.model.root.attach( atch )
        
        # Save a reference to the attachment so we can clean it up later.
        self._messageAttachment = atch
        
        # Setup the timer.
        self._setMessageHideTimer()

class Greeter( BigWorld.Entity ):
    ....

    def _clearMessage( self ):
        self._cancelMessageTimer()
        if self._messageAttachment is not None:
            self.model.root.detach( self._messageAttachment )
            self._messageAttachment = None

    def _setMessageHideTimer( self, timeout=5.0 ):
        self._cancelMessageTimer()
        self._messageTimerHandle = \
            BigWorld.callback( timeout, self._handleMessageHideTimer )

    def _cancelMessageTimer( self ):
        if self._messageTimerHandle is not None:
            BigWorld.cancelCallback( self._messageTimerHandle )
            self._messageTimerHandle = None

    def _handleMessageHideTimer( self ):
        self._messageTimerHandle = None
        self._clearMessage()

    def set_activated( self, oldValue ):
        if self.activated:
            self._displayMessage( "Alright! I'm now ready to GREET." )
        else:
            self._displayMessage( "Shutting up now." )

class Greeter:
    def modelName( self, props ):
        return "characters/barbarian.model"

To test the entity it will first need to be placed into a space in World Editor. Open the spaces/main and place the entity by dragging the Greeter entity into the scene from the Resources tab. Save the space.

If you are not using a Windows mount, update the resources on the server side and then restart the server. If all is well, you should be able to connect as per-normal and see the Greeter in the space.

Greeter entity in action

If you do not see the entity, there are a couple of things to check:

Note that at this point the only way to toggle the activation state is to use the in-game Python console. For example, on the client,

>>> $B.entities.items() # Find the ID for the Greeter
[(2402, Greeter at 0x088CFFE8), (2405, PlayerAvatar at 0x088CFC10)]
>>> greeter = $B.entities[2402]
>>> greeter.cell.toggleActive()

While the entity satisfies the basic requirements, there are some improvements that could be made.