Skip to content

Commit 57a61fa

Browse files
hactaziahactazia
committed
feat: Add comprehensive documentation for BasisVR
- Introduced new sections for uploading avatars, contributing guidelines, frequently asked questions, and project management. - Added detailed instructions for server deployment, configuration, monitoring, and advanced settings. - Included guidelines for building and testing custom worlds in Unity, along with setup instructions. - Enhanced technical documentation covering Linux builds and Unity CPU usage limitations. - Updated meta information for better navigation and organization of documentation.
1 parent c670c35 commit 57a61fa

42 files changed

Lines changed: 1437 additions & 410 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎content/docs/avatar/advanced.mdx‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
title: Advanced Features
3+
---
4+
5+
## Jiggles (Optional)
6+
7+
**To add Jiggle Physics:**
8+
9+
For each jiggle root:
10+
- Add a new component `Jiggle Rig`, which can be placed in a separate gameObject, but it must under the hierarchy of your Avatar root.
11+
- In the Jiggle Rig component, ensure to set a `Root Transform`, which is a bone in the avatar armature.
12+
- If you have a parent bone (for multiple chains of child bones that you wish to apply the same effect to) you can enable `Motionless Root` to only affect the child bones and not the root itself. (Optional)
13+
- Adjust `Settings` to your liking (activate `Advanced` to view all settings).
14+
15+
**Collision Interaction:**
16+
- Activate `Advanced` to view all settings.
17+
- Enable `Collision` and adjust `Collision Radius` to fit the object.
18+
19+
## Eye & Face Tracking (optional)
20+
21+
- Hai has created a comprehensive guide on how to add the Automatic Face Tracking component to an avatar in a Basis project
22+
- You can follow the link [here](https://docs.hai-vr.dev/docs/basis/avatar-customization/face-trackingsection) for instruction on how this works.

‎content/docs/avatar/building.mdx‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: Building
3+
---
4+
5+
import { Callout } from 'fumadocs-ui/components/callout';
6+
7+
## Avoid Duplicate GameObjects
8+
9+
- 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.
10+
11+
## Build the AssetBundle
12+
13+
- At the bottom of the Basis Avatar component on your Avatar, check that the appropriate build targets for your content are enabled (Windows, Linux, Android etc)
14+
- Press the 'Create Avatar Bee File' button and wait for this process to complete.
15+
16+
![Create Avatar Bee File](/img/avatars/7.png)
17+
18+
- The results will be opened in a new window automatically as shown below.
19+
20+
![Build results](/img/avatars/8.png)
21+
22+
<Callout type="info">
23+
Basis uses the .BEE file extension, which contains your compiled asset and meta data, in order to simplify user generated content.
24+
25+
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.
26+
</Callout>
27+
28+
## Locally Test the Avatar
29+
30+
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).
31+
32+
{/* - Once the .BEE file has been created, you can load this via the `BootManager` prefab found at `Packages > Basis SDK > Prefabs > Boot`.
33+
34+
![BootManager](/img/avatars/9.png)
35+
36+
- You can place the location of the .BEE file under the `Combinned URL` fields as shown in the example below, along with the `Unlock Password` provided in the `dontuploadmepassword.txt` file generated within the `/AssetBundles/` directory.
37+
- Make sure to tick `Is Local` if the file is not a URL.
38+
39+
![Local testing setup](/img/avatars/10.png)
40+
41+
- Load the `Initialization` scene from `Packages > Basis SDK > Scenes`, and then hit Play. */}

‎content/docs/avatar/face-tracking.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: Face Tracking
3+
---
4+
5+
- Hai has created a comprehensive guide on how to add the Automatic Face Tracking component to an avatar in a Basis project
6+
- You can follow the link [here](https://docs.hai-vr.dev/docs/basis/avatar-customization/face-trackingsection) for instruction on how this works.

‎content/docs/avatar/index.mdx‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
title: Introduction
3+
---
4+
5+
import { Card, Cards } from 'fumadocs-ui/components/card';
6+
7+
## Overview
8+
9+
Avatars are the heart of your social VR experience in Basis. This documentation will guide you through creating, building, uploading, and customizing your own avatars using Unity and the Basis SDK.
10+
11+
Basis uses the `.BEE` file format for avatars, which packages your compiled assets and metadata into a single, easy-to-share file. Avatars support humanoid rigs, blend shapes, materials, jiggle physics, and face tracking.
12+
13+
## Quick Start Guide
14+
15+
<Cards>
16+
<Card
17+
title="Setup"
18+
description="Set up Unity and prepare your avatar model"
19+
href="/docs/avatar/setup"
20+
/>
21+
<Card
22+
title="Building"
23+
description="Build your avatar into a .BEE file"
24+
href="/docs/avatar/building"
25+
/>
26+
<Card
27+
title="Uploading"
28+
description="Upload and load your avatar in Basis"
29+
href="/docs/avatar/uploading"
30+
/>
31+
<Card
32+
title="Jiggle Physics"
33+
description="Add dynamic physics to your avatar"
34+
href="/docs/avatar/jiggle"
35+
/>
36+
<Card
37+
title="Face Tracking"
38+
description="Add eye and face tracking support"
39+
href="/docs/avatar/face-tracking"
40+
/>
41+
<Card
42+
title="Shaders"
43+
description="Compatible URP shaders for avatars"
44+
href="/docs/avatar/shaders"
45+
/>
46+
</Cards>
47+
48+
## Key Features
49+
50+
- **Humanoid Rig Support**: Standard Unity humanoid rigs with automatic bone mapping
51+
- **Blend Shapes**: Full support for facial expressions and visemes
52+
- **Multi-Platform**: Build for Windows, Linux, and Android
53+
- **Jiggle Physics**: Optional physics simulation for dynamic elements
54+
- **Face Tracking**: Optional eye and face tracking support
55+
- **URP Shaders**: Compatible with Unity's Universal Render Pipeline
56+
57+
## Requirements
58+
59+
- **Unity**: Unity 6 (latest supported version)
60+
- **Model Format**: FBX with humanoid rig
61+
- **Shader**: URP-compatible shaders (Lit, Poiyomi, lilToon, etc.)
62+
- **Hosting**: Remote URL hosting for .BEE files (max 100MB for Google Drive)
63+
64+
## Workflow Overview
65+
66+
1. **Import** your avatar model into Unity
67+
2. **Configure** the rig and skinned meshes
68+
3. **Add** the Basis Avatar component
69+
4. **Build** the .BEE file for your target platforms
70+
5. **Upload** to a hosting service
71+
6. **Load** in Basis using the URL and password

‎content/docs/avatar/jiggle.mdx‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: Jiggle Physics
3+
description: Jiggle Physics allows you to add dynamic movement to parts of your avatar, such as hair, clothing, or accessories, enhancing realism and immersion.
4+
---
5+
6+
## To add Jiggle Physics
7+
8+
For each jiggle root:
9+
- Add a new component `Jiggle Rig`, which can be placed in a separate gameObject, but it must under the hierarchy of your Avatar root.
10+
- In the Jiggle Rig component, ensure to set a `Root Transform`, which is a bone in the avatar armature.
11+
- If you have a parent bone (for multiple chains of child bones that you wish to apply the same effect to) you can enable `Motionless Root` to only affect the child bones and not the root itself. (Optional)
12+
- Adjust `Settings` to your liking (activate `Advanced` to view all settings).
13+
14+
## Collision Interaction
15+
16+
- Activate `Advanced` to view all settings.
17+
- Enable `Collision` and adjust `Collision Radius` to fit the object.

‎content/docs/avatar/meta.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"title": "Avatar",
3+
"icon": "User",
4+
"pages": ["index", "setup", "building", "uploading", "jiggle", "face-tracking", "shaders"]
5+
}

‎content/docs/avatar/setup.mdx‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
title: Setup
3+
---
4+
5+
import { Callout } from 'fumadocs-ui/components/callout';
6+
7+
## Set up the Unity Editor
8+
9+
- As per the [Getting Started](/docs/getting-started#installing-unity) section for installing the latest supported Unity editor version and acquiring the Basis framework.
10+
- Open Unity Hub and add an existing project, choose the extracted/cloned Basis project folder
11+
- On the initial project load you will see the following prompt, please hit 'Restart Editor'.
12+
13+
![Unity restart prompt](/img/avatars/0.png)
14+
15+
- Once the project has loaded, you can now load in your Avatar files:
16+
- Either,
17+
- Find `Assets` in the Project hierarchy, inside `Assets` right-click any empty space and select `Show in Explorer`
18+
- Copy in your Avatar files [Mesh/Materials/Textures, etc.]
19+
- or
20+
- Import a .unity package containing your files, from the Assets menu, Import Package > Custom Package
21+
- Bring back the Unity window and allow the import process to finish.
22+
23+
<Callout type="info">
24+
If you place your content within a new directory "Assets > _UserContent" the default .gitignore file with the project will hide changes in git on this folder.
25+
</Callout>
26+
27+
## Import Model
28+
29+
- Find the location of your Avatar model (usually provided in .FBX format).
30+
- Click the file and then navigate to the `Model` section of the Import Settings window.
31+
- Ensure that `Red/Write` and `Legacy Blend Shape Normals` are selected as below.
32+
33+
![Model import settings](/img/avatars/1.png)
34+
35+
- Navigate to the `Rig` section of the Import Settings window.
36+
- Click the `Animation Type` drop-down menu and select `Humanoid`, press `Apply` as shown below.
37+
38+
![Rig settings](/img/avatars/2.png)
39+
40+
- Afterward, the `Configure` button above `Apply` is now selectable, click this and then check your bone mappings.
41+
42+
![Bone mappings](/img/avatars/3.png)
43+
44+
- This should show all mandatory bones as selected; make sure this looks correct for your Armature.
45+
- Lastly, click on the `Head` button in the `Mapping` window and remove the assignment for the `Jaw`; this is usually incorrect.
46+
47+
![Head mapping](/img/avatars/4.png)
48+
49+
## Skinned Mesh Setup
50+
51+
- There are currently no requirements to name your Avatar's Skinned Mesh as `Body` or other variation used on Virtual Platforms.
52+
- If you have multiple skinned meshes, consider pinning them to all use the same reference point on the body, for inheriting light probes in the scene. You can do this by assigning a bone from the Armature (Usually Hips) to the `Anchor Override` field.
53+
54+
![Anchor override](/img/avatars/5.png)
55+
56+
- Another consideration for Avatars with multiple Skinned Meshes is when different bounding box sizes cause individual meshes to pop in and out while the rest of the Avatar is visible to remote viewers.
57+
- You can override the Center X, Y, Z & Extent X, Y, Z values in the section named `Bounds` at the top of the Skinned Mesh Renderer component. Usually, it is a good idea to set this the same across the separate Skinned Meshes.
58+
59+
![Bounds settings](/img/avatars/6.png)
60+
61+
## Materials/Shaders
62+
63+
- You can jump straight in with the Universal Render Pipeline/Lit shader that comes with Unity 6
64+
- Otherwise, we have compiled a list of compatible [Avatar Shaders](/docs/avatar/shaders) that you can use.
65+
66+
## Basis Avatar Setup
67+
68+
- The steps above should automatically add an Animator component to your Avatar prefab when you pull it into the Scene.
69+
- On the Parent GameObject of the Avatar, click `Add Component`, and add `Basis Avatar`.
70+
71+
If you're struggling to find the view ball or indicator for the Eye Position, follow these steps:
72+
73+
- Top Right next to XYZ, click the Eye.
74+
- Enable "Eye Position Gizmo" inside of the `Basis Avatar` component.
75+
76+
You should now see a green Gizmo for your eyes; move this up between your eyes and on the same plane as your eyes.
77+
78+
**Ensure you have assigned each of the following:**
79+
- Animator
80+
- Face Viseme
81+
- Face Blink
82+
- Avatar Name
83+
- Avatar Description

‎content/docs/avatar/shaders.mdx‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: Avatar Shaders
3+
---
4+
5+
import { Callout } from 'fumadocs-ui/components/callout';
6+
7+
## URP Compatible Avatar Shaders
8+
9+
### Universal Render Pipeline/Lit (Unity License)
10+
11+
- https://docs.unity3d.com/Manual/urp/lit-shader.html
12+
13+
![URP Lit Shader](https://cdn.sanity.io/images/fuvbjjlp/production/ed8ae4aba799bd64a04b6dee9e9f4eaee5735bc6-415x100.png)
14+
15+
### Poiyomi [Free Version](MIT License) by Poiyomi
16+
17+
- https://discord.gg/poiyomi #urp-release
18+
19+
![Poiyomi Shader](https://s2.booth.pm/430bb41d-8aaa-46f4-ae48-63cff7c3ff3e/132c3ac8-cc2f-4858-9a92-2844c7f5cc05.png)
20+
21+
### lilToon (MIT License) by lilxzw
22+
23+
- https://github.com/lilxyzw/lilToon
24+
25+
![lilToon Shader](https://booth.pximg.net/d39ea11b-78fc-488b-90dd-457109c7cd9b/i/3087170/235a98b9-7d60-49c5-980d-8028f6d0c6ad_base_resized.jpg)
26+
27+
### MToon (MIT License) by UniVRM
28+
29+
- https://github.com/vrm-c/UniVRM
30+
31+
![MToon Shader](https://vrm.dev/en/images/vrm/card.png)
32+
33+
### Sakura Shader (Subscription) by Hyeve
34+
35+
- https://ko-fi.com/sakurashaders
36+
37+
![Sakura Shader](https://cdn.bsky.app/img/feed_fullsize/plain/did:plc:fxu7cua6kvrl7fz5fxso4cru/bafkreiad5qzfahj4yfrmljs7fgiztmjqsu4plfaenpeuaaxnga5ugfqkkm@jpeg)
38+
39+
<Callout type="info">
40+
These are known to be working/compatible at the time of the latest documentation update.
41+
</Callout>

‎content/docs/avatar/uploading.mdx‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: Uploading
3+
---
4+
5+
import { Callout } from 'fumadocs-ui/components/callout';
6+
7+
## Uploading Your Avatar
8+
9+
Basis allows you to load an Avatar .BEE file from a remote URL location, which is also required for other users in a networked session to also load the assets.
10+
11+
In order to support this, you will need to direct link to a remote location. For this example, we will use Google Drive.
12+
13+
(Google Drive supports the direct link of files up to 100MB due to their Virus Scanning policy.)
14+
15+
Upload the **BEE file** to Google Drive, or any hosting provider that allows direct links to files without login.
16+
17+
- Create a Folder on your Drive and set its sharing settings to "Anyone with the link."
18+
19+
Now when you drag your files into this Folder, you will not individually need to set that permission.
20+
21+
- Click the Hamburger Menu on the Top Right of the asset you have just uploaded into the folder.
22+
- Find "Share" and click "Copy Link."
23+
24+
We will need to look into the URL to grab the information we need for your BEE file.
25+
26+
Example:
27+
```
28+
https://drive.google.com/file/d/YourIDBringsAllTheLagToMyYard/view?usp=sharing
29+
```
30+
31+
We want to copy the unique identifier inside of the URL and add it to the following:
32+
```
33+
https://drive.google.com/uc?export=download&id=
34+
```
35+
36+
Example:
37+
```
38+
https://drive.google.com/uc?export=download&id=YourIDBringsAllTheLagToMyYard
39+
```
40+
41+
<Callout type="warn">
42+
**DO NOT UPLOAD YOUR GENERATED PASSWORD FILE OR SHARE IT**
43+
</Callout>
44+
45+
## Loading in Basis
46+
47+
Load up Basis, open the menu, and select Avatars.
48+
49+
![Basis menu](/img/avatars/11.png)
50+
51+
In the Avatar menu, select 'Add Avatar' in the top left.
52+
53+
![Add Avatar button](/img/avatars/12.png)
54+
55+
Paste the **BEE File URL** into the field in the next window.
56+
57+
![BEE File URL field](/img/avatars/13.png)
58+
59+
Paste your **SUPER SECRET ENCRYPTED PASSWORD** into the Password field.
60+
61+
![Password field](/img/avatars/14.png)
62+
63+
Load!
64+
🥱
65+
66+
## Remove Avatars
67+
68+
Basis will save the details of Avatars added through the game menu for convenience. Avatars can be removed by clicking on the Avatar in the menu and hitting the Red Delete Avatar button *(Currently no confirmation dialog is shown.)*
69+
70+
![Delete Avatar button](/img/avatars/15.png)
71+
72+
To remove all saved avatar information, outside of the game interface, you can also do the following:
73+
74+
- Delete `%appdata%\..\LocalLow\Basis Unity\Basis Unity\VerySafePasswordStore.json`.
75+
76+
When you next reload the game the previously stored Avatars will now be gone.

0 commit comments

Comments
 (0)