Guide · Making models

Animation controllers in YSM

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

Registering Animation Controllers in ysm.json

To use custom animation controllers, add the animation_controllers array inside the player files section of your ysm.json file. This tells YSM where to load your controller JSON files from.

A single controller JSON file can hold multiple controllers, or you can split your controllers across several files—YSM automatically merges all listed files when loading the model. The file names themselves do not matter.

"files": {
  "player": {
    "model": {
      "main": "models/main.json",
      "arm": "models/arm.json"
    },
    "animation": {
      "main": "animations/main.animation.json",
      "parcool": "animations/parcool.animation.json"
    },
    "animation_controllers": [
      "controller/custom_controller.json"
    ],
    "texture": [
      "textures/texture.png"
    ]
  }
}
If Blockbench fails to import your animation controller file, remove the GeckoLib plugin from Blockbench and try importing again.

Built-in Controller Slot Names

While your JSON file can have any name, the internal controller identifiers must match specific YSM slot names. Defining a controller with one of these names replaces YSM's default hardcoded logic for that slot.

Player Parallel & Main Controllers: Parallel slots run alongside other animations, while main slots handle core body movement.

Player Hand, Armor, Mount & GUI Controllers: These slots control item interactions, armor piece animations, riding states, GUI screen reactions, and third-party mod actions.

Projectile, Vehicle & First-Person Arm Controllers: Used for arrows/projectiles, custom vehicles, and first-person arm rendering. Note that in version 2.5.0 and later, the legacy arrow.* controllers were removed and merged into the projectile.* controllers.

// Parallel & Main
player.pre_parallel_0 .. player.pre_parallel_7
player.parallel_0 .. player.parallel_7
player.main | player.pre_main | player.post_main

// Hands (Hold, Use, Swing)
player.hold_mainhand | player.hold_offhand | player.pre_hold | player.post_hold
player.use | player.pre_use | player.post_use
player.swing | player.pre_swing | player.post_swing

// Riding, Armor & GUI
player.passenger | player.vehicle
player.armor_feet | player.armor_legs | player.armor_chest | player.armor_head
player.gui_hover | player.gui_focus

// Mod Compatibility & Maid
player.fire (TaCZ firing only) | player.carry_on | player.parcool
maid.misc | maid.statue

// Projectiles (2.5.0+, replaces arrow.main and arrow.parallel_0..7)
projectile.main | projectile.pre_main | projectile.post_main
projectile.parallel_0 .. projectile.parallel_7

// Vehicles
vehicle.main | vehicle.pre_main | vehicle.post_main | vehicle.ride | vehicle.move
vehicle.pre_parallel_0 .. vehicle.pre_parallel_7
vehicle.parallel_0 .. vehicle.parallel_7

// First-Person Arm
fp.arm.misc
fp.arm.parallel_0 .. fp.arm.parallel_7
fp.arm.armor_head | fp.arm.armor_chest | fp.arm.armor_legs | fp.arm.armor_feet

Controller Molang Variables

YSM provides built-in boolean variables starting with ctrl. (plus standard Bedrock animation completion queries) so you do not have to write complex velocity or state checks from scratch. All of the following variables return true or false.

query.all_animations_finished // true when all animations in the current state finish
query.any_animation_finished  // true when any animation in the current state finishes

ctrl.death            // Dead
ctrl.riptide          // Using trident Riptide
ctrl.sleep            // Sleeping
ctrl.swim             // Swimming
ctrl.swim_stand       // Upright/standing in water
ctrl.climb            // Crawling and moving
ctrl.climbing         // Crawling while stationary
ctrl.ladder_up        // Climbing up a ladder
ctrl.ladder_stillness // Stationary on a ladder
ctrl.ladder_down      // Sliding down a ladder
ctrl.fly              // Creative/ability flying
ctrl.elytra_fly       // Gliding with Elytra
ctrl.attacked         // Taking damage / hurt
ctrl.jump             // Jumping
ctrl.sneak            // Sneaking and moving
ctrl.sneaking         // Sneaking while stationary
ctrl.run              // Sprinting
ctrl.walk             // Walking
ctrl.idle             // Standing idle

Controller Molang Functions for Items, Armor, and Riding

To check what the player is holding, using, wearing, or riding, use the ctrl. functions. They take two string arguments: the slot/type and the target filter.

The second parameter uses prefix symbols just like YSM's item animation naming: $ for a specific item/entity ID, # for an item tag, and : for a special use action category.

// Holding items ('mainhand' or 'offhand')
ctrl.hold('mainhand', '$minecraft:apple')

// Swinging items ('mainhand' or 'offhand')
ctrl.swing('offhand', '#minecraft:axes')

// Using items ('mainhand' or 'offhand')
ctrl.use('offhand', ':eat')

// Wearing armor ('feet', 'legs', 'chest', or 'head')
ctrl.armor('head', '$minecraft:iron_helmet')

// Riding entities ('vehicle' or 'passenger')
ctrl.ride('vehicle', '$minecraft:pig')
ctrl.ride('passenger', '$minecraft:pig')

Third-Party Mod Compatibility Molang

YSM includes dedicated ctrl. variables for popular mods like Carry On, ParCool, SWEM (Star Worm Equestrian Mod), TaCZ (Timeless and Classics Zero), SlashBlade, and Create. String variables return an empty string ('') when inactive.

// Carry On
ctrl.carryon_type          // String: 'block', 'entity', 'player', or ''
ctrl.carryon_is_princess   // Boolean: true if the player is being carried

// ParCool
ctrl.parcool_state         // String: current parkour action name, or ''

// SWEM
ctrl.swem_is_ride          // Boolean: true if riding a SWEM horse
ctrl.swem_state            // String: current equestrian action, or ''

// TaCZ
ctrl.tac_hold_gun          // Boolean: holding a TaCZ gun in mainhand
ctrl.tac_gun_type          // String: gun category (rifle, pistol, etc.), or ''
ctrl.tac_gun_id            // String: gun ID, or ''
ctrl.tac_is_fire           // Boolean: currently firing
ctrl.tac_is_aim            // Boolean: currently aiming
ctrl.tac_is_reload         // Boolean: currently reloading
ctrl.tac_is_melee          // Boolean: performing melee/bayonet attack
ctrl.tac_is_draw           // Boolean: drawing/switching gun

// SlashBlade & Create
ctrl.slashblade_animation   // String: current sword art name, or ''
ctrl.create_hanging_skyhook // Boolean: hanging on a Create chain drive with a skyhook

Dynamic Animation Controllers (Since 2.6.3)

Starting in version 2.6.3, you are no longer restricted to fixed slot numbers like 0–7. You can create dynamic animation controllers by appending any custom suffix to specific prefixes.

Controllers sharing the same prefix are sorted alphabetically by their full name and loaded in order. Controllers that appear later in the execution order have higher priority and override earlier ones.

// Execution order from lowest priority (earliest) to highest priority (latest):
1. player.pre_parallel  (e.g., player.pre_parallel_custom) -> Very beginning of all controllers
2. player.pre_main_     (e.g., player.pre_main_custom)     -> Before player.main
3. player.post_main_    (e.g., player.post_main_custom)    -> After player.main
4. player.pre_hold_     (e.g., player.pre_hold_custom)     -> Before player.hold_offhand & player.hold_mainhand
5. player.post_hold_    (e.g., player.post_hold_custom)    -> After player.hold_offhand & player.hold_mainhand
6. player.pre_swing_    (e.g., player.pre_swing_custom)    -> Before player.swing
7. player.post_swing_   (e.g., player.post_swing_custom)   -> After player.swing
8. player.pre_use_      (e.g., player.pre_use_custom)      -> Before player.use
9. player.post_use_     (e.g., player.post_use_custom)     -> After player.use
10. player.parallel     (e.g., player.parallel_custom)     -> End of all controllers

Fallback to Hardcoded Logic with ysm-builtin (Since 2.6.3)

Normally, overriding a controller like player.main wipes out all of YSM's default movement logic, forcing you to rebuild walk, run, swim, and jump states yourself. In version 2.6.3, you can manually add a state named ysm-builtin to fall back to YSM's default hardcoded controller whenever that state is active.

For example, in player.main, you can stay in ysm-builtin most of the time, and only transition to a custom state when both ctrl.idle and a custom variable like v.idle_type == 1 are true.

Important rules for ysm-builtin: Transition blend times on this state affect the hardcoded controller. Particle effects, sound effects, and on_entry/on_exit Molang expressions work normally, as do Molang script controllers. However, ysm-builtin is treated as an empty state, so any animations listed directly inside it will not play.

Empty State Chaining and Sub-Controllers (Since 2.6.3)

Continuous Empty State Transitions: Since 2.6.3, when a controller transitions into an empty state (a state with no animations), YSM immediately evaluates that empty state's transitions in the same frame (allowing instant A -> B -> C jumps where B is empty, rather than waiting for the next frame). On_entry/on_exit scripts, sounds, and particles on intermediate empty states still trigger. If an infinite loop like A -> B -> C -> A is detected, the controller halts at the state right before the loop closes (state C).

Sub-Controllers: You can organize complex state machines into hierarchical sub-controllers (up to 5 levels deep). When a parent controller named {parent} enters a state named ysm-entry-{child}, it invokes a separate controller named {parent}.{child}.

For instance, if player.main transitions into the entry state ysm-entry-idle, YSM runs the player.main.idle sub-controller. If player.main.idle then enters ysm-entry-type1, it runs player.main.idle.type1.

Sub-controller rules: The entry state (ysm-entry-*) is treated as an empty state—its animations and blend transition times are ignored, though its particles, sounds, and entry/exit expressions still run. Every frame, parent transitions are checked first; if the parent leaves the entry state, the active sub-controller immediately resets and runs its current state's on_exit expressions. Sub-controllers cannot use the ysm-builtin state.

Questions

Why can't I import my animation controller JSON into Blockbench?

The GeckoLib plugin in Blockbench conflicts with standard Bedrock animation controller imports. Uninstall the GeckoLib plugin, restart Blockbench, and import the controller file again.

How do I replace just one animation in player.main without recreating the entire movement state machine?

In YSM 2.6.3 or later, create a state named ysm-builtin inside player.main. When the controller is in ysm-builtin, YSM runs its normal default animations. You can then transition out of ysm-builtin only when your custom condition is met.

What happened to the arrow.main controller?

In YSM 2.5.0, all arrow.* controllers were removed and merged into the projectile.* controllers (such as projectile.main and projectile.parallel_0 through 7).

Can I put all my controllers in one JSON file, or do they need separate files?

Either way works. You can put multiple controllers inside a single JSON file or split them into several files under the animation_controllers list in ysm.json. YSM merges them automatically on load.

Next: Custom Animation Wheel and Config Menus for YSM Models →

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
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.
M
Modeling a YSM Character Step by StepCreating a custom character for Yes Steve Model (YSM) is much easier when you understand its standardized bone and locator system. This guide explains how to use the built-in template, set up special locator groups for items and compatibility with other mods, and build first-person arm and custom arrow models.