YSM 文档与教程

简体中文

English

简体中文

English

外观

项目结构

约 3405 字大约 11 分钟

模型结构

2025-01-26

了解一个模型包的项目结构是最必要的一环。

因为压缩包格式和 ysm 格式的模型都是文件夹格式模型转换而来的，这里我们直接以文件夹形式格式讲解。

文件目录结构

注意

新版本特性需要使用新版本的文件结构，旧版结构无法使用新版特性

2.3.0/2.3.1 版本

2.3.0 版本新增了音频和动画控制器的支持。

除资源描述文件 ysm.json 为固定名称，固定位置文件。自定义模型、动画、材质文件等均可以依据所需放置在不同的子文件夹中，文件夹、材质名称等也可以使用任意字符。

  • custom或者 auth 文件夹
    • 纸板狐模型包模型包文件夹，可以自定义修改此名称，游戏将会以此文件夹名作为模型 ID
      • ysm.json资源描述文件，固定名称，固定位置
      • animations动画文件夹，推荐用此名称，支持任意字符，可以自定义
        • arm.animation.json各种文件名称没有限制，可以使用任意字符
        • 弓箭动画.json
        • carryon.animation.json
        • extra.animation.json
        • main.animation.json
        • tac.animation.json
      • avatar作者头像文件夹，推荐用此名称，支持任意字符，可以自定义
        • 哥斯拉.png
        • 海螺.png
        • ...
      • models模型文件夹，推荐用此名称，支持任意字符，可以自定义
        • arm.json
        • 箭.json
        • main.json
      • textures材质文件夹，推荐用此名称，支持任意字符，可以自定义
        • arrow.png
        • 蓝色材质.png
        • 默认材质.png
        • ...
      • controller控制器文件夹，推荐用此名称，支持任意字符，可以自定义
        • parallel_controllers.json
        • 挥剑控制器.json
        • ...
      • sounds音效文件夹，限定用此名称，但是可以自定义
        • song.ogg音频仅支持 ogg 格式
        • 恭喜发财.ogg
        • ...

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"
            },
            // 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"
        }
    }
}