VIVERSE Unity SDK

Current VIVERSE C# SDK for Unity games. Use this SDK for authentication, cloud save, multiplayer, leaderboards, profiles, and avatars in Unity.

Current SDK: VIVERSE Unity SDK 1.2. For a Unity game, use this C# SDK. Do not use the JavaScript SDK or a .jslib for authentication, cloud save, multiplayer, leaderboards, or avatars. The JavaScript SDK is for three.js, PlayCanvas, and other browser JavaScript.

Requires Unity 2021.2 or newer.

---

What to call

I want to	Unity API
Authenticate a player	AuthManager
Save player data	CloudSaveClient
Add multiplayer	MultiplayerClient
Add leaderboards	LeaderboardClient
Get the player's profile or avatar	AvatarClient
Publish a Unity WebGL build	Unity WebGL publishing guide

Authentication, cloud save, and leaderboard samples are on this page. Multiplayer and avatar samples are in the README. Publishing a WebGL build does not call these gameplay APIs.

How to authenticate a player in a Unity game

VIVERSE Unity SDK 1.2 · C# · ViverseSDK

Use AuthManager to sign a player in. Every feature except the public avatar catalog needs the access token from that sign-in.

Authentication best practice

Calling the VIVERSE login method immediately starts the sign-in flow. Before requesting login, check whether the player already has an authenticated session or access token.

If the player is not signed in, provide feedback in your game UI and allow them to continue as a guest when authentication is not required for gameplay.

Start the login flow when the player chooses to sign in or when they access a feature that requires authentication, such as cloud save, player profiles, or submitting a leaderboard score.

After Initialize, read IsLoggedIn or AccessToken. Call Login() only when you are ready to start sign-in. In a WebGL build, Login() redirects the parent page.

// VIVERSE Unity SDK 1.2 — Unity C#
using UnityEngine;
using ViverseSDK;

public class Bootstrap : MonoBehaviour
{
    void Start()
    {
        var auth = AuthManager.Instance;
        auth.OnLoginSuccess += result => Debug.Log($"Signed in as {result.account_id}");
        auth.OnError        += err    => Debug.LogError($"Auth error: {err}");

        auth.Initialize("YOUR_APP_ID");
    }

    public void OnLoginButtonClicked()  => AuthManager.Instance.Login();
    public void OnLogoutButtonClicked() => AuthManager.Instance.Logout();
}

Create an empty GameObject in your first scene, name it [AuthManager], and add the AuthManager component. In WebGL, Login() redirects the parent page through the VIVERSE OAuth server. In the Editor, AuthHttpServer starts a temporary local server on port 40078 to receive the redirect. Both paths raise OnLoginSuccess with the same AuthResult payload.

How to save player data in a Unity game

VIVERSE Unity SDK 1.2 · C# · ViverseSDK

Use CloudSaveClient for cloud save in Unity. It supports versioned save files (a full history of blobs) and key-value entries for small named values. Call it only after AuthManager has an access token.

// VIVERSE Unity SDK 1.2 — Unity C#
using ViverseSDK;

var cloud = new CloudSaveClient("YOUR_APP_ID");
string token = AuthManager.Instance.AccessToken;

// Versioned saves
await cloud.Save("{\"level\":5,\"score\":1200}", token);
var latest = await cloud.GetLatest(token);
if (latest.success) Debug.Log($"Latest save: {latest.data}");

// Key-value entries
await cloud.SetPlayerData("coins", "150", token);
var coins = await cloud.GetPlayerData("coins", token);
if (coins.success) Debug.Log($"Coins: {coins.data}");

Every method returns a CloudSaveResult with success, data, and error fields. Write operations return null in data.

How to add a leaderboard to a Unity game

VIVERSE Unity SDK 1.2 · C# · ViverseSDK

Use LeaderboardClient. Create the leaderboard in VIVERSE Studio first. The metaName argument must match the name configured there. The in-room multiplayer Leaderboard module does not persist scores across sessions.

// VIVERSE Unity SDK 1.2 — Unity C#
using ViverseSDK;

var leaderboard = new LeaderboardClient("YOUR_APP_ID");
string token = AuthManager.Instance.AccessToken;

await leaderboard.SubmitScore("time_attack", "100", token);
var mine = await leaderboard.GetLeaderboard("time_attack", token);
if (mine.success) Debug.Log($"My ranking: {mine.data}");

Legacy Unity APIs

These names are from VIVERSE Unity SDK v0.96. Do not use them for a new Unity project.

• CloudSaveService is a legacy API. Use CloudSaveClient.

• LoginManager is a legacy API. Use AuthManager.

• SDK_v0.96.unitypackage is a legacy package. Import Viverse-Unity-SDK-1.2.0.unitypackage.

Introduction

The VIVERSE Unity SDK lets you ship VIVERSE-connected Unity games to WebGL and iterate them in the Editor with the same C# API. Version 1.2 covers authentication, Lambda functions, matchmaking, real-time multiplayer, cloud save, leaderboards, achievements, and avatars.

This page is the entry point for the artifacts published on GitHub. It answers three questions:

• What are these three artifacts?

• Who should use each one?

• Where do I go next?

The README remains the full API guide. This page includes the authentication and cloud save samples.

Prerequisites

• Unity 2021.2 or newer with the .NET 4.x scripting runtime

• WebGL build support installed through Unity Hub

• A VIVERSE App ID from VIVERSE Studio

• Optional: UniVRM v0.130.1 or newer if you want to render downloaded VRM models. The SDK compiles and runs without it.

• Optional: Cursor if you want to use the AI skills pack

The three artifacts at a glance

Two are files (the .unitypackage and the README). The third is the viverse-sdk-skills folder.

Artifact	What it is	You use it when
SDK v1.2 .unitypackage	The plugin you import into Unity	You need the SDK running in a project
README	The human-facing getting-started and API guide	You need to learn or look up C# APIs
AI skills folder	Instructions for Cursor and other coding agents	You want an agent to implement the SDK correctly

Artifact	GitHub
SDK v1.2 package	Viverse-Unity-SDK-1.2.0.unitypackage
README	README.md
AI skills folder	viverse-sdk-skills

Start with the package. The README and AI skills describe how to use the SDK. Neither one adds the SDK to Unity by itself.

SDK v1.2 package

The .unitypackage is the actual Unity plugin. Download it, import it, and it places C# clients, WebGL bridges, and assemblies under Assets/viverse-unity-sdk/. Without this file, nothing runs.

Download: Viverse-Unity-SDK-1.2.0.unitypackage

What you get

Unity applications call AuthManager, CloudSaveClient, and LeaderboardClient. In WebGL builds, the SDK internally talks to the VIVERSE JavaScript runtime. Do not create a .jslib, and do not call checkAuth or loginWithWorlds from game code. In the Editor, the same C# API talks directly to VIVERSE REST endpoints and WebSocket gateways, so you can develop and test without a browser.

Feature	What it does
Authentication	Signs a player in with their VIVERSE account through OAuth 2.0.
Lambda	Invokes server-side functions you register in VIVERSE Studio.
Matchmaking	Creates, discovers, and joins rooms over WebSocket.
Multiplayer	Runs WebRTC data channels for real-time sync, action, leaderboard, and general modules.
Cloud Save	Persists versioned save files and key-value player data.
Leaderboard	Submits scores and reads rankings, with RSA/AES payload encryption.
Achievements	Fetches and unlocks achievements, with the same encryption pipeline.
Avatar	Reads a player's profile and avatar list, downloads VRM models, and (optionally) renders them via UniVRM.

After import, the SDK lands under Assets/viverse-unity-sdk/ and adds three assemblies:

• Viverse.SDK — runtime

• Viverse.SDK.Editor — editor tooling

• Viverse.NativeWebSocket — a vendored WebSocket transport, renamed so it can coexist with the community NativeWebSocket package

If your project already uses the community NativeWebSocket package, see Coexisting with an existing NativeWebSocket in the README.

Import the package

1

Download the package

Download Viverse-Unity-SDK-1.2.0.unitypackage from GitHub.

2

Import into Unity

In Unity, open Assets > Import Package > Custom Package and select the file.

3

Confirm the import

Leave every item checked in the import dialog and select Import. Wait for Unity to finish recompiling. You should see zero errors in the Console.

For C# samples, WebGL build notes, local testing, and the full API reference, use the README.

README

The README is the human-facing implementation and API guide. A person reads it in GitHub or in GitBook after you upload it. It is not imported into Unity.

Open it: Getting started with the VIVERSE Unity SDK

Use the README when you need to:

• Install and authenticate a player

• Call a specific feature with C# examples

• Look up types, events, and methods

• Build and test WebGL locally

• Understand the project layout under Assets/viverse-unity-sdk/

The README currently covers:

Section	What it contains
What you get / Requirements / Install	Baselines and how to import the package
Authenticate a player	AuthManager OAuth flow for WebGL and Editor
Invoke Lambda functions	LambdaClient and Studio reply(...) notes
Match players into rooms	MatchmakingClient WebSocket lifecycle
Sync players in real time	MultiplayerClient and modules
Save player progress to the cloud	CloudSaveClient
Submit scores and read rankings	Persistent REST leaderboard
Fetch and unlock achievements	AchievementsClient
Load a player's avatar	AvatarClient and optional UniVRM
Build / test WebGL	Template, local server, CORS proxy
API reference	Member tables for the public C# surface
Project layout	Folder map of Assets/viverse-unity-sdk/

Treat the README as the source of truth for APIs. This overview stays short on purpose so it does not go stale when samples in the repo change.

AI skills

The AI skills pack is a set of instructions for Cursor and other coding agents. Each skill folder teaches the agent when to use a feature, which C# types to call, how the WebGL vs Editor paths work, and which rules not to break.

AI skills help the coding agent use the SDK correctly; they do not add runtime functionality to the Unity project.

They are not:

• A second Unity package

• A substitute for the README

• Something you import through Assets > Import Package

Open the pack: viverse-sdk-skills

When to use them

Use the skills when you are implementing VIVERSE Unity features with Cursor (or a similar agent) and you want the agent to follow the official dual-path architecture instead of inventing a different integration.

If you are writing the integration yourself, the README is enough. The skills are optional.

How to add them in Cursor

Each folder under unity-sdk/viverse-sdk-skills/skills/ is one skill (SKILL.md, skill.json, rules.json, and optional patterns/). Copy those folders into Cursor's skills location:

Type	Path	Scope
Project	.cursor/skills/ in your Unity project	Shared with anyone using that repo
Personal	~/.cursor/skills/ (Windows: %USERPROFILE%\.cursor\skills\)	Available across your projects

1

Get the skill folders

Clone or download viverse-sdk-skills from GitHub.

2

Copy each skill into Cursor

Copy every folder inside skills/ (for example viverse-unity-auth) into .cursor/skills/ or your personal skills directory. Keep the folder names. Do not copy the parent viverse-sdk-skills wrapper as a single skill.

3

Use them while coding

Ask Cursor to implement the VIVERSE feature you need. The agent should pick up the matching skill (auth, matchmaking, multiplayer, and so on) and follow its API, dual-path rules, and compliance checklist.

Skill catalog

Descriptions below are taken from each skill's skill.json. Multiplayer module skills require an active room from matchmaking first.

Core and REST

Skill	Depends on	What it covers
viverse-unity-auth	—	VIVERSE Unity SDK Authentication — OAuth2 login via dual-path architecture (WebGL viverse-sdk UMD + Editor localhost HttpServer redirect).
viverse-unity-lambda	viverse-unity-auth	VIVERSE Unity SDK Lambda — Invoke server-side functions via REST, dual-path (WebGL fetch + Editor UnityWebRequest).
viverse-unity-cloudsave	viverse-unity-auth	VIVERSE Unity SDK Cloud Save — Persistent player data storage via REST, dual-path (WebGL fetch + Editor UnityWebRequest). Two patterns: versioned saves + key-value.
viverse-unity-leaderboard	viverse-unity-auth	VIVERSE Unity SDK Leaderboard — Score submission (RSA/AES encrypted) and ranking retrieval via REST, dual-path (WebGL viverse-sdk GameDashboard + Editor UnityWebRequest with Ironhide encryption).
viverse-unity-avatar	viverse-unity-auth	VIVERSE Unity SDK Avatar — User profiles, avatar lists, VRM model download & loading. Dual-path (WebGL Avatar SDK + Editor UnityWebRequest). Includes VRM 3D rendering with UniVRM10.
viverse-unity-matchmaking	—	Unity Matchmaking — room create/join/leave, actor management, and real-time room events via dual-path architecture (WebGL viverse-sdk UMD + Editor NativeWebSocket). Session ID auto-generated.

Real-time multiplayer

Skill	Depends on	What it covers
viverse-unity-multiplayer	viverse-unity-matchmaking	Unity Play SDK Multiplayer — real-time data channels, 6 game modules (Game, NetworkSync, ActionSync, Leaderboard, Lambda, General), and master/client architecture via dual-path (WebGL Mediasoup + Editor WebRTC proxy).
viverse-unity-game-module	matchmaking + multiplayer	Unity Play SDK Game Module — manages multiplayer game lifecycle (ready, countdown, start, end, restart) through the GameModule property on MultiplayerClient.
viverse-unity-network-sync	matchmaking + multiplayer	Unity Play SDK NetworkSync Module — continuous per-frame position and transform synchronization for players and game entities via the NetworkSyncModule property on MultiplayerClient.
viverse-unity-action-sync	matchmaking + multiplayer	Unity Play SDK ActionSync Module — broadcasts discrete competitive game actions (attacks, abilities, emotes) to all peers with caller-supplied action IDs for de-duplication.
viverse-unity-leaderboard-module	matchmaking + multiplayer	Unity Play SDK Leaderboard Module — broadcasts real-time in-room scores to all peers via WebRTC data channel during an active multiplayer session (ephemeral, not persisted to backend).
viverse-unity-general-module	matchmaking + multiplayer	Unity Play SDK General Module — sends and receives arbitrary freeform messages between peers over the WebRTC data channel. Also fires connection/disconnection events for all room participants.

Two different leaderboards

• viverse-unity-leaderboard is the persistent REST ranking you configure in VIVERSE Studio. Scores survive after the session ends.

• viverse-unity-leaderboard-module is in-room ephemeral scores sent over the multiplayer data channel. They are not stored on the backend.

Use viverse-unity-multiplayer first to connect and call Init(). Then use a module-specific skill when you need the detailed pattern for that module.

Suggested order

1

Import the SDK

Download and import Viverse-Unity-SDK-1.2.0.unitypackage so the C# API exists in your project.

2

Read the README for the feature you need

Open the README for install details, C# samples, and the API reference. Most features need an access token from AuthManager first. The public avatar catalog is the documented exception.

3

Optionally add AI skills

If you use Cursor, copy the skill folders from viverse-sdk-skills into .cursor/skills/. This helps the agent follow the official APIs. It does not replace importing the package.

Where to go next

• Get an App ID and publish from VIVERSE Studio.

• Build and upload a WebGL project with the Unity WebGL publishing guide.

• Explore the sample scenes under Assets/viverse-unity-sdk/Sample/ after you import the package. ViverseTestRunner wires every feature for interactive testing.

• Use the README as the day-to-day API reference.