Setting Up Rig Features

The AzureLib Animator plugin can set up AzureLib's rig features right on your model, preview them in Blockbench, and write the Java code for them:

Hitboxes that follow your bones, for per-limb damage and interaction.
Sockets, named points on bones for spawning projectiles and particles or attaching items.
IK chains, so feet step onto slopes and stairs and limbs reach for targets.
Look-at, so a head, neck and spine turn to watch a target.
Constraints, which keep joints in a believable range.
Spring bones, for tails, antennae and ears that swing on their own, with colliders so they swing around the body instead of through it.
Blend spaces, which mix walk, run or aim animations by speed, direction or pitch.

All of these run in game on top of your animations. You still animate as usual; the plugin only helps you configure them and generate the code.

Note

These features need AzureLib Animator 2.3.0 or newer. See Installing Blockbench Plugin to install or update it.

Finding the Panel

The AzureLib Rig panel opens as a tab next to the Outliner on the right side of Blockbench. Click its tab to switch to it, and click Outliner to switch back.

The panel only shows when:

The project is an AzureLib Animated Model (see Creating or Converting a Project).
You're in the Edit or Animate tab.

Note

You can drag the panel's tab anywhere, like any other Blockbench panel. If you've hidden or lost it, the same tools are also under File -> Export: Generate AzureLib Rig Code and Check AzureLib Rig.

Using the Panel

The top row has two buttons and three toggles:

Code writes the AzureLib Java for everything you've set up; see Generating the Code.
Check looks for problems, such as a bone that was renamed or deleted. A number on the button means problems were found.
Boxes, Sockets, Colliders and Pose switch the viewport preview of hitboxes, sockets, spring colliders and pose features on and off.

Below that is a section for each feature. Each one is a single line with a count and a + button:

Click a section's name to open or close it.
Click + to add an entry. Most entries are made from what you have selected, so select bones or locators first.
Click an entry to edit it, or hover it and click × to remove it.

An entry with a problem shows a yellow note, such as missing bone tail3.

Note

Everything you set up is saved inside your .bbmodel project and can be undone with Ctrl+Z. None of it goes into the exported .geo.json, so keep your .bbmodel to keep your rig setup.

Hitboxes

Hitboxes are boxes that follow your bones, so the game can tell which part of the model was hit. See Bone Hitboxes for what they do in game.

Adding Hitboxes

Select one or more bones in the Outliner.
Open the AzureLib Rig tab and press + next to Hitboxes. Each selected bone gets a hitbox named after it.
Click a hitbox to change its settings.

The boxes show in the viewport as outlines that move with your animations:

Colour	Meaning
Green	A normal combat hitbox
Red	Takes more damage (damage multiplier above 1)
Blue	Takes less damage (damage multiplier below 1)
Cyan	An interact hitbox
Yellow	An anchor hitbox

Hitbox Settings

Setting	What it does
Name	The hitbox's name in code. Defaults to the bone's name
Bone	The bone it follows
Role	Combat hitboxes take damage, Interact hitboxes only handle right-clicks, Anchor hitboxes are just tracked positions
Fit to bone cubes	Sizes the box to fit the bone's own cubes (not its child bones). Turn it off to set a size yourself
Size	The box's size in pixels, when not fitting
Offset	Moves the box, in pixels
Inflate	Grows (or with a negative number, shrinks) the box on every side, in pixels
Center on pivot	Centers the box on the bone's pivot instead of on its cubes
Damage multiplier	How much damage hits on this box do, for combat hitboxes. `2` is double, `0.5` is half
Tags	Labels your code can check, such as `weak_point`

Under the hitbox list, keep entity box keeps the entity's normal hitbox working alongside the bone hitboxes, and client only turns off syncing hitboxes to the server.

Note

A hitbox fitted to a bone with no cubes of its own is empty and shows empty box. Give it a size, or put it on the bone that actually holds the cubes.

Sockets

Sockets are named points that follow a bone, such as a gun's muzzle or a hand. Your code can find where they are in the world, or draw items there. See Bone Sockets and Attachments for using them in code.

The easiest way to make one is with a locator.

Adding Sockets

From locators: select one or more locators and press + next to Sockets, or press all to add a socket for every locator in the model.
On a bone: select a bone and press +, then click the socket to set its offset from the bone's pivot.

Each socket shows in the viewport as a pink arrow pointing the way the socket faces (its front, -Z) and a short purple arrow pointing up. Check the pink arrow points where you expect, for example out of the gun barrel.

Socket Settings

Setting	What it does
Follows	A bone or A Blockbench locator
Name	The socket's name, for bone sockets. Locator sockets use the locator's name
Offset	Extra offset from the bone's pivot (or the locator), in pixels
Rotation	Extra rotation, in degrees
Server anchor hitbox	A name for an anchor hitbox, so the server can find the socket too (for example to spawn projectiles server-side)

Note

Bone positions only exist on the client. If your mod spawns things at a socket on the server, give the socket a Server anchor hitbox name; the generated code adds the matching anchor hitbox for you. For locator sockets, the generated code leaves a note showing how to add it by hand.

IK Chains

IK (inverse kinematics) chains turn a limb so its end reaches a target. The most common use is feet that step onto slopes, stairs and ledges instead of floating or sinking. See Inverse Kinematics for how it works in game.

Adding an IK Chain

Select the chain's bones in the Outliner, from the root to the tip. For a leg, that's the thigh, the shin and the foot.
Or select just the root bone: the plugin follows its children down for as long as each bone has a single child bone.
Press + next to IK chains. The settings open straight away.

IK Chain Settings

Setting	What it does
Modifier id	The chain's name in code
Bones	The chain's bones, root first, separated by commas
Effector	The point that should reach the target, in pixels from the last bone's pivot. For a foot, move it down to the sole, e.g. `0, -2, 0`
Solver	Two-bone for legs and arms, CCD for tails and tentacles. Auto picks two-bone for 2 or 3 bones
Use pole / Pole	A point the knee or elbow turns towards, in pixels. Needed if the limb is modelled perfectly straight
Iterations / Tolerance	How hard CCD tries, and how close (in pixels) counts as reached
Target	Where the effector goes in game: Ground for foot placement, Another entity's eyes, a World position your code supplies, or a Fixed model point
Max step up / down	How far above and below the foot to look for ground, in blocks
Priority	The order pose features run in, lowest first
Default weight	How strongly it applies, from 0 (off) to 1 (full)

Note

If a knee or elbow bends the wrong way, add a constraint to it, or set a pole in front of (or behind) the joint.

Previewing an IK Chain

In the Animate tab, with Pose switched on, the chain is solved on top of your animation every frame. The Preview target setting picks where the preview aims, since the real target only exists in game:

Ground (raised by offset): pretends the ground under each foot is higher or lower by Ground offset pixels. Try 4 to see the feet step up onto a ledge.
Fixed point: a point in the model, in pixels.
Follow a locator: follows a locator. Add a locator, pick it here, and move it around with Blockbench's move tool to drag the target.
Off: no preview.

Look-At

A look-at turns a chain of bones, such as the neck and head, so the last one faces a target. The turn is spread across the chain.

Select the bones from the root to the head (for example neck, head) and press + next to Look-at.
Click it to pick the target and preview settings.

Look-at uses the same Target, Priority, Default weight and Preview target settings as IK chains, plus Forward: the direction the last bone faces, in its own axes. The default 0, 0, -1 suits a head modelled facing north. Change it if the head looks sideways in the preview.

Constraints

Constraints limit how far a bone can turn, like a knee that only bends one way. IK chains, look-at and spring bones all respect them.

Select a bone and press + next to Constraints.
Click it to set the limits.

Setting	What it does
Type	Limit clamps all three axes. Hinge X, Hinge Y and Hinge Z allow turning on one axis only, like a knee or elbow
Min / Max	The allowed range in degrees, relative to the bone's rest pose
Also clamp the final pose	Also limits the animation itself, after everything else has run

Note

Limits use the signs of your exported animation file. Blockbench 5 shows X and Y keyframe rotations with the opposite sign (Z is the same), so for X and Y, flip what Blockbench 5 shows: if a keyframe of -90 on X bends the knee the right way, a Hinge X from 0 to 150 allows that direction.

Spring Bones

Spring bones make a chain of bones swing on its own: it lags behind, overshoots and settles, and in game it trails when the entity moves or turns. See Secondary Motion for more.

Select the chain from the root to the tip (or just the root) and press + next to Spring bones.
Click it to tune the motion.

Setting	What it does
Last bone swings (tip) / Tip	The end of the last bone, in pixels from its pivot. Without it, the last bone doesn't swing on its own
Stiffness	How strongly the chain pulls back to the animation, from 0 (limp) to 1 (rigid)
Damping	How quickly the swinging dies down, from 0 (bouncy) to 1 (no overshoot)
Gravity	Pulls the chain down, in blocks per tick². Small values like `0.005` make it droop
Inertia	How much moving through the world swings the chain in game, from 0 to 1
Colliders	The colliders the chain can't pass through, by id, separated by commas
Chain radius	Roughly how thick the chain is, in pixels, so it stays off colliders and the ground
Stay above the ground	Stops the chain going below the model's feet

The first bone follows the animation exactly and anchors the chain. Press play in the Animate tab to see the swing; it reacts to how the animation moves the chain.

Colliders

Colliders stop spring chains swinging through the body, like a tail through the legs.

Select the bones the chain hits, such as the thighs and the body, and press + next to Colliders. Each bone gets a capsule fitted along its cubes (or a sphere, if it's about as wide as it's long).
Click a collider to adjust its Shape, its Start and End (pixels from the bone's pivot) and its Radius.
Open the spring chain and list the colliders it should hit under Colliders, for example gLeftLeg, gRightLeg.

Colliders show in the viewport as orange wireframes that move with their bones. In the Animate tab, play an animation to see the chain bump against them.

Note

Don't put a collider on one of the chain's own bones, or overlapping where the chain sits in its animation; the chain is always pushed out of colliders, so it would never settle. Check warns about the first case.

Blend Spaces

A blend space mixes several looping animations based on a value such as movement speed. For example: idle at speed 0, walk at 2 and run at 6. See Blend Spaces for how they work in game.

Adding a Blend Space

Make the animations you want to blend first, in the Animate tab.
Press + next to Blend spaces. The settings open straight away.

Setting	What it does
Name	The blend space's name in code
Dimensions	1D blends by one value (speed). 2D blends by two (forward and strafe speed)
Input (X) / Input (Y)	The value to blend by: horizontal speed, forward speed, strafe speed, look pitch, or custom (you fill it in)
Samples	One per line: `position, animation` for 1D, or `x, y, animation` for 2D
Input smoothing	Eases sudden changes in the input, in ticks
Sync phase	Keeps walk and run cycles in step while blending

For example, a 1D locomotion blend space:

0, idle
2, walk
6, run

Previewing a Blend Space

In the Animate tab, press ▶ on a blend space. Sliders appear under it; drag them to change the input and see each sample's share. Press play on the timeline to see the blended motion, and ■ to stop the preview.

Note

In the preview, all samples play on Blockbench's one timeline, so cycles of different lengths drift apart. In game, sync phase keeps them in step.

Checking Your Rig

Press Check (or File -> Export -> Check AzureLib Rig) to list problems, such as:

Bones or locators that were renamed or deleted.
Chain bones in the wrong order (each must be inside the one before it).
Names or modifier ids used twice.
Hitboxes with no size.
Blend space animations that don't exist.

Fix these before generating code, or the code won't match your model.

Generating the Code

Press Code (or File -> Export -> Generate AzureLib Rig Code).
Pick your AzureLib branch: 26.3, 1.21.1, 1.20.1, 1.18.2, 1.12.2 / 1.7.10, or Beta 1.7.3.
Enter your Animatable class: the name of your entity class, for example GraboidEntity.
Leave Package root blank unless your AzureLib build uses a different package than the branch default.
Press Confirm. The code appears with Copy and Save .java buttons.

The code comes in sections. Each starts with a header naming the class it belongs in, followed by the imports it needs:

Section	Goes in
Entity	Your entity class: socket constants and the hitbox set (your entity implements `AzHitboxHolder`)
Animator: pose modifiers	Your animator's `registerPoseModifiers` method: IK, look-at, spring bones and constraints
Animator: blend spaces	Your animator's `registerControllers` method, plus any speed helper methods for your entity class
Renderer: attachments	Your renderer config builder: an attachment layer with a spot for each socket

Note

Look for TODO comments in the generated code. They mark the parts only you can fill in, such as which entity a look-at should watch or what to draw at a socket.

The branch, class name and package root are saved with your project, so next time you only need to press Confirm.