.. _Getting Started:

===============
Getting Started
===============

.. include:: /Refs.rst

In this page you will learn how to quickly add an avatar to a scene with minimal setup. 

Step 0 : Adding a VR Rig
_________________________

Before following this guide you will need to add a VR Rig in your scene. Your VR Rig must contain a **camera object** whose pose follows the hmd movements, 
and **two hand object** following the left and right controller's movements respectively.

Step 1 : Choose a type of avatar
________________________________

There are two types of avatar you can use:

- **Runtime avatars**, they are best suited for applications where the users will choose their avatars or where avatars may change.
- **Static avatars**, they are best suited for applications using a single pre-loaded avatar that will not change.

Step 2 - A : Adding a Runtime Avatar
____________________________________

A Runtime Avatar is an avatar where the model will be loaded during runtime.

To add a runtime avatar in a scene, right click on the Hierarchy view of the scene, and select AvatarReady -> Runtime Avatar.

|AvatarReady_RuntimeAvatarMenu|

This will add a **[Runtime Avatar]** GameObject to the scene. 

This GameObject will contain an :ref:`AvatarReadySetup` component, and an :ref:`AvatarRuntimeLink` component.
The **[Runtime Avatar]** has a child GameObject **CC_DummyAvatar**.

This **CC_DummyAvatar** GameObject has an :ref:`AvatarReadyComponent` component. 

How to setup the Avatar Ready component will be explain :ref:`in step 3 <ARQuick>`.

Loading an avatar at runtime:
-----------------------------

With On Screen UI
++++++++++++++++++

Avatar Ready includes an on screen UI to load avatars. To add the UI to your scene, right click on the Hierarchy view of the scene, and select AvatarReady > Runtime Import UI.

This UI will allow you to select an avatar from those available (remote or local) to load on an AvatarReady target.

|AvatarReady_AvatarRuntimeUI| 

At runtime, if there are runtime avatars in the scene, they will be displayed in the target field. Select the Avatar target you wish to load an avatar for.
You will then be able to select the avatar set to use (local or AvatarGallery), apply some filters, and select an avatar.

Select Avatar button will then apply that avatar. 

From a Script
+++++++++++++

To load an avatar from a script, you can call the **ApplyAvatar** coroutine from the *AvatarReadyRuntimeImportHelper* class.

.. doxygenfunction:: Inria::Avatar::AvatarReady::AvatarReadyRuntimeImportHelper::ApplyAvatar(AvatarReadySetup avatarReadyTarget, string avatarName, string provider, Action OnAvatarLoaded = null)

.. hint::
    ApplyAvatar is a coroutine, use StartCoroutine(AvatarReadyRuntimeImportHelper.ApplyAvatar(...)) to call Apply Avatar.

With a Virtual Interface
++++++++++++++++++++++++

Avatar Ready doesn't include a default VR interface, but the VR interface sample contains an example of interface that can be used in VR. 

.. hint::
    This interface is not included by default since it requires the XRInteraction package.

.. note::
    - When downloading an avatar, AvatarReady will first check if the avatar is available in the local cache.
    - Downloaded avatar are placed in the local cache folder before loading.
    - Loading an avatar can take a few seconds, the process can be longer when downloading the avatar.


Step 2 - B : Converting a Model To Static Avatar
________________________________________________

A static avatar is an avatar where the model is already in the scene. The model will not be changed during runtime.

To convert a character model in your scene into a static avatar **the model must have an animator component with a humanoid rig** defined.
Right click on the character model GameObject in the Hierarchy view, and select AvatarReady > Convert to AvatarReady.

|AvatarReady_StaticAvatarMenu|

This will create a new parent for the model **[Static Avatar: NameOfTheModel]** with an :ref:`AvatarReadySetup` component.
The model will be added as child of this object with an :ref:`AvatarReadyComponent` component. 

Once the values of the :ref:`AvatarReadyComponent` Component have been set :ref:`(see step 3)<ARQuick>` . Click on the Setup Avatar button to finish preparing the avatar.

.. _ARQuick:

Step 3 : AvatarReady Setup
__________________________

Quick setup of an avatar animated by IK and controlled using a three point setup (HMD and two hand controllers).

Additional information on how to use specific aspects of AvatarReady is available in other sections of this guide.

|AvatarReady_ARComponent|

* On the :ref:`AvatarReady Component <AvatarReadyComponent>` set Animation Type to :ref:`IK<IK>`.
* For Animation system choose FinalIK if available (this requires the finalIK package) or Unity Animation rigging otherwise.
* For :ref:`Configuration<IntroductionConfig>` select Default config. This will display three Object fields under *Trackers:* 
* Right click on your VR Rig root GameObject and select AvatarReady > XR Rig Helper > Default
* Drag the HMD tracked object and both controller tracked objects into the XR Rig Helper component.
* Click setup Effectors. This will generate child GameObjects for each tracker, you can add a position or rotation offset to this objects to better align the trackers with the user's hands.
* Set you Avatar as Avatar Ready target and press *Apply Rig*
* We will leave the default AvatarReady features for this example.