Entity Class
Entity is part of the KBEngine module. More...
import KBEngine
Member Functions
def addTimer( self, initialOffset, repeatOffset=0, userArg=0 ):
def createCellEntity( self, cellEntityCall ):
def createCellEntityInNewSpace( self, cellappIndex ):
def delTimer( self, id ):
def destroy( self, deleteFromDB, writeToDB ):
def destroyCellEntity( self ):
def getComponent( self, componentName, all ):
def fireEvent( self, eventName, *args ):
def registerEvent( self, eventName, callback ):
def deregisterEvent( self, eventName, callback ):
def writeToDB( self, callback, shouldAutoLoad, dbInterfaceName ):
Callback Functions
def onCreateCellFailure( self ):
def onDestroy( self ):
def onGetCell( self ):
def onLoseCell( self ):
def onPreArchive( self ):
def onRestore( self ):
def onTimer( self, timerHandle, userData ):
def onWriteToDB( self, cellData ):
Properties
cell Read-only CellEntityCall
client Read-only ClientEntityCall
databaseID Read-only int64
databaseInterfaceName Read-only string
shouldAutoArchive True, False or KBEngine.NEXT_ONLY
shouldAutoBackup True, False or KBEngine.NEXT_ONLY
Detailed Description
The Entity class represents an entity residing on the Baseapp. Entity entities can be created via the KBEngine.createEntity function (and functions prefixed with createEntity). An Entity can also be remotely created via the Cellapp function KBEngine.createEntityOnBaseApp.
An Entity can be linked to an entity in an active cell, and can also be used to create an associated entity on a suitable cell. This class allows you to create and destroy entities on cell, register timers on the base entity, access contact information for this object,
and access a CellEntityCall through which the base entity can communicate with its cell entity (the associated cell entity can move to different cells, and KBEngine will perform load balancing as a result of the cell entity moving).
Member Function Documentation
def addTimer( self, initialOffset, repeatOffset=0, userArg=0 ):
Description:
Registers a timer, which is triggered by the callback function onTimer. The callback will be executed for the first time after "initialOffset" seconds, and then every "repeatOffset" seconds. You can set a user parameter "userArg" (integer only).
The onTimer function must be defined in the base part of the entity and should take two parameters: the first is the timer's integer id (can be used to remove the timer with "delTimer"), and the second is the userArg.
Example:
# Example of using addTimer
import KBEngine
class MyBaseEntity( KBEngine.Entity ):
def __init__( self ):
KBEngine.Entity.__init__( self )
# Add a timer: first call after 5 seconds, then every 1 second, userArg is 9
self.addTimer( 5, 1, 9 )
# Add a timer: first call after 1 second, userArg defaults to 0
self.addTimer( 1 )
# Entity's timer callback "onTimer" is called
def onTimer( self, id, userArg ):
print "MyBaseEntity.onTimer called: id %i, userArg: %i" % ( id, userArg )
# if this is a repeating timer, call the following to remove it when no longer needed:
# self.delTimer( id )Parameters:
initialOffset: float, time interval (seconds) from registration to the first callback.
repeatOffset: float, interval (seconds) between subsequent callbacks after the first. Must be removed with delTimer, otherwise it will repeat indefinitely. Values <= 0 are ignored.
userArg: integer, value passed as userArg to the underlying "onTimer" callback.
Returns:
integer, the internal id of the timer, which can be used to remove the timer with delTimer.
def createCellEntity( self, cellEntityCall ):
Description:
Requests to create an associated entity in a cell.
The information used to create the cell entity is stored in the entity's cellData property. This property is a dictionary corresponding to the default values in the entity's .def file, and also includes "position", "direction", and "spaceID" for location and orientation.
Parameters:
cellEntityCall: An optional CellEntityCall parameter specifying in which space to create the cell entity.
TIP
Only a direct CellEntityCall can be used. If you have a BaseEntityCall of an entity, you cannot use baseEntityCall.cell as a parameter. You must create a new function on the base of that entity to return the direct CellEntityCall.
For example:
baseEntityCallOfNearbyEntity.createCellNearSelf( self )On the base of the entity:
def createCellNearSelf( self, baseEntityCall ):
baseEntityCall.createCellNearHere( self.cell )On the original entity's base, call createCellNearSelf():
def createCellNearHere( self, cellEntityCall ):
self.createCellEntity( cellEntityCall )def createCellEntityInNewSpace( self, cellappIndex ):
Description:
Creates a space on the cellapp and creates the entity's cell in this new space, requested via cellappmgr.
The information used to create the cell entity is stored in the entity's cellData property. This property is a dictionary corresponding to the default values in the entity's .def file, and also includes "position", "direction", and "spaceID" for location and orientation.
Parameters:
cellappIndex: integer, if None or 0, the engine will dynamically select via load balancing; if greater than 0, the space will be created on the specified cellapp.
INFO
Example: If you expect to have 4 cellapps, the cellappIndex can be 1, 2, 3, or 4. If there are fewer than 4 cellapps running (e.g., only 3), then 4 will wrap to 1, 5 to 2, etc.
Tip: This feature can be used with KBEngine.setAppFlags(KBEngine.APP_FLAGS_NOT_PARTCIPATING_LOAD_BALANCING), for example: place large map spaces on a few fixed cellapps and set these cellapps to not participate in load balancing, while other cellapps are used for instance spaces.
When creating instance spaces, set cellappIndex to 0 or None, so the load of instance maps does not affect the main map process, ensuring smoothness of the main scene.
def delTimer( self, id ):
Description:
Removes a registered timer. Removed timers will no longer execute. Timers that execute only once are automatically removed after the callback, so you don't need to call delTimer for them. If delTimer is called with an invalid id (e.g., already removed), an error will occur.
See Entity.addTimer for an example of using timers.
Parameters:
id: integer, the id of the timer to remove. If the parameter is the string "All", all timers will be removed at once.
def destroy( self, deleteFromDB, writeToDB ):
Description:
Destroys the base part of the entity. If the entity has a cell part, you must destroy the cell part first, otherwise an error will occur. To destroy the cell part, call Entity.destroyCellEntity.
It is often appropriate to call self.destroy in the onLoseCell callback. This ensures the base part is destroyed.
Parameters:
deleteFromDB: If True, the associated entry in the database will be deleted. Defaults to False.
writeToDB: If True, the archive properties associated with this entity will be written to the database. Only executed if the entity was loaded from the database or has been written to the database via Entity.writeToDB. Defaults to True, but ignored if deleteFromDB is True.
def destroyCellEntity( self ):
Description:
destroyCellEntity requests to destroy the associated cell entity. If there is no associated cell entity, this method will cause an error.
def writeToDB( self, callback, shouldAutoLoad, dbInterfaceName ):
Description:
Saves the entity's archive properties to the database so it can be reloaded later if needed.
Entities can also be marked for auto-loading, so that after the service restarts, the entity will be recreated.
Parameters:
callback: Optional callback function called after the database operation completes. It takes two parameters: a boolean indicating success or failure, and the base entity.
shouldAutoLoad: Optional parameter specifying whether the entity should be loaded from the database when the service starts.
TIP
Note: When the server starts and entities are auto-loaded, the engine will by default call createEntityAnywhereFromDBID to create the entity on the baseapp with the least load. The entire process will complete before onBaseAppReady is called on the first baseapp.
You can override the entity creation method in the script layer (kbengine_defaults.xml->baseapp->entryScriptFile), for example:
def onAutoLoadEntityCreate(entityType, dbid):
KBEngine.createEntityFromDBID(entityType, dbid)dbInterfaceName: string, optional parameter specifying which database interface to use. Defaults to "default". Database interfaces are defined in kbengine_defaults.xml->dbmgr->databaseInterfaces.
def getComponent( self, componentName, all ):
Description:
Gets the instance(s) of a specific component type bound to the entity.
Parameters:
componentName: string, the component type name (module name).
all: bool, if True, returns all instances of the component type; otherwise, returns only the first or an empty list.
def fireEvent( self, eventName, *args ):
Description:
Triggers an entity event.
Parameters:
eventName: string, the name of the event to trigger.
args: event data to attach, variable arguments.
def registerEvent( self, eventName, callback ):
Description:
Registers an entity event.
Parameters:
eventName: string, the name of the event to listen for.
callback: the callback method to respond to the event.
def deregisterEvent( self, eventName, callback ):
Description:
Unregisters an entity event listener.
Parameters:
eventName: string, the name of the event to stop listening for.
callback: the callback method to unregister.
Callback Function Documentation
def onCreateCellFailure( self ):
Description:
If implemented in the script, this function is called when the cell entity creation fails. This function has no parameters.
def onDestroy( self ):
Description:
If implemented in the script, this function is called after Entity.destroy() is called, but before the entity is actually destroyed. This function has no parameters.
def onGetCell( self ):
Description:
If implemented in the script, this function is called when the entity obtains a cell entity. This function has no parameters.
def onLoseCell( self ):
Description:
If implemented in the script, this function is called after the associated cell entity is destroyed. This function has no parameters.
def onPreArchive( self ):
Description:
If implemented in the script, this function is called before the entity is automatically written to the database. This callback is called before the Entity.onWriteToDB callback.
If this callback returns False, the archive operation is aborted. It should return True to continue. If this callback does not exist, the archive operation continues.
def onRestore( self ):
Description:
If implemented in the script, this function is called when the Entity is recreated on another Entity application after a crash. This function has no parameters.
def onTimer( self, timerHandle, userData ):
Description:
This function is called when a timer associated with this entity is triggered. A timer can be added using Entity.addTimer.
Parameters:
timerHandle: the id of the timer.
userData: the integer user data passed to Entity.addTimer.
def onWriteToDB( self, cellData ):
Description:
If implemented in the script, this function is called when the entity's data is about to be written to the database.
Note: Calling writeToDB in this callback will cause an infinite loop.
Parameters:
cellData: the cell properties to be stored in the database. cellData is a dictionary.
Property Documentation
cell
Description:
cell is an ENTITYCALL used to contact the cell entity. This property is read-only and is None if the base entity has no associated cell.
Type:
Read-only ENTITYCALL
cellData
Description:
cellData is a dictionary property. Whenever the base entity has not created its cell entity, the cell entity's properties are stored here.
If the cell entity is created, these values and the cellData property will be deleted. In addition to the properties specified in the entity definition file, it also contains position, direction, and spaceID.
Type:
className
Description:
The class name of the entity.
Type:
Read-only string
client
Description:
client is an EntityCall used to contact the client. This property is read-only and is None if the base entity has no associated client.
Type:
Read-only ENTITYCALL
databaseID
Description:
databaseID is the entity's permanent ID (database id). This id is uint64 and greater than 0; if it is 0, the entity is not permanent.
Type:
Read-only int64
databaseInterfaceName
Description:
databaseInterfaceName is the name of the database interface where the entity is persisted. This interface name is configured in kbengine_defaults->dbmgr. The property is only available if the entity has been persisted (databaseID > 0), otherwise it returns an empty string.
Type:
Read-only string
id
Description:
id is the entity's object id. This id is an integer and is the same across the base, cell, and client associated entities. This property is read-only.
Type:
Read-only int32
isDestroyed
Description:
If the Entity has been destroyed, this property is True.
Type:
bool
shouldAutoArchive
Description:
This property determines the auto-archive strategy. If set to True, auto-archive is enabled; if False, auto-archive is disabled. If set to KBEngine.NEXT_ONLY, auto-archive will be enabled at the next scheduled time, and after the next archive, this property will be set to False.
Type:
True, False or KBEngine.NEXT_ONLY
shouldAutoBackup
Description:
This property determines the auto-backup strategy. If set to True, auto-backup is enabled; if False, auto-backup is disabled. If set to KBEngine.NEXT_ONLY, auto-backup will be enabled at the next scheduled time, and after the next backup, this property will be set to False.
Type: