通用设置接口规范

欢迎使用由官方牵头，允许开发者通过接口快速注册设置选项的工具。

下面我们将介绍如何使用通用设置接口。

由于通用设置接口不更改引擎内容，可不需要跟整包更新，补全库更新后即可使用。

注册通用设置界面

我们首先需要获取通用设置接口的Comp组件，然后在Comp组件中使用RegisterSettingInst方法

python

comp = clientApi.GetEngineCompFactory().CreateNeteaseWindow(playerId)

# 第一个参数必须要填写 ItemID，我们强烈建议您先上传一个模组，获取到ItemID再进行开发。

# 后面两个参数是为了在 ModPC 中测试开发而引入的参数，在正式服中后面两个参数没有任何作用。

settingInst = comp.RegisterSettingInst("itemId", "模组1", "textures/ui/abc")

由于要传入 itemId，你需要先在开平上传一个模组，获取到 itemId，然后再通过此方法注册

由于页面注册的到的是 Cocos UI 页面，页面里的模组数据都是从开平上传的模组中获取的，所以才需要传入 itemId

由于ModPC不自带 Cocos UI 页面，所以需要传入后面两个参数，以便ModPC使用进行测试

注册控件

控件是指在设置页面中的设置选项，例如按钮、开关、输入框等

控件注册允许链式调用

python

if settingInst:

    # 允许链式调用，添加多个控件

    (settingInst
        .AddText("text_uid_01", "这是一段文字",5)
        .AddToggle("toggle_uid_01", "开关按钮", callbackFunction, 1, False)
        .AddToggle("toggle_uid_02", "开关按钮2", callbackFunction, 3, False)
        .AddToggle("toggle_uid_03", "开关按钮3", callbackFunction, 4, True)
        .AddInput("input_uid_01", "输入框", callbackFunction, 2, "神秘")
        .AddButton("button_uid_01", "按钮", "点击前往设置页面", callback, 2))

callbackFunction与callback是回调函数

python

def callbackFunction(*args):

    # args1 参数是 key 值，用于获取控件ID
    # args2 参数是 value 值，用于获取控件的当前值

    if settingInst.GetToggleDefault("toggle_uid_01"):

        #获取 控件1 的默认值，如果是True，则将默认值改成 False，下次打开页面就会显示False了

        #  settingInst.SetToggleDefault("toggle_uid_01", False)

        settingInst.SetLockSettingComp("toggle_uid_02", False)
        
    else:

        # 这里我们判断，如果从 False 改成 True了，我们还会给控件 toggle_uid_02 上锁

        # settingInst.SetToggleDefault("toggle_uid_01", True)

        settingInst.SetLockSettingComp("toggle_uid_02", True)

def callback(*args):

    # args1 参数是 key 值，用于获取控件ID
    # args2 参数是 value 值，用于获取控件的当前值

    comp.CloseSettingUI()

上述内容完成后您就成功注册了设置界面中的控件，并且可以通过设置页面中的按钮进行调用。

此时你就可以前往开发者测试服查看效果

alt text

设置页面集束在暂停菜单 - 模组中

我们不限制开发者必须把模组设置做在通用设置界面中，但设置入口一定要在这个界面中，减少玩家寻找模组设置的时间成本。

您可以只在通用设置界面注册一个按钮，点击按钮可以跳转到你们的设置页面中

疑难解答

Q1：怎么没有翻页功能？

A：为了确保与原本UI风格一致，我们没有做翻页功能，而是内置了滚动功能。

Q2：怎么不能加图片？

A：为了确保各开发者风格一致，我们没有做图片功能，以免开发者随心所欲添加图片造成设置界面杂乱无章

Q3：限制有点大，我不想用你们的设置怎么办？

A：我们不限制开发者使用自己的设置界面，但为了提高玩家体验，减少模组设置学习成本，开发者可以即使不适用官方提供的设置接口，也可以在这个页面注册按钮，允许玩家点击按钮打开开发者自己定义的设置界面中

接口速查

CloseSettingUI

客户端

method in mod.client.component.neteaseWindowCompClient.NeteaseWindowCompClient

描述
关闭模组信息界面
参数
无
返回值
数据类型
说明
bool 是否关闭成功
备注
- 该接口在modPC环境下，将是关闭局内json ui
示例

数据类型	说明
bool	是否关闭成功

python

import mod.client.extraClientApi as clientApi
levelId = clientApi.GetLevelId()
comp = clientApi.GetEngineCompFactory().CreateNeteaseWindow(levelId)
# 关闭界面
result = comp.CloseSettingUI()

GetSettingInst

客户端

method in mod.client.component.neteaseWindowCompClient.NeteaseWindowCompClient

描述
获取当前模组的通用设置实例
参数
参数名
数据类型
说明
modNamespace str 组件命名空间，需唯一性，仅在开发环境预览使用
返回值
数据类型
说明
SettingInst 返回实例对象，未注册则返回None
备注
- 请先使用RegisterSettingInst注册，再使用GetSettingInst获取。
- 开发环境中，将会获取modNamespace对应的通用设置实例；正式环境中则仅能获取当前模组注册的实例。
- 建议不要在__init__的时候就获取实例，过早获取会返回None。
示例

数据类型	说明
SettingInst	返回实例对象，未注册则返回None

python

import mod.client.extraClientApi as clientApi
levelId = clientApi.GetLevelId()
comp = clientApi.GetEngineCompFactory().CreateNeteaseWindow(levelId)
settingInst = comp.GetSettingInst()
if settingInst:
    settingInst.AddText("text_uid_01", "这是一段文字").AddToggle("toggle_uid_01", "开关按钮", False, callbackFunction)

OpenSettingUI

客户端

method in mod.client.component.neteaseWindowCompClient.NeteaseWindowCompClient

描述
在模组信息界面中打开设置页面（此操作仅可访问本模组的配置选项）
参数
无
返回值
数据类型
说明
bool 是否打开成功
备注
- 该接口在modPC环境下，将是打开局内json ui
示例

数据类型	说明
bool	是否打开成功

python

import mod.client.extraClientApi as clientApi
levelId = clientApi.GetLevelId()
comp = clientApi.GetEngineCompFactory().CreateNeteaseWindow(levelId)
# 打开界面
result = comp.OpenSettingUI()

RegisterSettingInst

客户端

method in mod.client.component.neteaseWindowCompClient.NeteaseWindowCompClient

描述
注册通用设置实例

参数

参数名	数据类型	说明
modNamespace	str	组件命名空间，需唯一性，仅在开发环境预览使用
modName	str	组件名字，默认为None，仅在开发环境预览使用
iconPath	str	组件icon图路径，默认为None，仅在开发环境预览使用

返回值
数据类型
说明
SettingInst 返回实例对象，系统未初始化则返回None
备注
- 每个模组仅能注册一个通用设置实例，重复注册会返回同样的实例。
- 建议在UiInitFinished触发时再注册，注册过早会导致注册失败而返回None。
- 设置界面的注册是通过Scripts文件夹名称来判断是由哪个模组注册的实例，开发者的Scripts名称需要确保不与其他模组作者的Scripts名称冲突。
示例

数据类型	说明
SettingInst	返回实例对象，系统未初始化则返回None

python

import mod.client.extraClientApi as clientApi
levelId = clientApi.GetLevelId()
comp = clientApi.GetEngineCompFactory().CreateNeteaseWindow(levelId)
settingInst = comp.RegisterSettingInst("123456789", "模组1", "textures/ui/abc")
if settingInst:
    settingInst.AddText("text_uid_01", "这是一段文字").AddToggle("toggle_uid_01", "开关按钮", False, callbackFunction)

SettingInst 下的方法

AddText

添加文本控件。

python

def AddText(self, key, name, priority=None)

参数
参数名数据类型说明
key str 控件id
name str 控件的文字描述
priority int或None 显示顺序优先级，默认根据添加顺序排列
返回值
数据类型说明
SettingInst 当前实例，支持链式调用

数据类型	说明
SettingInst	当前实例，支持链式调用

AddToggle

添加开关控件。

python

def AddToggle(self, key, name, callback, priority=None, default=False)

参数

参数名	数据类型	说明
key	str	控件id
name	str	控件的文字描述
callback	function	控件的回调函数，定义：`def callback(*args)`
priority	int或None	显示顺序优先级，默认根据添加顺序排列
default	bool	默认值，默认为False

返回值
数据类型说明
SettingInst 当前实例，支持链式调用

数据类型	说明
SettingInst	当前实例，支持链式调用

AddSlider

添加滑动条控件。

python

def AddSlider(self, key, name, step, callback, priority=None, default=0)

参数

参数名	数据类型	说明
key	str	控件id
name	str	控件的文字描述
step	int	滑动条的最大值，范围：0~step
callback	function	控件的回调函数，定义：`def callback(*args)`
priority	int或None	显示顺序优先级，默认根据添加顺序排列
default	int	默认值，默认为0

返回值
数据类型说明
SettingInst 当前实例，支持链式调用

数据类型	说明
SettingInst	当前实例，支持链式调用

AddDropDown

添加下拉选项控件。

python

def AddDropDown(self, key, name, options, callback, priority=None, default=None)

参数

参数名	数据类型	说明
key	str	控件id
name	str	控件的文字描述
options	list[str]	下拉选项列表
callback	function	控件的回调函数，定义：`def callback(*args)`
priority	int或None	显示顺序优先级，默认根据添加顺序排列
default	str或None	默认选项，该值需在options中

返回值
数据类型说明
SettingInst 当前实例，支持链式调用

数据类型	说明
SettingInst	当前实例，支持链式调用

AddInput

添加输入框控件。

python

def AddInput(self, key, name, callback, priority=None, default="")

参数

参数名	数据类型	说明
key	str	控件id
name	str	控件的文字描述
callback	function	控件的回调函数，定义：`def callback(*args)`
priority	int或None	显示顺序优先级，默认根据添加顺序排列
default	str	默认显示的文本，默认为空字符串

返回值
数据类型说明
SettingInst 当前实例，支持链式调用

数据类型	说明
SettingInst	当前实例，支持链式调用

AddButton

添加按钮控件。

python

def AddButton(self, key, name, buttonText, callback, priority=None)

参数

参数名	数据类型	说明
key	str	控件id
name	str	控件的文字描述
buttonText	str	按钮的文字描述
callback	function	控件的回调函数，定义：`def callback(*args)`
priority	int或None	显示顺序优先级，默认根据添加顺序排列

返回值
数据类型说明
SettingInst 当前实例，支持链式调用

数据类型	说明
SettingInst	当前实例，支持链式调用

GetToggleDefault

获取开关控件的默认值。

python

def GetToggleDefault(self, key)

参数
参数名数据类型说明
key str 控件id
返回值
数据类型说明
bool 开关状态

数据类型	说明
bool	开关状态

GetInputDefault

获取输入框的默认输入文本。

python

def GetInputDefault(self, key)

参数
参数名数据类型说明
key str 控件id
返回值
数据类型说明
str 输入框的文本

数据类型	说明
str	输入框的文本

GetDropDownDefault

获取下拉选项控件的默认值。

python

def GetDropDownDefault(self, key)

参数
参数名数据类型说明
key str 控件id
返回值
数据类型说明
str 默认选项在列表中的索引

数据类型	说明
str	默认选项在列表中的索引

GetSliderDefault

获取滑动条控件的默认值。

python

def GetSliderDefault(self, key)

参数
参数名数据类型说明
key str 控件id
返回值
数据类型说明
int 滑块的值

数据类型	说明
int	滑块的值

GetText

获取文字控件的文本。

python

def GetText(self, key)

参数
参数名数据类型说明
key str 控件id
返回值
数据类型说明
str 显示的文本

数据类型	说明
str	显示的文本

SetToggleDefault

设置开关控件的默认值。

python

def SetToggleDefault(self, key, value)

参数
参数名数据类型说明
key str 控件id
value bool 开关的值
返回值
数据类型说明
SettingInst 当前实例，支持链式调用

数据类型	说明
SettingInst	当前实例，支持链式调用

SetInputDefault

设置输入框控件的默认文本。

python

def SetInputDefault(self, key, value)

参数
参数名数据类型说明
key str 控件id
value str 显示的文本
返回值
数据类型说明
SettingInst 当前实例，支持链式调用

数据类型	说明
SettingInst	当前实例，支持链式调用

SetDropDownDefault

设置下拉选项控件的默认选项。

python

def SetDropDownDefault(self, key, option)

参数
参数名数据类型说明
key str 控件id
option str 选项文字，如文字不在选项列表里，会自动添加到列表
返回值
数据类型说明
SettingInst 当前实例，支持链式调用

数据类型	说明
SettingInst	当前实例，支持链式调用

SetSliderDefault

设置滑动条控件的默认值。

python

def SetSliderDefault(self, key, value)

参数
参数名数据类型说明
key str 控件id
value int 滑块的值
返回值
数据类型说明
SettingInst 当前实例，支持链式调用

数据类型	说明
SettingInst	当前实例，支持链式调用

SetButtonText

设置按钮控件的文字。

python

def SetButtonText(self, key, value)

参数
参数名数据类型说明
key str 控件id
value str 显示的文字
返回值
数据类型说明
SettingInst 当前实例，支持链式调用

数据类型	说明
SettingInst	当前实例，支持链式调用

SetText

设置文本控件的值。

python

def SetText(self, key, value)

参数
参数名数据类型说明
key str 控件id
value str 显示的文本
返回值
数据类型说明
SettingInst 当前实例，支持链式调用

数据类型	说明
SettingInst	当前实例，支持链式调用

SetLockSettingComp

设置锁定控件，锁定后无法点击。

python

def SetLockSettingComp(self, key, is_locked)

参数
参数名数据类型说明
key str 控件id
is_locked bool 是否锁定
返回值
数据类型说明
SettingInst 当前实例，支持链式调用

数据类型	说明
SettingInst	当前实例，支持链式调用

GetFormatData

获取当前实例的结构化数据，控件数据根据priority的值升序排序。

python

def GetFormatData(self)

参数
无
返回值
数据类型说明
dict 结构化数据

数据类型	说明
dict	结构化数据

返回格式

json

{
    "modId": "str  // 模组ID",
    "name": "str  // 名称",
    "icon": "str  // 图标路径",
    "settings": "list  // 设置项列表，按priority升序排序"
}

GetSettingsControl

获取控件的结构化数据。

python

def GetSettingsControl(self, key)

参数
参数名数据类型说明
key str 控件id
返回值
数据类型说明
dict 控件的结构化数据

数据类型	说明
dict	控件的结构化数据

GetModId

获取实例的modId。

python

def GetModId(self)

参数
无
返回值
数据类型说明
str 模组ID

数据类型	说明
str	模组ID

GetAutoPriority

获取自动设置的优先级的值。

python

def GetAutoPriority(self)

参数
无
返回值
数据类型说明
int 当前自动优先级的值
备注
当添加控件时，如果不设置优先级，则会自动从0开始设置。优先级会影响控件排列顺序，升序排列。

制作简易射击附加包（视频）

预设

内置零件

更新信息

预设管理

预设对象

通用

零件

预设

自定义3D物品

特殊方块

基础技术

通用设置接口规范 ​

注册通用设置界面 ​

注册控件 ​

疑难解答 ​

接口速查 ​

CloseSettingUI ​

GetSettingInst ​

OpenSettingUI ​

RegisterSettingInst ​

SettingInst 下的方法 ​

AddText ​

AddToggle ​

AddSlider ​

AddDropDown ​

AddInput ​

AddButton ​

GetToggleDefault ​

GetInputDefault ​

GetDropDownDefault ​

GetSliderDefault ​

GetText ​

SetToggleDefault ​

SetInputDefault ​

SetDropDownDefault ​

SetSliderDefault ​

SetButtonText ​

SetText ​

SetLockSettingComp ​

GetFormatData ​

GetSettingsControl ​

GetModId ​

GetAutoPriority ​

通用设置接口规范

注册通用设置界面

注册控件

疑难解答

接口速查

CloseSettingUI

GetSettingInst

OpenSettingUI

RegisterSettingInst

SettingInst 下的方法

AddText

AddToggle

AddSlider

AddDropDown

AddInput

AddButton

GetToggleDefault

GetInputDefault

GetDropDownDefault

GetSliderDefault

GetText

SetToggleDefault

SetInputDefault

SetDropDownDefault

SetSliderDefault

SetButtonText

SetText

SetLockSettingComp

GetFormatData

GetSettingsControl

GetModId

GetAutoPriority