Base - KBEngine base 文档

KBEngine

previous page next page
KBEngine

Base类

[KBEngine模块]

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

import KBEngine

成员函数

def addTimer( self, initialOffset, repeatOffset=0, userArg=0 ):
def createCellEntity( self, cellEntityMB ):
def createInNewSpace( self, cellappIndex ):
def delTimer( self, id ):
def destroy( self, deleteFromDB, writeToDB ):
def destroyCellEntity( self ):
def teleport( self, baseEntityMB ):
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 ):

属性

cell  只读 CellEntityMailbox
cellData  CELLDATADICT
className  只读 string
client  只读 ClientEntityMailbox
databaseID  只读 int64
databaseInterfaceName  只读 string
id  只读 int32
isDestroyed  bool
shouldAutoArchive  True, False or KBEngine.NEXT_ONLY
shouldAutoBackup  True, False or KBEngine.NEXT_ONLY

详细描述

Base类代表一个驻留在Baseapp上的实体。 Base 实体可以通过KBEngine.createBase函数(以及以createBase为前缀的函数)创建。一个Base实体也可以通过Cellapp的函数KBEngine.createEntityOnBaseApp远程创建。

一个Base实体可以在一个活动的cells里面链接到一个实体，还可以被用来在一个合适的cell上创建一个关联的实体。 这个类允许你创建和销毁在cell上的实体或者在base实体上注册一个定时器也或者访问此对象的联系信息，
还可以访问一个CellEntityMailBox，通过它这个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.Base ):
 
    def __init__( self ):
        KBEngine.Base.__init__( self )
 
        # 增加一个定时器，5秒后执行第1次，而后每1秒执行1次，用户参数是9
        self.addTimer( 5, 1, 9 )
 
        # 增加一个定时器，1秒后执行，用户参数缺省是0
        self.addTimer( 1 )
 
    # Base的定时器回调"onTimer"被调用
    def onTimer( self, id, userArg ):
        print "MyBaseEntity.onTimer called: id %i, userArg: %i" % ( id, userArg )
        # if 这是不断重复的定时器，当不再需要该定时器的时候，调用下面函数移除:
        #     self.delTimer( id )

参数：

initialOffset float，指定定时器从注册到第一次回调的时间间隔（秒）。
repeatOffset float，指定第一次回调执行后每次执行的时间间隔（秒）。必须用函数delTimer移除定时器，否则它会一直重复下去。值小于等于0将被忽略。
userArg integer，指定底层回调"onTimer"时的userArg参数值。

返回:

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

def createCellEntity( self, cellEntityMB ):

功能说明：

请求在一个cell里面创建一个关联的实体。

用于创建cell实体的信息被存储在该实体的属性cellData里。这个属性是一个字典，对应实体的.def文件里的默认值，同时还包括用于表示
实体位置和方向(roll, pitch, yaw)的"position", "direction" 和 "spaceID"。

参数：

cellEntityMB 一个可选的CellEntityMailBox参数， 指定哪个空间里创建这个cell实体的。

只能使用一个直接的CellEntityMailBox。如果你有一个实体的BaseMailbox，你不可以使用baseMailbox.cell传给这个函数。
你必须在这个实体的base上创建一个新的函数来回传这个直接的CellEntityMailBox。

例如： 
baseMailboxOfNearbyEntity.createCellNearSelf( self )
在实体的base上： 
def createCellNearSelf( self, baseMailbox ):
    baseMailbox.createCellNearHere( self.cell )
在原实体的base上调用createCellNearSelf()方法： 
def createCellNearHere( self. cellMailbox ):
    self.createCellEntity( cellMailbox )

def createInNewSpace( self, cellappIndex ):

功能说明：

在一个空间的cell上创建一个关联的实体，它请求通过cellappmgr来完成。

用于创建cell实体的信息被存储在该实体的属性cellData里。这个属性是一个字典，对应实体的.def文件里的默认值同时还包括用于表示
实体位置和方向(roll, pitch, yaw)的"position", "direction" 和 "spaceID"。

参数：

cellappIndex integer，为None或者0则由引擎负载均衡进行动态选择，如果大于0则在指定的cellapp中创建space。
例子：假如预期会开启4个cellapp，那么cellappIndex需要指定时索引可以是1、2、3、4，
如果实际运行的cellapp不足4个，例如只有3个，那么cellappIndex输入4时由于数量溢出4代表1，如果输入5则代表2。

提示：此功能可以结合KBngine.setAppFlags(KBEngine.APP_FLAGS_NOT_PARTCIPATING_LOAD_BALANCING)来使用，例如：将大地图space放到几个固定的cellapp中，并将这些cellapp设置为不参与负载均衡，其他cellapp用于放置副本space。 创建副本space时cellappIndex设置为0或者None，副本地图的消耗将不会影响到大地图进程，从而保证了主场景的流畅。

def delTimer( self, id ):

功能说明：

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

到Base.addTimer参考定时器的一个使用例子。

参数：

id integer，它指定要移除的定时器id。

def destroy( self, deleteFromDB, writeToDB ):

功能说明：

这个函数销毁该实体的base部分。如果实体存在cell部分，那么用户必须先销毁cell部分，否则将会产生错误。要销毁实体的cell部分，调用Base.destroyCellEntity。

也许在onLoseCell回调里调用self.destroy更为恰当。这能保证实体的base部分被销毁。

参数：

deleteFromDB 如果是True，在数据库里与这个实体有关联的条目将会被删除，该参数默认为False。
writeToDB 如果是True，与这个实体相关联的存档属性将会写入数据库。只有在这个实体是从数据库读取的或者是使用过Base.writeToDB写入数据库才会被执行。这个参数默认为True，但当deleteFromDB为True的时候它将被忽略。

def destroyCellEntity( self ):

功能说明：

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

def teleport( self, baseEntityMB ):

功能说明：

teleport会瞬移这个实体的cell部分到参数指定的实体所在的空间。

在抵达新的空间后，Entity.onTeleportSuccess被调用。这可以用来在新的空间里移动该实体到合适的位置。

参数：

baseEntityMB 实体应该移到的指定实体所在的空间，baseEntityMB即指定实体的mailbox。当成功的时候，与此参数相关联的cell实体会被传入到Entity.onTeleportSuccess函数。

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

功能说明：

该函数保存这个实体的存档属性到数据库，使得以后需要的时候可以重新从数据库加载。

实体也可以被标记为自动加载，这样当服务启动后实体将会被重新创建。

参数：

callback 这个可选参数是当数据库操作完成后的回调函数。 它有两个参数。第一个是boolean类型标志成功或失败，第二个是base实体。
shouldAutoLoad 这个可选参数指定这个实体在服务启动的时候是否需要从数据库加载。
注意：服务器启动时自动加载实体，底层默认将会调用createBaseAnywhereFromDBID将实体创建到一个负载最小的baseapp上，整个过程将会在第一个启动的baseapp调用onBaseAppReady之前完成。

脚本层可以在个性化脚本(kbengine_defaults.xml->baseapp->entryScriptFile定义)中重新实现实体的创建方法，例如：
def onAutoLoadEntityCreate(entityType, dbid):
      KBEngine.createBaseFromDBID(entityType, dbid)
dbInterfaceName string，可选参数，指定由某个数据库接口来完成, 默认使用"default"接口。数据库接口由kbengine_defaults.xml->dbmgr->databaseInterfaces中定义。

回调函数文档

def onCreateCellFailure( self ):

功能说明：

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

def onDestroy( self ):

功能说明：

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

def onGetCell( self ):

功能说明：

如果这个函数在脚本中有实现，这个函数在它获得cell实体的时候被调用。 这个函数没有参数。

def onLoseCell( self ):

功能说明：

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

def onPreArchive( self ):

功能说明：

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

def onRestore( self ):

功能说明：

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

def onTimer( self, timerHandle, userData ):

功能说明：

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

参数：

timerHandle 定时器的id。
userData 传进Base.addTimer的integer用户数据。

def onWriteToDB( self, cellData ):

功能说明：

如果这个函数在脚本中有实现，这个函数在实体数据将要写进数据库的时候被调用。

需要注意的是在该回调里调用writeToDB会导致无限循环。

参数：

cellData 包含将要存进数据库的cell属性。 cellData是一个字典。

属性文档

cell

说明：

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

类型：

只读 MAILBOX

cellData

说明：

cellData是一个字典属性。每当base实体没有创建它的cell实体时，cell实体的属性会保存在这里。

如果cell实体被创建，这些用到的值和cellData属性将被删除。除了cell实体在实体定义文件里指定的属性外，它还包含position, direction and spaceID。

类型：

CELLDATADICT

className

说明：

实体的类名。

类型：

只读，string

client

说明：

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

类型：

只读 MAILBOX

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

说明：

如果该Base实体已经被销毁了，这个属性为True。

类型：

bool

shouldAutoArchive

说明：

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

类型：

True, False or KBEngine.NEXT_ONLY

shouldAutoBackup

说明：

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

类型：

True, False or KBEngine.NEXT_ONLY

版权归KBEngine所有。

previous page start next page