---
front: 	https://nie.res.netease.com/r/pic/20220408/e24733db-2cc1-49ee-bacb-c1913b2e6c82.png
hard: 入门
time: 10分钟
selection: true
---

# 规范

制作符合规范的插件，不仅可以增加可读性，还可以减少插件间的冲突问题，并且更加便于使用，方便二次开发。

本节将介绍插件开发的相关规范。

## 设计文档规范

在设计插件的时候，用文档将设计方案记录。一方面便于将插件功能转化成开发者所需的说明文档，另一方面便于日后二次开发。

文档需要包含一下几个方面:

- 插件功能描述（若功能流程较为复杂，最好能包含流程图）
- UI示意图
- 配置说明
- API
- 事件以及运营指令
- 功能描述

[点我](./设计文档示例.html)查看随身仓库插件的设计文档示例。

## 插件规范

插件目录及命名的规范可以参考[这里](https://g.126.fm/02YRPPK)

## 介绍文档规范

介绍文档，即插件目录下的readme.txt，为了使他人更好地理解并使用你的插件，需要根据规范编写readme.txt。

具体规范可参考[这里](https://g.126.fm/02AskEc)

例如下方的neteaseMenus的readme.txt

```
插件介绍：
该服务器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中搜索“经济插件”，并把对应的获取货币和更新货币的地方换成自己的接口管理即可
- 交易物品：玩家可以通过选择背包中的物品及数量进行交易
```