Building for VR - Unity Plugin Guide for VR development with Convai.
If you want to make your Convai Plugin compatible with VR, you can do so using the automatic or manual process. Please see the instructions below or check out our latest tutorial video on YouTube.
Recommended for new projects.
The following processes will be performed:
Universal Render Pipeline (URP)
OpenXR Plugin
XR Interaction Toolkit
Convai Custom VR Package
Convai URP Converter
If these packages are not present, they will be installed.
If the target build platform is not Android, it will be switched to Android.
Make sure to download the Android platform support from Unity Hub for your project's version.
Click on " Convai / Convai Custom Package Installer / Install VR Package "
Confirm the changes and processes to be made. If you agree, the process will start. Click " Yes, Proceed " and the process will begin. You'll see logs in the console.
If you encounter an error like " Failed to Resolve Packages " don't worry. The process will continue and the error will be resolved automatically after the package installations are complete.
Open the " Convai / Scenes / Convai Demo - VR " demo scene. If the TMP Importer window appears, click " Import TMP Essentials " to install TextMeshPro for UI text objects.
Alternatively, you can use the " Window / TextMeshPro / Import TMP Essential Resources " to install it.
Build your project by going to " File /Build Settings / Build " Ensure that the " Convai Demo - VR " scene is included in the Scenes in Build section.
Now everything is ready for testing. 🙂✅
Ensure you've set up your API Key. ( Convai / Convai Setup )
Ensure you have the following packages installed in your project:
OpenXR or Oculus XR
XR Interaction Toolkit
URP (Universal Render Pipeline)
Double-click on " Convai / Convai Custom Unity Packages / ConvaiVRUpgrader.unitypackage "
You'll see a warning that the settings will overwrite your project settings. You can either allow it by clicking " Import " or create a temporary project by clicking " Switch Project "
In the Import Unity Package window, review the assets to be imported and click " Next "
In this window, select the project settings you want to import and complete the installation by clicking " Import ".
Open the " Convai / Scenes/ Convai Demo - VR " demo scene. If the TMP Importer window appears, click " Import TMP Essentials " to install TextMeshPro for UI text objects.
If you see 3D objects in pink, it's a shader issue. If you're using URP, convert the materials to URP by double-clicking on " Convai / Convai Custom Unity Packages / ConvaiURPConverter " and importing all assets in the window that appears.
Build your project by going to " File / Build Settings / Build " Ensure that the " Convai Demo - VR " scene is included in the Scenes in Build section.
Now everything is ready for testing. 🙂✅
Ensure you've set up your API Key (Convai/Convai Setup).
With Convai's Unity SDK, you can build your favorite application for several platforms, including Windows, MacOS and Android. Currently, we also support these platforms:
(Occulus)
(Android/iOS)
Building for AR - Unity Plugin Guide for AR development with Convai.
If you want to make your Convai Plugin compatible with AR, you can do so in two ways. Please see the instructions below or check out our on YouTube.
Recommended for new projects.
The following processes will be performed:
Universal Render Pipeline (URP)
ARCore Plugin
Convai Custom AR Package
Convai URP Converter
If these packages are not present, they will be installed.
If the target build platform is not Android, it will be switched to Android.
Make sure to download the Android platform support from Unity Hub for your project's version.
Click on " Convai / Convai Custom Package Installer / Install AR Package "
Confirm the changes and processes to be made. If you agree, the process will start. Click " Yes, Proceed " and the process will begin. You'll see logs in the console.
If you encounter an error like "Failed to Resolve Packages," don't worry. The process will continue, and the error will be resolved automatically after the package installations are complete.
Open the " Convai / Scenes / Convai Demo - AR " demo scene. If the TMP Importer window appears ( It will appear if TMP Essentials is not installed in your project ), click " Import TMP Essentials " to install TextMeshPro Essentials for UI text objects.
Alternatively, you can use the " Window / TextMeshPro / Import TMP Essential Resources " to install it.
After importing TMP Essentials, you can remove the empty GameObject in your scene that triggers the Prompt window to appear.
Build your project by going to " File / Build Settings / Build " Ensure that the " Convai Demo - AR " scene is included in the Scenes in Build section.
Ensure you've set up your API Key. ( Convai / Convai Setup )
Now everything is ready for testing. 🙂✅
Ensure you have the following packages installed in your project:
ARCore
URP (Universal Render Pipeline) - Recommended for optimization, though not mandatory
Double-click on " Convai / Convai Custom Unity Packages / ConvaiVRUpgrader.unitypackage "
You'll see a warning that the settings will overwrite your project settings. You can either allow it by clicking " Import " or create a temporary project by clicking " Switch Project "
In the Import Unity Package window, review the assets to be imported and click " Next "
Select all settings to be changed in the Project Settings and complete the installation by clicking " Import "
Open the " Convai / Scenes / Convai Demo - AR " demo scene. If the TMP Importer window appears ( It will appear if TMP Essentials is not installed in your project ), click " Import TMP Essentials " to install TextMeshPro Essentials for UI text objects.
Alternatively, you can use the " Window / TextMeshPro / Import TMP Essential Resources " to install it.
After importing TMP Essentials, you can remove the empty GameObject in your scene that triggers the Prompt window to appear.
If you see 3D objects in pink, it's a shader issue. If you're using URP, convert the materials to URP by double-clicking on " Convai / Convai Custom Unity Packages / ConvaiURPConverter " and importing all assets in the window that appears.
Ensure you've set up your API Key ( Convai / Convai Setup ).
Build your project by going to " File / Build Settings / Build " Ensure that the " Convai Demo - AR " scene is included in the Scenes in Build section.
Now everything is ready for testing. 🙂✅
If you've created a Ready Player Me character on convai.com playground and want to add it to your AR project, follow these steps:
Right-click on the " Convai / ConvaiAR / Prefabs / Convai NPC AR Base Empty Character " prefab.
Click on " Create / Prefab Variant "
You'll see a prefab variant created for " Convai NPC AR Base Empty Character "
Double-click on this prefab variant.
In the Hierarchy section, add your imported character as a child to this prefab variant.
After adding your character, click on your character.
In the Inspector, adjust the Scale settings as needed. To prevent your character from moving with animation while talking, disable the " Apply Root Motion " option in the Animator.
After these steps, save your prefab variant by pressing CTRL + S.
Open the " Convai / Scenes / Convai Demo - AR " scene.
Click on the " Convai AR Player " object under " ConvaiAR Base Scene "
In the Inspector, under the " Convai Character Spawner " component, add your prefab variant to the Character Prefab field.
Now, everything is ready to test your character in the AR environment!🙂✅
Creating this prefab variant is to prevent automatic scaling ( 1,1,1 ) of your prefab when instantiated in the AR environment.
To avoid issues with scale adjustments, we added our character as a child to an empty parent object. For convenience, we created an empty prefab variant.
This guide will walk you through the process of installing Convai-powered Unity applications on iOS and iPadOS devices.
Before you begin, make sure you have the following:
Unity 2022.3 or later
Xcode (latest version recommended)
Apple Developer account
Project with Convai's Unity SDK integrated and running properly
MacBook for building and deploying to iOS/iPadOS
Open your Convai-powered Unity project.
Ensure you have the latest version of the Convai Unity SDK into your project.
In Unity, go to File
→ Build Settings
.
Select iOS
as the target platform.
Click Switch Platform
if it's not already selected.
Check the Development Build
option for testing purposes.
If you wish to add a few required files manually, follow step 3. If you want it to be done automatically, jump to step 4
Create a new file named link.xml
in your project's Assets
folder.
Add the following content to the file:
This file prevents potential FileNotFoundException
errors related to the libgrpc_csharp_ext.x64.dylib
file.
Create a new C# script in Assets/Convai/Scripts
named iOSBuild.cs
.
Add the following content to the script:
Go to Convai -> Custom Package Installer
Click on Install iOS Build Package
Attach the script iOSBuild.cs
to any GameObject in your scene.
In Unity, go to File
→ Build Settings
.
Click Build
and choose a location to save your Xcode project.
Wait for Unity to generate the Xcode project.
Open the generated Xcode project.
In Xcode, select your project in the navigator.
Select your target under the "TARGETS" section.
Go to the "Signing & Capabilities" tab.
Ensure that "Automatically manage signing" is checked.
Select your Team from the dropdown (you need an Apple Developer account for this).
If needed, change the Bundle Identifier to a unique string.
Connect your iOS device to your Mac.
In Xcode, select your connected device as the build target.
Click the "Play" button or press Cmd + R
to build and run the app on your device.
If you encounter any build errors, ensure all the steps above have been followed correctly.
Check that your Apple Developer account has the necessary provisioning profiles and certificates.
If you face any GRPC-related issues, verify that the libgrpc_csharp_ext.a
and libgrpc.a
files are correctly placed in the Assets/Convai/Plugins/gRPC/Grpc.Core/runtime/ios
folder.
This guide will help you integrate Convai's WebGL capabilities into your Unity projects, enabling you to bring to life AI characters with human-like conversational abilities.
Convai's Unity WebGL SDK is designed to complement the standalone application capabilities of our Unity Asset Store version. With this specialized SDK, you can build and deploy interactive WebGL applications that leverage Convai's advanced conversation pipeline. Please see the instructions below or check out our on YouTube.
When attempting to play the scene in the Unity Editor, you may encounter the following error:
This error occurs because the WebGL SDK cannot be tested directly within the Unity Editor. To test your WebGL application, you must create a development build.
Now, your Unity setup is done, let's setup WebGL
Head on over to File
→ Build Settings
, then:
Click on WebGL
.
Check the Development Build
box.
Select Switch Platform.
Patience, remember? This shift takes a bit.
After the platform is switched to WebGL, click on Player Settings
.This is where the fun begins:
Once the platform conversion is complete,
Open the filePlayer Settings
.
Navigate to the pageWebGL settings
.
Under theResolution and Presentation
tab, select theConvai PWA Template
.
After the reloads is completed, check if the settings have changed. then, close all the open menus and follow these steps :
Double-click the Convai folder
and go to scenes.
Open the Convey Demo WebGL
scene.
Head to Convai's website, grab your API key, and input it back in Unity via Convai
→ Convai Setup
.
Now, head again to the Convai’s website and grab your favourite character’s id and paste it to Convai
→ Character Importer
.
Remember, Unity's editor won't let us test WebGL directly. But fear not, there's a Build and Run
option:
Go back to File
→ Build Settings
.
Click Add Open Scenes
and then Build and Run
.
Choose a folder for the build output, make a new one if needed, and name it "WebGL."
The First build may take some time. For subsequent builds and runs, use the Unity shortcut key Ctrl + B.
The first build is the longest, so feel free to stretch a bit – but don't venture too far. Soon, you'll greet our demo character, Amelia, or any other character you brought into your digital oasis. Just give your Microphone permissions and here you go!
Now the magic happens. Press and hold 'T' to chat with your carefully cultivated character. Or click on the text box to type out a question. And for the attention to detail – press F10 to access the settings panel where you can change your name and the UI style to your liking.
Feeling accomplished? You should! You now have a successfully working WebGL build in your browser. Curious developers can take a step further by downloading the project files from GitHub, available for all who desire to peek behind the curtain.
When you are ready with your production build, just uncheck the Development Build field in the Build Settings before publishing
When building Unity projects for macOS, developers may encounter issues with microphone permissions, particularly when targeting both Intel and Apple Silicon Macs. This document outlines the problem, symptoms, causes, and solutions to help ensure successful access to the microphone across different Mac architectures.
Some users have reported that while building macOS universal apps, Apple Silicon Macs handle microphone permissions without issue, while Intel Macs may fail to access the microphone due to differences in architecture. This can result in a lack of microphone response, DLL not found Exceptions, error messages, potential application crashes, or no audio input being detected.
The issue stems from the grpc_csharp_ext.bundle
, which is crucial for networking in Unity projects. There are separate versions of this DLL for Intel and Apple Silicon architectures, and they cannot be easily merged or applied universally. The grpc library currently lacks dedicated support for resolving these dll issues in Unity.
For Intel Macs: Use Standalone builds targeted specifically for the Intel architecture to ensure compatibility.
For Apple Silicon Macs: Prefer Standalone builds for the ARM64 framework for optimal performance, although Universal builds are also an option.
After completing a Universal build on an Intel Mac, you must manually update the grpc_csharp_ext.bundle
to ensure proper functionality. Follow these steps:
Locate the .app
file generated by the build process.
Right-click on the .app
file and select "Show Package Contents."
Navigate to the Contents/Plugins
folder within the package.
Important: The grpc_csharp_ext.bundle
may not be included correctly in the final build when built from an Intel Mac. Always verify that the Plugins
folder in the build contains the correct DLLs. If there is any confusion or the DLLs are missing, replace or add the contents of the Plugins
folder with the one provided by us.
Building for macOS requires careful consideration of the distinct Intel and Apple Silicon architectures. The current best practice is to use Standalone build settings tailored to the specific architecture of the target Mac. As we progress, we will have a more integrated solution for managing DLLs that will simplify the development process for universal macOS applications.
Use the " " guide to add your character to your project.
You should now have successfully installed your Convai-powered Unity app on your iOS or iPadOS device. If you encounter any issues or need further assistance, please visit our or contact Convai support.
Please ensure that Git is installed on your computer prior to proceeding.
Follow the Import and Setup Instructions from and .
Replace the contents of this folder with the components from the provided plugin folder ().