模组API

From Minecraft基岩版开发Wiki

模组APIModAPI)是网易为了使开发者能够结合自定义游戏内容对游戏进行更深入的监测与修改而开发的一套API,是模组SDK的一部分。与其同时被开发的姊妹API还有专门针对网络服务器游戏管理的网络游戏开服工具

基本内容介绍[edit]

模组API使用Python语言编写,其基本运行方式与原版的脚本引擎(Script Engine)类似,都采用Client-Server(即客户端-服务端)结构。服务端负责数据的管理与逻辑的计算,而客户端负责完成与用户的交互任务。举个通俗的例子,玩家在游戏里遇到一只僵尸,这只僵尸的外观、被攻击时的粒子效果由客户端渲染,而这只僵尸的内部属性(如位置,血量,速度等)和它的行为(如攻击玩家,在太阳下燃烧等)则由服务端控制,两者的分工负责非常明确,可用的事件和组件也有很大不同。而每个端的运行流程又大致为[监听事件-#响应事件-回调函数-执行逻辑(调用组件)#-销毁事件](其中##部分为循环部分),其中内置事件和组件皆为网易封装好的方法。

系统[edit]

系统是整个模组API的核心基础,所有操作都必须基于系统之上进行。

系统System是我们的核心类,用于监听事件,使用组件,更新等。 获取自定义的System需要继承引擎的系统基类 ClientSystem/ServerSystem.

——网易开发者文档

模组API中并不是所有的接口都经过API库执行,有部分底层操作方法如获取运行平台、所有事件相关操作、创建物品实体、创建粒子效果等等都使用System类自带的方法执行。

事件[edit]

事件,指在游戏内触发了某个操作或达到某一种条件时游戏向引擎发送的包含返回值的信息,如监测玩家升级的AddLevelEvent附带[玩家ID][增加的等级值][新等级]三个返回值。所有返回值皆可通过预先在回调函数中设置的参数读取。在模组API中,所有事件皆使用ListenForEvent方法监听UnListenForEvent方法反监听

在网易的脚本系统中,客户端和服务端实际上拥有很多触发时机相同的事件,但其中部分类型相同的事件对象又不同,开发者可根据自身需要选择相应的部分进行监听。

事件依赖于系统,事件需要系统才能监听触发,因此在使用事件之前需要先拥有自己的系统system。事件分为定义事件、监听事件、反监听、发布事件和响应事件。
定义事件
定义事件分为引擎定义的事件和自定义事件。引擎定义的事件不需要定义可以直接使用。自定义函数DefineEvent(新版中此函数已废弃).
监听事件
监听事件的含义是将回调函数注册到事件上,当事件发生时主动调用该回调函数。监听函数ListenForEvent.
反监听事件
监听完毕后需要自行反监听该事件(即销毁事件)在System的Destroy函数中。反监听函数UnListenForEvent.
发布事件
发布事件是指,在事件发生时发布这个事件通知所有监听了这个事件的回调函数。引擎定义的事件会在引擎事件发生时自动发布,自定义事件的发布需要先DefineEvent后才能发布(已废弃,新版可以直接发布),需要先CreateEventData创建事件数据,发布函数有BroadcastEvent / NotifyToClient / BroadcastToAllClient / NotifyToServer.
响应事件
上述的发布事件很多都是广播,但是不是每条消息都需要每个system都处理,因此响应函数只会响应那些监听了这些事件消息源有发布这些事件的时候才会响应。
响应函数会响应在监听事件时ListenForEvent的参数中的回调函数。回调函数会传入参数dict,不同事件的参数在下面具体事件(见网易开发者文档)中进行了说明,其中部分参数是可设置参数,可以通过修改值来改变事件的结果。

——网易开发者文档

接口[edit]

接口(原称组件),是一些已经封装好的方法,开发者可以更好对其进行调用以达到直接或间接修改游戏(核心玩法)逻辑的目的。

组件是为了完成某个或某些特定逻辑功能的数据集合,组件只会保存数据并不会执行相应的逻辑,只有组件在System中更新的时候,System从判断组件是否需要更新,从组件中拿到需要更新的数据来执行相应的逻辑功能。 组件分为引擎组件和自定义组件。引擎组件的参数类型和功能都是确定好的,玩家可以创建Create或获取Get组件来完成逻辑功能。自定义组件需要自定义组件的数据结构,自定义组件的更新逻辑。

——网易开发者文档

组件和事件一样,都依赖System类运行。同时组件在很大程度上也必须依赖事件所传入的返回值进行注册和绑定。