Saturday, 15 March 2014

VRChat: Now with Custom Avatars


VRChat has moved from this custom avatar solution to using an SDK that has custom rooms, avatars, animations and even interactive elements.  I'll leave this article here for now, but the links are obsolete. You can download the full SDK from and the updated directions are included.



Howdy All

VrChat is a great VR application (  Many enthusiasts and developers meet up in there after Cymatic Bruce's Sunday afternoon stream.  This last week I've had the priviledge of working with it's creator Graham Gaylor on a new feature.  It's one of the corner stones of virtual reality and any cyberpunk offshoot... Customization.

I don't want any limit on who or what I can be in virtual reality.  I like skiing (check out and so I want to look like a down hill skier. Maybe I'd even put my game's logo on my back.  I've used a bunch of character creation schemes in the past but none have the level of customization I want.  Sure, City of Heroes came close but it still had limitations imposed by the developers on what I could look like.

You might say "that sounds good Jesse, but short of a full model importer that's as good as you're going to get!", to which I would reply "Challenge Accepted!".

You now have the ability to use any existing model you like as your avatar in VRChat.

For the first version of this tool you need to have Unity Pro, or a friend with Unity Pro. Hopefully there will be enough interest to expand this feature to other formats in the future.  You'll also need somewhere to host your file so it can be downloaded by the other people who connect to VRChat who can see you.  This should be any normal web hosting environment.

Here's how you make it work...

Reminder, this document is obsolete, download the SDK from and follow the included directions.

Building your Custom Model Package
  1. Load your model into the latest version of unity.  Make sure the import scale and settings are such that the model is the correct height in meters.  It should be about 1.5 to 2 game units tall.  1.5m is pretty short and 2.0m is pretty tall.  For most models your import scale will be 0.01.

  2. In your model import settings, set the rig type to "humanoid".
  3. Instantiate your model into your scene.
  4. Add the VRC_AvatarDescriptor object from the SDK by dragging it onto your player.
  5. Change the view position field until the little sphere is hovering about 15cm in front of your model's eyes.
  6. ===================================================================
    Reminder, this document is obsolete, download the SDK from and follow the included directions.

  7. Now for the technical part, setting up the AvatarDescriptor object.
    1. Add three bones from your player's spine to spine 1, 2 and 3 in order from bottom to top to the Avatar Descriptor (see pic). 
    2. Also add the character's neck.
    3. And the left and right arm.  The arms should be the bones that have a pivot at the character's shoulder.  
    4. Fill in a name for your character and leave the URL blank and you're done.  Here's what the Avatar Descriptor should look like.
  8. Create a blank prefab to hold your model, name it as you wish and drag your model (and the attached script) onto it, creating a prefab of the whole package.
  9. Select the prefab in your asset hierarchy. Select the menu item "Assets/Build AssetBundle from Selection" and save the *.unity3d file onto your computer.

Using your Custom Model

  1. ===================================================================
    Reminder, this document is obsolete, download the SDK from and follow the included directions.
  2. Upload your model to a web site that's visible from the internet. 
  3. Launch VRChat.
  4. bring up the console (` key) and type "/setavatar http://<url>/<package name>.unity3d"
  5. After a little download time you should be wearing your new avatar.
  6. You may share the URL of your avatar if you'd like to make it available to other people to use.

  • ===================================================================
    Reminder, this document is obsolete, download the SDK from and follow the included directions.
  • Can you please host my model?
    • Probably not. That would likely open us up to legal responsibilities associated with distributing this material.
  • Why Unity Pro?
    • Unity pro is required to build the asset bundles that models are distributed in.
  • Can't you just import my model at run-time?
    • Hopefully soon, but not yet, no.
  • I can see my model on my body, but it's not animating.
    • You probably forgot to set the avatar type to humanoid, or perhaps you're not using the latest version of unity.
  • I'm in the chat room but my body is invisible to other people
    • The other people in the chat may be still downloading your avatar file, or perhaps they are having problems with the link.
  • My model is live and the url is correct but no-one can download it in the app.
    • Make sure you have a valid crossdomain.xml file.
  • Can I make my avatar a naked man or woman?
    • Yes, but please don't. Virtual Reality is in it's early stages and we need to be accepting and tolerant of cultures, genders, sexes, races and orientations.  We're trying to grow a community and everything we do that reduces the speed of that growth will hurt us all. 
  • All those directions look difficult. I only understood half of it. I really want to have a custom avatar though.
    • Find someone with Unity Pro, give them a link to these instructions, your model and $10.
  • Can I host my character on dropbox or google drive?
    • I haven't tested it, but I'm pretty sure the answer is no.
  • Where can I find a model to use if I'm not an artist
    • Try or There's a wide selection there.  But let's keep it PG people.  Also some hobbyist models are just technically bad.  Try them out in the default world before you commit to using it in a chat.
  • Isn't the barrier to entry kinda high?
    • Yes, for now.  Hopefully we'll be able to relax some of these restrictions in the near future.


  1. Great FAQ!

    Thanks again Jesse for the help trying to figure out my Avatar issues. =)

    Until he posts it, for anyone making avatars, a extra requirement is now known that you need to compile your avatar bundle in the same Unity as VRChat is built for maximum compatibility. (Currently 4.3).

    I compiled mine in 4.2 at first, and they weren't animating were otherwise working. So it gives hope that you won't need to recompile your avatar very often.

  2. Thanks DarkAkuma for helping us diagnose this issue. I've added a couple notes in the description and FAQ, but let's leave this comment here as an extra warning.

  3. My model looks crippled in VRchat XD

    In Unity I see a bunch of warnings: MuscleClip 'WormSlayerAvatar_01' conversion warning: Bone length is different in avatar and animation


    1. Is your avatar still contorted after closing and reopening VRChat.exe? I see that with my models, along with that same error. But reloading VRChat usually does the trick to get the model looking correct.

  4. So for us non-Developer types, I figured this might be a decent enough intro to maybe figure at least a little something out about managing model packages, but the instructions here seem to still be a bit more geared towards actual developers. I'm having a trouble reconciling the directions and screenshots with what I'm actually seeing on my screen in Unity Pro 4.3.

    For example, the first step talks about model hight and import scale. I didn't actually see a place to set the scale on the import or what the height is. Although I also figure it's not that importante because I can clearly see the "Scale Factor" setting and I figure I can just change that after seeing the madel in VRChat to see if it's just the wrong size.

    Setting the rig typye to Humanoid is clear, butwhat does it mean to "instantiate" your model into the scene? Is that just dragging the model name so it's under/subordinate to "Main Camera"?

    What about the AvatarDescriptor.cs file. Does it matter where I drag it to?

    Adding bones to the descriptor? What has to be selected from which window(s) and then what do I click to add those "bones" entries?

    Stuff like that. I understand if you guys don't really want to walk some n00b through this stuff, but I'm completely lost on it and if someone really wants to do this step by step I'd really appreciate the help.

    1. Import scale can be adjusted by selecting the models file icon under the Project panel, and clicking the Model tab in the Inspector panel. Top option.

      Instantiate means "Spawn in", or in this case just putting the model int the scene by selecting it in the Project panel and dragging it into the Hierarchy panel.

      It doesn't matter what order the AvatarDescriptor.cs is in on the game object. But it need to be dragged onto the avatars model in the Hierarchy panel. You will see it in the Inspector when you do so.

      Once the model is in the Hierarchy panel, you can expand it's game object listing and locate the bones. You highlight and drag the bones game object from there into the avatar descriptors fields.

    2. Thanks DA for filling in some of the blanks for Lenny.

      Yes Lenny, the process is difficult for non-developers. I hope we can have a simplified pipeline for people without a unity background at some point. Would it help if there was a youtube video that showed someone going through the process?

    3. Yeah, it probably would help some. I'm noticing some differences in how I'm trying to do it and I think I'm stuck right now on the step for changing the view position field and the bones. I've been trying to put together something a little more step-by-step with screen shots as well to see if that might help others, but I'm still a bit lost at the moment.

      I notice, for example, in your screen shots that in the upper left, right under the menus, you have selected an eye on the toolbar with 4 things (eye, cross, rotation and kind of like an expansion icon) but on mine I have a hand there. I'm wondering if I've missed a step that would change that, if it's even needed for me to do so.

    4. Here's what I have so far if it helps to show what I might be doing wrong. The layout is a little different from yours, jut because mine is still completely in the default layout on initial install.

    5. Those 4 icons are just for toggling between the non-precision 3D manipulators. You shouldn't have to worry about them at all in this process.

      FYI Zarlor, When I said I'd help you, at the time I didn't know you had no experience with game development. I'd still offer help, but I would have been a little clearer that this process is not non-dev friendly. It's questionable if it's even dev friendly. =p

      Worth mentioning. I'm assuming you grabbed a pre-made model from the internet, correct? If so, it may not even have bones. A clear indication is when its referred to as un-rigged/un-skinned. I mention it because recently someone sent me a couple models for me to help them with, and both were lacking bones. Rigging/skinning requires another program like Blender, and if the model doesn't have them I don't recommend trying to do it yourself without experience with such programs.

    6. I gotcha. Yeah I do believe the one I was working with doesn't have bones. I'll play around a bit more and if I can figure it out I'll try to put together something a bit more step-by-step for other folks. I may not be a dev, but I am a Sys. Admin so troubleshooting and figuring things out is kind of part of my nature. ;)

    7. Ok, I think I've figured out some of the basics, at least. Here's a new document with screen shots to maybe help some other folks out in doing this with ready-made models:

      However, the models I was playing with didn't seem to come with their textures on them. They were in the archive they were packed with, but not layered onto the model, so the next step is figuring out how to make something other than a white statue version to use.

    8. Lenny, thanks so much for helping to work out some of these issues.
      Textures are pretty easy. The model should have created materials when it was imported. They should be in a subdirectory off the folder you dropped your model onto. If you drop you textures into the same location they'll import. Then you can try right clicking on your model and "reimport"ing. If that doesn't work select each of the materials that were created during the model import and drag the appropriate texture onto the texture box in it. You might have to try the textures on different materials and look at the results to see if you have them right.

      When we build a video walk-through for this (and other similar unannounced features) I'd like to send it to you first to see if I've done a good job. Does that work for you?

    9. Sure, I'd be happy to help. The model I was working with did have a bunch of .tga files for body, head and so on, with obvious textures in the same folder as the asset, but it didn't seem to apply them. And if I tried to apply them to that location they do load, but not correctly. They're just all skewed wrong. I'll have to play it with some more though.

    10. The trick I do to make sure models import with textures already applied is first import the textures, then import the model itself. I guess Unity just queues things in a unlucky order often when batch importing, and imports the model first before the textures.

      I've never had much luck trying other methods like the re-import option.

      From your document, the "little ball" might be inside your model. Increasing the Z value of the View Position 0.1-0.3 might help.

      That ball, once visible, can be a good guide for proper scaling. The default Y value Jessy set for it can be considered normal adult male eye height. So before adjusting the View Position to suit your model, you can adjust the scale of the model to suit it somewhat close first. If I remember right though, the little ball can only be seen when you have the parent game object (with the avatar descriptor) selected.

      When you configure the model in the mapping tab, before applying and selecting done, I recommend clicking the Pose drop down and selecting Reset, then Enforce T-Pose. It can just help avoid some oddities in avatars.

      @Jessy - "and other similar unannounced features".

      If it's what I think it is, I can't wait. It dawned on me one day that it shouldn't be to hard, and I was going to offer suggestions. I think soon after I heard you or grahm let it slip. So I figured you were already well on it.

  5. This comment has been removed by the author.

  6. This comment has been removed by the author.