Blockbench

The basics on how to use Blockbench

Proper tutorials for Blockbench can be found online. This page just explains Figura specific stuff. This page assumes you are using the Desktop version of Blockbench, not the online app.

Project Properties

This is the popup that appears when you create a Project. You can also get to this page via File->Project.
<img src={require("@site/static/img/blockbench/project.png").default} width="400"></img>
Figura only accepts <Emoji icon="file/bbmodel"/> bbmodels in the Generic Model format. If your format is not Generic Model, Figura will refuse to load the avatar. To convert a project, File->Convert Project. Deselect Create Copy, ensure format is Generic Model, and press Confirm. If the popup does not go away after pressing Confirm, close it manually.
<img src={require("@site/static/img/blockbench/convert_project.png").default} width="400"></img>

The File Name and Model Identifier fields are unused by Figura.
UV Mode determines how Blockbench handles how UVs are positioned. Figura will handle both Box UV and Per-face UV. Its up to you which you want. UVs determine where a 2D texture is applied to a 3D model. Each face has it’s own UV coordinates which determines where on the 2D texture it will get it’s pixels from.

<img src={require("@site/static/img/blockbench/uvmode_box.png").default} width="200" style=Template:"float":"right"></img> Box UV forces each face of a cube to match how vanilla does UVs. If you have ever edited your own vanilla skin before, you will recognize the pattern. While this does simplify the texturing process, it limits what you can do. Also, all textures in the model must have the same size, as what is a pixel is determined by the project’s global Texture Size instead of the size of the texture itself. Also, meshes cannot be used while using Box UV

<img src={require("@site/static/img/blockbench/uvmode_perface.png").default} width="200" style=Template:"float":"right"></img>

Per-face UV allows full control over each face of the cube/mesh. Each face can be positioned, scaled, and rotated individually from each other. You can even set a different texture for each face, or remove a face to reduce clutter. While the pixel grid is effected by the project’s global Texture Size, changing the Texture Size has zero effect on the UVs themselves, unlike Box UV which will have destructive effects when changing the project

Texture Size.

The Texture Size field aids with UV calculation. In rendering, UVs are a float from 0-1 representing the percentage of the texture that this point is at. A UV of (0.5,0.5) represents the center of the texture, regardless of the texture’s own size. A way of calculating this percentage is to take the pixel coordinate you want and divide it by the texture’s size. (32,16)/(64,64)=(0.5,0.25). The Texture Size field determines this texture size globally. Blockbench never uses the texture’s actual size, which causes issues when you have a model with textures of different sizes. Thankfully, changing it only has an effect on ModelParts that use Box UV, so when you need to edit ModelParts using a different sized texture, you can change this with no worries so long as you are using Per-face UV.

ModelParts

ParentTypes

If the name of a <Emoji icon="blockbench/group"/> group begins with a specific string, Figura will apply special effects to that group. Some examples include Head, RightArm, and World. These are called [[../enums/ModelPartParentTypes|ParentTypes]].

Blank Texture

ModelParts that use the Blockbench inbuilt Blank texture will not be loaded by Figura at all. If you want a Model to not have a texture and assign the texture via script, use the [[../tutorials/Avatar-Metadata|ignoredTextures metadata customization]]. The Transparent texture that can only be applied to individual faces in Per-face UV behave the same way. Figura will not load those faces.

Meshes

<Emoji icon="blockbench/mesh"/> Meshes are allowed. Nothing special with Figura. This is just here for those that need to be explicitly told Meshes work.

Textures

Local/External Textures

In Blockbench, textures have 2 distinct states: Local and External.
To determine the state your texture is in, Right Click a texture->Properties. An External texture will have a file path, while a Local one will not.
There is one key factor for a texture to be External, and that is for the file itself to be inside the avatar’s folder. If the filepath does not lead to a file inside the avatar’s folder, Figura will load it as a Local file.
<img src={require("@site/static/img/blockbench/texture_local.png").default} width="300"></img><img src={require("@site/static/img/blockbench/texture_external.png").default} width="300"></img>

Whether a texture is Local or External will determine how Figura will load it which is important when getting a Texture in script.

The Render Mode field determines how the texture will be rendered. In Blockbench, this changes nothing visually.
Figura ignores Render Mode. The Primary Texture will always be TRANSLUCENT by default, and the Secondary Texture will always be EMISSIVE by default.

The Render Sides field determines if the cube should be rendered when looking at the back of a face.
Figura ignores Render Sides. To apply the same effect, use the TRANSLUCENT_CULL [[../enums/RenderTypes|RenderType]] in a script.

Texture Suffix

In Blockbench, each cube (face) can only point to a single texture, which means that Figura needs to get creative when it wants to link multiple textures together for stuff like emissive textures.
When Figura loads a texture, it looks for another texture with the same name but with a specific suffix. Then for all ModelParts in Blockbench that use the texture, Figura will link the suffixed texture to that ModelPart as well.

List of suffixes used by Figura:

• _e: This texture will be used as the Secondary Texture, also known as the [[../tutorials/Emissive%20Textures|Emissive Texture]], of the ModelPart. The Secondary RenderType of a ModelPart is by default EMISSIVE, but can be changed in script.
• _n: This texture will be used as the Normal Texture. Do not confuse this with the Primary Texture. “Normal” means something very specific in modeling. This suffix is used with Iris Shaders, and does nothing with vanilla rendering. This suffix currently does not function.
• _s: This texture will be used as the Specular Texture. This suffix is used with Iris Shaders, and does nothing with vanilla rendering. This suffix currently does not function.

An example is the <Emoji icon="blockbench/group"/> Head, <Emoji icon="file/texture"/> skin, and <Emoji icon="file/texture"/> skin_e. When the <Emoji icon="blockbench/group"/> Head uses the texture <Emoji icon="file/texture"/> skin, when the Avatar is loaded, <Emoji icon="file/texture"/> skin_e is used as the Secondary Texture, ie the Emissive Texture.
<img src={require("@site/static/img/blockbench/settexture.png").default} width="300"></img>

For a texture to have the same name, they must both be either Local or External, and should they be external, they must be in the same folder. Otherwise, they will not have the same name internally.
For textures with file extensions, the suffix goes before the extension. <Emoji icon="file/texture"/> skin_e.png

Animations

Animation Properties

This popup appears when you create an animation. To get back to this popup, Right Click an Animation->Properties.

<img src={require("@site/static/img/blockbench/animation_properties.png").default} width="500"></img>

Name

This is the animation’s name. It is very important that you change this to something shorter. The entire textbox is the animation’s name, so unless you want to refer to this animation in lua with animations.player["animation.model.new"], change the name. An animation named just "new" is indexed via animations.player.new. Much nicer, right?

Loop Mode

This controls what happens when the animation reaches the end. There are 3 valid loop modes:

Play Once

The animation will stop immediately at the end. Note that badly-made animations may have a visible jump to their original position in this mode.

Hold On Last Frame

The animation will hold the values from its last frame after ending. Note that while an animation is holding, it is still considered playing, so calling :play() again will do nothing.

Loop

When the animation reaches its end, it will jump to the beginning. Note that the start and end frames should be the same in this mode, as there won't be an in-between animation.

Override

If this is enabled, Mimic-type Enums/ParentTypes won't apply their rotations while this animation is playing. Note that keyframes must be present on the specific channel for override to apply! For example, putting a keyframe on Head's rotation won't apply override to its position or scale, Body, or even other Heads.

Snapping

This sets what unit of time Blockbench will set animations to. Holding Ctrl allows you to bypass this. Figura ignores this value.

Anim Time Update

Default value: 0

This allows you to set the time Figura starts playing the animation at. For example, setting this to 2 skips the first 2 seconds of the animation. This lets you add keyframes before the animation to help with interpolations.

Trivia:  In Molang (and, therefore, Blockbench), this sets the animation's time every tick to a Molang expression. In Figura, you can achieve the equivalent by calling setTime in a script.

Blend Weight

Every keyframe value in the animation is multiplied by this value. This isn't very useful itself, but can be used by scripts (for example, GSAnimBlend) to transition into or out of animations.

Start Delay

Default value: 0

This delays the animation's start time by the given amount.

Loop Delay

Default value: 0

This sets the amount of time the animation will pause at the end before it loops again. This is only relevant in Loop mode.

Keyframe Expressions

While Blockbench supports Molang, Figura does not.
To remedy this, Figura allows writing lua code into keyframe fields.

Figura provides data for the keyframe expression, which is accessible via the ... variable.

It has 2 pieces of data, the keyframe time, and the Animation object of the animation itself.
Keyframe time is measured in percentage, not seconds. So, assuming a Step interpolation keyframe, 0 is at the time at the keyframe itself and 1 is at the next keyframe. Keyframe time is only useful when the keyframe uses Step interpolation.
When using other interpolation types, the expression will execute before it has reached the keyframe itself to interpolate. While this happens, it will give the Keyframe time of the previous keyframe and go back to zero once it reaches itself.

They can be extracted via the following line:

local time, anim = ...

Keyframe Expressions accept 2 different formats:

• A single lua expression that evaluates to a number
• A lua script that returns a number

math.sin(world.getTime()) is a single lua expression, so it is a valid Keyframe Expression.
However, local _, anim=... math.sin(anim:getTime()) is not a single lua expression and will need to have an explicit return value:

local _, anim = ...

return math.sin(anim:getTime())

Alternatively, you can rewrite it as a single lua expression: math.sin({...}[2]:getTime())
This deconstructs the ... varargs into a table and grabs the second value.

Instruction Keyframes

Instruction Keyframes run lua code when the Animation reaches that keyframe. This can be used to play sounds, spawn particles, literally anything. Remember that Lua code is what goes in this spot, not Molang.
You can access Instruction Keyframes via the Magic Wand icon. An Effects timeline should appear along with the other ModelPart timelines.

Animation Features That Figura Does Not Care About

Below are features provided by Blockbench Animations that figura does not use when loading the bbmodel.

Variable Placeholders
<img src={require("@site/static/img/blockbench/animation_variableplaceholders.png").default} width="200"></img>
This is completely ignored by Figura.

Inverse Kinematics
Don’t bother. Not a thing in Figura.

Global Rotation
There is a toggle for Global Rotation next to the Rotation timeline for ModelParts. Figura does not obey this, so keep it disabled.

Sound Keyframes
Figura does not read these. Use Instruction Keyframes.

Particle Keyframes
Figura does not read these. Use Instruction Keyframes.