The class BigWorld.Proxy on the BaseApp extends BigWorld.Base to support player-controlled entities. By deriving an entity from BigWorld.Proxy, you can implement player characters, their accounts, and any other relevant player-controlled objects on the server.

An entity derived from BigWorld.Proxy is created from the database whenever a client logs in to the server. For details on how BigWorld determines which Proxy to load, see User Authentication and Billing System Integration. Proxies created in this way (see below for other ways of creating proxies) which have a property called password, will have the value of that property set to the login password.

An instance of BigWorld.Proxy needs neither a cell entity, nor a client one. A proxy entity can be created using the method BigWorld.createBase, just like any other entity. For more detail on this method, see Entity Instantiation on the BaseApp.

Like other base entities, saving and loading proxy entities from the database is possible. Initially, these reloaded proxy entities will be created without an attached client. An existing proxy can later hand its client over to the reloaded one, in which case the reloaded proxy will be the one handling the client connection.

This allows you to have, for example, an Account entity that people can log in to, and a Character entity that people can select from a menu in order to use in the game.

To pass the control of a client from one proxy to another, use the method giveClientTo, as in the example below:

clientControlledProxy.giveClientTo( nonClientControlledProxy )

Whenever a client moves between proxies, or the cell entity of the proxy that a client is attached to is destroyed, the client receives a call on onEntitiesReset to clear out its current knowledge of the world. This effectively interrupts all game communications, and forces the client to refresh. If only the cell entity has been destroyed, then the client's knowledge of its proxy is retained.

If giveClientTo does not succeed because of a problem with the destination proxy, onGiveClientToFailure will be called on the origin proxy.

Whenever a proxy with an attached client has a corresponding cell entity, an extra object called witness is attached to the cell entity.

This object manages the entity's AoI, and sends updates to the proxy, which forwards them on to the client.

The updates consist of the bulk of game-related messages, such as:

By default, every cell entity is considered to be controlled by the server. When an entity incorporates a witness object, it is considered to be controlled by the client attached to the corresponding proxy.

However, the control of an entity may be explicitly assigned and queried, using the entity attribute .controlledBy. This attribute may be set to None, to indicate server control, or to a BaseEntityMailBox to indicate control by the client attached to that proxy. Within this context, control implies ownership of and responsibility for the entity's position and direction. Clients (and proxies) are informed of changes to the set of entities that they are allowed to control. Proxies may read this set through their attribute wards.

When an entity is controlled by a client, setting the attribute Entity.topSpeed to a value greater than zero enables the physics checking. By default the topSpeed enables physics checking on all 3 axis, however this may not always be appropriate. For example, if the gravity of your game environment enables a Y-axis acceleration that results in a top speed exceeding the maximum allowable X/Z-axis top speed. In order to accommodate this there is a secondary attribute named Entity.topSpeedY which takes precedence when set to a value greater than zero. topSpeedY will only be used when both topSpeed and topSpeedY are greater than zero.

Entity movement is validated in the following ways:

Other scenarios in which physics checking is applied include:

When a server script directly sets the position or direction of an entity that is controlled by a client, the CellApp treats that as a physics correction. A new position and direction (sometimes referred to as the pose) are forced down to the client, and no future position and direction updates are accepted until the correction is acknowledged. This feature can be very useful for teleporting a player in response to some action or event on the server. Notably, the methods Entity.teleport, Entity.boardVehicle and Entity.alightVehicle also adhere to this mechanism. Server-side teleports are the only way to move an entity between spaces.

While in most cases movement controllers would also result in downstream-forced positions, their use on client-controlled entities is neither recommended nor supported, since they continually set the position via a system intended for one-off adjustments.