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 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, we would have the lines below:

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

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

By convention, the meaning of each argument is written next to it as an XML comment.

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

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.

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

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

Data is added to a proxy via method addProxyData:

id = Proxy.addProxyData( id, data )

Where the parameters are:

Once the client has received the entire data string, the virtual method onProxyData in the ServerMessageHandler interface is invoked.

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/>
      <Arg> STRING </Arg> <!-- phrase to exclaim -->
    </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 less than are 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).

When the server updates a property with distribution flag ^[6] ALL_CLIENTS, OTHER_CLIENTS or OWN_CLIENT, an implicit method called set_<property_name> is called on the client.

This method should not need be declared in the section <ClientMethods> of the definition file as it is automatically provided by BigWorld.

All implicitly defined set_property_name methods have one argument which receives the old value of the property when the method is called. For example:

class Seat( BigWorld.Entity ):
    ...
	def set_seatType( self, oldType = None ):
		...

<res>/scripts/client/Seat.py ‐ Example of an implicit set_seatType for the Seat entity.

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 (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 ]

Mailboxes are used to communicate to 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^[8], however it is frequently 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:

These properties 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 documentation's entry Main Page → BigWorld (Module) → Member Functions.

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.