Skip around this guide based on your needs, although it is suggested to go through this as a set of steps.
Guide to the Guide
This section describes what the step entails, and what to do.
| WARNING: There are gotchas in this process Skipping these tags may result in something going wrong, possibly resulting in the avatar getting deleted or mangled. |
| NOTE: This guide is long Common approaches and issues are listed here, most of the guide is how to fix things that go wrong. If sections don't apply to you, skip them! |
| VERIFY: Do you have a working PC Small issues during this process get worse over time, these alert you to possible issues early on. |
| NOTE: The guide is ordered The guide is structured to be read throughout the importing process, if one step is before another the steps should likely be done in that same order. |
Preparing Models
Many file types are supported, with varying supported features.
| NOTE: Humanoid Rig Requirements for IK |
| WARNING: Model Scale Resonite uses meter scale, many avatars do not. The import process will scale the avatar to average human height with a multiplier. If that multiplier is >1000 or <0.0001 some creator steps may misbehave. During the export process from tools like Blender the model can be scaled. If you use the scale applied by Resonite during blender export the avatar will import at 1 scale and not have issues. This can make it difficult to change avatar meshes later on, if the model scale is inside this range no scaling is required. a CHECK tag in this guide marks when to verify the model scale. |
.GLB/.GLTF - Recommended
.FBX - Good
| WARNING: Transform Slots Some FBX files import with additional bones, this can cause many parts of an avatar to break. A CHECK tag in this guide marks when this can be detected. If the model has these bones, the following features may not work properly:
|
| WARNING: Many variants of FBX exist Two FBX files of the same model may import wildly differently based on FBX versions and slight export option differences, FBX is not suggested for this reason. |
| NOTE: This format is common This is the commonly found format in Gumroad and other platforms. |
Preparing Textures
| NOTE: Animated Textures A Texture atlas is used for animated textures, see Panner2D. Also see AtlasInfo and AtlasAnimator. |
| NOTE: Resolutions In general 2k is a good size for the body of most textures. It is suggested to export the texture in the destination resolution, instead of resizing inside Resonite. |
.WEBP - Recommended
This loads faster and is smaller than PNG, while having the same color support.
| NOTE: Asset Conversions Modifying a texture (such as resizing or stripping the alpha channel) inside of Resonite will re-save the texture as WEBP. |
.PNG - Good
Commonly provided with avatars,
Find a World
Importing an avatar is a social event, bring friends, bring popcorn! See how it goes wrong and try out new things, who knew your hands could be scaled to 20x their normal size, and they still worked?! Have a drinking game for every time someone says "oops", have fun with this.
Cultural Considerations
Importing an avatar in a world is like building a Lego set in someone's living room, some people enjoy it and some people would rather you didn't. When in doubt ask if it's OK if you can import an avatar in the world.
| NOTE: No does not mean leave Hosts that ask you not to import an avatar are not asking you to leave (unless they say that as well), being denied can be emotionally a bit confusing but you are more than likely free to stay there, just not while importing an avatar. If you would still like to import an avatar ask where you can, they may know of other candidate sessions. |
Technical Considerations
Importing an avatar can require loading large numbers of possibly large assets directly into the world. Resonite pre-processes cloud saved assets, but it can't do that for imported ones without them being saved.
| WARNING: Imported assets are retransmitted by the host If you import a resource such as a mesh or model, that resource is streamed from your machine to the host, then out to the other users in the session. If the session isn't doing great, or the network of a user in the session is having trouble keeping up, importing assets and creating an avatar may accidentally force them out of the world. |
| NOTE: Cloud Assets Once resources are saved to the Resonite cloud they are downloaded directly from the Cloud, instead of from the host. Assets stored in the cloud are also pre-processed, making them smaller and more quickly loaded (each client independently does this pre-processing for imported assets). |
| NOTE: Asset Processing Assets stored in the cloud are also pre-processed, making them smaller and quicker to load, but when importing the assets directly, each client in the session independently does this pre-processing. |
Permissions
You will require builder permissions to import an avatar, this gives you the ability to modify anything in the world. Users may not be OK with you having that power.
Importing Models
Drag and drop the model from your desktop onto the Resonite window, or import the asset via the File Browser.
A dialog should appear, these options are important:
- 3D Model
- Regular / Avatar
- Auto Humanoid Height (See #Model Scale)
- Advanced Settings
- Scale - This is not the same as #Model Scale.
- Material and Prefer Specular - PBS with Prefer Specular is recommended, but XiexeToon is a close alternative. See #Texturing the Model and PBS_Metallic, PBS_Specular, and XiexeToon
- Spawn Material Orbs - This can make #Texturing the Model easier, as an inspector is not required to access the materials. But this is optional.
| WARNING: Do not grab the model after it is imported By default many avatars import in a T or A pose, and the symmetry of the avatar can make #Aligning Hands less error prone. If grabbed, select Undo in the Context menu. |
| CHECK: Model Scale Inspect the avatar with a developer tool and look at the scale applied to the root slot. This scale is what is referred to in #Model Scale. |
Avatar Creator
| WARNING: Ensure you are logged in A valid account is required to save the avatar to the Inventory, and SimpleAvatarProtection (Component) may soft lock avatars in some cases, see #Protecting an Avatar. |
| WARNING: You may be blinded when first getting into a newly created avatar. Geometry over the eyes can cover the viewport, blinding the user in the avatar. To get out of the avatar equip the previous avatar by clicking it and equipping through the context menu. Switching to desktop mode and using the third person camera is another workaround. Equipping a new avatar through the inventory will delete the currently equipped avatar, destroying your progress. See #Near Clip and #Adjusting Proxies to resolve the issue. If importing with another person, have the blinded user stay in the avatar as the other user follows #Near Clip and #Adjusting Proxies. |
An Avatar Creator is spawned from the home page of the Dash Menu.
Aligning Head
Place the headset representation over the head of the model and press Align Head Forward, Align Head Up, Align Head Right, Center Head Position, and Try Align Hands in sequence.
Aligning Hands
| NOTE: Align the head first The hands by default use the head as a line of symmetry, aligning the head first makes aligning the second hand unneeded as long as the model is still in a symmetric pose. See #symmetric pose warning. |
Adjust one of the hands to align the center and rotation of the hand with the model's hand. If the model is symmetric the other hand will also be aligned, if not uncheck Use Symmetry in the Avatar Creator and place the second hand.
Aligning Tool Anchors
Optionally check Show Tool Anchors in the Avatar Creator to customize the position of the avatar's Tool Anchors, Grab Spheres, and Tool Shelves.
If the tool anchors were adjusted, press Align Tool Anchors in the Avatar Creator before pressing Create
Additional Creator Options
In the Avatar Creator optionally check Setup Volume Meter and Setup Face Tracking (there is no reason not to).
| WARNING: Pressing Create When Protect Avatar is checked If Protect Avatar is checked, whoever clicks Create will have the avatar bound to them with SimpleAvatarProtection (Component). This may lock the avatar from being usable by anyone if the user that clicks Create is not registered as Logged In in the current session. |
| WARNING: Getting into the avatar may blind you Make sure to have a strategy for getting out of the avatar if you are blinded, see the #blinded warning. |
When ready, have the user who is to own the avatar press Create on the Avatar Creator.
Adjusting Proxies
Avatars created with the Avatar Creator have a common hierarchy. The Target slot under each proxy controls where the avatar's body part attempts to be, relative to a provided position input (such as a controller or the headset).
If the avatar head is obscuring part of the viewport: move the Target under Head Proxy backwards. This moves the head back, moving the problem geometry behind the cameras.
| WARNING: Adjusting the viewport back can stretch the spine As the head is balanced farther back, when looking down the spine will stretch up to compensate. This can pull the avatar's feet off the ground when looking down. |
Near Clip
Near and far clip can be configured via a AvatarRenderSettings (Component) being in an avatar when the avatar is equipped.
Add a slot with the AvatarRenderSettings (Component) to the avatar and set the NearClip field to 0.1, from there check if the view is clear, and slowly reduce the value until it just removes the problem geometry.
| WARNING: Near clip effects everything It is suggested to not use near clip whenever possible, as near clip doesn't render anything that distance in front of the camera, including props or some effects. When possible, it is suggested to move proxies first, and if needed use a very small near clip if still required. |
| NOTE: Check no clipping happens when moving Sometimes the avatar can lag slightly behind the player, ensure that when moving the problematic geometry is still not visible. |
Texturing the Model
Extract the material orbs from the avatar by inspecting the avatar with a developer tool and look just under the Armature slot of the avatar to find the renderers, those renderers reference materials
| NOTE: Extracting materials may not be needed If material orbs were spawned as part of #spawn material orbs, then the materials for the mesh are already provided. |
Import the materials by dragging the textures onto the Resonite window, or import them through the File Browser.
Using a material tool edit the material orbs spawned in with the imported avatars, or use the panels spawned in when viewing the materials in the inspector.
Drag and drop the textures into the corresponding slots of the materials.
| CHECK: The color of an imported model often defaults to gray When adding the texture, be sure to change the gray color to white to prevent the colors from looking washed out. |
Optional Steps
Dynamic Bones
Nameplates
By default, every user will have a nameplate and is colored according to what they do (Mentors, Moderation, and the Dev Team are a few examples of this). This however can be customized, and as long as your not impersonating someone from the aformentioned roles, you are fine.
Badges
By default, everyone has some badges depending on what a user does. Some are granted through the Resonite system, while most are custom and added through other means like Patreon or self added by the user themselves.
Badges can be easily added using community tools like this user badge manager.
There is also a tutorial on how to add a custom badge.