YSM 文档与教程

简体中文

English

外观

项目结构

约 5515 字大约 18 分钟

模型结构

2025-01-26

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

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

文件目录结构

注意

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

2.5.0 版本

2.5.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

...

functions自定义函数文件夹，限定用此名称，但是可以自定义

my_function.molang

parallel6@ctrl_player_parallel_6.molang

...

lang语言文件夹，限定用此名称，但是可以自定义

en_us.json

zh_cn.json

...

ysm.json 文件详解

ysm.json 文件是 2.2.1 版本往后新增的资源描述文件，新版模型和相关配置均以它作为索引。

该文件支持如下内容：

  • 支持设置默认材质和材质文件的展示顺序；
  • 支持设置预览动画，在模型选择界面播放（旧版统一为 idle）；
  • 支持自定义 Extra 动画的数量、顺序、名称（不再限制为 extra+数字）；
  • 支持读取模型目录内的子目录文件。
  • 支持插入作者信息，并分配头像、角色、简介、联系方式
  • 支持插入主页和捐赠网页信息
  • 支持 PBR 材质指定
  • 支持轮盘动画配置功能（2.3.0 新增）
  • 支持轮盘动画分类（2.3.0 新增）

ysm.json 必须放在模型文件夹的根目录下，且需要使用 UTF-8 无 BOM 编码保存，其内容结构如下：

2.5.0 版本
{
    // 版本信息字段，当前必须为 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.5.0 新增字段
        // 用于禁用模型选择界面的模型阴影
        "gui_no_lighting": false,
        // 2.5.0 新增字段
        // 用于设置模型选择界面的前景图
        "gui_foreground": "textures/gui/foreground.png",
        // 2.5.0 新增字段
        // 用于设置模型选择界面的背景图
        "gui_background": "textures/gui/background.png",
        // 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",
                "parcool": "animations/parcool.animation.json",
                "swem": "animations/swem.animation.json",
                "slashblade": "animations/slashblade.animation.json",
                "tlm": "animations/tlm.animation.json",
                "fp_arm": "animations/fp.arm.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"
                }
            ]
        },
        // 可选字段，替换弹射物的渲染
        "projectiles": {
            "minecraft:arrow": {
                "model": "models/arrow.json",
                // 可选字段
                "animation": "animations/arrow.animation.json",
                // 支持动画控制器
                "controller": "controller/arrow.controller.json",
                // 同样支持 PBR
                "texture": {
                    "uv": "textures/arrow.png",
                    "normal": "textures/arrow_n.png",
                    "specular": "textures/arrow_s.png"
                }
            },
            "minecraft:trident": {
                "model": "models/trident.json",
                "texture": "textures/trident.png"
            },
            "minecraft:fishing_bobber": {
                "model": "models/fishing_bobber.json",
                "texture": "textures/fishing_bobber.png"
            },
            "minecraft:firework_rocket": {
                "model": "models/firework_rocket.json",
                "texture": "textures/firework_rocket.png"
            }
        },
        // 可选字段，替换载具的渲染
        "vehicles": {
            "minecraft:boat": {
                "model": "models/boat.json",
                "animation": "animations/boat.animation.json",
                // 同样支持动画控制器
                "controller": "controller/boat.controller.json",
                "texture": "textures/boat.png"
            },
            "minecraft:horse": {
                "model": "models/boat.json",
                "animation": "animations/boat.animation.json",
                "texture": "textures/boat.png"
            }
        },
        // 可选字段，修改声音文件夹的位置
        "sound_path": "sounds",
        // 可选字段，修改自定义函数文件夹的位置
        "function_path": "functions",
        // 可选字段，修改语言文件夹的位置
        "language_path": "lang"
    }
}

部分字段作用说明

render_layers_first

指定原版模型层级的渲染是否先于 YSM 模型渲染，默认为 false。

pEgLH2Q.png

disable_preview_rotation

默认情况下，选择界面动画如果想要贴合角度，需要给人物加一个非常诡异的旋转角度。

将此属性设置为 true 可以取消掉这个诡异的旋转角度。

此时模型的正视图和游戏内 GUI 选择界面是完全一致的角度！

1.png