QuPresetTool.exe

为QuModLibs v1.1及以上版本提供的预设解决方案

初始配置

将 QuPresetTool.exe 放置在行为/资源包的任意前3层级 程序本身会自动向上分析识别项目结构, 首次运行将 生成 setting.json 配置文件, 内容如：{"presetHome":"..."} 设置presetHome为您的本地预设仓库目录即可 (PS: 您也可以直接拖拽对应的预设文件/文件夹到QuPresetTool.exe上直接解析使用)

预设结构

通常来说一个预设项目由以下几个文件/文件夹组成

- behPackage (行为文件夹)    - 该目录的所有文件将会在变量运算后生成到MOD行为目录中
- resPackage (资源文件夹)     - 该目录的所有文件将会在变量运算后生成到MOD资源目录中
- dataView.json (参数视图)    - 预设在加载后弹出的字面量输入视图
- manifest.json (预设清单信息)    - 预设加载时预读的配置信息 如宏替换, doc描述
- useApi.json (API调用)    - 预设在加载完毕后最后调用的处理 用于调用C++层面预先编写好的函数

功能加载顺序: manifest -> dataView(阻塞等待输入) -> behPackage / resPackage -> useApi

manifest.json

预设配置清单 优先解析并加载 其中宏置换优先于变量置换

{
    "api_version": 1,        // API版本 当预设工具不符合时将会抛出错误 (该字段不填时将会始终视为最新版本)
    "title": "测试预设",      // 预设标题 (使用时将会弹出提示)
    "doc": "By Zero123",     // 预设描述 (使用时将会弹出提示)
    
    // 以下内容为选填项
    "unsafe_replace": {
        // 不安全置换 也就是宏替换 为了快速的将一个已完成的MOD包装成可复用预设 只需要用宏置换一些关键字如MOD名称
        // 置换操作优先于变量运算 因此你可以直接将原有MOD名称置换成{MOD变量}引用 以便快速生成在任何MOD
        "MODNAME": "{&__QuModName__}"
    },
    "write_cover": false,	// 写入覆盖 默认false 设置为true后重复文件将会强制覆盖
    "ignoring_path": [
        // 忽略目录 预设中特定的目录起始文件将会被忽略合并到MOD
        "behPackage/{&__QuModName__}/QuModLibs"
    ],
    "must_has_qumod": false, // 默认false 声明该项目必须依赖QuModLibs 此时预设加载器将会给出不符合条件的mod警告
    "custom_var": {}		// 默认{} 自定义常量var
}

其中{&VarName}格式字段为变量引用 变量分为内置变量与用户输入变量 (在dataView.json配置) 变量能够针对文件名称/目录名称

以及文本内容(.py / .json)进行置换 以便生成自定义字面量的不同结果, 内置变量可查阅底部内置参数

dataView.json

参数视图 基于该配置文件弹出相关输入提示 用户的输入将会直接作为var变量

// 视图文件由无数个json对象组成列表 有序弹出提示 输入期间阻塞后续流程
[
    {
        "text": "实体标识符",	// 弹出的提示文本 通常引导用户
        "var": "entityId",		// 将输入内容写入特定变量(变量字符串自定义)
        "f_var": "f_entityId"	// 将输入内容转换为格式化字段变量 (如 mc:zombie -> mc_zombie) 用于解决命名规范问题
        // 除了 f_var 还可以用 uwu_var 生成一个大写下划线命名的字段变量 (mc:zombie -> MC_ZOMBIE) 允许共存使用
    },
    {
        // 通常来说您也可以只写2条甚至更少的参数
        "text": "中文名称",
        "var": "name"
    },
    {
        "text": "实体纹理",
        "use": "@textures",							// USE字段 用于弹出资源提示 可以参考下文内置参数
        "default": "textures/entity/armor_stand",	// 默认字段 当用户什么都不输入直接回车将会引用
        "var": "tex",
        "type": "string"	// 类型字段 暂时没有实际作用仅提示用户该输入什么类型不具有校验
    },
    ...
]

用户视图输入的字面量能够写入您指定的var变量 随后下文文件将会访问并且置换相关变量 语法为 {&变量} 可以用在文件名称,目录,文本内容, 其中behPackage / resPackage中的文件名称变量引用将会自动格式化(即f_var效果) 确保符合MC标准

useApi.json

调用C++层内置的API函数 后置执行

// 在所有流程执行完毕后将会解析并执行useApi 通常用于常规文件生成无法搞定的合并业务
[
    [
        "addZhLang",				// API名称
        "item.{&itemId}.name",		// 参数1
        "{&itemName}"				// 参数2
    ],
    [
        "setItemTexture",
        // 此处您仍然可以引用变量 同理: 宏置换同样影响这里
        "{&f_itemId}",
        "{&texture}"
    ],
    [
        "setMaterial",
        "postprocess",	// 对应材质文件名称 postprocess.material
        "{&__LQuModName__}_xxx",
        {
            "vertexShader": "shaders/uv_fullscreen.vertex",
            "fragmentShader": "shaders/{&__LQuModName__}/xxx.fragment",
			...
        }
    ]
]

内置参数

VAR变量

__QuModName__    返回当前QuMod项目名称 (无QuModLibs时将返回null)
__LQuModName__   返回转换为下划线风格的项目名称 (如: modName -> mod_name)
__TIME__         返回预设加载时的系统整数时间 (精度为秒)

视图USE提示

(现版本控制台 同类型只会弹出一次防止刷屏)

@animations 弹出项目内所有动画资源

@models 弹出项目内所有模型资源(仅支持微软模型1.12及以上版本)

@textures 弹出项目内所有png贴图资源(仅识别.png)

@eventHandler 弹出python部分所有使用EventHandler装饰器绑定的名称

API函数

// API通常用于解决生成器无法处理的需要合并内容的部分
// 其中API在执行前也会经过宏置换与变量运算

{ "print", API_PRINT }						// print输出字符串内容 参数(待输出文本: str)
{ "addZhLang", API_AddZhLang }				// 在资源包添加中文描述 参数(键: str, 值: str)
{ "setItemTexture", API_SetItemTexture }	// item_texture.json 注册信息 参数(键: str, 相对纹理路径: str)
{ "registerUI", API_RegisterUI }			// _ui_defs.json 注册UI文件 参数(相对json路径: str)
{ "registerServer", API_RegisterServer }	// modMain.py 注册服务端 参数(相对文件路径: str)
{ "registerClient", API_RegisterClient }	// modMain.py 注册客户端 参数(相对文件路径: str)
{ "setMaterial", API_SetMaterial }			// 注册材质 参数(材质文件名无后缀: str, 设置key: str, 设置值: json)
{ "mergePyCodeFile", API_MergePyCodeFile }	// 合并Python文件 参数(预设内文件路径: str, 输出行为包文件路径: str)
/* API_MergePyCodeFile:
从预设中读取特定文件合并到指定MOD的行为包路径中 若无文件存在将会直接创建
否则进行合并运算, 合并运算下将会计算import/from import/注释utf-8声明剔除重复 */
{ "registerNeteaseModel", API_REG_NETEASE_MODEL }	// 注册网易Model 参数(keyName: str, data: json)

关于QKV

QKV文件为自制的二进制键值关系映射文件(为避免引入zip相关库导致的程序体积大增) 用于打包预设项目 以便网络传输 该类型文件能够直接被解析使用, 您可以通过 QKVCompile.exe 编译并生成QKV

注意: QKV不会压缩/加密数据信息 若考虑压缩率请使用zip