Space class
Space is part of the KBEngine module. More...
import KBEngine
Member functions
def addTimer( self, initialOffset, repeatOffset=0, userArg=0 ):
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 readonly CellEntityCall
databaseID readonly int64
databaseInterfaceName readonly string
shouldAutoArchive True, False or KBEngine.NEXT_ONLY
shouldAutoBackup True, False or KBEngine.NEXT_ONLY
Detailed description
A Space is an abstract concept that exists only in the memory of a cellapp. Creating a KBEngine.Space entity on a Baseapp causes the engine to allocate a space on a Cellapp and create the corresponding entity's cell part inside that new space.
This space is isolated from other spaces: views, trigger systems, entity collisions, etc., only affect entities within the same space.
Because a space is an abstract concept, its concrete meaning is defined by the user — it can be a scene, an instance, a room, and so on. For example, in an MMORPG, a map or an instance can be a Space; only characters, monsters, and NPCs inside the same space can interact with each other. When you move or teleport to another map, the previous monsters and NPCs are no longer visible, you cannot attack monsters that were in the previous map, and you cannot talk to NPCs from that previous map. Another example: in board/card games, there are usually many rooms, each room representing a table/game round; players inside one room play that round and two different rooms do not interact with each other (aside from global systems like chat).
A Space is actually an Entity; Space will call createCellEntityInNewSpace automatically when created.
All attributes and methods are the same as Entity, but to avoid confusion we remove methods and properties that are not used by Space here.
Member function documentation
def addTimer( self, initialOffset, repeatOffset=0, userArg=0 ):
Description:
Registers a timer. The timer triggers the callback function onTimer. The callback will be executed the first time after initialOffset seconds, and then repeated every repeatOffset seconds. You can specify a user argument userArg (integer only).
The onTimer function must be defined in the entity's base part and must accept two parameters: the first integer parameter is the timer id (which can be used to remove the timer via [delTimer](#delTimer)), the second is the user argument userArg.
Example:
# An example 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: call after 1 second; userArg defaults to 0
self.addTimer( 1 )
# The Entity 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 and you no longer need it, remove it:
# self.delTimer( id )Parameters:
initialOffset: float, specifies the time interval (in seconds) from registration until the first callback execution.
repeatOffset: float, specifies the interval (in seconds) between subsequent callbacks after the first execution. Must be removed with delTimer if you want to stop it; otherwise it will repeat indefinitely. Values less than or equal to 0 are ignored.
userArg: integer, specifies the userArg value passed to the lower-level callback [onTimer](#onTimer).
Return:
integer — this function returns the internal id of the timer; this id can be used with delTimer to remove the timer.
def delTimer( self, id ):
Description:
delTimer removes a registered timer; once removed, the timer will no longer run. One-shot timers are automatically removed after their callback executes — you don't need to call delTimer for them. Calling delTimer with an invalid id (for example, an id that is already removed) will produce an error.
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:
This function destroys the base part of the entity. If the entity has a cell part, the user must destroy the cell part first, otherwise an error will occur. To destroy the cell part of an entity, call Entity.destroyCellEntity.
It may be more appropriate to call self.destroy inside the onLoseCell callback. That ensures the entity's base part will be destroyed.
Parameters:
deleteFromDB: If True, any database records associated with this entity will be deleted. Defaults to False.
writeToDB: If True, the entity's archived ("persistent") properties will be written to the database. This is only performed if the entity was loaded from the database or has been previously written using Entity.writeToDB. This parameter defaults to True, but is ignored when deleteFromDB is True.
def destroyCellEntity( self ):
Description:
destroyCellEntity requests the destruction of the associated cell entity. If there is no associated cell entity, this method will raise an error.
def writeToDB( self, callback, shouldAutoLoad, dbInterfaceName ):
Description:
This function saves the entity's persistent (archived) properties to the database so it can be reloaded later.
An entity can also be marked for auto-load, so the entity will be recreated from the database when the server restarts.
Parameters:
callback: This optional parameter is a callback function invoked when the database operation completes. It takes two arguments: the first is a boolean flag indicating success or failure, the second is the base entity.
shouldAutoLoad: This optional parameter specifies whether the entity should be loaded from the database when the service starts.
TIP
Note: When the server starts, auto-loading entities will by default call createEntityAnywhereFromDBID to create the entity on a baseapp with the least load; the entire process completes before the first started baseapp calls onBaseAppReady.
Script-level code can override the entity creation method in the entry script (defined by kbengine_defaults.xml -> baseapp -> entryScriptFile), for example:
def onAutoLoadEntityCreate(entityType, dbid):
KBEngine.createEntityFromDBID(entityType, dbid)dbInterfaceName: string, optional; specifies which database interface to use. The default is the "default" interface. Database interfaces are defined under kbengine_defaults.xml -> dbmgr -> databaseInterfaces.
def getComponent( self, componentName, all ):
Description:
This function retrieves component instances of a certain type bound to the entity.
Parameters:
componentName: string — the component type name (module name of the component).
all: bool — if True, return all component instances of that type; otherwise return only the first one 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: optional variable arguments to pass as event data.
def registerEvent( self, eventName, callback ):
Description:
Registers an entity event listener.
Parameters:
eventName: string — the name of the event to listen for.
callback: the callback function to invoke when the event is triggered.
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 function to unregister.
Callback function documentation
def onCreateCellFailure( self ):
Description:
If implemented in script, this function is called when creation of the cell entity fails. This function has no arguments.
def onDestroy( self ):
Description:
If implemented in script, this function is called after Entity.destroy() is invoked but before the actual destruction occurs. This function has no arguments.
def onGetCell( self ):
Description:
If implemented in script, this function is called when the entity obtains its cell entity. This function has no arguments.
def onLoseCell( self ):
Description:
If implemented in script, this function is called after the associated cell entity is destroyed. This function has no arguments.
def onPreArchive( self ):
Description:
If implemented in script, this function is called before the entity is automatically written to the database. This callback is invoked before Entity.onWriteToDB. If this callback returns False, the archive operation is aborted. The callback should return True for the operation to continue. If this callback does not exist, the archive operation proceeds.
def onRestore( self ):
Description:
If implemented in script, this function is called when the entity is recreated on another Entity application after an application crash. This function has no arguments.
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: integer user data passed into Entity.addTimer.
def onWriteToDB( self, cellData ):
Description:
If implemented in script, this function is called when the entity's data is about to be written to the database.
Note that calling writeToDB inside this callback will cause an infinite loop.
Parameters:
cellData: a dictionary containing the cell properties that will be saved to the database. cellData is a dictionary.
Property documentation
cell
Description:
cell is an ENTITYCALL used to refer to the cell entity. This property is read-only, and will be None if this base entity does not have an associated cell.
Type:
readonly ENTITYCALL
cellData
Description:
cellData is a dictionary property. Whenever the base entity's cell entity is not created, the cell entity's properties are stored here.
If the cell entity is created, these values used by the cell and the cellData property are removed. 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:
readonly string
databaseID
Description:
databaseID is the persistent ID (database id) of the entity. This id is of type uint64 and greater than 0; if it is 0 the entity is not persistent.
Type:
readonly int64
databaseInterfaceName
Description:
databaseInterfaceName is the name of the database interface where the entity is persisted. The interface name is configured in kbengine_defaults -> dbmgr. This property is available only if the entity has been persisted (databaseID > 0); otherwise it returns an empty string.
Type:
readonly string
id
Description:
id is the object's id. This id is an integer and is the same among the base, cell and client associated entities. This property is read-only.
Type:
readonly int32
isDestroyed
Description:
This property is True if the Entity has already been destroyed.
Type:
bool
shouldAutoArchive
Description:
This property controls the auto-archive policy. If set to True, auto-archiving is enabled; if set to False, it is disabled. If set to KBEngine.NEXT_ONLY, auto-archive will be enabled at the next scheduled time; after the next archive it will be set to False.
Type:
True, False or KBEngine.NEXT_ONLY
shouldAutoBackup
Description:
This property controls the auto-backup policy. If set to True, auto-backup is enabled; if set to False, it is disabled. If set to KBEngine.NEXT_ONLY, auto-backup will be enabled at the next scheduled time; after the next backup it will be set to False.
Type: