Models - mchorse/bbs-mod-wiki GitHub Wiki

BBS supports loading Blockbench models by exporting them with BBS Model Ex/importer plugin.

Features

The format that the custom plugin exports supports decent chunk of Blockbench's features. Following known features that are not supported: extra animation options (including different loop modes, anim time update, blend weight, etc.), texture meshes, locators and null objects, and multiple textures per model (use Texture Stitcher plugin to combine multiple textures into one).

Following features are known to be supported:

Cubes with support for Box or per-face UV modes
Meshes
Groups, their rotation and pivots
Animations, including linear, step and smooth interpolations, and math expressions

Installation

In Blockbench, go to File > Plugins > Available, search for BBS and there will be BBS Model Ex/exporter plugin. Install it.

File > Plugins > Available

Exporting

IMPORTANT: BBS mod expects at least 1 group! Beside that, all of the cubes/meshes have to go into top-level groups, or else they would be discarded!

Once the plugin is installed, you can export your model via File > Export > Export BBS model:

Press Confirm button.
Go to BBS mod's models folder, which you can open by entering Dashboard (0 key by default), press F6 and click Models button.
Once file explorer opens, create a folder with any name (the folder's name will be model's ID).
Save the file as .bbs.json file.
In Blockbench, export the texture as well to the same folder as a .png file.

After that, the model should appear next time you open one of the form picker menus.

Available actions

BBS mod's models forms are animated using action system. For different states of an entity, there is a dedicated action for that. Here is a table that describes what every action does, its default name in the .animation.json file, and the name in the Chameleon morph's actions panel list.

Name in Blockbench	Description
`idle`	Default animation when an entity is standing still on the ground.
`running`	Running animation when an entity walks on the ground (WASD).
`sprinting`	Sprinting animation when an entity sprints (i.e. by pressing `W` twice or `Ctrl` keys) on the ground.
`crouching_idle`	Sneaking animation when an entity stands still on the ground.
`crouching`	Sneaking animation when an entity walks on the ground (WASD).
`falling`	Falling animation when an entity quickly falls (moves vertically down).
`swipe`	Swiping animation when an entity is hitting something (i.e. left clicking).
`jump`	Jumping animation when an entity jumps (i.e. pressing Space).

Available variables

Following variables can be used within Blockbench's animations:

Name	Description
`query.anim_time`	Current animation progress in ticks.
`query.head_yaw`	Horizontal rotation of entity's head.
`query.head_pitch`	Vertical rotation of entity's head.
`query.velocity`	Velocity of the entity in block units.
`query.ground_speed`	Velocity of the entity in block units (only horizontal, i.e. X and Z).
`query.yaw_speed`	Entity's horizontal rotation speed.
`query.age`	Current age of the entity in ticks, i.e. for how many ticks did this entity exist.
`joystick.l_x`	Left stick's X position. `-1` is fully left, `0` is in the middle, `1` is fully right.
`joystick.l_y`	Left stick's Y position. `-1` is fully up, `0` is in the middle, `1` is fully down.
`joystick.r_x`	Right stick's X position. `-1` is fully left, `0` is in the middle, `1` is fully right.
`joystick.r_y`	Right stick's Y position. `-1` is fully up, `0` is in the middle, `1` is fully down.
`joystick.l_trigger`	Left trigger's held state. `-1` is fully released, `1` is fully pressed.
`joystick.r_trigger`	Right trigger's held state. `-1` is fully released, `1` is fully pressed.
`extra1.x`	Horizontal axis of the first extra mouse controlled animation group.
`extra1.y`	Vertical axis of the first extra mouse controlled animation group.
`extra2.x`	Horizontal axis of the second extra mouse controlled animation group.
`extra2.y`	Vertical axis of the second extra mouse controlled animation group.

This is WIP page. Important note: the joystick variables are legacy names for variables controlled by game controller. Nowadays, these variables are solely as extra variables for animation from film editor.

`config.json`

In the model's folder, you can create a file named config.json that allows you to setup extra options for the model. Following options exist:

Name	Description
`procedural` (boolean)	Enables procedural animation mode for the model. See below for more information!
`culling` (boolean)	Toggles backface culling for the model, by default it's enabled.
`pose_group` (string)	Allows you to specify pose group for the model. If you have multiple models that share the same group structure, you can reuse saved poses by specifying the pose group for a single model. See below for more information.
`items_main` (array of strings)	Allows you to specify group(s) where the main slot item will be rendered. See below for more information.
`items_off` (array of strings)	Allows you to specify group(s) where the offhand slot item will be rendered. See below for more information.
`ui_scale` (float)	Specifies the scale factor when rendered in UI.
`scale` (array of 3 floats)	Specifies the default scale factors (XYZ).
`sneaking_pose` (object)	Specifies the pose that will be applied to the model when sneaking when `procedural` mode is enabled. See below for more information.

`procedural`

When procedural is enabled, the model will be animated using hardcoded animation that looks like Minecraft models. At the moment, the limbs are hardcoded, following groups have animations:

Name	Description
`anchor`	Animates rotation when player is in water, elytra flying or using riptide. It should be vertically in the center of the model.
`head`	Animates the direction in which head is looking. If it's oriented in a non standard position, the head won't be automatically oriented where the look is. It just uses head yaw and pitch of the entity.
`left_arm`	Animates left arm: the swing during walking and a little offset when entity holds an item in that arm.
`right_arm`	Animates right arm: the swing during walking and a little offset when entity holds an item in that arm.
`left_leg`	Animates left leg swing during walking.
`right_leg`	Animates right leg swing during walking.

There is special case for attack (swiping) animation to work. For swiping animation to work, you have to have torso, left_arm and right_arm groups present. Then the swiping animation will be properly displayed.

Finally, "sneaking_pose" is applied to procedural animation when an entity is crouching (sneaking). You can setup a pose for sneaking animation in model block, right click on the limbs/bones list, and copy the pose. Then you can paste into "sneaking_pose" that JSON, and it should apply correctly.

`pose_group`

In BBS mod, when you right click on the list of limbs, you'll see poses context menu where you can copy, paste, reset, save or pick a saved pose.

Let's say we have four models player_steve, player_fred, player_alex, player_claire that have the same bone structure.

For every other model than player_steve, you can specify player_steve as a pose group:

{
    "pose_group": "player_steve"
}

Then all of these models will share same poses.

`items_main` and `items_off`

With those items_main and items_off, you can specify in which limbs main and off hand items will be rendered.

Imagine your model is a chicken, and at the tips of the wing bones, you have left_wing_item and right_wing_item.

{
    "items_main": ["right_wing_item"],
    "items_off": ["left_wing_item"]
}

Packing models into the mod

With BBS mod, it's possible to pack models and textures into the mod, so that you could much more easily share them with your friends, players or workers. It's really simple!

Just grab all of the files in .minecraft/config/bbs/assets/models/ and move it with WinRaR or any other archive editor into /assets/bbs/assets/models/. Imagine you have three models in your models folder cat, dog, and steve. That's how it supposed to look in bbs.jar:

assets/
 └─ bbs/
     └─ assets/
         └─ models/
             ├─ cat/
             │   ├─ cat.bbs.json
             │   └─ cat.png
             ├─ dog/
             │   ├─ dog.bbs.json
             │   └─ dog.png
             └─ steve/
                 ├─ steve.bbs.json
                 └─ steve.png

This feature doesn't seem to be working on Forge (with Sinytra Connector).