Documentation: Add extra clarifications about how to set up avatars (#73)

Author: Chylum

content/docs/avatar/building.mdx

@@ -4,16 +4,21 @@ title: Building
 
 import { Callout } from 'fumadocs-ui/components/callout';
 
+## The Basis Encrypted Extension (BEE) File
+
+Basis stores user-generated content as a .BEE file which contains your compiled asset and metadata about it. Each generated .BEE file comes with a randomly generated password used to access it, both of which can be found in the root directory of your Unity project at: `Basis\Basis\AssetBundles`.
+
 ## Avoid Duplicate GameObjects
 
-- Basis Avatar will by default rename all duplicate name GameObjects within the avatar's hierarchy. 
+- By default, the BasisAvatar component will rename all duplicate name GameObjects within the avatar's hierarchy.
+
 <Callout type="warning">
 If you enable `Do not auto-rename bones` in the Processing Options. Ensure that there are **NO** duplicate named GameObjects within the hierarchy of your avatar, including the armature, as this will cause your avatar to fail to load after building the AssetBundle.
 </Callout>
 
 ## Build the AssetBundle
 
-- At the bottom of the Basis Avatar component on your Avatar, check that the appropriate build targets for your content are enabled (Windows, Mac, Linux etc) (NOTE: If building for Basis Framework public testing please use all possible build targets)
+- At the bottom of the Basis Avatar component on your Avatar, check that the appropriate build targets for your content are enabled. Basis supports various target platforms, including: Windows, Android, Mac, Linux and IOS.
 - Press the 'Create Avatar Bee File' button and wait for this process to complete.
 
 ![Create Avatar Bee File](/img/avatars/7.png)
@@ -22,24 +27,22 @@ If you enable `Do not auto-rename bones` in the Processing Options. Ensure that
 
 ![Build results](/img/avatars/8.png)
 
+- Depending on your hardware, each platform may take an average of a minute or two to build the first time. Subsequent builds should take less time due to caching. Building for all platforms will likely take additional time and increase the overall file size.
+
 <Callout type="info">
-Basis uses the .BEE file extension, which contains your compiled asset and meta data, in order to simplify user generated content.
+Nice to know:
 
-The .BEE file, along with a randomly generated password to access it, is created under your Unity Project path /AssetBundles/ directory and is hidden from Unity by default.
+- You can conveniently use a custom password for your generated BEE file instead. This can make things easier to remember if you prefer a single password to use for different BEE files. 
 
-If you prefer, you can also replace the generated .BEE file name with something more easily memorable. Keep in mind that reusing the same name will result in any previous version being replaced by the new one!
-</Callout>
+- If you prefer, you can also replace the generated .BEE file name with something more easily memorable. Keep in mind that reusing the same name will result in any previous version being replaced by the new one!
 
-- Each platform takes on average 2 minutes from cold/no cache build. Building for all platforms will take some time. Likely more than 10 minutes for all platforms. Hot build/cached took little over 2 mins on same avatar and specs.
 
-<Callout type="info">
-An avatar with 18 materials using Poiyomi URP with 120K polygons, with package size 45MB per platform, took 9m 43s on a Ryzen 7 9800x3D. Jan, 2026
+![Create Avatar Bee File](/img/avatars/7a.png)
 </Callout>
 
-
-## Locally Test the Avatar
-
-Testing the .BEE file locally is not yet supported and will be implemented in the near future, please proceed to [Uploading Your Avatar](/docs/avatar/uploading).
+<Callout type="info">
+January 2026 Anecdote: An avatar with 18 materials using Poiyomi URP with 120K polygons, with package size 45MB per platform, took 9m 43s on a Ryzen 7 9800x3D to build for all target platforms.
+</Callout>
 
 {/* - Once the .BEE file has been created, you can load this via the `BootManager` prefab found at `Packages > Basis SDK > Prefabs > Boot`.
 

content/docs/avatar/setup.mdx

@@ -46,6 +46,15 @@ If you place your content within a new directory "Assets > _UserContent" the def
 
 ![Head mapping](/img/avatars/4.png)
 
+<Callout type="info">
+In some cases, the Unity inspector might mention that your avatar's bone mappings aren't properly assigned, or that the avatar isn't T-posed properly. To fix this, you can click on the Mapping and Pose dropdowns and select Automap or Enforce T-Pose.
+
+![Inspector window showing how to automap avatar rig](/img/avatars/4a.png)
+
+![Inspector window showing how to enforce t-pose](/img/avatars/4b.png)
+
+</Callout>
+
 ## Skinned Mesh Setup
 
 - There are currently no requirements to name your Avatar's Skinned Mesh as `Body` or other variation used on Virtual Platforms.
@@ -67,21 +76,25 @@ If you place your content within a new directory "Assets > _UserContent" the def
 
 - The steps above should automatically add an Animator component to your Avatar prefab when you pull it into the Scene.
 - On the Parent GameObject of the Avatar, click `Add Component`, and add `Basis Avatar`.
+- Enter your preferred Avatar Name and Description.
+- In `Assigned Input`, ensure an Animator is assigned. Usually, this will automatically be done for you. Additionally, assign the Skinned Mesh Renderers which contain the face and blink blendshapes for your avatar. You can also add an optional thumbnail icon for your avatar if you like.
+- In `Viseme Setup`, assign the relevant visemes and blinking for your avatars. You can also use the automatic detection buttons which will try to automatically do this for you.
+- Optionally, you can test your avatar in the editor by first entering play mode and then selecting the `Test in Editor` option.
+- Before selecting `Create Avatar Bee File`, ensure that all your shaders are compatible. The BEE file will not generate if there are incompatible shader errors on your avatar (this includes clothing and attachments). If there are any issues, the inspector will report about it so make sure to resolve them!
 
-If you're struggling to find the view ball or indicator for the Eye Position, follow these steps:
+![Inspector Window Basis Avatar Component Added with Fields Assigned](/img/avatars/6a.png)
+
+![Inspector Window showing example of avatar blendshape movements](/img/avatars/6b.png)
+
+<Callout type="info">
+In case you're new to Skinned Mesh Renderer blendshapes or uploading avatars in general, they're basically just sliders that you can control to change the morphs on your avatar.
+
+![Inspector Window showing example of avatar blendshape movements](/img/avatars/6c.gif)
+</Callout>
 
-- Top Right next to XYZ, click the Eye.
-- Enable "Eye Position Gizmo" inside of the `Basis Avatar` component.
 
-You should now see a green Gizmo for your eyes; move this up between your eyes and on the same plane as your eyes.
 
-**Ensure you have assigned each of the following:**
-- Animator
-- Face Viseme
-- Face Blink
-- Avatar Name
-- Avatar Description
 
 ## Constraints Setup
 
-Basis does not use the built-in Unity Constraints system, instead it uses Animation Rigging. You can find the setup guide [here](/docs/avatar/animation-rigging#setup-for-animation-rigging-packages).
+Basis does not use the built-in Unity Constraints system, instead it uses Animation Rigging. You can find the setup guide [here](/docs/avatar/animation-rigging#setup-for-animation-rigging-packages).