Unity SDK (Legacy)

Welcome to the VIPE Unity SDK documentation. This comprehensive guide aims to help you seamlessly integrate VIPE's powerful features into your Unity projects. Whether you're looking to manage avatars or utilize blockchain-based assets, our SDK has got you covered.

📘

We offer support for Unity versions 2021.3.12f1 and later

In this documentation, you'll find step-by-step installation instructions, feature explanations, and code samples to fast-track your development process. From setting up GIT and installing essential dependencies to customizing avatar settings and in-game menus, we cover it all. By the end of this guide, you'll be well-equipped to leverage the VIPE Unity SDK for enhanced user experiences and efficient project development.

So, let's dive right in and get started! For a quick and visual guide, you can also start by watching the video tutorial just below.

1. Installation and configuration

1.1. Installing GIT

GIT is essential for accessing and downloading necessary libraries such as vrmshaders, gltf, univrm and vrm. Follow the steps below for proper installation:

  • Visit the official GIT site to start the download.
    Download Link: Git - Downloads
  • Once downloaded, choose the version corresponding to your operating system and follow the installation instructions.

This installation will ensure that you do not encounter any issues when installing packages with GitHub URLs.

1.2. Installing Dependencies

For the proper functioning of the plugin, it is necessary to have certain libraries that have already been mentioned previously.

  • Access the official Unity VRM repository on GitHub to download and install the required dependencies.
    Installation Link: UniVRM on GitHub

1.3 VIPE Package Installation

Finally, to integrate our VIPE package to your Unity project:

  • Download the VIPE Unity SDK here
  • Simply drag the package file into your project in Unity. Alternatively, you can open it directly, and you will be presented with a pop-up window that will guide you through the import process.

2. How to use

Before taking advantage of the features of this Plugin, it is essential to carry out its proper configuration. Follow the steps below to ensure proper integration:

2.1 Accessing the Main Menu

Locate the menu in the top left task bar of your screen.

How to use Accesing the Main Menu

2.2 Settings

Select the 'Settings' option from the drop-down menu.

How to use Settings

2.3 API-Key Entry

In the pop-up window, you will find a field requesting an API-Key. This code is essential to establish a connection to our services.

How to use API-Key Entry
  • If you do not already have an API-Key, click on 'Get API Key'. You will be redirected to a website where detailed instructions on how to obtain it are provided. Alternatively, you can go straight to the Authorization section.
  • Once in possession of the key, enter it in the designated field. Use the icon to the right of the field to paste the API-Key if you prefer.

With these steps, you have completed the basic configuration of the Plugin. You will now be able to view the CC0 avatars in the sample scene.

2.4 Connect wallet

To display and manage your own avatars in the Plugin, it is essential to establish a connection to your digital wallet. You can see a section where you will identify a field called 'Wallet Address'.

How to use Connect wallet
  • Click on the 'Login to VIPE' button. You will be redirected to our web portal, where you will need to authenticate using your Metamask or WalletConnect wallet. Once the connection is established, return to Unity. You will notice that the 'Wallet Address' field will now be populated, indicating that the link has been success.

We recommend that you ensure that you keep your login details secure and manage your avatars with caution.

2.5 Render Settings

This menu allows you to adjust the VRM materials, ensuring their correct display in Built-in or URP modes.

How to use Render Settings
  • Project Render Pipeline: Reflects the current state of the engine configuration.
  • VRM Configuration: Displays the active VRM configuration. Use the buttons below to adjust these settings, making sure they match the project settings.

It is crucial that both the Project and VRM states match to ensure optimal representation of the avatars.

2.6 Avatar Library

This menu provides the functionality to load avatars directly into the scene. Depending on how you want to use these avatars, it is essential to assign the appropriate animator and other corresponding components to them.

How to use avatar library

2.7 Overview

The "Overview" menu is distinguished by its intuitive and functional structure:

How to use Overview menu
  • Load Buttons:
    • Load Owned: Enables uploading avatars that are under your possession.
    • Load Open source: Enables the loading of avatars that are offered for free.
  • Search Bar: This tool is useful for quickly locating a specific avatar by name.
  • Collection Filters: Facilitates the organisation and display of avatars, allowing you to filter them according to their respective collections. The collections displayed contain Open source avatars.
  • Navigation between Pages: If the avatars presented exceed the capacity of a single page, use the "Next Page" and "Previous Page" buttons to navigate between the different avatar pages.

2.8 In-Game Menu

The in-game menu provides players with a simple interface to customise their in-game experience, offering multiple options for avatar selection and customisation. It is designed to be intuitive and easy to use, allowing players to easily navigate between the available options.

In game menu Unity SDK
  1. Log In:
    • This option allows players to access their account. Upon successful login, players can access the avatars they own on the platform.
  2. Start As Guest:
    • Players who choose this option can play without logging in. It is a quick way to join the game, although it does not offer the personalised experience of having your own avatars.
  3. Upload Avatar:
    • Players can upload a custom avatar from their device using this option. This is particularly useful for those who have a VRM avatar that does not exist within the platform and wish to use it in the game.
Upload avatar Unity SDK
  • Avatar Preview:
    • The interface prominently displays a preview of the currently selected avatar. This gives players a clear view of how their character will look in-game.
  • Avatar Collection Browsing:
    • Players can browse various avatar collections. These collections feature CC0 (Open source) licensed avatars, ensuring a wide range of options for all players.
  • Avatar Search Function:
    • If players have a specific avatar in mind, they can use the search function. By entering the name of the avatar, they can quickly locate and select it.
  • Upload Avatars via URL:
    • As mentioned, players always have the option to upload an avatar that is in the cloud and possess the URL.
  • ESC Functionality:
    • Pressing the 'ESC' key provides dual functionality. It hides the avatar selection interface, allowing players to return to the game. In addition, it releases the mouse, allowing players to control their selected avatar.

3. Scripts

3.1 VIPE Core script

This VIPE script handles avatar management and interaction with the cryptoavatars.io API.

3.1.1 Variables and Components:

  • mainThreadDispatcher: Dispatcher to execute tasks in the main thread.
  • NextPageUrl, prevPageUrl: URLs for paged avatar navigation.
  • modelCreated: Event invoked when a model is successfully created.

3.1.2 Main Methods:

  • GetAvatars(): Retrieves avatars from the API.
  • PrevPage(): Navigates to the previous page of avatars.
  • NextPage(): Navigates to the next avatar page.
  • GetAvatarPreviewImage(): Gets a preview image of an avatar from a URL.
  • GetAvatarVRMModel(): Download and load a VRM model from a URL.
  • GetNFTCollections(): Retrieves all available NFT collections.
  • DefaultQuery(): Provides a default set of query parameters.
  • GetAvatarsByURL(): Retrieves avatars based on a specific URL.

3.2 MenuManager

The MenuManager script manages the user interface and user interaction with avatars and collections.

3.2.1 Variables and Components:

  • canvas, loginPanel, avatarsPanel: References to GUI components for navigation.
  • loadVRM, nextPageBtn, prevPageBtn: Buttons for loading VRM models and navigating between avatar pages.
  • messageEnableUI, avatarCardPrefab, collectionCardPrefab, loadingSpinner: References to gameObjects and prefabs used in the UI.
  • scrollViewAvatars, scrollViewCollections: Scrollable areas showing avatars and collections.

3.2.2 Main Methods:

  • LoadByURL(): Load a VRM model using a user-entered URL.
  • CancelExistingTasks(): Cancels any existing asynchronous tasks.
  • LoadAvatarUI(): Toggles the display between the login panel and the avatar panel.
  • SetSearchField(): Sets the search field to execute a search query when the text changes.
  • DebounceSearch(): Delays the execution of a search query and performs it after a specified delay.
  • ExecuteSearch(): Execute a search query to load avatars based on the provided search criteria.
  • LoadOwnVRMAsync(): Asynchronously loads the user's own VRM models.
  • LoadOwnVRMButtonWrapper(): A wrapper to load the user's own VRM models.

3.3 CardAvatarController.cs

This CardAvatarController script is responsible for managing and presenting avatar specific information on a card.

3.3.1 Variables and Components:

  • avatarName: Reference to the text component where the avatar name is displayed.
  • vrmUrl: Stores the URL associated with the avatar's VRM model.

3.3.2 Avatar Data Set (SetAvatarData):

This method sets the avatar information on the card, including the name, the VRM model URL, and the action to perform when the card is clicked.

  • Parameters:
    • name: Avatar name.
    • vrmUrl: URL associated with the avatar's VRM model.
    • onClickCardBtn: Action to execute when the card is clicked.

3.3.3 Load Avatar Image (LoadAvatarImage):

Allows to load and display the avatar image on the card from a provided texture.

  • Parameters:
    • texture: The avatar image represented as a Texture2D object.

3.4 CardCollectionController.cs

The CardCollectionController script manages and presents collection specific information on a card.

3.4.1 Variables and Components:

  • imageCollection: Reference to the image component where the image of the collection will be displayed.
  • textCollection: Reference to the text component where the name of the collection will be displayed.

3.4.2 Initialisation (Awake):

This method is automatically invoked when the object is instantiated. It initialises the references to the image and text components of the card.

3.4.3 Set Collection Data (SetCollectionData):

This method is invoked automatically when the object is instantiated.

Sets the collection information on the card, including the name, the URL of the associated VRM model, and the action to perform when the card is clicked.

  • Parameters:
    • name: Collection name.
    • vrmUrl: URL associated to the VRM model of the collection.
    • onClickCardBtn: Action to be executed when the card is clicked.

3.4.4 Load Collection Image (LoadCollectionImage):

Allows to load and display the collection image on the card from a provided texture.

  • Parameters:
    • texture: The collection image represented as a Texture2D object.