主题

调整地图插件（事件侦听与回调） ​

这一篇以官方地图属性插件（neteaseMapAttrs）为例，讲怎么读懂一个官方插件、并在它基础上微调加新功能。学会这套方法，任何官方插件你都能拿来改。

地图属性插件能做什么 ​

neteaseMapAttrs 用于设置整张地图的通用属性：主城保护、禁止藤蔓生长、禁止流体流动、定时清理掉落物、浮空文字、地图边界（走出边界传送回合法位置）、禁止丢弃/捡起物品、地图替换等。它支持一个运营指令：设置指定服务器的地图边界。

试用插件 ​

  1. MC Studio →【新建】→【基岩版网络服】，命名如「地图属性插件微调」，填开发机信息
  2. 大厅服 Mod 下拉 →【获取公共 Mod】→ 选地图属性插件 →【全部下载】
  3. 大厅服选中 neteaseMapAttrs，控制服选中 neteaseMapAttrsMaster（功能服/代理服无此插件，跳过）
  4. 部署 →【开发测试】进游戏体验

读懂插件的方法 ​

拿到一个不熟悉的官方插件，按这个顺序分析，效率最高：

1. 找源码 ​

下载的插件在 C:\MCStudioDownload\ApolloMod\{开发者账号} 下；也可在 Studio【服务器 Mod】选中插件 →【更多 → 打开目录】。把源码复制到本地代码目录，方便加注释和调试。

2. 从 readme 入手 ​

readme 里的功能列表、运营指令，是判断插件结构的第一手信息。地图属性插件的 readme 说明它没有多服协作功能、只有一个运营指令——由此可推断 Master（控制服）Mod 仅仅是运营指令的入口，与游戏逻辑关系不大。

3. 按目录结构定位 ​

结合功能、文件名、文件大小，给每个代码文件定位。地图属性插件只有两个 Mod：

neteaseMapAttrs            # 大厅服/游戏服
├── behavior_packs/…Script # 客户端 Mod
│   ├── mapAttrsClientSys.py   # 客户端 system 类
│   ├── textBoardMgr.py        # 浮空文字管理（对应"浮空文字"功能）
│   └── modMain.py             # 客户端入口
└── developer_mods/…Script # 服务端 Mod
    ├── mapAttrsServerSys.py   # 服务端 system 类
    ├── playerMgr.py           # 玩家管理（对应"地图边界"功能）
    ├── coroutineMgrGas.py     # 用 yield 实现的延时执行管理
    └── modMain.py             # 服务端入口
neteaseMapAttrsMaster      # 控制服（仅接收/反馈运营指令）

小结：每个端的 Mod 通常只有一个 system 文件 + 一两个管理类。抓住 system 类和管理类，就抓住了插件主干。

事件侦听与回调 ​

网络服插件的核心是事件驱动：各端 system 通过监听事件、发送事件来协作。

  • ListenForEvent(namespace, systemName, eventName, self, callback)：注册监听，事件触发时执行 callback
  • 引擎事件由引擎抛出，插件监听后做处理
  • 自定义事件（NotifyToClient / NotifyToServer）用于客户端↔服务端通信

微调地图插件的思路就是：监听更多引擎事件，在回调里加判断和拦截。

微调实战：拦截更多破坏行为 ​

在官方"主城保护"基础上，额外阻止：破坏耕地、触发压力板、踩红石矿、踩拌线钩。做法是在服务端 system 里监听对应引擎事件，在回调里判断并取消：

python
# mapAttrsServerSys.py
def Init(self):
    self.ListenForEvent(
        serverApi.GetEngineNamespace(), serverApi.GetEngineSystemName(),
        "OnStepOnBlockServerEvent", self, self.OnStepOnBlock)

def OnStepOnBlock(self, args):
    blockName = args.get("fullName", "")
    if blockName in ("minecraft:tripwire_hook", "minecraft:wooden_pressure_plate"):
        args["cancel"] = True   # 拦截触发

改完后重新部署该网络服，即可用上修改后的插件。

拦截类事件的通用套路

判断 args 里的方块/物品名 → 满足条件时把 args["cancel"] 或对应取消字段设为 True。具体事件名和 args 字段，查 ModSDK 事件文档。

地图插件是单机逻辑，不需要跨服。下一篇调整聊天插件会引入功能服（Service）——跨服通信必须用到它。回到基岩版网络游戏首页。