Entity类

[KBEngine模块]

Entity是KBEngine模块的一部分。更多...

import KBEngine

成员函数

• 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 ):

回调函数

• 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 ):

属性

详细描述

Entity类代表一个驻留在Baseapp上的实体。Entity实体可以通过KBEngine.createEntity函数(以及以createEntity为前缀的函数)创建。一个Entity实体也可以通过Cellapp的函数KBEngine.createEntityOnBaseApp远程创建。 一个Entity实体可以在一个活动的cells里面链接到一个实体，还可以被用来在一个合适的cell上创建一个关联的实体。 这个类允许你创建和销毁在cell上的实体或者在base实体上注册一个定时器也或者访问此对象的联系信息， 还可以访问一个CellEntityCall，通过它这个base实体可以与它的cell实体通信（这个被关联的cell实体可以移动到不同cell上，作为该cell实体移动的结果KBEngine会进行负载均衡）。

成员函数文档

def addTimer(self, initialOffset, repeatOffset=0, userArg=0):

功能说明： 注册一个定时器，定时器由回调函数onTimer触发，回调函数将在"initialOffset"秒后被执行第1次，而后将每间隔"repeatOffset"秒执行1次，可设定一个用户参数"userArg"（仅限integer类型）。 onTimer函数必须在entity的base部分被定义，且带有2个参数，第1个integer类型的是timer的id（可用于移除timer的"delTimer"函数），第2个是用户参数"userArg"。 例子:

# 这里是使用addTimer的一个例子
import 
KBEngine

 
class MyBaseEntity( 
KBEngine
.
Entity
 ):
 
    def __init__( self ):
        
KBEngine
.
Entity
.__init__( self )
 
        # 增加一个定时器，5秒后执行第1次，而后每1秒执行1次，用户参数是9
        self.addTimer( 5, 1, 9 )
 
        # 增加一个定时器，1秒后执行，用户参数缺省是0
        self.addTimer( 1 )
 
    # 
Entity
的定时器回调"onTimer"被调用
    def onTimer( self, id, userArg ):
        print "MyBaseEntity.onTimer called: id %i, userArg: %i" % ( id, userArg )
        # if 这是不断重复的定时器，当不再需要该定时器的时候，调用下面函数移除:
        #     self.delTimer( id )

参数：

返回:

• integer，该函数返回timer的内部id，这个id可用于delTimer移除定时器。

def createCellEntity(self, cellEntityCall):

功能说明： 请求在指定 CellEntityCall 所在的空间里创建当前 Base 实体对应的 cell 实体。 它不是在 Base 进程里本地直接构造一个 cell 对象，而是由 Base 把 entityType、baseapp componentID、是否带客户端以及 cellData 序列化后发给目标 CellApp，再由对端完成真正的 Cell 实例创建。 创建成功前 cell 属性仍不可用；Base 侧真正拿到直接 cellEntityCall 的时机，是后续收到回调并触发 onGetCell 的时候。

源码解析：

• 实体系统：Entity.createCellEntity() 不是本地建对象，而是一次 Base -> Cell 交接

参数：

def createCellEntityInNewSpace(self, cellappIndex):

功能说明： 在cellapp上创建一个空间(space)并且将该实体的cell创建到这个新的空间中，它请求通过cellappmgr来完成。 用于创建cell实体的信息被存储在该实体的属性cellData里。这个属性是一个字典，对应实体的.def文件里的默认值同时还包括用于表示 实体位置和方向(roll, pitch, yaw)的"position", "direction" 和 "spaceID"。

参数：

def delTimer(self, id):

功能说明： 函数delTimer用于移除一个注册的定时器，移除后的定时器不再执行。只执行1次的定时器在执行回调后自动移除，不必要使用delTimer移除。 如果delTimer函数使用一个无效的id（例如已经移除），将会产生错误。 到Entity.addTimer参考定时器的一个使用例子。

参数：

def destroy(self, deleteFromDB, writeToDB):

功能说明： 这个函数销毁该实体的base部分。如果实体存在cell部分，那么用户必须先销毁cell部分，否则将会产生错误。要销毁实体的cell部分，调用Entity.destroyCellEntity。 也许在onLoseCell回调里调用self.destroy更为恰当。这能保证实体的base部分被销毁。

参数：

def destroyCellEntity(self):

功能说明： destroyCellEntity请求销毁关联的cell实体。如果没有关联的cell实体该方法将会产生错误。

def writeToDB(self, callback, shouldAutoLoad, dbInterfaceName):

功能说明： 该函数保存这个实体的存档属性到数据库，使得以后需要的时候可以重新从数据库加载。 实体也可以被标记为自动加载，这样当服务启动后实体将会被重新创建。

参数：

def getComponent(self, componentName, all):

功能说明： 该函数用于获取实体所绑定的某一类组件实例。

参数：

def fireEvent(self, eventName, *args):

功能说明： 该函数用于触发实体事件。

参数：

def registerEvent(self, eventName, callback):

功能说明： 该函数用于注册实体事件。

参数：

def deregisterEvent(self, eventName, callback):

功能说明： 该函数用于注销监听实体事件。

参数：

回调函数文档

def onCreateCellFailure(self):

功能说明： 如果这个函数在脚本中有实现，这个函数在cell实体创建失败的时候被调用。 这个函数没有参数。

def onDestroy(self):

功能说明： 如果这个函数在脚本中有实现，这个函数在调用Entity.destroy()后，在实际销毁之前被调用。 这个函数没有参数。

def onGetCell(self):

功能说明： 如果这个函数在脚本中有实现，这个函数会在 Base 侧收到 cell 创建成功回调、并补齐当前实体的直接 cellEntityCall 后被调用。 底层会先结束 creatingCell 状态并销毁一次性的 cellData 启动数据，然后才进入这个脚本回调；恢复路径 restoreCell() 不会触发它。

源码解析：

• 实体系统：Entity.createCellEntity() 不是本地建对象，而是一次 Base -> Cell 交接

这个函数没有参数。

def onLoseCell(self):

功能说明： 如果这个函数在脚本中有实现，这个函数在它关联的cell实体销毁之后被调用。 这个函数没有参数。

def onPreArchive(self):

功能说明： 如果这个函数在脚本中有实现，这个函数在该实体自动写入数据库之前被调用。这个回调在Entity.onWriteToDB回调之前被调用。 如果该回调返回False，该归档操作中止。这个回调应该返回True使得操作继续。如果这个回调不存在，则归档操作继续进行。

def onRestore(self):

功能说明： 如果这个函数在脚本中有实现，这个函数在Entity应用程序崩溃后在其它Entity应用程序上 重新创建该实体时被调用。 这个函数没有参数。

def onTimer(self, timerHandle, userData):

功能说明： 这个函数当一个与此实体关联的定时器触发的时候被调用。 一个定时器可以使用Entity.addTimer函数添加。

参数：

def onWriteToDB(self, cellData):

功能说明： 如果这个函数在脚本中有实现，这个函数在实体数据将要写进数据库的时候被调用。 需要注意的是在该回调里调用writeToDB会导致无限循环。

参数：

属性文档

cell

说明： cell是用于联系cell实体的ENTITYCALL。这个属性是只读的，且如果这个base实体没有关联的cell时属性是None。

类型：

• 只读ENTITYCALL

cellData

说明： cellData是一个字典属性。每当base实体没有创建它的cell实体时，cell实体的属性会保存在这里。 如果cell实体被创建，这些用到的值和cellData属性将被删除。除了cell实体在实体定义文件里指定的属性外，它还包含position, direction and spaceID。

类型：

• CELLDATADICT

className

说明： 实体的类名。

类型：

• 只读，string

client

说明： client是用于联系客户端的EntityCall。这个属性是只读的，且如果这个base实体没有关联的客户端时属性是None。

类型：

• 只读ENTITYCALL

databaseID

说明： databaseID是实体的永久ID(数据库id)。这个id是uint64类型且大于0，如果是0则表示该实体不是永久的。

类型：

• 只读 int64

databaseInterfaceName

说明： databaseInterfaceName是实体持久化所在的数据库接口名称，该接口名称在kbengine_defaults->dbmgr中配置。实体必须持久化过（databaseID>0）该属性才可用，否则返回空字符串。

类型：

• 只读 string

id

说明： id是实体的对象id。这个id是一个整型，在base，cell和client相关联的实体之间是相同的。 这个属性是只读的。

类型：

• 只读 int32

isDestroyed

说明： 如果该Entity实体已经被销毁了，这个属性为True。

类型：

• bool

shouldAutoArchive

说明： 这个属性决定了自动存档的策略。如果设为True，自动存档将可用，如果设为False，自动存档将不可用。 如果设为KBEngine.NEXT_ONLY，自动存档将在下一个预定的时间可用， 在下一次存档后，这个属性将置为False。

类型：

• True, False orKBEngine.NEXT_ONLY

shouldAutoBackup

说明： 这个属性决定了自动备份的策略。如果设为True，自动备份将可用，如果设为False，自动备份将不可用。 如果设为KBEngine.NEXT_ONLY，自动备份将在下一个预定的时间可用， 在下一次备份后，这个属性将置为False。

类型：

• True, False orKBEngine.NEXT_ONLY