Table of Contents
Entities are a key BigWorld concept, and involve a large system in their own right. They are the link between the client and the server and are the feature most particular to BigWorld Technology, in comparison to other 3D game systems.
This section deals only with the management aspects of entities on the client.
For details on the environment in which entity scripts are placed, and the system that supports them, see Scripting. For details on the definition of an entity, which is shared between the server and the client, see the document Server Programming Guide's section Directory Structure for Entity Scripting → The Entity Definition File.
Depending on the entity type, it can exist in different parts of BigWorld, as listed below:
-
Client-only
For example, a security camera prop, or an information icon. Client-only entities are created by setting World Editor's Properties' panel Client-Only attribute to true. (for details on this panel, see the document Content Tools Reference Guide 's section World Editor → Panel summary → Properties panel). Client-only entities should not have cell or base scripts.
-
Client and server
The entity will exist in both parts at the same position. For example, the player Avatar, NPCs, a vending machine.
-
Server-only
The entity will be instantiated on the server only. For example, a NPC spawn point or teleportation destination point. Server-only entities do not have any scripts on the client side.
The Entity Manager stores two lists of entities:
-
Active List — Contains the entities that are currently in the world, as relayed by the server or indicated by the chunk files.
-
Cached List — Contains the entities that have recently been in the world, but are now just outside the client's 500m radius area of interest (AoI).
Entities are cached so that if they come back into the client's AoI shortly after they have left it, the server does not have to resend all the data associated with that entity; only the fields that have changed.
Since messages may be received from the server out of order, the Entity Manager is not sensitive to their order. For example, if an entity enters the player's AoI then quickly leaves it, the BigWorld client behaves correctly even if it receives the entity's 'leave AoI' message before its 'enter AoI' message.
The Entity Manager can always determine the relative time that it should have received a message from the sequence number of the packet, since packets are sent at regular intervals.
Entity scripts on the client are Python classes that derive from the
BigWorld.Entity class. This base class exposes a number of
methods and attributes which allow the script to control the behaviour of
the entity (e.g. position, orientation, and the entity model are all
exposed via the BigWorld.Entity interface).
In addition exposing to methods and attributes, the client engine will notify the entity scripts when certain events occur via named event handlers.
See Scripting and the Client Python API reference guide for details on what methods, attributes, and event handlers are available.
Generally, each entity type require some resources in order to operate, for example models, textures, shaders, sounds, or particle systems. The BigWorld client provides a couple of ways to make sure these resources are available when the entity enters the world, avoiding stalling the main thread.
When the client starts up, it will query each entity Python module
for a function named preload. Resource names returned by
this function will be loaded on client startup and kept in memory for
the entire life-time of the client (i.e. it will be instantly available
for use at any time). This is useful for commonly used assets to avoid
potentially loading and re-loading at a later time. The tradeoff,
however, is that the client will take longer to start and will use more
memory (if the resource isn't actually being used at some point).
To use the preloads mechanism, create a global function called
preload in the relevant entity module. It must take a
single parameter which is a Python list containing resource to preload.
Modify this list in place (e.g. using list.append or list
concatenation), inserting the string names of each resource to be
preloaded by the client.
For example,
# Door.py
import BigWorld
class Door( BigWorld.Entity ):
def __init__( self ):
...
def preload( list ):
list.append( "doors/models/generic_door.model" )
list.append( "doors/maps/door_highlight.tga" )
... The type of resources which can be preloaded are,
-
Fonts
-
Textures
-
Shaders
-
Models
When an entity is about to appear in the world on the client, the
engine will execute a callback on the entity script called
prerequisites. This allows entity scripts to return a list
of resources that must be loaded before the entity may enter the world.
These resources are loaded by the loading thread, so as to not interrupt
the rendering pipeline.
It is recommended practice for an entity to expose its required
resources as pre-requisites, and load them in the method
onEnterWorld. Unlike using preloads, prerequisites do not
leak a reference, so when the entity leaves the world, it will free its
resources.
The Entity Manager calls Entity::checkPrerequisites
before allowing an entity to enter the world. This method checks whether
the pre-requisites for this entity entering the world are satisfied. If
they are not, then it starts the process of satisfying them (if not yet
started).
Note that when the prerequisites method is called on
the entity, its script has already been initialised and its properties
have been set up. The entity thus may specialise its pre-requisites list
based on the specific instance of that entity. For example:
def Door( BigWorld.Entity ):
...
def prerequisites( self ):
return [ DoorResources[ self.modelType ].modelName ]
...