KBEngine模块

KBEngine模块提供了Python脚本访问实体的部分，特别是它提供了定时器的注册与移除， 以及实体的创建。

类

• Entity
• Proxy

成员函数

• def addWatcher( path, dataType, getFunction ):
• def address( ):
• def MemoryStream( ):
• def charge( ordersID, dbID, byteDatas, pycallback ):
• def createEntity( ):
• def createEntityAnywhere( entityType, *params, callback ):
• def createEntityRemotely( entityType, baseMB, *params, callback ):
• def createEntityFromDBID( entityType, dbID, callback, dbInterfaceName ):
• def createEntityAnywhereFromDBID( entityType, dbID, callback, dbInterfaceName ):
• def createEntityRemotelyFromDBID( entityType, dbID, baseMB, callback, dbInterfaceName ):
• def createEntityLocally( entityType, *params ):
• def debugTracing( ):
• def delWatcher( path ):
• def deleteEntityByDBID( entityType, dbID, callback, dbInterfaceName ):
• def deregisterReadFileDescriptor( fileDescriptor ):
• def deregisterWriteFileDescriptor( fileDescriptor ):
• def executeRawDatabaseCommand( command, callback, threadID, dbInterfaceName ):
• def genUUID64( ):
• def getResFullPath( res ):
• def getWatcher( path ):
• def getWatcherDir( path ):
• def getAppFlags( ):
• def hasRes( res ):
• def isShuttingDown( ):
• def listPathRes( path, extension ):
• def lookUpEntityByDBID( entityType, dbID, callback, dbInterfaceName ):
• def matchPath( res ):
• def open( res, mode, encoding ):
• def publish( ):
• def quantumPassedPercent( ):
• def registerReadFileDescriptor( fileDescriptor, callback ):
• def registerWriteFileDescriptor( fileDescriptor, callback ):
• def reloadScript( fullReload ):
• def scriptLogType( logType ):
• def setAppFlags( flags ):
• def time( ):
• def urlopen( url, callback, postData, headers ):

回调函数

• def onBaseAppReady( isBootstrap ):
• def onBaseAppShutDown( state ):
• def onCellAppDeath( addr ):
• def onFini( ):
• def onBaseAppData( key, value ):
• def onBaseAppDataDel( key ):
• def onGlobalData( key, value ):
• def onGlobalDataDel( key ):
• def onInit( isReload ):
• def onLoseChargeCB( orderID, dbID, success, datas ):
• def onReadyForLogin( isBootstrap ):
• def onReadyForShutDown( ):
• def onAutoLoadEntityCreate( entityType, dbID ):

属性

成员函数文档

def addWatcher(path, dataType, getFunction):

功能说明： 与调试监视系统交互，允许用户向监视系统注册一个监视变量。 例：

>>> def countPlayers( ):
>>>     i = 0
>>>     for e in KBEngine.entities.values():
>>>     	if e.__class__.__name__ == "Avatar":
>>>     		i += 1
>>>     return i
>>>
>>> 
KBEngine
.
addWatcher
( "players", "UINT32", countPlayers )

这个函数添加一个监视变量在"scripts/players"监视路径之下。函数countPlayers在观察者观察时被调用。

参数：

def address():

功能说明： 返回内部网络接口的地址。

def MemoryStream():

功能说明： 返回一个新的MemoryStream对象。 MemoryStream对象存储的是二进制信息，提供这个类型是为了让用户能够方便的序列化与反序列化Python基本类型同时能与KBEngine底层序列化规则相同。 例如：你可以使用这个对象构造一个KBEngine能解析的网络数据包。 用法：

>>> s = KBEngine.MemoryStream()
>>> s
>>> b''
>>> s.append("UINT32", 1)
>>> s.pop("UINT32")
>>> 1

目前MemoryStream能够支持的类型仅为基本数据类型。参考:基本类型

def charge(ordersID, dbID, byteDatas, pycallback):

功能说明： 计费接口。

参数：

def createEntity():

功能说明： KBEngine.createEntityLocally的别名.

def createEntityAnywhere(entityType, params, callback):

功能说明： 创建一个新的Entity实体， 服务端可能选择任何的Baseapp来创建Entity实体。 这个方法应作为KBEngine.createEntityLocally的首选， 这样服务端会灵活地选择一个合适的Baseapp来创建实体。 函数参数需要提供创建的实体的类型，还有一个Python字典作为参数来初始化实体的值。 这个Python字典不需要用户提供所有的属性，没有提供的属性默认为实体定义文件".def"提供的默认值。 例子：

params = {
	"name" : "kbe", # base, BASE_AND_CLIENT
	"HP" : 100,	# cell, ALL_CLIENT, in cellData
	"tmp" : "tmp"	# baseEntity.tmp
}

def onCreateEntityCallback(entity)
	print(entity)

createEntityAnywhere("Avatar", params, onCreateEntityCallback)

参数：

返回：

• 通过回调返回Entity实体的entityCall。

def createEntityRemotely(entityType, baseMB, params, callback):

功能说明： 通过baseMB参数在一个指定的baseapp上创建一个新的Entity实体。 应该将KBEngine.createEntityAnywhere方法作为首选。 函数参数需要提供创建的实体的类型，还有一个Python字典作为参数来初始化实体的值。 这个Python字典不需要用户提供所有的属性，没有提供的属性默认为实体定义文件".def"提供的默认值。 例子：

params = {
	"name" : "kbe", # base, BASE_AND_CLIENT
	"HP" : 100,	# cell, ALL_CLIENT, in cellData
	"tmp" : "tmp"	# baseEntity.tmp
}

def onCreateEntityCallback(entity)
	print(entity)

createEntityRemotely("Avatar", baseEntityCall, params, onCreateEntityCallback)

参数：

返回：

• 通过回调返回Entity实体的entityCall。

def createEntityFromDBID(entityType, dbID, callback, dbInterfaceName):

功能说明： 从数据库里加载数据创建一个Entity实体。 这个新的Entity实体会在调用这个函数的Baseapp上创建。 如果该实体已经从数据库检出，那么将返回这个存在的Entity实体的引用。

参数：

def createEntityAnywhereFromDBID(entityType, dbID, callback, dbInterfaceName):

功能说明： 从数据库里加载数据创建一个Entity实体。 服务端可能选择任何的Baseapp来创建Entity实体。 使用这个函数将有助于BaseApps负载平衡。 如果该实体已经从数据库检出，那么将返回这个存在的Entity实体的引用。

参数：

返回：

• 通过回调返回Entity实体的entityCall。

def createEntityRemotelyFromDBID(entityType, dbID, baseMB, callback, dbInterfaceName):

功能说明： 从数据库里加载数据并通过baseMB参数在一个指定的baseapp上创建一个Entity实体。 如果该实体已经从数据库检出，那么将返回这个存在的Entity实体的引用。

参数：

返回：

• 通过回调返回Entity实体的entityCall。

def createEntityLocally(entityType, params):

功能说明： 创建一个新的Entity实体。 函数参数需要提供创建的实体的类型，还有一个Python字典作为参数来初始化实体的值。 这个Python字典不需要用户提供所有的属性，没有提供的属性默认为实体定义文件".def"提供的默认值。 KBEngine.createEntityAnywhere应该作为这个方法的首选，因为服务端可以灵活地 在合适的Baseapp上创建实体。 例子：

params = {
	"name" : "kbe", # base, BASE_AND_CLIENT
	"HP" : 100,	# cell, ALL_CLIENT, in cellData
	"tmp" : "tmp"	# baseEntity.tmp
}

baseEntity = createEntityLocally("Avatar", params)

参数：

返回：

• 新创建的Entity实体（参考Entity）

def debugTracing():

功能说明： 输出当前KBEngine追踪的Python扩展对象计数器。 扩展对象包括：固定字典、固定数组、Entity、EntityCall... 在服务端正常关闭时如果计数器不为零，此时说明泄露已存在，日志将会输出错误信息。 ERROR cellapp [0x0000cd64] [2014-11-12 00:38:07,300] - PyGC::debugTracing(): FixedArray : leaked(128) ERROR cellapp [0x0000cd64] [2014-11-12 00:38:07,300] - PyGC::debugTracing(): EntityCall : leaked(8)

参数：

def delWatcher(path):

功能说明： 与调试监视系统交互，允许用户在脚本删除监视的变量。

参数：

def deleteEntityByDBID(entityType, dbID, callback, dbInterfaceName):

功能说明： 从数据库删除指定的实体（包括属性所产生的子表数据），如果实体没有从数据库检出则删除成功， 如果实体已经从数据库检出那么KBEngine服务系统将会删除失败，并且从回调中返回Entity实体的entityCall。

参数：

def deregisterReadFileDescriptor(fileDescriptor):

功能说明： 注销已经通过KBEngine.registerReadFileDescriptor注册的回调。 例子: http://www.kbengine.org/assets/other/py/Poller.py

参数：

def deregisterWriteFileDescriptor(fileDescriptor):

功能说明： 注销已经通过KBEngine.registerWriteFileDescriptor注册的回调。 例子: http://www.kbengine.org/assets/other/py/Poller.py

参数：

def executeRawDatabaseCommand(command, callback, threadID, dbInterfaceName):

功能说明： 这个脚本函数在数据库上执行原始数据库命令，该命令将直接由相关数据库进行解析。 请注意使用该函数修改实体数据可能不生效，因为如果实体已经检出，被修改过的实体数据将仍会被实体存档而导致覆盖。 强烈不推荐这个函数用于读取或修改实体数据。

参数：

def genUUID64():

功能说明： 该函数生成一个64位的唯一ID。 注意：这个函数依赖于Baseapps服务进程启动参数gus，请正确设置启动参数保持唯一性。 另外如果gus超过65535则该函数只能在当前进程上保持唯一性。 用途： 多个服务进程上产生唯一物品ID并且在合服时不会产生冲突。 多个服务进程上产生一个房间ID，不需要进行唯一性校验。

返回：

• 返回一个64位的integer。

def getResFullPath(res):

功能说明： 获取资源的绝对路径。 注意：资源必须在KBE_RES_PATH之下才可以访问到。

参数：

返回：

• string，如果存在返回资源的绝对路径，否则返回空。

def getWatcher(path):

功能说明： 从KBEngine调试系统中获取一个监视变量的值。 例子：在baseapp1的Python命令行输入:

KBEngine.getWatcher("/root/stats/runningTime") 12673648533 KBEngine.getWatcher("/root/scripts/players") 32133

参数：

返回：

• 该变量的值。

def getWatcherDir(path):

功能说明： 从KBEngine调试系统中获取一个监视目录下的元素列表(目录、变量名)。 例子：在baseapp1的Python命令行输入:

KBEngine.getWatcher("/root") ('stats', 'objectPools', 'network', 'syspaths', 'ThreadPool', 'cprofiles', 'scripts', 'numProxices', 'componentID', 'componentType', 'uid', 'numClients', 'globalOrder', 'username', 'load', 'gametime', 'entitiesSize', 'groupOrder')

参数：

返回：

• 监视目录下的元素列表(目录、变量名)。

def getAppFlags():

功能说明： 获取当前引擎APP的标记, 参考:KBEngine.setAppFlags。

返回：

• KBEngine.APP_FLAGS_*。

def hasRes(res):

功能说明： 使用这个接口可以判断一个相对路径的资源是否存在。 注意：资源必须在KBE_RES_PATH之下才可以访问到。 例子:

KBEngine.hasRes("scripts/entities.xml") True

参数：

返回：

• BOOL, 存在返回True，否则返回False。

def isShuttingDown():

功能说明： 返回服务端是否正在关闭中。 在onBaseAppShutDown(state=0)回调函数被调用后，这个函数返回True。

返回：

• 系统正在关闭返回True，否则返回False。

def listPathRes(path, extension):

功能说明： 获得一个资源目录下的资源列表。 注意：资源必须在KBE_RES_PATH之下才可以访问到。 例子:

KBEngine.listPathRes("scripts/cell/interfaces") ('/home/kbe/kbengine/demo/res/scripts/cell/interfaces/AI.py', '/home/kbe/kbengine/demo/res/scripts/cell/interfaces/新建文本文档.txt') KBEngine.listPathRes("scripts/cell/interfaces", "txt") ('/home/kbe/kbengine/demo/res/scripts/cell/interfaces/新建文本文档.txt') KBEngine.listPathRes("scripts/cell/interfaces", "txt|py") ('/home/kbe/kbengine/demo/res/scripts/cell/interfaces/AI.py', '/home/kbe/kbengine/demo/res/scripts/cell/interfaces/新建文本文档.txt') KBEngine.listPathRes("scripts/cell/interfaces", ("txt", "py")) ('/home/kbe/kbengine/demo/res/scripts/cell/interfaces/AI.py', '/home/kbe/kbengine/demo/res/scripts/cell/interfaces/新建文本文档.txt')

参数：

返回：

• Tuple, 资源列表。

def lookUpEntityByDBID(entityType, dbID, callback, dbInterfaceName):

功能说明： 查询一个实体是否从数据库检出， 如果实体已经从数据库检出那么KBEngine服务系统将从回调中返回Entity实体的entityCall。

参数：

def matchPath(res):

功能说明： 使用相对路径的资源获得资源的绝对路径。 注意：资源必须在KBE_RES_PATH之下才可以访问到。 例子:

KBEngine.matchPath("scripts/entities.xml") '/home/kbe/kbengine/demo/res/scripts/entities.xml'

参数：

返回：

• string, 资源的绝对路径。

def open(res, mode, encoding):

功能说明： 使用这个接口可以使用相对路径来打开相关资源。 注意：资源必须在KBE_RES_PATH之下才可以访问到。

参数：

def publish():

功能说明： 这个接口返回当前服务端发行模式。

返回：

• int8，0：debug，1：release，其它可自定义。

def quantumPassedPercent():

功能说明： 返回取得当前tick占用一个时钟周期的百分比。

返回：

• 返回取得当前tick占用一个时钟周期的百分比。

def registerReadFileDescriptor(fileDescriptor, callback):

功能说明： 注册一个回调函数，这个回调函数当文件描述符可读时被调用。 例子: http://www.kbengine.org/assets/other/py/Poller.py

参数：

def registerWriteFileDescriptor(fileDescriptor, callback):

功能说明： 注册一个回调函数，这个回调函数当socket描述符/文件描述符可写时被调用。 例子: http://www.kbengine.org/assets/other/py/Poller.py

参数：

def reloadScript(fullReload):

功能说明： 重新加载与实体和自定义数据类型相关的Python模块。当前实体类会设置为新加载的类。 这个方法应该只用于开发模式，对于产品模式不合适。下面几点应该注意： 1）重载脚本仅仅能在Baseapp上执行， 用户应该确保所有的服务端组件加载完成。 2）自定义类型在脚本重载后应该确保内存中已经实例化的对象也被更新，下面是一个例子:

for e in 
KBEngine
.
entities
.values():
   if type( e ) is Avatar.Avatar:
      e.customData.__class__ = CustomClass

当这个方法完成时KBEngine.onInit( True ) 被调用。

参数：

返回：

• 重新加载成功返回True，否则返回False。

def scriptLogType(logType):

功能说明： 设置当前Python.print输出的信息类型(参考: KBEngine.LOG_TYPE_*)。

def setAppFlags(flags):

功能说明： 设置当前引擎APP的标记。 KBEngine.APP_FLAGS_NONE // 默认的(未设置标记) KBEngine.APP_FLAGS_NOT_PARTCIPATING_LOAD_BALANCING //不参与负载均衡 例如： KBEngine.setAppFlags(KBEngine.APP_FLAGS_NOT_PARTCIPATING_LOAD_BALANCING | KBEngine.APP_FLAGS_*)

def time():

功能说明： 这个方法返回当前游戏的时间（周期数）。

返回：

• uint32，当前游戏的时间，这里指周期数，周期受频率影响，频率由配置文件kbengine.xml或者kbengine_defaults.xml->gameUpdateHertz决定。

def urlopen(url, callback, postData, headers):

功能说明： 这个脚本函数在提供对外HTTP/HTTPS异步请求。

参数：

回调函数文档

def onBaseAppReady(isBootstrap):

功能说明： 当前Baseapp进程已经准备好的时候回调此函数。 注意：该回调接口必须实现在入口模块(kbengine_defaults.xml->entryScriptFile)中。

参数：

def onBaseAppShutDown(state):

功能说明： Baseapp关闭过程会回调此函数。 注意：该回调接口必须实现在入口模块(kbengine_defaults.xml->entryScriptFile)中。

参数：

def onCellAppDeath(addr):

功能说明： 某个cellapp死亡会回调此函数。 注意：该回调接口必须实现在入口模块(kbengine_defaults.xml->entryScriptFile)中。

参数：

def onFini():

功能说明： 引擎正式关闭后回调此函数。 注意：该回调接口必须实现在入口模块kbengine_defaults.xml->entryScriptFile)中。

def onBaseAppData(key, value):

功能说明： 当前 BaseApp 在收到其他 BaseApp 对 KBEngine.baseAppData 的广播，或在启动阶段从 dbmgr 回放已有键值时，如果某个顶层 key 被新增或覆盖，就会回调此函数。 当前进程自己直接执行 KBEngine.baseAppData[key] = value 时，不会额外再回调一次本函数。

注意：

• 该回调接口必须实现在入口模块(kbengine_defaults.xml -> entryScriptFile)中。
• 只有顶层 key -> value 的新增或整体改写会触发；value 内部可变对象的局部修改不会触发。

源码解析：

• 网络与消息系统：baseAppData / globalData / cellAppData 的同步链与回调分发

参数：

def onBaseAppDataDel(key):

功能说明： 当前 BaseApp 在收到其他 BaseApp 对 KBEngine.baseAppData 的删除广播时，会在对应顶层 key 从本地字典移除后回调此函数。 当前进程自己直接执行 del KBEngine.baseAppData[key] 时，不会额外再回调一次本函数。

注意：

• 该回调接口必须实现在入口模块(kbengine_defaults.xml -> entryScriptFile)中。
• 只对应顶层 key 的删除同步。

源码解析：

• 网络与消息系统：baseAppData / globalData / cellAppData 的同步链与回调分发

参数：

def onGlobalData(key, value):

功能说明： 当前 BaseApp 在收到其他 BaseApp 或 CellApp 对 KBEngine.globalData 的广播，或在启动阶段从 dbmgr 回放已有键值时，如果某个顶层 key 被新增或覆盖，就会回调此函数。 当前进程自己直接执行 KBEngine.globalData[key] = value 时，不会额外再回调一次本函数。

注意：

• 该回调接口必须实现在入口模块(kbengine_defaults.xml -> entryScriptFile)中。
• 只有顶层 key -> value 的新增或整体改写会触发；value 内部可变对象的局部修改不会触发。

源码解析：

• 网络与消息系统：baseAppData / globalData / cellAppData 的同步链与回调分发

参数：

def onGlobalDataDel(key):

功能说明： 当前 BaseApp 在收到其他 BaseApp 或 CellApp 对 KBEngine.globalData 的删除广播时，会在对应顶层 key 从本地字典移除后回调此函数。 当前进程自己直接执行 del KBEngine.globalData[key] 时，不会额外再回调一次本函数。

注意：

• 该回调接口必须实现在入口模块(kbengine_defaults.xml -> entryScriptFile)中。
• 只对应顶层 key 的删除同步。

源码解析：

• 网络与消息系统：baseAppData / globalData / cellAppData 的同步链与回调分发

参数：

def onInit(isReload):

功能说明： 当引擎启动后初始化完所有的脚本后这个接口被调用。 注意：该回调接口必须实现在入口模块(kbengine_defaults.xml->entryScriptFile)中。

参数：

def onLoseChargeCB(orderID, dbID, success, datas):

功能说明： 当在interfaces中调用KBEngine.chargeResponse后，如果该订单丢失或者是不明interfaces未被记录的订单会收到此回调通知。 注意：该回调接口必须实现在入口模块(kbengine_defaults.xml->entryScriptFile)中。

参数：

def onReadyForLogin(isBootstrap):

功能说明： 当引擎启动并初始化完成后会一直调用此接口询问脚本层是否准备完毕，如果脚本层准备完毕则loginapp允许客户端登录。 注意：该回调接口必须实现在入口模块(kbengine_defaults.xml->entryScriptFile)中。

参数：

返回：

• 返回值大于等于1.0则脚本层准备完成，否则返回准备的进度值0.0~1.0。

def onReadyForShutDown():

功能说明： 如果这个函数在脚本中有实现，当进程准备退出时，该回调函数被调用。 可以通过该回调控制进程退出的时机。 注意：该回调接口必须实现在入口模块(kbengine_defaults.xml->entryScriptFile)中。

返回：

• bool，如果返回True，则允许进入进程退出流程，返回其它值则进程会过一段时间后再次询问。

def onAutoLoadEntityCreate(entityType, dbID):

功能说明： 自动加载的实体创建时的回调，如果脚本层实现此回调，那么实体由脚本层创建，否则引擎默认使用createEntityAnywhereFromDBID来创建实体。 这个回调被调用是由于Entity.writeToDB时设置了实体自动加载。 注：该回调优先于onBaseAppReady执行，可在onBaseAppReady时检查是否已加载实体。

参数：

属性文档

LOG_ON_ACCEPT

说明： 这个常量由Proxy.onLogOnAttempt返回，意指允许新的client与一个Proxy实体绑定。 如果Proxy实体已经存在一个client绑定关系，那么将踢出之前的client。

LOG_ON_REJECT

说明： 这个常量由Proxy.onLogOnAttempt返回，意指拒绝当前client与Proxy实体绑定。

LOG_ON_WAIT_FOR_DESTROY

说明： 这个常量由Proxy.onLogOnAttempt返回，当前请求client将会等待直到Proxy实体完全销毁，底层再完成后续绑定过程。 在这返回之前Proxy.destroy或者Proxy.destroyCellEntity应该被调用。

LOG_TYPE_DBG

说明： 日志输出类型为调试类型。 由scriptLogType设置。

LOG_TYPE_ERR

说明： 日志输出类型为错误类型。 由scriptLogType设置。

LOG_TYPE_INFO

说明： 日志输出类型为常规信息类型。 由scriptLogType设置。

LOG_TYPE_NORMAL

说明： 日志输出类型为常规类型。 由scriptLogType设置。

LOG_TYPE_WAR

说明： 日志输出类型为警告类型。 由scriptLogType设置。

NEXT_ONLY

说明： 这个常量用于Entity.shouldAutoBackup和Entity.shouldAutoArchive属性。这个值意指在下一次认为可以的时候自动备份该实体，然后这个属性自动设为False（0）。

component

说明： 这是正运行在当前Python环境的组件。（至今为止）可能值有'cellapp', 'baseapp', 'client', 'dbmgr', 'bots' 和 'editor'。

entities

说明： entities是一个字典对象，包含当前进程上所有的实体。 调试泄露的实体（调用过destroy却没有释放内存的实体，通常是由于被引用导致无法释放）：

>>> KBEngine.entities.garbages.items()
[(1025, Avatar object at 0x7f92431ceae8.)]


>>> e = _[0][1]
>>> import gc
>>> gc.get_referents(e)
[{'spacesIsOk': True, 'bootstrapIdx': 1}, 
]

调试泄露的KBEngine封装的Python对象： KBEngine.debugTracing

类型：

• Entities

baseAppData

说明： BaseApp 进程级共享字典，只在所有 BaseApp 之间同步。 脚本执行 KBEngine.baseAppData[key] = value 或 del KBEngine.baseAppData[key] 时，请求会先发往 dbmgr 持有的权威副本，再广播给其他 BaseApp。 写入方本地值会在本次脚本赋值/删除流程中直接更新，不会再收到一次自己的回环广播；其他 BaseApp 收到广播后，才会触发 onBaseAppData 或 onBaseAppDataDel。 新启动的 BaseApp 在登录 dbmgr 时，还会收到当前全量快照，不只是后续增量。 键和值都必须能在目标组件上完成 pickle/unpickle。

源码解析：

• 网络与消息系统：baseAppData / globalData / cellAppData 的同步链与回调分发

例子：

KBEngine.baseAppData["hello"] = "there"

其余 BaseApp 可以读取：

print(KBEngine.baseAppData["hello"])

参看：KBEngine.onBaseAppData 和 KBEngine.onBaseAppDataDel。

注意：

• 同步粒度是顶层 key -> value；只改 value 内部元素不会广播。
• 它不会同步到 CellApp。
• 不要做下面这种“局部改列表元素”的写法：

KBEngine.baseAppData["list"] = [1, 2, 3]

KBEngine.baseAppData["list"][1] = 7

这样本地看到的是 [1, 7, 3]，其他 BaseApp 仍然是 [1, 2, 3]。

globalData

说明： BaseApp 与 CellApp 共享的进程级字典。 脚本执行 KBEngine.globalData[key] = value 或 del KBEngine.globalData[key] 时，请求会先进入 dbmgr 持有的权威副本，再由 dbmgr 广播给所有其他 BaseApp 和 CellApp。 写入方本地不会收到一遍自己的同步回调；其他组件在完成反序列化和本地落地后，才会触发 onGlobalData 或 onGlobalDataDel。 新启动的 BaseApp 或 CellApp 也会在登录 dbmgr 后收到当前全量快照。 键和值都必须能在目标组件上完成 pickle/unpickle。

源码解析：

• 网络与消息系统：baseAppData / globalData / cellAppData 的同步链与回调分发

例子：

KBEngine.globalData["hello"] = "there"

其余 BaseApp 或 CellApp 可以读取：

print(KBEngine.globalData["hello"])

参看：KBEngine.onGlobalData 和 KBEngine.onGlobalDataDel。

注意：

• 同步粒度是顶层 key -> value；只改 value 内部元素不会广播。
• 它同步给所有 BaseApp 和 CellApp，但不会同步到 loginapp、interfaces 这类其他组件。
• 不要做下面这种“局部改列表元素”的写法：

KBEngine.globalData["list"] = [1, 2, 3]

KBEngine.globalData["list"][1] = 7

这样本地看到的是 [1, 7, 3]，远端组件仍然是 [1, 2, 3]。