> ## Documentation Index
> Fetch the complete documentation index at: https://docs.musterbox.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Unity

> Integrate the MusterBox SDK with Unity 2020.3+.

The Unity adapter wraps the native MusterBox core behind a C# API
(`MusterBoxSdk` singleton). Min Unity version **2020.3**; package id
`com.musterbox.sdk`.

## Install

```bash theme={"dark"}
# Window > Package Manager > + > Add package from tarball...
# select dist/unity/musterbox-unity-1.0.0.tgz
```

Native FFI plugins ship per platform in the package (desktop, Android, iOS),
and a **WebGL template** is included for browser builds. Add the singleton
before your first scene that uses the SDK.

## Initialize

```csharp theme={"dark"}
using MusterBox;

var config = MusterBoxConfig.Create()
    .WithGameId("my-arena-game")
    .WithGameKey("gk_...")
    .WithEnvironment("sandbox")
    .Build();

MusterBoxSdk.Instance.Initialize(config);
MusterBoxSdk.Instance.Start();
```

## Authenticate and open a session

```csharp theme={"dark"}
MusterBoxSdk.Instance.Authenticate("player@example.com", "secret");
var ctx = MusterBoxSdk.Instance.OpenSession("sandbox", 1042);
// ctx.sessionId, ctx.token, ctx.context.tournamentId ...
```

## Submit results and events

```csharp theme={"dark"}
MusterBoxSdk.Instance.SubmitResult(1042, "PLAYER_A_WIN", boardHash);
MusterBoxSdk.Instance.SubmitEvent("match.start", new MBox.Json() { ["mode"] = "arena" });
```

## Runtime mode

Use **Manual** tick mode for frame-driven integration so the SDK only runs
bounded work per frame:

```csharp theme={"dark"}
void Update()
{
    MusterBoxSdk.Instance.Tick(maxCommands: 8, maxElapsedMs: 2);
}
```

## Threading note

The SDK's blocking variants own their own current-thread runtime — safe to
call from Unity worker threads, but never inside a running async/Tokio
context. Drive the singleton from the main thread for standard flows.

## Support matrix

| Unity       | SDK   | Notes                                                   |
| ----------- | ----- | ------------------------------------------------------- |
| 2020.3+ LTS | 1.0.0 | C# API `MusterBoxSdk.Instance`, WebGL template included |

Next: [Godot](/engines/godot).