学习了这么多期插件理论知识

开发者们是不是已经

想要大展身手了呢？

别急！在正式开始制作之前

我们还要学习插件开发规范！

没有规范

大家制作的插件就会

五花八门，难以兼容

所以请先跟着发发菌一起

学习一下如何“优雅”地开发插件吧！

 

插件开发规范，是制作插件至关重要的一点。一个符合规范的插件，不仅可以增加可读性，还可以减少插件间的冲突问题，并且规范的插件使用起来会更加便利，还方便二次开发。

因此，接下来发发菌就带大家了解下在插件开发过程中，应该遵循哪些规范~

开发者们在设计插件的时候，需要使用文档记录设计方案。这样做能更方便的将插件功能，转化成开发者所需的说明文档。

一般来说，一个规范的设计文档需要包含以下几个方面：

① 插件功能描述

（若功能流程较为复杂，最好能包含流程图）

② UI示意图

③配置说明

④API

⑤事件以及运营指令

⑥功能描述

举个例子，当我们要为一个随身仓库插件撰写设计文档时，我们可以这样写：

（随身仓库示意图）

1、功能描述

1）点击界面入口可打开随身仓库。（作为本需求的示例，入口通过官方的主菜单插件打开即可）

2）仓库的列数固定为7，行数可动态适配，最多32行，超出显示的部分通过翻页或滚动实现。

3）随身仓库的界面示意，可参考上图。

a、配置为初始行的仓库格子，状态是已解锁。其余格子是上锁状态。

b、点击任意上锁状态的格子，弹出二次确认弹窗，弹窗内容通过本行解锁提示配置获取。

c、上述弹窗选择确认，但物品、货币不足的情况下，用官方插件neteaseAlert进行弹窗提示“解锁所需物品或货币不足！”

d、上述弹窗选择确认且物品、货币足够的情况下，扣除响应物品、货币并开启下一行格子。用官方插件neteaseAlert进行弹窗 提示“成功解锁第%s行仓库格子”

2、配置说明

1）随身仓库初始行数，最小值是0。

2）随身仓库最大行数。

3）非初始行的解锁消耗：支持物品+货币两种形式，其中货币需要将官方的经济插件作为前置。若解锁配置设为 -1，则由开发者根据自己写的判断进行解锁。

配置说明举例：

初始行数：0

最大行数：10

解锁配置： [行数区间]:(货币dough_id,货币数量，[(物品1identifier：aux，物品数量1),(物品2identifier：aux，物品数量2),...],"本行解锁提示")

3、API需求

1）服务端API：某uid玩家打开随身仓库。

2）服务端API：设置某uid玩家随身仓库解锁多少行。（假如当前已解锁3行，调用这个API，解锁行数设为3，则第4~6行进行解锁）

3）服务端API：查询某uid玩家随身仓库已解锁的行数。

4）服务端API：删除仓库中某一格的物品。

5）服务端API：删除仓库中所有的物品。

4、事件需求

1）服务端事件：点击任意上锁状态格子时抛出，参数包含：玩家uid

2）服务端事件：成功解锁时抛出，参数包含：玩家uid、当前解锁的行数集合

5、运营指令

1）某uid玩家打开随身仓库。

2）设置某uid玩家随身仓库解锁多少行。

3）查询某uid玩家随身仓库已解锁的行数。

4）设置某uid玩家随身仓库上锁多少行。原来已解锁格子中的物品，设为上锁状态后将无法放入但可以取出，直到重新解锁。

5）删除仓库中某一格的物品。

6）删除仓库中所有的物品。

由于新的插件层出不穷，为了减少插件之间的冲突问题，开发时的命名就变得非常重要。而其中涉及到两个重要的概念：

（1）团队名

每个官网公开插件的开发团队，都需要一个全局唯一的团队名，比如官方的团队名为netease。

团队名仅能使用小写英文字符+数字，并且不能以数字开头，团队名限制最大字符数为10。

（2）插件名

每个插件都需要有一个与插件具体实现的功能相关的插件名，比如官方的公告插件的插件名为announce。

插件名仅能使用小写英文字符+数字，并且不能以数字开头，插件名限制最大字符数为20。

根目录命名规范

在创作过程中，开发者需要注意：插件强制要求按照运行的具体服务器类型（游戏服、功能服等）分目录，并且每种服务器都需要创建一个目录。

目录必须使用驼峰法命名，且以团队名开头，具体规范如下：

（1）大厅服/游戏服 插件目录名规范：

团队名（全小写）+插件名（首字母大写）

（2）控制服 插件目录名规范：

团队名（全小写）+ 插件名（首字母大写） + Master

（3）功能服 插件目录名规范：

团队名（全小写）+插件名（首字母大写）+Service

假设团队名为lovecraft，插件名为guild，功能涉及到控制服、功能服和大厅服，那么插件的分目录结构应该是这样的：

├─lovecraftGuildMaster

├─lovecraftGuild

├─lovecraftGuildService

这里发发菌只展开介绍根目录的命名规范，更多插件目录，美术资源，自定义物品等命名规范，开发者们可以复制以下链接至浏览器查阅完整的开发规范说明。

该文档描述了官网公开插件（即公开下载并许可任意服主使用的插件）的开发规范，开发者们的自用插件建议也参照此规范：

https://g.126.fm/02YRPPK

介绍文档，即插件目录下的readme.txt。为了使其他开发者或玩家更好地理解并使用插件，我们需要根据规范编写介绍文档。

想要了解更详细的规范说明，开发者们可以复制以下链接至浏览器查看官网文档：

https://g.126.fm/02AskEc

例如官方的neteaseMenus插件，它的介绍文档是这样的：

插件介绍：

该服务器Mod隶属于“主菜单”插件。

“主菜单”插件实现主菜单功能：

- 主菜单：定义并在游戏中生效主菜单（配置于lobby/game下的mod.json）

插件构成：

目前“主菜单”插件包含以下Mod：

- neteaseMenus：部署于大厅服或游戏服

使用步骤：

（1）在部署配置中，将neteaseMenus添加至需要的大厅服或者游戏服的mods列表中

插件api：

（1）设置主菜单按钮状态

适用范围：客户端

函数：UpdateMenus(data)

参数：

data: dict, 设置按钮状态的字典，格式参照下面例子

返回：

bool, 是否设置成功，注意设置失败也有可能已经改变了菜单状态

示例：

import client.extraClientApi as clientApi

data = { # key对应按钮序号，从0开始，value为(0, 1)中的一个数字，【0】代表禁用该按钮，【1】代表开启该按钮

1: 0,

4: 1,

16: -1,

}

menusSystem = clientApi.GetSystem("neteaseMenus", "neteaseMenusBeh")

flag = menusSystem.UpdateMenus(data)

（2）获取主菜单所有按钮配置

适用范围：客户端

函数：GetMenus()

参数：

无

返回：

menus:dict 主菜单按钮配置，结构对应mod.json中的配置，详见mod.json

示例：

import client.extraClientApi as clientApi

menusSystem = clientApi.GetSystem("neteaseMenus", "neteaseMenusBeh")

menus = menusSystem.GetMenus() # 结构对应mod.json中的配置，详见mod.json

插件event：

（1）MenusNavigateEvent

适用范围：客户端

命名空间：namespace = 'neteaseMenus', systemname = 'neteaseMenusBeh'

描述：玩家点击了某按钮事件

参数：

playerId: str, 点击按钮玩家的playerId

order: int, 被点击按钮的序号，从0开始

示例：

def __init__(self, namespace, systemName):

self.ListenForEvent('neteaseMenus', 'neteaseMenusBeh', 'MenusNavigateEvent', self, self.OnMenusNavigate)

def OnMenusNavigate(self, data):

print 'OnMenusNavigate', data

playerId = data["playerId"]

order = data["order"]

print '玩家 {} 点击了主菜单中的 {} 号按钮'.format(playerId, order)

更新列表：

1.0.0版本：

初始版本

1.0.1版本：

调整了UI资源，增加了代码注释

1.0.2版本：

按照新规范调整UI和代码

1.0.3版本：

迭代新UI和代码

1.0.4版本：

重构了UI和代码，配置方式也发生了变化

1.0.5版本：

优化插件readme文档描述

在上述例子中我们可以看到，一个完整的介绍文档，一般会包含以下内容：

① 插件介绍

② 插件构成

③ 使用步骤

④ 插件api

⑤ 插件event

⑥ 更新列表

需要注意的是，在上述展示的介绍文档中，没有包含运营指令和前置插件的相关介绍。如果开发者们编写的插件中有运营指令和前置插件的需求，记得一定要把它们的介绍写上哦！

在这里提供了两个示例供大家参考↓

运营指令：

（1）查询一个玩家身上的货币剩余数量（该玩家需在线）

post url: http:masterip:masterport/query-player-doughs

post body:{

"uid": 996 # 玩家的uid

}

response:

{

"code": 1, # 返回码，【1】代表成功，其他代表失败

"message": "请求成功", # 失败原因的具体描述

"entity": { # 返回该玩家身上货币剩余数量信息，查询失败则为空字典

"RMB": 996,

"USD": -996

}

}

（2）为一个玩家添加/减少货币（参数：玩家id、货币类型、货币数量，货币数量可为负数）

post url: http:masterip:masterport/update-player-doughs

post body:{

"uid": 996, # 玩家的uid

"mod": { # 修改货币数据的字典

"RMB": 996,

"USD": -996

}

}

response:

{

"code": 1, # 返回码，【1】代表成功，其他代表失败

"message": "请求成功", # 失败原因的具体描述

"entity": { # 返回该玩家身上货币剩余数量信息，操作失败则为空字典

"RMB": 1992,

"USD": -1992

}

}

（3）查询当前总共有多少个出售摊位（2.0.0新增）

post url: http:masterip:masterport/count-stalls

post body:{}

response:

{

"code": 1, # 返回码，【1】代表成功，其他代表失败

"message": "请求成功", # 失败原因的具体描述

"entity": {

"stalls": {

"996": {

"duration": 12, # 摆摊总时长

"deadline": 1590462263, # 摆摊自动收摊时间戳

"ver": 0, # 无用

"label": "好货不便宜", # 摊位名称

"deals": [...] # 该摊位的出售记录

}

}

}

}

（经济插件的运营指令介绍）

插件介绍：

该服务器Mod隶属于“面对面交易”插件。

“交易”插件实现2个主要功能，1个是交易货币，1个是交易物品：

- 交易货币：弱依赖经济插件，需要配置对应的货币类型和货币贴图。也可以自行进行管理，只需要在transactionServerSystem.py中搜索“经济插件”，并把对应的获取货币和更新货币的地方换成自己的接口管理即可

- 交易物品：玩家可以通过选择背包中的物品及数量进行交易

（面对面交易插件的前置插件介绍）

插件不规范

服主两行泪

开发者们在创作当中

要多回顾今天列举的示例

争取开发出“懂事”的插件！