@tpgames/unity-bridge

Initial TPG bridge for Unity WebGL exports.

Supported Runtime

• TPG SDK contract: 1.0.0
• Unity target: Unity 2022 LTS or newer WebGL builds that can call browser JavaScript and receive SendMessage callbacks
• Export preset: WebGL export with generated loader, framework, data, wasm, and streaming assets served from the same TPG bundle directory

How It Works

Host/controller pages boot a normal TPG game runtime and call createUnityBridgeGame(). On boot, the bridge exposes window.TPG_UNITY for Unity WebGL JavaScript plug-ins and relays TPG runtime updates as browser events:

• tpg:lifecycle
• tpg:loading
• tpg:settings
• tpg:participants
• tpg:shared-state
• tpg:player-state
• tpg:message

When a Unity WebGL instance is attached, the same updates are also sent to a configured GameObject with Unity's WebGL SendMessage(gameObjectName, methodName, jsonPayload) API. The default GameObject is TPGBridge, with methods such as OnTpgLifecycle, OnTpgSharedState, and OnTpgMessage.

Unity-side scripts can call the exposed runtime API through a WebGL JavaScript plug-in to report readiness, update shared/player state, broadcast controller actions, target a participant, or ask the shell to return to the lobby. Shared state is authority-only, player state is participant-owned, mutation promises return typed acknowledgement results, and sharedStateSnapshot() / playerStateSnapshot() expose revisions for optimistic concurrency.

Minimal Host Surface

import { createUnityBridgeGame } from "@tpgames/unity-bridge";
import { bootGameRuntime } from "@tpgames/runtime-game";

const unityBridgeGame = createUnityBridgeGame({
  gameObjectName: "TPGBridge"
});

bootGameRuntime(unityBridgeGame, {
  bridge,
  initialContext
});

After the Unity loader creates the instance, attach it:

const unityInstance = await createUnityInstance(canvas, config);
window.TPG_UNITY.attachUnityInstance(unityInstance);

Unity WebGL Plug-In Shape

A Unity project can add a JavaScript plug-in under Assets/Plugins/WebGL/TpgBridge.jslib that calls the browser runtime:

mergeInto(LibraryManager.library, {
  TpgReportReady() {
    window.TPG_UNITY?.reportLoading(false);
  },
  TpgBroadcastSignal(messagePtr) {
    const message = UTF8ToString(messagePtr);
    window.TPG_UNITY?.broadcast("unity:signal", { message });
  }
});

The matching C# script declares the imported functions and implements the callback methods configured on the bridge GameObject:

using System.Runtime.InteropServices;
using UnityEngine;

public sealed class TpgBridge : MonoBehaviour
{
    [DllImport("__Internal")]
    private static extern void TpgReportReady();

    public void OnTpgLifecycle(string json)
    {
        Debug.Log($"TPG lifecycle: {json}");
    }

    public void OnTpgMessage(string json)
    {
        Debug.Log($"TPG message: {json}");
    }

    public void ReportReady()
    {
        TpgReportReady();
    }
}

Manifest Helper

import { createUnityManifest } from "@tpgames/unity-bridge";

const manifest = createUnityManifest({
  gameId: "unity-jump",
  version: "0.1.0",
  title: "Unity Jump",
  hostEntry: "/unity/index.html",
  controllerEntry: "/controller.html"
});

Current Limitations

• This package provides the browser-side TPG bridge, Unity SendMessage adapter, and manifest helper. It does not run the Unity editor or create a WebGL build.
• Unity projects still need a project-side WebGL JavaScript plug-in and a GameObject with callback methods.
• Controller UI can be a normal DOM page or a second Unity WebGL export; the first bridge contract keeps host and controller entries explicit.
• Threading, compression, WebAssembly memory, and asset streaming settings must stay compatible with the target browser and TPG iframe sandbox.
• The first full Unity sample game and long-form tutorial are tracked separately so this bridge can remain a small, reusable contract package.