Guide · Making models

YSM Model Pack Structure and ysm.json Explained

Every Yes Steve Model (YSM) pack starts as an organized folder of geometry, animations, textures, and sounds. Since version 2.2.1, the entire pack is indexed by a single descriptor file named ysm.json, giving creators complete freedom over file names, subfolder organization, and advanced features like PBR textures and config menus.

Modern Folder Structure (YSM 2.2.1 to 2.5.x+)

Whether you distribute your model as a folder, a zip archive, or a compiled .ysm file, the underlying project structure is identical. Your model pack folder must be placed inside the custom or auth directory, and the folder name itself becomes the in-game Model ID.

Introduced in YSM 2.2.1 and expanded in 2.3.0 and 2.5.0, the modern structure only requires ysm.json to have a fixed name and root location. Almost all other files and folders can use custom names (including Unicode characters) as long as they are properly linked inside ysm.json.

Here is the recommended directory layout for YSM 2.5.x, which supports models, animations, controllers (added in 2.3.0), sounds (added in 2.3.0), custom Molang functions (added in 2.5.0), and language files:

custom (or auth)/
└── my_model_pack/                  <-- Folder name becomes the Model ID
    ├── ysm.json                    <-- Required descriptor file (fixed name & location)
    ├── animations/                 <-- Recommended folder for animations
    │   ├── arm.animation.json
    │   ├── bow.json
    │   ├── carryon.animation.json
    │   ├── extra.animation.json
    │   ├── main.animation.json
    │   └── tac.animation.json
    ├── avatar/                     <-- Author avatar images
    │   └── author1.png
    ├── models/                     <-- Geometry files
    │   ├── arm.json
    │   ├── arrow.json
    │   └── main.json
    ├── textures/                   <-- Skin and projectile textures
    │   ├── arrow.png
    │   ├── blue_skin.png
    │   └── default.png
    ├── controller/                 <-- Animation controllers (since 2.3.0)
    │   └── parallel_controllers.json
    ├── sounds/                     <-- Audio files (.ogg only, since 2.3.0)
    │   └── song.ogg
    ├── functions/                  <-- Custom Molang functions (since 2.5.0)
    │   ├── my_function.molang
    │   └── parallel6@ctrl_player_parallel_6.molang
    └── lang/                       <-- Localization files (since 2.5.0)
        ├── en_us.json
        └── zh_cn.json
To use newer YSM features (like animation controllers, sounds, vehicles, or custom functions), you must use the modern ysm.json structure. The legacy 1.2.0 flat-folder structure cannot load new features.

Legacy Structure (YSM 1.2.0 and Earlier)

If you inspect very old YSM packs made for 1.2.0 or earlier, you will not find a ysm.json file. Legacy packs required all files to sit together in a single flat folder using strict lowercase English letters, numbers, and underscores.

In that older format, only three files were strictly required: main.json, arm.json, and at least one .png texture. Optional metadata was stored in info.json, and compatibility animations had fixed file names like main.animation.json, extra.animation.json, arm.animation.json, arrow.json, arrow.animation.json, arrow.png, tac.animation.json, carryon.animation.json, slashblade.animation.json, and tlm.animation.json.

What is ysm.json? (Metadata & Credits)

Sitting in the root of your model folder, ysm.json is the master index file that tells YSM where your assets live and how the model behaves in the GUI. It must be saved with UTF-8 without BOM encoding.

At the top of the file, the required spec key must be set to 2 (which enables PBR support). The optional metadata object controls what players see in the model switcher UI, including the model's display name, tooltip description, license, and author credits with avatars.

{
  "spec": 2,
  "metadata": {
    "name": "Custom Model Name",
    "tips": "Line 1 description\nLine 2 description",
    "license": {
      "type": "CC 0",
      "desc": "Additional license notes\nSupports line breaks"
    },
    "authors": [
      {
        "name": "Author 1",
        "avatar": "avatar/author1.png",
        "role": "Model / Animation",
        "contact": {
          "email": "author@example.com"
        },
        "comment": "Single line note (no line breaks)"
      },
      {
        "name": "Author 2"
      }
    ],
    "link": {
      "home": "https://example.com",
      "donate": "https://example.com/support"
    }
  }
}
Inside metadata, only metadata.name, license.type (if license is present), and authors[].name are required. All other metadata fields are optional, and author lists preserve the exact order you write them in.

Model Properties & GUI Settings

The optional properties object controls scaling, authorization rules, rendering behavior, and how your character appears in the model selection screen. By default, height_scale and width_scale are set to 0.7, and preview_animation defaults to idle.

Pay special attention to default_texture: you must write the texture's file name without the folder path and without the .png extension (for example, "default" for textures/default.png).

  1. free: When set to true, this model cannot be restricted as an authorized (auth-only) model.
  2. render_layers_first (since 2.2.2): Defaults to false. Controls whether vanilla render layers draw before the YSM model.
  3. disable_preview_rotation (since 2.3.0): Disables character rotation in the selection GUI, useful for custom camera/GUI animations.
  4. all_cutout (since 2.3.0): Forces backface culling across all textures regardless of transparency, required for inverted-hull (negative scale) outline models.
  5. gui_no_lighting, gui_foreground, gui_background (since 2.5.0): Removes GUI shadows and adds custom foreground/background overlay images in the selection screen.
  6. merge_multiline_expr (since 2.6.4): When true, merges multi-line Molang expressions inside instruction keyframes.
"properties": {
  "height_scale": 0.7,
  "width_scale": 0.7,
  "preview_animation": "idle",
  "default_texture": "default",
  "free": false,
  "render_layers_first": false,
  "disable_preview_rotation": false,
  "gui_no_lighting": false,
  "gui_foreground": "textures/gui/foreground.png",
  "gui_background": "textures/gui/background.png",
  "all_cutout": false,
  "merge_multiline_expr": true
}

Wheel Animations, Sub-Menus, and Config Forms

Also inside properties, the extra_animation object defines the animations shown on the in-game emote wheel. You are no longer limited to 8 animations or fixed extra0-extra7 names; YSM preserves whatever order and animation names you define.

Starting in YSM 2.3.0, using the # symbol unlocks interactive wheel menus: a # prefix in the value links to extra_animation_buttons (opening a configuration form), while a # prefix in the key links to extra_animation_classify (opening a sub-wheel menu). In 2.3.1+, adding "#return": "Back" creates a return button inside sub-menus.

"properties": {
  "extra_animation": {
    "extra1": "Wave Hand",
    "extra2": "#button1",
    "#category1": "Dance Submenu",
    "#return": "Back Button"
  },
  "extra_animation_classify": [
    {
      "id": "category1",
      "extra_animation": {
        "extra0": "Dance 1",
        "extra1": "Dance 2"
      }
    }
  ],
  "extra_animation_buttons": [
    {
      "id": "button1",
      "name": "Model Settings",
      "config_forms": [
        {
          "type": "range",
          "title": "Size",
          "description": "Adjust player scale",
          "value": "v.player_size",
          "step": 0.1,
          "min": 0.2,
          "max": 5
        },
        {
          "type": "checkbox",
          "title": "Toggle Cat Ears",
          "description": "Show or hide ears",
          "value": "v.neko"
        },
        {
          "type": "radio",
          "title": "Outfit Style",
          "description": "Choose an outfit index",
          "value": "v.type",
          "labels": {
            "Style A": "v.type=0;",
            "Style B": "v.type=1;"
          }
        }
      ]
    }
  ]
}
In config_forms, the value field must always be a Molang variable name (like v.player_size or v.type), never a full expression. For radio buttons, YSM reads the variable's integer value (0, 1, 2...) to highlight the active option, and executes the Molang statement in labels when clicked.

Player Files, Animations, and PBR Textures

The required files object maps all actual asset paths. Inside files.player, only model.main, model.arm, and at least one entry in texture are mandatory. If you omit any animation file under files.player.animation, YSM automatically falls back to the default built-in animation.

Texture entries can be simple path strings or objects that attach normal and specular maps for Oculus and Iris PBR shaders. You can also register multiple parallel animation controllers under animation_controllers (since 2.3.0).

"files": {
  "player": {
    "model": {
      "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"
    },
    "animation_controllers": [
      "controller/parallel.controller.json"
    ],
    "texture": [
      "textures/default.png",
      {
        "uv": "textures/blue.png",
        "normal": "textures/pbr/blue_n.png",
        "specular": "textures/pbr/blue_s.png"
      }
    ]
  },
  "sound_path": "sounds",
  "function_path": "functions",
  "language_path": "lang"
}
All file paths inside files are strictly case-sensitive, even on Windows. Double-check uppercase and lowercase letters in your folder and file names.

Custom Projectiles and Vehicles (2.5.0 & 2.5.2+)

YSM allows your model pack to replace projectiles (arrows, tridents, fishing bobbers, fireworks) and vehicles (boats, chest boats, minecarts, horses) with custom models, animations, controllers, and PBR textures.

Note the syntax change across versions: In 2.3.x–2.4.x, only a single arrow object was supported. YSM 2.5.0 introduced projectiles and vehicles as keyed objects, and YSM 2.5.2+ updated both to arrays using a match list that accepts both entity IDs and entity tags (like #minecraft:arrows).

"projectiles": [
  {
    "match": [
      "minecraft:arrow",
      "#minecraft:arrows"
    ],
    "model": "models/arrow.json",
    "animation": "animations/arrow.animation.json",
    "controller": "controller/arrow.controller.json",
    "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"
  }
],
"vehicles": [
  {
    "match": ["minecraft:boat"],
    "model": "models/boat.json",
    "controller": "controller/boat.controller.json",
    "animation": "animations/boat.animation.json",
    "texture": "textures/boat.png"
  }
]

Questions

Why does my ysm.json fail to load or show garbled text in-game?

Make sure ysm.json is located directly in the root of your model pack folder and saved with UTF-8 without BOM encoding. Also verify that all file paths in the files section match your actual file names with exact uppercase/lowercase casing.

How do I set the default texture in ysm.json?

Set properties.default_texture to the texture's file name only, omitting both the folder path and the .png extension (for example, write "default" for "textures/default.png").

Can I use MP3 or WAV files in the sounds folder?

No. YSM only supports .ogg format audio files inside the sounds directory.

What is the difference between putting # on the key vs. the value in extra_animation?

Putting # on the value (e.g., "extra2": "#button1") links that wheel slot to an entry in extra_animation_buttons to open a config UI with sliders or checkboxes. Putting # on the key (e.g., "#cat1": "Submenu") links to extra_animation_classify to open a nested animation wheel.

How does YSM decide my model's ID in-game?

YSM uses the name of your model pack's root folder (the folder placed inside custom or auth) as the model ID.

Next: YSM Model UV Rules and Standards →

More in Making models

M
Adding sounds to a YSM modelSince version 2.3.0, Yes Steve Model (YSM) allows you to trigger custom or vanilla Minecraft audio directly inside your animations. This guide explains how to prepare audio files, link them in Blockbench, and control playback using Molang and playback contexts introduced in 2.5.3.
M
Adding translations (multi-language) to a YSM modelSince version 2.5.0, Yes Steve Model (YSM) supports multi-language localization through simple JSON language files. This guide walks you through setting up a language folder and writing translation keys for your model's metadata, animations, textures, and configuration menus so players worldwide can understand your model.
M
Animation controllers in YSMBefore YSM 2.3.0, animation playback rules were completely hardcoded. Starting from version 2.3.0, YSM supports Bedrock Edition animation controllers, allowing model creators to customize exactly when and how animations trigger using state machines and Molang.
M
Custom Animation Wheel and Config Menus for YSM ModelsStarting from version 2.3.0, Yes Steve Model (YSM) allows model creators to expand the standard animation roulette wheel with nested sub-wheels and interactive configuration panels. By editing the ysm.json file, you can organize extra animations into categories and let players toggle model parts or adjust values using sliders, checkboxes, and radio buttons.
M
Foreground and Background Images in the Model MenuStarting from version 2.5.0, Yes Steve Model (YSM) allows you to set custom foreground and background images for your model cards in the selection menu. This feature makes it much easier to create decorative frames and backdrops without having to build static 2D planes directly inside your 3D model geometry.
M
Make YSM models with the Blockbench YSM pluginLearning the raw Yes Steve Model (YSM) pack format manually can be complex and overwhelming for beginners. The easiest way to create YSM models is by installing the ysm-utils plugin for Blockbench, which automates the setup and export process. This guide covers how to choose, install, and update the plugin for your specific mod version.