Mannequins

One file per kind in plugins/BoxStand/mannequins/. Add a file to add a kind; delete it to remove one.

Kinds and variants

A kind is one file, and the settings its variants share. A variant is one entry in the picker, naming the model it shows.

# mannequins/torso-mannequin.yml   <- one kind
name: Torso Mannequin
variants:
  wooden:                          # <- one variant
    model: mannequin_torso
  white:
    model: mannequin_torso_white
  black:
    model: mannequin_torso_black

Players see the variants, not the kinds: the picker lists every model they may use, side by side.

The whole file

# Every key a kind file takes. Only name and variants are needed.
name: Torso Mannequin            # button label, or the file name
order: 2                         # place in the button cycle
require-permission: false        # boxstand.<file-name>
off-item: boxstand:mannequin_torso_off   # icon while the button is off
off-modeldata: 1010              # custom-model-data, for a plain material
hide-slots: [leggings, boots]    # slots this kind has no use for

# animations, pose and defaults may also sit here, covering every variant
# that sets none of its own.
animations:
  all: wear_chestplate
pose:
  pose_1: pose1
defaults:
  base-plate: false

variants:
  wooden:
    model: mannequin_torso       # ModelEngine blueprint id
    item: boxstand:mannequin_torso_on
    modeldata: 1011              # only when item is a plain material
    permission: boxstand.mannequin.wooden   # hidden without it
    pose:                        # button label: animation
      pose_1: pose1
      champion: pose3
    animations:                  # slot: animation
      helmet: wear_helmet
      chestplate: mannequin:wear_chestplate    # another model's animation
      balloon:
        on-fill: wear_balloon    # put in or swapped
        on-empty: wear_chestplate
        on-click: wear_chestplate
      backpack:
        on-fill:
          play: wear_chestplate
          item-delay-ticks: 6        # the item appears 6 ticks in
          hide-worn: true            # and everything else waits with it
          animation-delay-ticks: 0   # when the animation starts
          animation-lerp-ticks: 2    # blend in instead of snapping
    defaults:                    # toggles held while this model is worn
      base-plate: false
      gravity: false
      arms: true

  white:
    model: mannequin_torso_white
    template: wooden             # borrows the rest from that variant
    item: boxstand:mannequin_torso_white_on

Plain materials work anywhere an item id does - item: ARMOR_STAND with a modeldata number beside it. A Nexo or ItemsAdder id needs no number, it carries its own look.

hide-slots

Slots: helmet, chestplate, leggings, boots, right-arm, left-arm, backpack, balloon.

Hidden slots and their pose parts leave the menus; items in them return when the model does. The torso kind hides leggings and boots - the model has no legs.

template

Copies another variant's animations, pose and defaults - plus model, item and modeldata when unset. Anything written in the variant wins.

pose

A button label and the animation that holds the pose.

pose:
  pose_1: pose1        # shows as "Pose 1"
  champion: pose3      # shows as "Champion"

Each must be one still frame on Loop - see Loop and override.

The Pose button opens a page with Custom Pose first. Manual edits sit on top of the chosen pose, and picking it again clears them.

Building the model

Start from a copy of mannequin.bbmodel in the pack: its pivots already sit on the armor stand's joints, and a wrong pivot is what makes a model bend in the wrong place.

Bones

The pose is written to these six, named under mannequin.bones. A name no bone answers to is skipped - a torso model leaves the legs out and hides those slots with hide-slots.

Bone	Carries
head	the head pose
body	the body pose
left_arm, right_arm	the arm poses, shown only while Arms is on
left_leg, right_leg	the leg poses
baseplate	shown only while Base Plate is on

Two more, both optional:

• a bone whose name contains l_ ties the balloon's lead. balloon.leash-bone picks which one when there are several.
• a bone whose name contains emissive is lit at full brightness (model.emissive-bone).

Child bones

The six can sit anywhere in the tree, and anything you add inside one follows it. The bundled mannequin, with its own bones marked:

• waist (its own)
  • head - head pose
    • neck (its own)
  • body - body pose
• left_arm, right_arm - arm poses
• left_leg, right_leg - leg poses
  • left_foot, right_foot (its own)
• baseplate

The pose only ever writes to the six. Everything else is free for the animation, which is where a scarf, hair or a tail goes.

Loop and override

Names are yours - animations: says which plays where, and the rest pose is named by pose.default-animation. The bundled wear_* prefix is just tidiness.

Animation	Loop	Override	Why
the rest pose (idle)	Loop	No	It has to stay on the model, and the pose sits on top of it
a preset pose	Loop	No	Same: a still frame the model holds
a slot reaction	Once	No	It plays and gets out of the way

Use Loop. Once ends and drops the model back to the rest pose; Hold matches Loop only while the animation really is one frame.

Leave Override off: it cancels the rest pose underneath. A reaction need only keyframe the bones it moves - the pose shows through on the rest.

animations

One entry per slot: helmet, chestplate, leggings, boots, right-arm, left-arm, backpack, balloon, or all.

helmet: animation            # every trigger
helmet: model:animation      # another model's, same skeleton only
helmet:
  on-fill: animation         # put in or swapped
  on-empty: animation        # taken out
  on-click: animation        # clicked, no item moved

A name with no prefix belongs to the variant it sits in.

Timing

Any trigger can be a block instead of a name. Ticks, so 20 = 1 second.

helmet:
  on-fill:
    play: wear_helmet
    item-delay-ticks: 6        # the helmet appears 6 ticks in
    hide-worn: true            # the rest of the outfit waits with it
    animation-delay-ticks: 0   # when the animation starts
    animation-lerp-ticks: 2    # blend in instead of snapping

item-delay-ticks makes the item wait for the hand to reach it - on the way in and on the way out.

hide-worn strips the rest of the outfit for that same wait so it all lands in one tick. Needs item-delay-ticks; a slot the player changes meanwhile keeps what they put there.

defaults

Toggles held while the mannequin is worn: base-plate, gravity, arms.

defaults:
  gravity: false
  base-plate: false

Removing the model puts the old state back, unless the player changed that toggle themselves.