# 规范

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

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

# 设计文档规范

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

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

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

点我查看随身仓库插件的设计文档示例。

# 插件规范

插件目录及命名的规范可以参考这里 (opens new window)

# 介绍文档规范

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

具体规范可参考这里 (opens new window)

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