# 地图插件调整（中）

# 插件核心代码解析

阅读源码之前，需要对python脚本语言有基础的了解。
插件中使用了yield关键字实现了一个延时函数执行机制，具体yield的用法可以自助查询，但是不了解也不影响对逻辑的理解，简单地当成一个延时的Timer就行了。
默认对插件的事件、回调机制比较了解，相关基础知识详见事件简介。

# mapAttrsClientSys.py

# 初始化

初始化时，生成了一个【textBoardMgr.py】中定义的类【TextBoardMgr】的实例

class MapAttrsClientSys(ClientSystem):
	def __init__(self, namespace, systemName):
		...
		self.mTextMgr = TextBoardMgr(self.mPlayerId, offset=50.0)

# 处理引擎事件【UiInitFinished】

回调函数【OnUiInitFinished】中向服务端发送一个自定义事件，用于提示服务端本客户端准备就绪。
服务端接收到此事件后会回应客户端自定义事件【ServerEvent.LoginResponse】，事件中会带有客户端玩家初始所在的维度信息与【功能5、在地图指定位置设置浮空文字】相关的配置信息

class MapAttrsClientSys(ClientSystem):
	def __init__(self, namespace, systemName):
		...
		util.ListenClientEngineEvent("UiInitFinished", self, self.OnUiInitFinished)

	def OnUiInitFinished(self, data):
		print 'OnUiInitFinished', data
		requestData = {
			"playerId": self.mPlayerId,
		}
		util.NotifyToServer(ClientEvent.PlayerEnter, requestData)

# 处理引擎事件【DimensionChangeClientEvent】

回调函数【OnDimChange】中更新当前自己所在的维度

class MapAttrsClientSys(ClientSystem):
	def __init__(self, namespace, systemName):
		...
		util.ListenClientEngineEvent("DimensionChangeClientEvent", self, self.OnDimChange)
	
	def OnDimChange(self, data):
		self.mPlayerDim = data["toDimensionId"]
		self.mTextMgr.OnDimChange(data)
	
	def OnLoginResponse(self, data):
		print 'OnLoginResponse', data
		self.mPlayerDim = data["dim"]

# 处理服务端自定义事件【ServerEvent.LoginResponse】

回调函数【OnLoginResponse】中，从服务端返回的信息中，初始化自己当前所在的维度，并提交【功能5、在地图指定位置设置浮空文字】所需的浮空文字配置信息给【TextBoardMgr】实例

class MapAttrsClientSys(ClientSystem):
	def __init__(self, namespace, systemName):
		...
		util.ListenServerEvent(ServerEvent.LoginResponse, self, self.OnLoginResponse)
	
	def OnLoginResponse(self, data):
		print 'OnLoginResponse', data
		self.mPlayerDim = data["dim"]
		self.mTextMgr.Init(data["configData"])

# textBoardMgr.py

管理浮空文字，实现【功能5】的类
浮空文字的创建，依赖于浮空文字所在位置的区块已经成功加载进客户端的内存中，否则无法创建成功
需要一个管理类通过时钟触发的检查逻辑，动态判定哪些浮空文字进入了玩家的【逻辑视野】，并且尝试创建之。
需要处理和维度跳转相关的清理、重新创建的逻辑

class TextBoardMgr(object):
	# 创建对象时，初始化参数为玩家自己的entityId，以及逻辑视野（当浮空文字距离玩家小于多少时，便会被创建）
	def __init__(self, playerId, offset=5.0):
		...
		self.mCheckOffset = offset
		
	def Init(self, configData):
		# 通过服务端自定义事件【ServerEvent.LoginResponse】中的浮空文字配置信息，生成等待创建的浮空文字字典。
		textWithPlaceList = configData.get("text_with_place_list", None)
		...
		# 注册每3秒钟执行一次的timer，触发检查是否有浮空文字需要被创建
		self.mAddTimer = comp.AddRepeatedTimer(3.0, self.CheckAddTextBoard)

	def Destroy(self):
		...
	# 当玩家所处维度变化时，删除位于旧维度的全部浮空文字实例
	def OnDimChange(self, data):
		...
	# 检查是否有浮空文字需要被创建
	def CheckAddTextBoard(self):
		...
		for idx, conf in self.mTextWithPlaceMap.iteritems():
			# 跳过已经创建完成的浮空文字
			if self.mTextIdxToEntityId.has_key(idx):
				continue
			# 跳过维度不一致的浮空文字
			if dim != conf["dim"]:
				continue
			# 跳过逻辑视野之外的浮空文字
			if self.IsFar(pos, conf["pos"]):
				continue
			...
			# 创建浮空文字
			entityId = util.GetSystem().CreateEngineTextboard(
				conf["text"], self.mPlayerId, conf["pos"], conf["textColor"],
				conf["tagColor"], conf["size"], conf["depthTest"])
			if entityId is None or entityId <= 0:
				continue
			# 缓存浮空文字的实体ID，记录已经创建成功了
			self.mTextIdxToEntityId[idx] = entityId

# mapAttrsServerSys.py

# 初始化

读取mod.json的配置信息
生成【coroutineMgrGas.py】中定义的类【CoroutineMgr】的实例
生成【playerMgr.py】中定义的类【PlayerMgr】的实例，假如配置中激活了【功能6、设置地图边界】的话。

class MapAttrsServerSys(ServerSystem):
	def __init__(self, namespace, systemName):
		...
		util.LoadModConf()
		...
		self.Init()
		self.mCoroutineMgr = CoroutineMgr()
		
	def Update(self):
		self.mCoroutineMgr.Tick()
	
	def Init(self):
		...
		self.mPlayerMgr = None
		if util.GetModConfByField("map_area_limit"):
			self.mPlayerMgr = PlayerMgr()
			self.mPlayerMgr.Init(util.GetModConfByField("map_area_limit"))

# 功能1、是否开启主城保护

直接使用组件API【OpenCityProtect】实现

gameComp = self.CreateComponent(extraServerApi.GetLevelId(), 'Minecraft', 'game')
if util.GetModConfByField("open_map_protect"):
	suc = gameComp.OpenCityProtect()

# 功能2、是否禁止藤蔓生长

直接使用组件API【DisableVineBlockSpread】实现

gameComp = self.CreateComponent(extraServerApi.GetLevelId(), 'Minecraft', 'game')
if util.GetModConfByField("forbid_vine_spread"):
	gameComp.DisableVineBlockSpread(True)

# 功能3、是否禁止流体流动

直接使用组件API【ForbidLiquidFlow】实现

gameComp = self.CreateComponent(extraServerApi.GetLevelId(), 'Minecraft', 'game')
if util.GetModConfByField("forbid_liquid_flow"):
	gameComp.ForbidLiquidFlow(True)

# 功能4、是否定时清理掉落物与定时清理掉落物间隔

使用组件API【AddRepeatedTimer】注册一个定时执行的清理函数
使用【/kill @e[type=item]】指令清理道具实体

gameComp = self.CreateComponent(extraServerApi.GetLevelId(), 'Minecraft', 'game')
self.mCleanDropTimer = None
if util.GetModConfByField("enable_clean_drop_item"):
	interval = util.GetModConfByField("clean_drop_item_interval")
	if interval > 0:
		self.mCleanDropTimer = gameComp.AddRepeatedTimer(interval, self.CleanDropItem)
		
def CleanDropItem(self):
	comp = extraServerApi.CreateComponent(extraServerApi.GetLevelId(), "Minecraft", "command")
	comp.SetCommand("/kill @e[type=item]")

# 功能7、设置玩家是否可丢弃物品

直接使用组件API【SetDisableDropItem】实现
在玩家登录完成后（客户端的初始化完成消息），使用组件API【EnableKeepInventory】保证死亡物品也不掉落

gameComp = self.CreateComponent(extraServerApi.GetLevelId(), 'Minecraft', 'game')
if util.GetModConfByField("forbid_drop_item"):
	gameComp.SetDisableDropItem(True)

if util.GetModConfByField("forbid_drop_item"):
	comp = self.CreateComponent(playerId, "Minecraft", "player")
	suc = comp.EnableKeepInventory(True)
	print "EnableKeepInventory for player=%s suc=%s" % (playerId, suc)

# 功能8、玩家是否可捡起物品

注册引擎事件【ServerPlayerTryTouchEvent】和【ServerPlayerGetExperienceOrbEvent】
回调函数【OnPlayerPickItem】中设置cancel=True，pickupDelay=100000（取消本次拾取，并设置下次拾取的cd大于97813帧，视作无法拾取）
回调函数【ServerPlayerGetExperienceOrbEvent】中设置cancel=True（取消本次拾取）

gameComp = self.CreateComponent(extraServerApi.GetLevelId(), 'Minecraft', 'game')
if util.GetModConfByField("forbid_pickup_item"):
	util.ListenServerEngineEvent("ServerPlayerTryTouchEvent", self, self.OnPlayerPickItem)
	util.ListenServerEngineEvent("ServerPlayerGetExperienceOrbEvent", self, self.OnPlayerPickOrb)

def OnPlayerPickItem(self, data):
	data["cancel"] = True
	data["pickupDelay"] = 100000

def OnPlayerPickOrb(self, data):
	data["cancel"] = True

# 功能9、可以根据针对地图编辑器导出的地图文件替换游戏地图

只有对应区块加载进内存的前提下，才能对区块对应的地图方块进行修改，所以需要一个用于【开地图】的玩家，在配置中需要指定一个特定的uid。
利用mCoroutineMgr实现的延时执行函数，每隔一定时间执行一块地图区域的覆盖工作
单次地图区域的覆盖逻辑：先把【开地图】的玩家传送到需要进行地图覆盖的位置，然后使用【PlaceStructure】函数对地图区域进行覆盖

def SetMapStructure(self, playerId, playerUid):
	if playerUid != util.GetModConfByField("change_uid"):
		return
	needChangeDimension = util.GetModConfByField("change_map_dimension")
	neteaseMapStructureConfigPath = commonNetgameApi.GetModScriptRootDir("neteaseMapAttrsScript") + "/mapStructureConfig" + "/neteaseMapStructueConfig.json"
	neteaseMapStructureConfig = util.read_json(neteaseMapStructureConfigPath)
	print "SetMapStructure",neteaseMapStructureConfigPath, neteaseMapStructureConfig
	if neteaseMapStructureConfig is None:
		return
	for oneConfig in neteaseMapStructureConfig:
		self.mCoroutineMgr.StartCoroutine(self.RealSetMapStructure(playerId, needChangeDimension, oneConfig, neteaseMapStructureConfig.index(oneConfig) + 1))
		
def RealSetMapStructure(self, playerId, needChangeDimension, oneConfig, delayFrame):
	yield -1 * delayFrame * 60
	tpPos = oneConfig.get("pos")
	#changeDimension = oneConfig.get("change_map_dimension")
	dimensionComp = self.CreateComponent(playerId, "Minecraft", "dimension")
	# playerDimension = dimensionComp.GetEntityDimensionId()
	print "tpPos", tpPos, needChangeDimension
	dimensionComp.ChangePlayerDimension(needChangeDimension, (tpPos[0], tpPos[1] + 3, tpPos[2]))
	strucFile = oneConfig.get("file")[:-12]# 去掉后缀
	strucFile = "mapStructure:" + strucFile
	print "RealSetMapStructureFile", strucFile, tuple(tpPos)
	gameComp = self.CreateComponent(extraServerApi.GetLevelId(), "Minecraft", "game")
	suc = gameComp.PlaceStructure(playerId, tuple(tpPos), strucFile.encode("utf-8"))
	print "RealSetMapStructure", suc

# 处理客户端自定义事件【ClientEvent.PlayerEnter】

回调函数【OnClientEnter】中，获取目标客户端的玩家所在的维度，玩家的uid（这两个信息当前仅能通过服务器API获取），以及配置信息中的浮空文字配置（浮空文字显示逻辑由客户端实现），并返回给目标客户端（利用服务器自定义事件【ServerEvent.LoginResponse】）
在【OnClientEnter】中，才调用【EnableKeepInventory】保证死亡物品也不掉落，是因为在【AddServerPlayerEvent】中，其实引擎层的player实体还没有彻底创建完毕，有些组件API是没法正常生效的。

util.ListenClientEvent(ClientEvent.PlayerEnter, self, self.OnClientEnter)

def OnClientEnter(self, data):
	...
	playerId = data['playerId']
	uid = netgameApi.GetPlayerUid(playerId)
	responseData = {
		"uid": uid,
		"dim": util.GetEntityDimensionId(playerId),
		"configData": {},
	}
	responseData["configData"]["text_with_place_list"] = self.mCheckedTextWithPlaceList
	util.NotifyToClient(playerId, ServerEvent.LoginResponse, responseData)
	if util.GetModConfByField("forbid_drop_item"):
		comp = self.CreateComponent(playerId, "Minecraft", "player")
		suc = comp.EnableKeepInventory(True)
		print "EnableKeepInventory for player=%s suc=%s" % (playerId, suc)

# 实现运营指令（1）设置指定服务器地图边界。

注册控制服自定义事件【MasterEvent.SetMapArea】
回调函数【OnSetMapArea】中修改实际生效的地图边界，并返回结果给控制服
传递新的地图边界信息给【mPlayerMgr】对象，【功能6、设置地图边界】的逻辑有此对象负责管理。

util.ListenMasterEvent(MasterEvent.SetMapArea, self, self.OnSetMapArea)

def OnSetMapArea(self, data):
	bSuc, reason = self.TryChangeAreaLimit(data.get("minPos", None), data.get("maxPos", None))
	...
	self.NotifyToMaster(ServerEvent.HttpResponse, httpRes)

def TryChangeAreaLimit(self, minPos, maxPos):
	if not self.mPlayerMgr:
		return False, "not support area limit this server"
	if minPos is None or maxPos is None:
		return False, "must set minPos and maxPos first"
	try:
		for i in xrange(3):
			if minPos[i] >= maxPos[i]:
				return False, "minPos must larger than maxPos"
	except:
		return False, "minPos and maxPos must like (x, y, z)"
	self.mPlayerMgr.UpdateAreaLimit(minPos, maxPos)
	return True, ""

# playerMgr.py

管理玩家的对象
用于实现【功能6、设置地图边界（玩家走出边界会被传送回最近离开的合法位置）】

# SinglePlayer类

保留最近一段时间内的，玩家的移动轨迹（以定时坐标采样的形式）
当玩家走出边界，需要被传送时，从近期的移动轨迹中找出最近的合法位置，并强制传送

class SinglePlayer(object):
	def __init__(self, playerId):
		...
	# 缓存玩家的移动轨迹且去重
	# 当缓存数据超过30个点的时候，一次性的裁剪到剩余最新的15个点
	def CacheLastSafePos(self, x, y, z):
		if self.mLastSafePos and self.mLastSafePos[0] == x and self.mLastSafePos[1] == y and self.mLastSafePos[2] == z:
			return
		pos = (x, y, z)
		self.mLastSafePos = pos
		self.mCanUseSafePosList.insert(0, pos)
		if len(self.mCanUseSafePosList) > 30:
			self.mCanUseSafePosList = self.mCanUseSafePosList[:15]
	# 从移动轨迹中，获取最近离开的合法位置
	# 由于地图边界是可以动态设置的，过去缓存的轨迹现在就不一定合法了，所以最终用地图范围的中心点保底
	def FindUsableSafePos(self):
		for pos in self.mCanUseSafePosList:
			if util.IsInArea(pos, AABB_MIN, AABB_MAX):
				return pos
		return GetLimitAreaCenter()
	# 强制传送玩家到最近离开的合法位置
	# 强制传送前，需要强制玩家下坐骑
	def SyncToSafePos(self):
		# 如果找不到可以放置的点，就不重新设置了
		safePos = self.FindUsableSafePos()
		if safePos is None:
			return
		rideComp = extraServerApi.CreateComponent(self.mPlayerId, "Minecraft", "ride")
		if rideComp:
			riderId = rideComp.GetEntityRider()
			if riderId != -1:
				rideComp.StopEntityRiding()
				riderPosComp = extraServerApi.CreateComponent(riderId, "Minecraft", "pos")
				riderPosComp.SetPos(safePos)
		posComp = extraServerApi.CreateComponent(self.mPlayerId, "Minecraft", "pos")
		posComp.SetPos(safePos)

# PlayerMgr类

注册一个每秒执行一次的循环函数【CheckSafePos】
每次执行【CheckSafePos】，都会遍历当前全部在线玩家，判定玩家当前的位置，假如位置没有超出地图边界，那么就缓存，假如维持超出地图边界，那么就触发强制传送

class PlayerMgr(object):
	def __init__(self):
		...

	def Init(self, map_area_limit):
		gameComp = extraServerApi.CreateComponent(extraServerApi.GetLevelId(), 'Minecraft', 'game')
		self.mCheckTimer = gameComp.AddRepeatedTimer(1.0, self.CheckSafePos)
		...
	
	def CheckSafePos(self):
		for playerId, obj in self.mPlayerMap.iteritems():
			...
			if util.IsInArea((x, y, z), AABB_MIN, AABB_MAX):
				obj.CacheLastSafePos(x, y, z)
			else:
				obj.SyncToSafePos()

# coroutineMgrGas.py

利用python的yield关键字与迭代器机制，实现的延时执行函数的管理器
当yield的返回值为负数时，每个tick都会加1，直到为0时开始执行yield后面的语句，等价于多少帧后执行
当yield的返回值为正数时，在当前时间+返回值的时刻之后的第一帧，开始执行yield后面的语句，等价于多少秒后执行

class CoroutineMgr(object):
    ...
    @classmethod
    def Tick(cls):
        if cls.addCoroutines:
            for c,v in cls.addCoroutines.iteritems():
                cls.coroutines[c] = v
        cls.addCoroutines = {}
        if cls.globalEnd:
            for c in cls.globalEnd:
                if cls.coroutines.get(c):
                    del cls.coroutines[c]
            cls.globalEnd = []
        ended = []
        for c, v in cls.coroutines.iteritems():
            try:
                if v < 0:                                               
                    v += 1
                    cls.coroutines[c] = v
                if v == 0 or (v > 0 and time.time() >= v):
                    newv = c.next()                                     
                    if newv > 0:
                        newv = newv + time.time()
                    cls.coroutines[c] = newv
            except StopIteration:
                ended.append(c)
        for c in ended:
            del cls.coroutines[c]

def DelayDoByFrame(self, delayFrame):
    yield -1 * delayFrame

def DelayDoBySecond(self, delaySec):
    yield delaySec

# mapAttrsMasterSys.py

仅用于实现【运营指令（1）设置指定服务器地图边界】
分析http请求的参数，转发运营指令中的地图边界信息到指定类型的服务器进程（当时设计时，仅支持一种服务器类型单独一个进程）
监听来自其他服务器进程的自定义事件【ServerEvent.HttpResponse】，返回最终处理结果给运营指令的请求方

# 监听http请求【/mapAttrs/set-area-limit】

回调函数【OnChangeAreaLimit】中，通过服务器类型定位到对应的服务器ID，并转发新的地图边界信息给对应服务器ID的进程

class MapAttrsMasterSys(MasterSystem):
	def __init__(self, namespace, systemName):
		...
		masterHttp.RegisterMasterHttp("/mapAttrs/set-area-limit", self, self.OnChangeAreaLimit)

	def OnChangeAreaLimit(self, clientId, requestBody):
		eventData = json.loads(requestBody)
		...
		serverId = self.GetServerIdByType(eventData['type'])
		...
		eventData['clientId'] = clientId
		self.NotifyToServerNode(serverId, MasterEvent.SetMapArea, eventData)

	def GetServerIdByType(self, typeKey):
		...

# 处理服务端自定义事件【ServerEvent.HttpResponse】

回调函数【OnHttpResponse】中，直接打包返回结果给http请求的发起方

class MapAttrsMasterSys(MasterSystem):
	def __init__(self, namespace, systemName):
		...
		util.ListenServerEvent(ServerEvent.HttpResponse, self, self.OnHttpResponse)

	def OnHttpResponse(self, args):
		res = self.makeResponse(args['code'], args['message'], args['entity'])
		masterHttp.SendHttpResponse(args['clientId'], res)

# 多端协作逻辑

整个地图属性插件的逻辑都比较简单和原子化，仅少量的逻辑涉及到多端协作

# 客户端登录

【功能5、在地图指定位置设置浮空文字】，由每个客户端自主创建浮空文字实现
但是对应需要的浮空文字的维度和坐标配置信息，都在服务端的mod.json中，需要从服务端获取
此外，创建和维护浮空文字，需要知道当前客户端所在的维度信息，客户端能够通过引擎事件【DimensionChangeClientEvent】，监听到切换维度的事件，但是没有获取刚登录时，初始维度的信息，也需要从服务端获取
一般而言，考虑到客户端启动需要加载场景、加载人物、初始化UI等一系列工作，服务端也需要客户端主动给出一个明确的信号，确认客户端已经准备完毕，可以正常运行脚本逻辑。

# 客户端登录时的多端数据流如下图：

# 运营指令（1）设置指定服务器地图边界

运营指令以http请求的方式发送给控制服
控制服解析请求参数后定位到具体实现功能的服务器进程，并发送事件给目标游戏服/大厅服
服务器根据事件的参数，调整地图边界，并以事件的方式返回结果给控制服
控制服返回运营指令执行结果给http的请求方

https://mc.res.netease.com/pc/zt/20201109161633/mc-dev/assets/img/ditu_27.6f168b1c.png

进阶

25分钟

← 地图插件调整（上）地图插件调整（下） →

# 地图插件调整（中）

# 插件核心代码解析

# mapAttrsClientSys.py

# 初始化

# 处理引擎事件【UiInitFinished】

# 处理引擎事件【DimensionChangeClientEvent】

# 处理服务端自定义事件【ServerEvent.LoginResponse】

# textBoardMgr.py

# mapAttrsServerSys.py

# 初始化

# 功能1、是否开启主城保护

# 功能2、是否禁止藤蔓生长

# 功能3、是否禁止流体流动

# 功能4、是否定时清理掉落物 与 定时清理掉落物间隔

# 功能7、设置玩家是否可丢弃物品

# 功能8、玩家是否可捡起物品

# 功能9、可以根据针对地图编辑器导出的地图文件替换游戏地图

# 处理客户端自定义事件【ClientEvent.PlayerEnter】

# 实现运营指令（1）设置指定服务器地图边界。

# playerMgr.py

# SinglePlayer类

# PlayerMgr类

# coroutineMgrGas.py

# mapAttrsMasterSys.py

# 监听http请求【/mapAttrs/set-area-limit】

# 处理服务端自定义事件【ServerEvent.HttpResponse】

# 多端协作逻辑

# 客户端登录

# 客户端登录时的多端数据流如下图：

# 运营指令（1）设置指定服务器地图边界

插件核心代码解析

mapAttrsClientSys.py

textBoardMgr.py

mapAttrsServerSys.py

playerMgr.py

coroutineMgrGas.py

mapAttrsMasterSys.py

多端协作逻辑

客户端登录

运营指令（1）设置指定服务器地图边界

# 功能4、是否定时清理掉落物与定时清理掉落物间隔