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

# Game Bridge Architecture

Learn how Immutable game SDKs work internally and how to adapt them for custom engines.

> [!NOTE]
>
> This page is primarily for developers building custom engine integrations or wanting to understand the SDK architecture. If you're using Unity or Unreal, refer to their respective SDK documentation.

## Overview

The Unity and Unreal SDKs share a common architecture that bridges native game engines with TypeScript-based functionality. This design allows consistent behavior across platforms while leveraging platform-specific capabilities.

The architecture has three main components: a **game bridge** for communication, an **invisible WebView** for executing TypeScript, and an **in-app browser** for secure authentication.

## Architecture Diagrams

### High-Level Architecture

```mermaid theme={null}
graph TB
    Game["Game"]

    subgraph GameSDK["Game SDK"]
        direction TB

        subgraph InvisibleWebView["Invisible WebView"]
            direction TB

            subgraph IndexFile["index file"]
                direction TB
                GameBridge["game-bridge"]
                RequiredSDK["Required Immutable<br/>TypeScript SDK packages"]
            end
        end
    end

    Game --> GameSDK
```

### Communication Flow

How the game engine communicates with TypeScript SDK packages through JSON serialization:

```mermaid theme={null}
graph LR
    Game["Game Engine"]
    SDK["Game SDK"]
    WebView["Invisible<br/>WebView"]
    IndexFile["Game Bridge"]
    TSPackage["TypeScript<br/>SDK"]

    Game <-->|"function call"| SDK
    SDK <-->|"JSON serialize/<br/>deserialize"| WebView
    WebView <-->|"callFunction()<br/>parse JSON"| IndexFile
    IndexFile <-->|"callFunction()<br/>callbackToGame()"| TSPackage
```

### PKCE Authentication Flow

How authentication works using in-app browsers for security:

```mermaid theme={null}
sequenceDiagram
    participant Game
    participant SDK as Game SDK
    participant Native as Native Code
    participant Browser as In-App Browser

    Game->>SDK: Login via PKCE flow
    SDK->>Native: Launch in-app browser
    Native->>Browser: Open authentication URL
    Browser->>Browser: User authenticates
    Browser->>Native: Deep link callback
    Native->>SDK: Authentication complete
    SDK->>Game: Login success
```

## Core Components

### 1. Game Bridge

The game bridge enables string-based communication between your game engine and the [TypeScript SDK](https://docs.immutable.com/docs/sdks/typescript).

**How it works:**

* The [`game-bridge`](https://github.com/immutable/ts-immutable-sdk/tree/main/packages/game-bridge) package enables communication with TypeScript SDK packages
* TypeScript packages are bundled into a single file loaded into an invisible WebView
* The game SDK sends JSON string messages to the WebView and receives responses

**Implementation:**

* Unity: [`index.html`](https://github.com/immutable/unity-immutable-sdk/blob/main/src/Packages/Passport/Runtime/Resources/index.html)
* Unreal: [`index.js`](https://github.com/immutable/unreal-immutable-sdk/blob/main/Web/index.js)

Both contain the bundled TypeScript SDK and `game-bridge` package.

### 2. WebView

An invisible WebView loads the game bridge and executes TypeScript SDK functionality.

**Requirements:**

* HTML/JavaScript loading support
* Modern JavaScript (ES6+)
* Bidirectional native-JavaScript communication
* Hidden from user view (no UI rendering)

**Platform considerations:**

* Mobile: Native WebView components (Android/iOS)
* Desktop: May require embedded browser frameworks
* Windows: CEF 90+ required

### 3. In-App Browser

Authentication uses an in-app browser (not WebView) for security and SSO compatibility.

**Requirements:**

* Secure, isolated browser context
* Process isolation (runs separately from your app)
* Deep link callback handling
* System authentication session support

> [!WARNING]
>
> Never use WebView for authentication. In-app browsers run in separate processes, preventing credential theft and meeting OAuth 2.0 best practices. See [Why in-app browser?](https://docs.immutable.com/docs/sdks/unity/faq.md) for details.

For platform-specific implementations, see:

* [Unity SDK Repository](https://github.com/immutable/unity-immutable-sdk)
* [Unreal SDK Repository](https://github.com/immutable/unreal-immutable-sdk)

## Adapting for Custom Engines

> [!WARNING]
>
> This section is for custom game engine integrations. Unity and Unreal users don't need to modify these components.

To adapt the SDK for your custom engine, you'll need to modify three areas:

### 1. Modify the Game Bridge

Keep the bundled TypeScript SDK but modify the `callbackToGame()` function in [`game-bridge/index.ts`](https://github.com/immutable/ts-immutable-sdk/blob/main/packages/game-bridge/src/index.ts) to communicate with your engine.

After modification, rebuild the bundle following the [game-bridge README](https://github.com/immutable/ts-immutable-sdk/blob/main/packages/game-bridge/README.md).

### 2. Implement WebView Communication

**Option A:** Reuse our platform-native WebView implementations and adapt the communication layer

**Option B:** Implement a custom WebView with bidirectional string communication and lifecycle management

**Reference implementation:**

* C# engines: [Unity SDK](https://github.com/immutable/unity-immutable-sdk)
* C++ engines: [Unreal SDK](https://github.com/immutable/unreal-immutable-sdk)

### 3. Implement PKCE Authentication

Reuse our platform-native PKCE implementations and deep linking handlers. Adapt the communication layer between your engine and native code for URL scheme registration and callback handling.

> [!TIP]
>
> The Game SDK is lightweight—essentially a wrapper around the TypeScript SDK. Most complexity is in the bridge and WebView communication, not the SDK logic itself.

## Related Documentation

> [card] [Unity SDK](https://docs.immutable.com/docs/sdks/unity/overview.md)
>
> Unity SDK implementation

> [card] [Unreal SDK](https://docs.immutable.com/docs/sdks/unreal/overview.md)
>
> Unreal SDK implementation

> [card] [TypeScript SDK](https://docs.immutable.com/docs/sdks/typescript/overview.md)
>
> Core TypeScript packages

> [card] [Game Bridge Package](https://github.com/immutable/ts-immutable-sdk/tree/main/packages/game-bridge)
>
> Game bridge source code

> [card] [SDK FAQ](https://docs.immutable.com/docs/sdks/unity/faq.md)
>
> Common questions about SDK architecture


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.