项目结构
了解一个模型包的项目结构是最必要的一环。
因为压缩包格式和 ysm 格式的模型都是文件夹格式模型转换而来的，这里我们直接以文件夹形式格式讲解。
文件目录结构
注意
新版本特性需要使用新版本的文件结构，旧版结构无法使用新版特性
2.3.0/2.3.1 版本
2.3.0 版本新增了音频和动画控制器的支持。
除资源描述文件 ysm.json 为固定名称，固定位置文件。自定义模型、动画、材质文件等均可以依据所需放置在不同的子文件夹中，文件夹、材质名称等也可以使用任意字符。
2.2.1 / 2.2.2 版本
旧版本的设计在文件数量较多时极其混乱。故从 2.2.1 版本起，我们设计了一套新的文件结构，通过目录下的 ysm.json 文件统一管理其他资源，推荐的目录结构如下：
除资源描述文件 ysm.json 为固定名称，固定位置文件。自定义模型、动画、材质文件等均可以依据所需放置在不同的子文件夹中，文件夹、材质名称等也可以使用任意字符。
1.2.0 及以前版本
文件夹格式模型结构如下所示，这其中只有三个部分是必须的：main.json，arm.json，任意一个 png 格式的材质。
自定义模型、动画、材质文件均需放置在一个文件夹中。文件夹、材质名称等只能使用 小写英文字符、数字、下划线 等字符。
ysm.json 文件详解
ysm.json 文件是 2.2.1 版本往后新增的资源描述文件，新版模型和相关配置均以它作为索引。
该文件支持如下内容：
- 支持设置默认材质和材质文件的展示顺序；
- 支持设置预览动画，在模型选择界面播放（旧版统一为 idle）；
- 支持自定义 Extra 动画的数量、顺序、名称（不再限制为 extra+数字）；
- 支持读取模型目录内的子目录文件。
- 支持插入作者信息，并分配头像、角色、简介、联系方式
- 支持插入主页和捐赠网页信息
- 支持 PBR 材质指定
- 支持轮盘动画配置功能（2.3.0 新增）
- 支持轮盘动画分类（2.3.0 新增）
ysm.json 必须放在模型文件夹的根目录下，且需要使用 UTF-8 无 BOM 编码保存，其内容结构如下：
2.3.0/2.3.1 版本
{
// 版本信息字段，当前必须为 2，此版本添加了 PBR 的支持
"spec": 2,
// 可选字段，会作为游戏内模型切换界面的文本提示和详情界面显示出来
"metadata": {
// 只有 name 是必选字段，其它都是可选
"name": "自定义名称",
// 接受用 \n 进行换行
"tips": "描述",
"license": {
// 必选字段
"type": "CC 0",
// 接受换行
"desc": "更多许可描述"
},
// 读取时保留顺序
"authors": [
{
// 只有 name 是必选字段，其它都是可选
"name": "作者1",
// 模型详情页展示作者头像
"avatar": "avatar/头像.png",
"role": "角色（如：模型/动画）",
// 支持任意类型，不局限于给出的这两个。读取时保留顺序
"contact": {
"qq": "123456789",
"email": "123456789@qq.com"
},
// 不接受换行
"comment": "备注"
},
// 可以添加多个作者
{
"name": "作者2"
}
],
// 目前仅支持这两个
"link": {
"home": "https://www.主页链接.com",
"donate": "https://www.捐赠链接.com"
}
},
// 可选字段，内部所有字段都是可选
"properties": {
// 模型缩放，默认为 0.7
"height_scale": 0.7,
// 模型缩放，默认为 0.7
"width_scale": 0.7,
// 可任意调整数量、顺序和名称（不局限于 extra+数字）。读取时保留顺序
// 不限数量，超过 8 个也能正常播放了
"extra_animation": {
// 2.2.2 之前版本写法
"extra1": "轮盘动画1",
// 2.3.0 版本之后新增内容
// 注意这里后面的值里带了一个 # 号，这个就是有特殊意义了
// 它会去 extra_animation_buttons 里寻找 id 和这个相同的
// 从而添加一些配置项按钮
"extra2": "#按钮1",
// 注意这个前面带了一个 # 号，这个也有特殊意义
// 它会去 extra_animation_classify 里寻找动画
// 从而打开一个子菜单界面
"#分类1": "测试分类",
// 特殊分类的轮盘，#return 这个名称固定，此轮盘和返回按钮是一样的
// 2.3.1 新增
"#return": "返回按钮"
},
// 2.3.0 版本之后新增内容
// 用于添加子菜单界面
"extra_animation_classify": [
{
// 这个 ID 就是前面那个 # 后写的东西
"id": "分类1",
// 这个和前面 extra_animation 字段写法一致
"extra_animation": {
"extra0": "动画1",
"extra1": "动画2",
"extra2": "动画3",
"extra3": "动画4"
}
}
],
// 2.3.0 版本之后新增内容
// 给轮盘加配置按钮
"extra_animation_buttons": [
{
// 这个 ID 就是前面那个 # 后写的东西
"id": "按钮1",
// 显示名称，这个随便写
"name": "随便写的名字",
// 具体的配置组件
"config_forms": [
{
// 这个是滑条
"type": "range",
"title": "大小",
"description": "用来切换玩家的大小",
// 滑条会改变的 molang 变量，注意必须填变量！
"value": "v.player_size",
// 这个就不解释了吧
"step": 0.1,
"min": 0.2,
"max": 5
},
{
// 开关按钮
"type": "checkbox",
"title": "开关猫耳噢噢噢噢",
"description": "用来切换芙芙猫耳",
// 会改变的 molang 变量，注意必须填变量！
"value": "v.neko"
},
{
"type": "radio",
"title": "请选择正确答案",
"description": "试试效果",
// 打开配置界面时，会读取这里的 v.type 的数值，再根据 v.type 的值决定单选框勾选在第几个；
// 如果 v.type 的值是 0，那么会勾选第一个；如果值是 1，那么会勾选第二个；以此类推；
// 注意此处只能填写必须填变量名，不能填写表达式！
"value": "v.type",
// 选项了，可以无限添加
"labels": {
// 前面是显示名称，后面是执行语句（这里不是赋值语句了啊啊啊啊）
// 点击后就会执行对应的语句，进行计算！
"A": "v.type=0;",
"B": "v.type=1;",
"C": "v.type=2;",
"D": "v.type=3;",
"E": "v.type=4;",
"F": "v.type=5;",
"名字我可以随便写啊": "v.type=6;"
}
}
]
}
],
// 在模型选择界面播放的预览动画
"preview_animation": "idle",
// 默认材质名称（不含路径和后缀.png），在模型选择界面展示，以及在玩家切换至该模型时默认使用。
"default_texture": "default",
// 此字段为 true 后，无法将其设置为授权模型
"free": false,
// 2.2.2 起新增字段
// 默认 false，可指定原版模型层级的渲染是否先于 ysm 模型
// 具体作用可参考下章节
"render_layers_first": false,
// 2.3.0 新增字段
// 用于禁用模型选择界面的旋转，方便制作 GUI 动画
"disable_preview_rotation": false,
// 2.3.0 新增字段
// 当设置为 true 时，无论材质情况，全部启用面剔除。用于支持负尺寸描边模型
"all_cutout": false
},
// 必须的字段
"files": {
// 主模型文件
"player": {
"model": {
// 路径和文件名都可以自定义，注意严格区分大小写，即使是在 Windows 上
"main": "models/main.json",
"arm": "models/arm.json"
},
// 可选字段，内部八个字段也都是可选
// 没有的话，会自动调用默认模型
"animation": {
"main": "animations/main.animation.json",
"arm": "animations/arm.animation.json",
"extra": "animations/extra.animation.json",
"tac": "animations/tac.animation.json",
"carryon": "animations/carryon.animation.json",
"swem": "animations/swem.animation.json",
"parcool": "animations/parcool.animation.json",
"slashblade": "animations/slashblade.animation.json",,
"tlm": "animations/tlm.animation.json"
},
// 2.3.0 新增内容
// 动画控制器的索引，可以包含多个控制器。你如果喜欢，也可以将其拆分成多个⽂件
"animation_controllers": [
"controller/parallel.controller.json"
],
// 读取时保留顺序
"texture": [
// 可以直接书写材质路径
"textures/default.png",
// 也可以写成这样的形式
{
// 仅 uv 字段必选，以下两种 PBR 材质为可选
"uv": "textures/blue.png",
// Oculus 和 Iris PBR 支持
"normal": "textures/pbr/blue_n.png",
"specular": "textures/pbr/blue_s.png"
}
]
},
// 可选字段，替换箭的渲染
"arrow": {
"model": "models/arrow.json",
// 可选字段
"animation": "animations/arrow.animation.json",
// 同样支持 PBR
"texture": "textures/arrow.png"
}
}
}2.2.1 / 2.2.2 版本
{
// 版本信息字段，当前必须为 2，此版本添加了 PBR 的支持
"spec": 2,
// 可选字段，会作为游戏内模型切换界面的文本提示和详情界面显示出来
"metadata": {
// 只有 name 是必选字段，其它都是可选
"name": "自定义名称",
// 接受用 \n 进行换行
"tips": "描述",
"license": {
// 必选字段
"type": "CC 0",
// 接受换行
"desc": "更多许可描述"
},
// 读取时保留顺序
"authors": [
{
// 只有 name 是必选字段，其它都是可选
"name": "作者1",
// 模型详情页展示作者头像
"avatar": "avatar/头像.png",
"role": "角色（如：模型/动画）",
// 支持任意类型，不局限于给出的这两个。读取时保留顺序
"contact": {
"qq": "123456789",
"email": "123456789@qq.com"
},
// 不接受换行
"comment": "备注"
},
// 可以添加多个作者
{
"name": "作者2"
}
],
// 目前仅支持这两个
"link": {
"home": "https://www.主页链接.com",
"donate": "https://www.捐赠链接.com"
}
},
// 可选字段，内部所有字段都是可选
"properties": {
// 模型缩放，默认为 0.7
"height_scale": 0.7,
// 模型缩放，默认为 0.7
"width_scale": 0.7,
// 可任意调整数量、顺序和名称（不局限于 extra+数字）。读取时保留顺序
// 不限数量，超过 8 个也能正常播放了
"extra_animation": {
"extra0": "",
"extra1": "打招呼",
"run": "润",
"walk": "跑路",
"extra4": "",
"extra5": "",
"extra6": "",
"extra7": ""
},
// 在模型选择界面播放的预览动画
"preview_animation": "idle",
// 默认材质名称（不含路径和后缀.png），在模型选择界面展示，以及在玩家切换至该模型时默认使用。
"default_texture": "default",
// 此字段为 true 后，无法将其设置为授权模型
"free": false,
// 2.2.2 起新增字段
// 默认 false，可指定原版模型层级的渲染是否先于 ysm 模型
// 具体作用可参考下章节
"render_layers_first": false
},
// 必须的字段
"files": {
// 主模型文件
"player": {
"model": {
// 路径和文件名都可以自定义，注意严格区分大小写，即使是在 windows 上
"main": "models/main.json",
"arm": "models/arm.json"
},
// 可选字段，内部七个字段也都是可选
// 没有的话，会自动调用默认模型
"animation": {
"main": "animations/main.animation.json",
"arm": "animations/arm.animation.json",
"extra": "animations/extra.animation.json",
"tac": "animations/tac.animation.json",
"carryon": "animations/carryon.animation.json",
"swem": "animations/swem.animation.json",
"parcool": "animations/parcool.animation.json"
},
// 读取时保留顺序
"texture": [
// 可以直接书写材质路径
"textures/default.png",
// 也可以写成这样的形式
{
// 仅 uv 字段必选，以下两种 PBR 材质为可选
"uv": "textures/blue.png",
// Oculus 和 Iris PBR 支持
"normal": "textures/pbr/blue_n.png",
"specular": "textures/pbr/blue_s.png"
}
]
},
// 可选字段，替换箭的渲染
"arrow": {
"model": "models/arrow.json",
// 可选字段
"animation": "animations/arrow.animation.json",
// 同样支持 PBR
"texture": "textures/arrow.png"
}
}
}部分字段作用说明
render_layers_first
指定原版模型层级的渲染是否先于 YSM 模型渲染，默认为 false。
disable_preview_rotation
默认情况下，选择界面动画如果想要贴合角度，需要给人物加一个非常诡异的旋转角度。
将此属性设置为 true 可以取消掉这个诡异的旋转角度。
此时模型的正视图和游戏内 GUI 选择界面是完全一致的角度！
