YSM 文档与教程

简体中文

English

外观

项目结构

约 7123 字大约 24 分钟

模型结构

2025-01-26

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

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

文件目录结构

注意

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

2.5.x 版本

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.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": {
      // 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"
        }
      ]
    },
    // 可选字段，替换弹射物的渲染
    // 注意 2.5.2 及以后的版本支持这种新版写法
    "projectiles": [
      {
        // match 字段支持数组，可以匹配多个弹射物
        // 既可以填写实体 ID，也可以填写实体 Tag
        "match": [
          "minecraft:arrow",
          "#minecraft:arrows"
        ],
        "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"
        }
      },
      {
        "match": [
          "minecraft:trident"
        ],
        "model": "models/trident.json",
        "texture": "textures/trident.png"
      },
      {
        "match": [
          "minecraft:fishing_bobber"
        ],
        "model": "models/fishing_bobber.json",
        "texture": "textures/fishing_bobber.png"
      },
      {
        "match": [
          "minecraft:firework_rocket"
        ],
        "model": "models/firework_rocket.json",
        "texture": "textures/firework_rocket.png"
      }
    ],
    // 可选字段，替换载具的渲染
    "vehicles": [
      {
        "match": [
          "minecraft:boat"
        ],
        "model": "models/boat.json",
        // 同样支持动画控制器
        "controller": "controller/boat.controller.json",
        "animation": "animations/boat.animation.json",
        "texture": "textures/boat.png"
      },
      {
        "match": [
          "minecraft:chest_boat"
        ],
        "model": "models/chest_boat.json",
        "animation": "animations/boat.animation.json",
        "texture": "textures/boat.png"
      },
      {
        "match": [
          "minecraft:minecart"
        ],
        "model": "models/minecart.json",
        "texture": "textures/minecart.png"
      }
    ],
    // 可选字段，修改声音文件夹的位置
    "sound_path": "sounds",
    // 可选字段，修改自定义函数文件夹的位置
    "function_path": "functions",
    // 可选字段，修改语言文件夹的位置
    "language_path": "lang"
  }
}

部分字段作用说明

render_layers_first

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

pEgLH2Q.png

disable_preview_rotation

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

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

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

1.png