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.jsonLegacy 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"
}
}
}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).
- free: When set to true, this model cannot be restricted as an authorized (auth-only) model.
- render_layers_first (since 2.2.2): Defaults to false. Controls whether vanilla render layers draw before the YSM model.
- disable_preview_rotation (since 2.3.0): Disables character rotation in the selection GUI, useful for custom camera/GUI animations.
- all_cutout (since 2.3.0): Forces backface culling across all textures regardless of transparency, required for inverted-hull (negative scale) outline models.
- 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.
- 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;"
}
}
]
}
]
}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"
}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.