All methods in all categories have some fundamental common characteristics. They are declared in the relevant section in the file <res>/scripts/entity_defs/<entity>.def, with an XML tag per method.

The method's arguments and return values (if any) are also defined in the file, and its types are specified in the same way as property types. For more details, see Property Types.

In order to declare a method called yell on the cell, which receives a string argument named phrase, we would have the lines below:

<root>
  ...
  <CellMethods>
    <yell>
      <Args>
        <phrase> STRING </phrase> <!-- phrase to exclaim -->
      </Args>
    </yell>
  </CellMethods>
  ...
</root>

<res>/scripts/entity_defs/<entity>.def ‐ Declaration of cell method yell

Once the method is declared, it also needs to be declared in the appropriate Python implementation file. Each context of execution (cell, base, and client) has a folder containing scripts for each entity.

In our example, the method was added to the section <CellMethods>, and therefore will be executed on the cell entity.

The cell script for this entity, named <res>/scripts/cell/<entity>.py, will need to define the yell method, as illustrated below:

import BigWorld
...
class <entity>(BigWorld.Entity):

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

  def yell(self, phrase):
    # insert code to implement yell here
    return

<res>/scripts/cell/<entity>.py ‐ Definition of cell method yell

Remote two-way method calls can be used to get return values from Python calls between processes. Return values for entity methods are declared in the same format as the method arguments in the entity definition file, except that they are listed under the ReturnValues tag instead of Args. For example, the webCreateAuction Base method for an Avatar has the following definition:

<webCreateAuction>
  <Args>
    <itemSerial>  ITEMSERIAL  </itemSerial>
    <expiry>      UINT32      </expiry>
    <startBid>    GOLDPIECES  </startBid>
    <buyout>      GOLDPIECES  </buyout>
  </Args>
  <ReturnValues>
    <auctionID>   AUCTIONID   </auctionID>
  <ReturnValues>
</webCreateAuction>

This method takes a number of arguments containing the details of the item being listed for auction, and returns the unique auction ID. However, this method makes a remote call to an entity that is potentially on another process, which prevents us from receiving a return value in the usual way. Instead, this method will return a Twisted Deferred object, that will send the return values as an argument to a callback method once they are received. This entire process is explained in Twisted Deferred Objects.

...
    <BaseMethods>
        <remoteTakeDamage>
            <Args>
                <damage>        INT32   </damage>
            </Args>
            <ReturnValues>
                <health>        INT32   </health>
            </ReturnValues>
        </remoteTakeDamage>
        ...
    </BaseMethods>

    <CellMethods>
        <takeDamage>
            <Args>
                <damage>        INT32   </damage>
            </Args>
            <ReturnValues>
                <health>        INT32   </health>
                <maxHealth>     INT32   </maxHealth>
            </ReturnValues>
        </takeDamage>
        ...
    </BaseMethods>

# base/Avatar.py

from twisted.internet import defer
...

def remoteTakeDamage( self, damage )
    deferred = self.cell.takeDamage( damage )
    deferred.addCallback( partial( self.onDamageTaken, damage ) )
    return deferred

def onDamageTaken( self, damage, healthArgs ):
    health, maxHealth = healthArgs[ 0 ], healthArgs[ 1 ]
    print "Avatar 's' took %d damage, reducing its health to %d/%d" % \
        (self.basePlayerName, damage, health, maxHealth)
    return (health,)

deferred.addErrback( onError )

# cell/Avatar.py

import CustomErrors
from twisted.internet import defer
...

def takeDamage( self, damage ):
    if (damage < 0):
        # Goes to errback which 
        return defer.fail( CustomErrors.InvalidFieldError(
                "Avatar can not take negative damage" ) )

    self.health = self.health - damage

    if (self.health < 0):
        self.health = 0

    # Goes to onDamageTaken callback
    return (self.health, self.maxHealth)

raise CustomErrors.InvalidFieldError( "Avatar can not take negative damage" ) )

return defer.fail( CustomErrors.<Error Type>( <Args> ) )

Methods for services are defined in the much same way as base, cell and client methods. However, there are some slight differences, since, unlike the other categories, services are not entities. Service methods are declared in the file <res>/scripts/service_defs/<service>.def, with an XML tag per method.

Service methods fall under the Methods tag, instead of under a specific category such as BaseMethods or CellMethods.

In order to declare a method called addNote on the service, which receives a string argument named newNote, we would have the lines below:

<root>
  ...
  <Methods>
    <addNote>
      <Args>
        <newNote> STRING </newNote>
      </Args>
      <ReturnValues>
        <noteID> NOTE_ID </newNote>
      </ReturnValues>
    </addNote>
  </CellMethods>
  ...
</root>

<res>/scripts/service_defs/<service>.def ‐ Declaration of service method addNote

Once the method is declared, it also needs to be implemented in the service Python implementation file. The service execution context has a directory containing the scripts for each service.

The script for this entity, named <res>/scripts/service/<service>.py, will need to define the addNote method, as illustrated below:

import BigWorld
...
class <service>( BigWorld.Service ):

  def addNote( self, description ):
    # insert code to implement addNote here
    return

<res>/scripts/service/<entity>.py ‐ Definition of service method addNote

Different execution contexts of an entity communicate with each other by calling methods on the other execution contexts. These are exposed as special properties of the entity.

As a quick reference, the available objects are described below:

The methods of a nearby entity can be called from the client directly on the cell part of that entity.

BigWorld automatically exposes these objects to the relevant script classes.

What this means is that it is possible for any script that is part of an entity (cell, base or client part) to call other scripts that are part of the same entity. The definition file (<res>/scripts/entity_defs/<entity>.def) describes which methods are exposed to different execution contexts.

When a method is called on Entity.otherClients (or Entity.allClients), an event object is created and added to the event history. This event history is used when updating client applications that have this entity in their AoI. When this entity is considered^[7], any events that have been added since the last time this entity was considered are sent to the client. There is the potential for multiple calls of a single method to be sent in a single update.

If the SendLatestOnly flag is set on a client method, only the latest call is kept in the event history. This avoids sending multiple calls. This can save bandwidth being sent to the client and can save some memory on CellApps if a method is called frequently and only the latest call is needed.

This value is false by default.

Properties with the OTHER_CLIENTS flag also have this flag. See Bandwidth Optimisation: Send Latest Only.

When a method is called on Entity.otherClients (or Entity.allClients), a message is sent to the appropriate client applications that have this entity in their AoI^[8]. By default, these messages are sent reliably. If the IsReliable flag is set to false on a client method, this message will be sent unreliably.

Properties with the OTHER_CLIENTS flag also have this flag. See Bandwidth Optimisation: Is Reliable.

Auxiliary data can be streamed to the client via the proxy, without affecting the normal game traffic. This data is opportunistically streamed to the client when bandwidth is available.

The bandwidth used by auxiliary data streaming can be controlled using the bw.xml options in <baseApp/downloadStreaming>. For details of this option group refer to the Server Operations Guide section BaseApp Configuration Options.

All data types in this streamed data are user-defined, since BigWorld does not have any internal uses for it.

Data is added to a proxy via method streamStringToClient:

id = Proxy.streamStringToClient( id, data )

or via method streamFileToClient:

id = Proxy.streamFileToClient( id, resource )

Where the parameters are:

Once the client has received the entire data string, the callback BWPersonality.onStreamComplete is called on the client.

Because MMOGs operate over the Internet, and in order to stop players cheating, server methods (those on the cell or the base) are not automatically allowed to be called by the client.

In order to make a server method callable from the client (so that the world can provide interactivity), its declaration has to include the tag <Exposed/>, as illustrated below:

<root>
  ...
  <CellMethods>
    <yell>
      <Exposed/>
      <Args>
        <phrase> STRING </phrase> <!-- phrase to exclaim -->
      </Args>
    </yell>
  </CellMethods>
  ...
</root>

<res>/scripts/entity_defs/<entity>.def ‐ Declaration of the exposed method

The tag <Exposed/> accomplishes two things:

Client instances actually call the method with one argument fewer than the number received by the cell entity, which prevents 'entity-faking' outside the safe server environment. The entity ID needs to be passed as an argument when calling exposed methods from the server components.

The definition of the method on the cell must be extended to take this parameter, as illustrated below:

import BigWorld
class EntityName(BigWorld.Entity):

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

  def yell(self, sourceEntityID, phrase):
    # insert code to implement yell here
    # if desired, check that self.id == sourceEntityID before proceeding
    return

<res>/scripts/cell/<entity>.py ‐ Definition of cell method yell

On the client, the method yell can be called with the code below:

self.cell.yell( "BigWorld message test" )

Example of a client calling a cell method yell

If the cell method yell implements the check of sourceEntityID against self.id, only its client will be able to call it. Others clients will not be able to execute it.

There might be occasions where the method might run with a different sourceEntityID. For example, for a method called shakeHand, it is a good idea to check that the source entity is within a couple of metres away from the self entity before proceeding (and maybe that neither is dead).

The arguments of a method call made from the server to the client are optimised in the same way property updates are optimised.

See Server to Client bandwidth usage of Property updates.

When the server changes a property on the client a callback method is called on the entity to allow the client to take appropriate action.

set_<property_name> is called when a property of an entity is replaced with a new value. That is, a value in the entity's __dict__ is replaced.

If an existing property is modified, either setNested_<property_name> or setSlice_<property_name> is called.

class Seat( BigWorld.Entity ):
    ...
  def set_seatType( self, oldValue ):
    ...

class Seat( BigWorld.Entity ):
    ...
  def setNested_myFixedDict( self, path, oldValue ):
    ...

self.myFixedDict.rightHandItem.weight = 10

["rightHandItem", "weight"]

self.myArray[ 5 ][ 3 ] = 8

(5, 3)

self.myArray.append( 10 )

path = [(5,6)]
oldValues = [ ]
newValues = self.myArray[ path[-1][0] : path[-1][1] ]

del self.myFixedDict.myArray[-1]

path = ["myArray", (4,4)]
oldValues = [21]

Like properties, some methods need to be broadcast only to nearby entities.

For example, even though an entity may be visible at an AoI distance (say, 500 metres), it seems unlikely that players will be able to tell the difference between a smiling and a non-smiling entity.

To reflect his, the smile method's level of detail, can be declared as illustrated below:

<root>
  ...
  <ClientMethods>
    ...
    <smile>
      ...
      <DetailDistance> 30 </DetailDistance>
    </smile>
    ...
  </ClientMethods>
  ...
</root>

<res>/scripts/cell/<entity>.py ‐ Declaration of client method smile

The specification of the LOD for a method is far simpler than it is for a property. This is because a non-broadcast property change might have to be sent later if the LOD increases, while a non-broadcast method in the same scenario will not have to.

Consequently, the method just needs to declare a tag <DetailDistance> inline, and when it is called on exposed objects allClients or otherClients, it is broadcast only to clients within the specified distance around the entity.

Once the entities have methods assigned to them, it becomes useful to be able to call methods on other entities.

If you have an object ent as a Python script representation of another entity, then you can call ent.someMethod() to call that method on ent. This assumes that someMethod() runs on the same execution context you are in. For example, if you are on the cell, then ent.someMethod() must be defined and provided by the entity type of ent.

If you are on the cell, you can call a method on the base, with the code below:

ent.base.otherMethod()

This means that once you are able to obtain an entity object, there is a plethora of options for invoking methods on different execution contexts of different entity instances. For more details, see Intra-Entity Communication.

But to achieve this, first it is necessary to retrieve the object for another entity. The mechanism for that is described in the next sub-section

ent = BigWorld.entities[ entityID ]

serviceMailbox = BigWorld.services[ serviceName ]

BigWorld.services[ 'ExampleService' ].myTest( u"This is a test" )

Mailboxes are used to communicate with entities that are remote, i.e., not on the current process.

Entities can only access other entities that are running in the same execution context^[11]However, it is often useful to be able to send a message to entities in other execution contexts. For example, an entity may wish to send a message to all members of a chat channel, but the channel might not have all its members located on the same BaseApp as the executing entity.

Mailboxes are used to implement the following properties of an entity:

There are also a special set of mailboxes available for use from the cell which reference other entities in relation to the current entity. These mailboxes are discussed in Special Mailboxes.

These afore mentioned properties (cell, base, ownClient) allow you to reference objects located on different processes, and can be sent like any other value, using method calls, and the MAILBOX data type.

You can use the MAILBOX like a normal entity reference, and call methods declared in the entity's definition file on other entities on other processes.

Considering that an entity B (referenced in the following example as anotherEntity) has a method heyThere which takes one argument of type MAILBOX, an entity A can pass its base mailbox to entity B from the cell, as in the example below:

anotherEntity.heyThere( self.base )

<res>/scripts/cell/<original_entity>.py ‐ Passing base mailbox from cell

On the receiving entity B (referenced in the example as anotherEntity), the calling entities (entity A) base mailbox (as received via the method argument) can be used to call a method someMethod on entity A. For example:

def heyThere( self, originalEntity ):
  originalEntity.someMethod()

<res>/scripts/cell/<another_entity>.py ‐ Receiving base mailbox

It is also possible to store mailboxes in a class as properties. However this is only useful for base entity mailboxes, since they will not change address as the entity moves around the space.

Cell entity mailboxes should not be stored, because they can change as the entity moves between cells. It is possible to pass cell entity mailboxes to another entity for once-off use, since they are guaranteed to be usable for the time it takes to call a method and have it respond (i.e., up to approximately 1 second).

Using mailboxes, it is also possible to call methods within a different execution context to that of the mailbox being called. For example, using a base mailbox of an entity (baseMB in the following code), it is possible to call a cell method of the base entity as follows:

baseMB.cell.cellMethod()

Calling a cell method of another entity through its base mailbox

The call is sent to the base entity first, which then calls the cell method from where the base entity resides. Though it is more convenient than calling a base method that in turn calls the cell method, it still takes two hops to call the cell entity.

Available usages are:

These are in fact instances of MailBoxes, and can be passed as method arguments. However, the same restriction applies to cellMB.base and cellMB.client as to cell mailboxes ‐ they can change as an entity moves around, and therefore should not be stored for later use.

Note that both baseMB.ownClient and cellMB.ownClient refer to their own client only. There are no shortcut calls to otherClients and allClients.

A convenient way to obtain other entities' mailboxes is by using the methods BigWorld.lookUpBaseByDBID and BigWorld.lookUpBaseByName on the BaseApp. For more details, see the BaseApp Python API's entry Main Page → BigWorld (Module) → Member Functions.

6.13.1. Special Mailboxes

On top of the previously discussed mailboxes, the CellApp also offers a special set of mailboxes which can be used to communicate with entities within the AoI of the reference entity.

The available mailboxes are:

• entity.allClients

• entity.otherClients

• entity.clientEntity( EntityID )

The allClients mailbox will call a method on all client entities that exist in the AoI of the reference entity as well as on the reference entity's ownClient.

The following diagram illustrates a call to the allClients mailbox on Entity A such as A.allClients.chat(). This results in the chat() method being called on Entity A on ClientApps A, B and C.

The otherClients mailbox, is almost identical to the allClients mailbox, except that the method being called will not be executed on the reference entity's ownClient. This is useful for situations where the reference entity's client was the initiator of the action.

The following diagram illustrates a call to the otherClients mailbox on Entity A such as A.otherClients.jump(). This results in the jump() method being called on Entity A on ClientApps B and C.

The most complicated mailbox is clientEntity( EntityID ). This mailbox is used to call a method on an entity that is represented on the reference entity's ClientApp. This is useful for causing a behaviour that is specific to a single Client to only be seen by the interested client, such as a quest giver talking to the player.

The following diagram illustrates a call to the clientEntity mailbox on Entity B providing the EntityID of C such as B.clientEntity( C.id ).wave(). This results in the wave() method being called on Entity C on ClientApp B.

All entity method calls across physical machines are asynchronous. For example, if you execute self.cell.cellMethod() or self.client.clientMethod() on a base entity, the call returns immediately without any value. The actual method execution takes place on the machine where the cell or client part of the entity resides.

To inform the calling entity of the execution result you will have to call a function from within the method.

The example below describes the client entity of class Avatar initiating a sequence of actions to open a door, executing the following steps:

The same callback technique is used to return values from a called method.

The example below describes the client entity of class Avatar initiating a sequence of actions to inquire about an item's description based on its inventory index, executing the following steps:

For those entities residing in the same process, the method calls take place synchronously. However, since there is no guarantee that the calling entities and the called ones will always be in the same process, it is better to adopt the callback solution.

A special case is an entity method that is not defined in the entity's definition file (<res>/scripts/entity_defs/<entity>.def ‐ For details, see The Entity Definition File). In this case, the method is always executed synchronously, and is only executed in the process of the caller. For example, a method call on a ghosted entity normally will be delegated to the real one. However, if this method is not defined in the entity's definition file, it will be treated as a usual Python method, and run locally.

This mechanism does save a bit of network traffic between server components, and can return a result immediately to the caller, but it is also limited in that it can only access the read-only ghosted properties. Trying to access non-ghosted properties or to write read-only properties would result in unexpected errors. Unless carefully planned, one should not take advantage of this feature.