> ## 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.

<Info>
  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.
</Info>

## 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](/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?](/docs/sdks/unity/faq) for details.
</Warning>

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.
</Warning>

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.
</Tip>

## Related Documentation

<CardGroup cols={2}>
  <Card title="Unity SDK" icon="unity" href="/docs/sdks/unity/overview">
    Unity SDK implementation
  </Card>

  <Card title="Unreal SDK" icon="https://mintcdn.com/immutable-b818fae7/aPl7c1S4nykO3QqA/icons/unreal.svg?fit=max&auto=format&n=aPl7c1S4nykO3QqA&q=85&s=d1ca3198e0ed3d81cf4ef9653505c86c" href="/docs/sdks/unreal/overview" width="24" height="24" data-path="icons/unreal.svg">
    Unreal SDK implementation
  </Card>

  <Card title="TypeScript SDK" icon="code" href="/docs/sdks/typescript/overview">
    Core TypeScript packages
  </Card>

  <Card title="Game Bridge Package" icon="github" href="https://github.com/immutable/ts-immutable-sdk/tree/main/packages/game-bridge">
    Game bridge source code
  </Card>

  <Card title="SDK FAQ" icon="question" href="/docs/sdks/unity/faq">
    Common questions about SDK architecture
  </Card>
</CardGroup>