Bonelab Custom Avatar Import Guide

Hey folks, this is Chris Scotsman. Welcome to the Merrell SDK tutorial on importing a custom avatar into Bone Lab.

I've resized my Unity window layout so everything fits into the canvas of the video. This is a fresh Unity project with the Marrow SDK imported into it.

1. Creating a Palette

The first step in making any mod is to create a palette. This will hold whatever crates make up the mod—in this case, an avatar. If the Asset Warehouse window is not visible, open it from the Stress Level 0 > Tools menu. Make sure you name your palettes and crates well as the names are used to create unique identifiers for your mod and deleting palettes and crates is not recommended.

2. Importing the Model

I found a suitable rigged mechanism model on Mixamo and dropped the FBX into a folder in the project. You will probably want to place the FBX file into its own folder as materials and textures will be extracted into the same folder as the model file. Drag the model from the project window into the scene and reset its position so that it resides at (0, 0, 0).

3. Setting Up Materials and Textures

Select the Materials tab in the model's inspector. If your model does not seem to have any textures applied to it, extract them. A quick way to do this is to select the "Use External Materials (Legacy)" option in the location field. This will automatically extract the materials associated with the model and apply them to the appropriate meshes. If Unity prompts about normal map settings and needing to mark a texture as a normal map, click the fix now button.

4. Configuring the Rig

Next, click the Rig tab and make sure that the Animation Type is set to Humanoid. The Avatar Definition field should default to "Create From This Model." If you see a checkmark next to the Configure button, Unity has successfully auto-mapped the bones of the imported model. If you see an X or any console errors, click Configure. Look for any red indicators as Unity will warn you of missing or incompatible bones or other issues. You may need to manually map bones if Unity gets confused.

5. Handling Eye Bones

Many models like this one are not rigged with eye bones, but don't worry. Marrow has your back and there’s no need to break out Blender or other 3D software to alter the rig. Implementing an eye override will be covered shortly.

6. Creating a Prefab

Now that the model has been set up in Unity, drag this game object back into the project window to create a prefab. When prompted if you want to create a variant or original prefab, choose original. Select the prefab in the hierarchy and open it to edit directly.

7. Adding the Avatar Script

Add the Avatar script to the root game object. It is possible to fill out the bulk of the fields of the Avatar script, but solid Avatar functionality can be achieved by simply filling in the fields for the wrist bones, making sure that the body mesh has been referenced, and adding an eye center override if the rig does not have eye bones.

8. Configuring the Avatar Script

By default, the Avatar script will attempt to automatically add the main skin mesh renderer to the body meshes list. If the model has separate head or hair meshes, add them to the appropriate list. If specific wrist bones don't exist, the script will pre-fill those fields with hand bones as the best match guess. Tweak these fields as needed.

9. Adding Eye Center Override

Since this rig does not have the required eye bones, add an empty game object named Eye Center Override to the root of the prefab and place it into the Eye Center Override field. Position the Eye Center Override game object between the eyes of the avatar. Adjust the ellipses gizmos to fit the contours of the avatar to avoid visual clipping issues in-game.

10. Final Configuration

If you're unable to manipulate the chin or jaw handles, scroll down to the bottom of the Avatar script and use the sliders if needed. Select the palette in the Asset Warehouse window and then use the inspector to add a crate. Set the type to Avatar Crate, give it a title, and set the crate reference to the Avatar prefab. With the crate selected, click the Generate Packed Assets button to create a rough preview of the avatar.

11. Packing the Mod

The final step in Unity is to click the Pack Palette button in the Asset Warehouse window. This will pack your palette and all of its crates into a mod ready to be used in Bone Lab. Copy the folder that appears once the pack process completes into your Bone Lab mods folder and start the game.

You can verify the game has recognized your mod from the main menu. Navigate to a Bone Lab level, bring up the in-game menu by holding Y or B, and select Avatars. If you do not see the Avatar option listed in the menu, you may need to progress your story. Navigate the Avatar menu until you see your custom avatar listed and select it. Congratulations! You've successfully imported a custom avatar into Bone Lab.

Keywords

Bone Lab
Unity
Marrow SDK
Custom Avatar
Mixamo
FBX file
Materials
Textures
Rigging
Prefab
Avatar Script
Eye Center Override
Modding
Asset Warehouse

FAQ

Q: What is the first step to creating a custom avatar mod in Bone Lab? A: The first step is to create a palette in the Asset Warehouse in Unity.

Q: How do I handle missing textures in my imported model? A: Select the "Use External Materials (Legacy)" option in the location field, which will automatically extract and apply the appropriate textures.

Q: What if my model does not have eye bones? A: You can handle this by adding an Eye Center Override and positioning it between the avatar’s eyes.

Q: My avatar script isn't recognizing the wrist bones. What should I do? A: Ensure you manually tweak the wrist bone fields as needed.

Q: How do I pack my completed avatar mod? A: Click the Pack Palette button in the Asset Warehouse window, then copy the generated folder to your Bone Lab mods folder.

Q: The Avatar option is not showing in my in-game menu. What do I do? A: You may need to progress in the game’s story before this option becomes available.