Integrate the VIVERSE Avatar SDK

Wonderland Engine is the best choice for building highly performant 3D web experiences that need to run smoothly in VR. It is optimized for WebXR performance and fast load times. It runs fast on mobile browsers, including iOS Safari, and standalone VR headsets.

This guide explains how to integrate VIVERSE platform services using Wonderland Engine’s Universal Platform SDK (UPSDK) and the VIVERSE provider.

Links

• VIVERSE Documentation
• VIVERSE Studio

Prerequisites 

Start with a new or existing Wonderland Engine project.

Create a VIVERSE account on VIVERSE and create a World/App in VIVERSE Studio to obtain an appId for publishing your project.

Install our Universal Platform SDK (UPSDK) via npm together with the VIVERSE provider.

1npm i --save @wonderlandengine/upsdk \
2    @wonderlandengine/upsdk-provider-viverse

Setup 

Register the provider as early as possible in your application app.js entrypoint:

 1import {user} from "@wonderlandengine/upsdk";
 2import {ViverseProvider} from "@wonderlandengine/upsdk-provider-viverse";
 3
 4const provider = new ViverseProvider({
 5    appId: APPLICATION_ID, // replace with your real appId from VIVERSE Studio
 6    debug: false, // set to `true` for a debug user/avatar for testing.
 7});
 8
 9user.registerProvider(provider);
10
11/* wle:auto-constants:start */
12// ...

Obtain an appId by creating a World/Application in VIVERSE Studio.

Load an Avatar 

Once the provider is registered, you can request login and read the returned user object. Typical usage in a component looks like this:

 1import {user} from "@wonderlandengine/upsdk";
 2import {Vrm} from '@wonderlandengine/components';
 3
 4
 5// Inside a component:
 6
 7static onRegister(engine) {
 8    engine.registerComponent(Vrm);
 9}
10
11user.requestLogin()
12    .then((u) => {
13        // Use u.name and u.avatarUrl in your app
14        this.object.addComponent(Vrm, {
15            src: u.avatarUrl,
16        });
17        console.log(`Avatar for ${u.name} loaded`);
18    })
19    .catch((err) => {
20        console.error("Login failed:", err);
21    });

VIVERSE Publish Plugin 

The publish plugin is optional. It wraps viverse-cli SDK and helps publish your Wonderland Engine project to VIVERSE directly from within the editor.

Plugin Installation 

Go to Views > Plugins and enable plugin execution for your project. Then switch to the “Project Scope” tab and click “Install” next to @wonderlandengine/viverse-publish-plugin.

Finally, enable the plugin.

Usage (inside Wonderland Editor) 

1. View → Plugins → VIVERSE Publish Plugin.
2. Enter your VIVERSE username & password and log in via the plugin UI.
3. Use Create Application (which redirects to VIVERSE Studio) to create an application and retrieve an application id or Log App List to get existing appIds in the editor console.
4. Enter the appId and click Publish to viverse to generate an Open Preview URL button.
5. Click Submit to review to open the VIVERSE Studio application page where you can submit your app for review. From there you may also get a guest preview link to share.

Troubleshooting 

• appId not found / invalid: make sure you’ve created an application/world in VIVERSE Studio and copied the correct ID.
• requestLogin() rejects: check network logs and provider debug messages. If debug: true works but debug: false doesn’t, double-check your appId and VIVERSE Studio configuration.
• High memory from avatar textures: resize images and simplify the mesh before loading the avatar.
• Editor plugin login fails: ensure the editor has network access and your username/password are correct. Check the editor console for plugin errors.

If you still have trouble, please reach out via our Discord Community, we’re happy to help!