Custom Avatars Guide
Assistant's Guide to adding Full Body Avatars to Beat Saber.
If you're creating models, it's extremely important that you read the Shader Migration Guide to avoid any shader issues
This guide may have outdated fragments. If you run into issues don't be afraid to ask in the
#pc-3d-modeling channel in the BSMG Discord
Alright boys and girls, your favorite Assistant is going to teach you how to take your favorite anime models and put them into 3D Osu!
I will be assuming you have a basic grasp of blender and Unity and have made avatars for VRChat in the past. If not there's plenty of tutorials out there. This guide will start at the point when you're ready to export a fbx file to use on Unity. There is a video of me creating an avatar if you'd like something to follow along with. It is narrated by Megalon since a freak accident took away my ability to speak and edit videos. CC's coming soon™.
Shape Keys: Turning Bad Touch into Good Touch
So you don't want your waifu to hold the sabers through the sheer power of plot armor and sticky hands, but she doesn't have a fist shape key. To add one, we'll be using blender again, now I know I said we were ready to export, but I'm like 12 and have the attention span of
We'll be using the CATS blender plugin, If you don't have it installed, download it here.
Under the CATS menu.
Click Start Pose Mode.
With pose mode enabled, you'll be able to position the bones to your liking.
Right Click to select the bones, use
SHIFT to select multiple.
When you've gotten the desired look, click
Pose To Shape Key. This will create a shape key for closing a fist.
To finish up, hit
w and click Clear User Transforms (All), this will reset the hand's pose.
Then hit Stop Pose Mode.
To Unity and Beyond
Download and extract the
BeatSaberCustomAvatars-vx.x.x-UnityProject.zip from the Custom Avatars Release. This zip contains a barebones Unity project to get started with creating avatars. You will need to copy
DynamicBone.dll from the game's installation folder into the
Assets\Libraries folder of the extracted zip before opening the project in Unity to get it working.
Use Unity version 2019.3.15. And make sure to follow these instructions.
Import the fbx file with your waifu, and create an empty game object with her name, but don't drag her in yet.
Next step will be to click on the Avatar asset, and set its rig as humanoid, and then configure it. If you've worked with VRChat avatars before this should sound familiar, so I'll skip the configuration, which basically is just match the body parts and enforce T-Pose. After doing that you can drag your Avatar into the GameObject that you created before.
Create 4 Empty GameObjects in the root object, and name them
You want to position
Head where you want your camera to be, similar to VRChat's white dot.
RightHand, you want to position them on your Avatar's hands like if they were your controllers. The positive Y axis points up from the controller, so you want that to point towards your wrists.
Make sure you have your GameObjects where you want them, after the next step their position is final.
We're ready to start the fun! Navigate the hierarchy of the Armature until you reach the Head, select it and right-click and Create Empty, then drag it into the
Head we created and name it
HeadTarget. That process will make sure that it's in the correct place.
Do the same with your wrists, placing them into the
RightHand, and name them
RightHandTarget respectively. It should look something like this.
If you need to move
RightHand AFTER you've already placed the targets, you'll need to delete the targets and add them again after you're done moving them.
Select your Avatar, the one that is blue in my previous image, and add some components to it: First you'll need
VR IK and
IK Manager, or you can use
IK Manager Advanced if you want to change the IK settings. Add the 3 targets you just created to the
IK Manager of your choice.
You should have a fully functional avatar for Beat Saber, but don't hit that export button yet, we still need to give it the finishing touches. Once you're done testing out the Avatar in Play mode and IK is working, you'll have to set all your materials to use one of the included Beat Saber shaders, if you've atlased your materials, great, you get to skip the painstakingly arduous job of retexturing each one of them, because for some reason those shaders don't take the same texture parameter as most other shaders.
You might have noticed that your avatar crosses its legs like it needs to pee when it crouches down. You might have played around with the IK options and noticed that changing the
Swivel Offset on the legs fixes this in unity, but the changes don't appear in the game. Now you can fix that by using
IK Manager Advanced. Adding the swivel offsets to the
IK Manager Advanced component will make those settings work in the game. If you haven't played around with those before, they change the angle at which the knees bend. A positive value moves the knees to the right, and a negative value moves them to the left, from the avatar's perspective.
You can now go ahead and do cosmetic stuff to your avatar, add dynamic bones to your liking, but use the included scripts. You can also curl your waifu's fingers so she's actually holding the sabers, I used Shape Keys for that. Avatars are now visible in first person view. You can toggle it using the
Home key on your keyboard. If you want to be able to see your avatar in first person, but don't want to see the inside of your head, you can use the
First Person Exclusion component to exclude your head's mesh, note that it will have to be a separate mesh for this to work. If you have double vision of your avatar, like if you were cross eyed, you need to change a setting. Go to
Project Settings ->
Player. On the window that appears click on
XR Settings, Make sure that
Virtual Reality Supported is turned on, and that
Stereo Rendering Method is set to
Select the parent to your avatar, the upmost item in the hierarchy, and add 2 components to it,
Avatar Descriptor and
Event Manager. Fill out the Avatar Descriptor, and you can leave Event Manager empty, if you knew how to use it you would probably not be reading this.
To add a
Cover Image you'll need to add an image and set it as a
Sprite (2D and UI), you can then drag it into the
The last thing to do is export the avatar. Go to
Avatar Exporter, and you should see something like this. Just click on the Export button, and save it to the CustomAvatars folder, and you're golden.
If you're re-exporting an avatar make sure to delete the previous file, it will not overwrite it.
Once you've got your avatar exported, upload them to ModelSaber if you want to share it with the world.
Now go weeb out to the Nico Nico Nii remix as your waifu or something. Assistant out.
Animations: It's Alive
For the purpose of this guide an animation will be considered any behavior that is not directly caused by the IK scripts or the movements of the HMD and controllers. The most basic form of animations involve what you're probably familiar with,
Animation files, an
Animator Component, its corresponding
Animation Controller, and
Events. First we need to place an
Animator component, and we have to be very particular about how we do this. Just playing it on the avatar object will cause it to conflict with the IK scripts, so we have two options: We can set the animation layer in the
Animation Controller to
Additive Blending, which will allow us to place the
Animator Component on the avatar object.
The second way, and my prefered method, is to leave the layer as
Override Blending and place the
Animator Component on an object that isn't affected directly by the IK script, nor is a parent to any such object. This is an example of where you can safetly place the
Animator Component, and where you can't.
Once you have your
Animator Component and its respective
Animation Controller you'll need to add
Animation files to it, and make sure to create
Trigger Parameters, set transitions between states, and set the
Trigger Parameters to set off those transitions. For animations of set duration you can create a single
Trigger Parameters to start the animation, and leave the transition back empty, but for animations that you want to hold for an arbritrary amount of time you'll want to create a
Trigger Parameters to start the animation, another to end it, and set the animtion to looping.
Now that you have an animation layer with transitions and triggers, you'll need to set up events to fire them. First you'll want to create an
Event Manager component on the root object. This provides some events that you can use, and also allows other event scripts to work. The vanilla CustomAvatar.dll also comes with the
Combo Reached Event and
Every Nth Combo Filter.
Once you've selected which event you want to use for your animation, you need to select the Object that contains the
Animator Component, then select
Animator -> SetTrigger (string) as the function, and type the name of your
Trigger Parameter in the text field.
Once the event is setup, when it fires it will activate the trigger, which will activate the transition on your
Animation Controller. If you want to setup controller events similar to VRChat gestures, you'll want to set a trigger to activate your transition on a press event, and another for the deactivation transition on a release event.
We've seen how to use events to make animations happen, but there's a lot more that you can do with them. First lets look at what an event looks like. There's 4 parts to an event that you have to worry about. First, what triggers the event. It can be any of the things in the
Event Manager component, or the combo components, or even from a third party plugin, like
CustomKeyEvents. Second, you need to drag a game object into the field that says
None (Object), whatever object you pick will be the one affected by the trigger. Third, you have to select which function from that game object you want to use. Click on the field that says
No Function and pick the function you want the event to use. Here you will see all the public methods with at most 1 argument that are available to the object or its components. Finally, under the function you just picked you will be able to set the argument to that function, if any.
We saw how to do this with the animator component on the previous section, but you can use this for many other things besides triggering events. You can make it play audio clips using the
PlayOneShot function from an
Audio Source component. You can start particle systems, or make them emit a certain number of particles. You can turn objects on and off. You can edit materials. There's endless posibilities, so go drag some objects in and see what you can get out of them.
This plugin allows you to set event triggers to controller actions. You will need
CustomKeyEvents.dll (Unity Asset) in your Unity project in order to add those to your avatar. The user will also need
CustomKeyEvents.dll in their
Plugins folder for them to work in game.
Full Body Tracking: Ra Ra Rasputin~
If you want to create an avatar with
Full Body Tracking support you'll have to add 3 more Objects, one for each of the
Vive Trackers in your feet and hip. Place those Objects in the same level you placed the ones for the hands, and name them
These Objects work exactly the same way as the hand objects, you want to position them on the Avatar like they're positioned physically on your body. Make sure to pay attention to the orientation of the tracker.
Now that they're in the correct place, you'll want to create the targets by navigating the Armature to the feet and pelvis bones, the ones the IK calls
Right Foot, and
Pelvis. Right click on those bones and select
Create Empty. An Object called
GameObject will appear as a child to the bones, you want to rename them into
PelvisTarget and drag them into
Once complete your hierarchy should look something like this:
Now that all your Objects and Targets are ready, you'll have to add them to the
IK Manager Advanced script. You also want to set the values of both leg's and pelvis'
Position Weight and
Rotation Weight closer to
1, but feel free to experiment with the values.
So, you're probably wonder why now I'm telling you to use Unity 2019.3.15f1, when previously we said you shouldn't use any 2019 version. Well, the game has changed, figuratively, and literally. Beat Saber now uses Unity 2019 and as such the avatars need to be created with Unity 2019 to work correctly. You may need to set the
Scripting Runtime Version to
.NET 4.x Equivalent if it isn't already. For that you need to go to
Edit -> Project Settings -> Player and in the window that appears open the
Other Settings tab, and scroll down to the
You're going to need to use the new version of
CustomAvatar.dll in your Unity project. Delete the old one if you have it; this project contains the correct one—and replace it with this one. Preferably in the assets folder while Unity isn't running. You might have to re-add your components. If the asset doesn't have the arrow that lets you see all the scripts, right click it and select
PureDark's avatar plugin?
PureDark's plugin has been integrated into the main plugin. A few things have changed.
Make Children Visible is no longer needed, first person view is enabled by default, and is toggleable with the
Home key on your keyboard. To add exclusions to the first person view, you can use the
First Person Exclusion component.
Avatar VRIK Fix is now called
IK Manager Advanced, and since it's all in one plugin it's no longer needed to provide cross compatiblity, so only one of either
IK Manager or
IK Manager Advanced is needed. The controller events components were removed, and will appear on their own plugin.
I can't find the IK scripts or the Avatar exporter
Make sure you're using Unity 2018.1.6f1, not 5.6.3p1, not 2017, and you've followed these directions. If your CustomAvatar.dll asset doesn't have the arrow that you click to show the scripts, try deleting and re-importing the CustomAvatar.dll Asset to Unity.
I can export avatars but they're invisible in game. ↵
You can toggle first person view by pressing
Home. If they're invisible in your desktop window, make sure that you used the correct Beat Saber shaders, and Unity 2018.1.6f1.
Only my avatars are T-Posed
Well I'm very sorry, but this means that you did something wrong while creating your avatar. There's no way to know just what you did wrong, because so many things have the same effect. The only advice we can give you is make sure that you followed the guides exactly, and maybe watch a video to follow along.
Here is a video of me making an avatar, narrated by Megalon. [5:57]
https://www.youtube.com/watch?v=iBEfl_v71Nw is not a valid YouTube URL!
I know nothing about making avatars or using either Unity or Blender, I just threw shit at the wall blindly for 3 days and this is what stuck. But until someone who actually knows what they're doing makes a guide, this is all there is.
♥ Special Thanks
- ikeiwa, for creating this fantastic plugin.
- xyonico, for rewriting this fantastic plugin.
- PureDark, for making the fantastic plugin that fixes many issues.
- Emma, for making the first guide that led me to figuring this out, and helping with this one.
- Megalon, for providing the ASMR for the video.
- Ella, for making fun of me until I got gud, helping with the website design, parts of this guide, and putting up with all my dumb questions.