Unity WebGL Platform¶

IntelliVerseX runs natively in the browser via Unity's WebGL build target. All HTTP/WebSocket-based modules work out of the box; a few require WebGL-specific adapters shipped with the SDK.

Unity WebGL Build Pipeline¶

Player Settings¶

Configure these in Edit → Project Settings → Player → WebGL:

Compile Defines¶

IntelliVerseX gates WebGL-specific code behind preprocessor defines:

#if UNITY_WEBGL && !UNITY_EDITOR
    IVXWebGLBridge.InitializeJSPlugins();
    IVXWebGLAdsManager.Instance.LoadAdSenseBanner();
#endif

UNITY_WEBGL is set automatically by Unity when the active build target is WebGL. The SDK checks for !UNITY_EDITOR to avoid calling .jslib functions during Play Mode.

Build Size Optimization¶

• Strip Engine Code — Enable in Player Settings → Other Settings → Strip Engine Code
• Managed Stripping Level — Set to High (or Minimal if reflection issues arise)
• Disable unused modules — Uncheck Physics, Cloth, etc. in Player Settings → WebGL → Modules
• Compress textures — Use ASTC / ETC2 with crunch compression
• Addressables — Move non-critical assets to remote bundles loaded on demand
• IL2CPP code generation — Set to "Faster (smaller) builds" for release

Build command (CI):
  Unity -quit -batchmode -buildTarget WebGL \
        -executeMethod BuildScript.PerformWebGLBuild \
        -logFile build.log

WebGL-Specific Limitations¶

Understanding these constraints is critical for a stable WebGL deployment.

Threading¶

System.Threading.Thread is not available. Unity's WebGL backend runs single-threaded on the browser's main thread.

IntelliVerseX avoids System.Threading internally; all async operations use UniTask or coroutines on WebGL.

Networking¶

System.Net.Sockets is not available. All network calls must go through:

• UnityWebRequest — HTTP calls (used by Nakama REST client, Hiro RPCs, Satori)
• Browser WebSocket — Real-time connections (Nakama socket uses the native browser API automatically)
• .jslib interop — For custom JavaScript APIs (e.g., Applixir ads, AdSense, WebXR)

// Nakama auto-selects the correct transport on WebGL
var client = new Client("http", "nakama.example.com", 7350, "serverkey");
var socket = client.NewSocket(useMainThread: true);  // browser WebSocket

Audio¶

Unity's FMOD-based AudioSource is replaced by the WebAudio API on WebGL. Differences:

• Playback must start from a user gesture (click/tap) — autoplay is blocked by browsers
• Compressed audio uses browser decoding — prefer .ogg (wide support) or .mp3
• AudioSource.time seeking can be less precise

File System¶

There is no direct file system. Unity maps Application.persistentDataPath to IndexedDB:

// This works — Unity abstracts to IndexedDB
string path = Path.Combine(Application.persistentDataPath, "save.json");
File.WriteAllText(path, json);

// PlayerPrefs also persists to IndexedDB
PlayerPrefs.SetString("session_token", token);

Memory¶

WebGL runs inside a WebAssembly linear memory buffer. The default 256 MB is often insufficient.

• Set Initial Memory to 512 MB for typical games
• Set Maximum Memory to 2048 MB (browsers cap at ~4 GB)
• Monitor with Profiler.GetTotalAllocatedMemoryLong() in debug builds
• Memory cannot be freed back to the OS once allocated — avoid spikes

SDK Module Compatibility¶

Module	WebGL	Notes
Identity		Fingerprint-based guest ID via DeviceInfoHelper WebGL branch; no native keychain
Ads		IVXWebGLAdsManager with AdSense + Applixir via .jslib plugin
Monetization		IVXWebGLMonetizationManager for web payment flows (Stripe, PayPal)
AI Voice/Host		WebSocket via ConnectWebGL() coroutine; TTS uses Web Speech API fallback
Multiplayer		Nakama WebSocket works natively in browser
Hiro / Economy		All RPC-based, works over HTTP via UnityWebRequest
Satori Analytics		HTTP-based event capture
Quiz		S3 content fetch works via UnityWebRequest
Storage		Nakama cloud storage over HTTP
Social / Discord	Partial	API calls work; Rich Presence not available in browser context
Leaderboards		HTTP-based, fully functional
Localization		Local JSON bundles load from StreamingAssets

WebGL Ad Integration¶

The SDK ships a .jslib bridge for web ads:

// Assets/_IntelliVerseXSDK/Plugins/WebGL/IVXAdSense.jslib
mergeInto(LibraryManager.library, {
    IVXAdSense_ShowBanner: function(adSlotPtr) {
        var adSlot = UTF8ToString(adSlotPtr);
        // injects <ins class="adsbygoogle"> into the page
    }
});

// Assets/_IntelliVerseXSDK/Plugins/WebGL/IVXApplixir.jslib
mergeInto(LibraryManager.library, {
    IVXApplixir_ShowRewarded: function(callbackObjPtr, callbackMethodPtr) {
        invokeApplixirVideo({
            zoneId: window.IVX_APPLIXIR_ZONE,
            accountId: window.IVX_APPLIXIR_ACCOUNT,
            callback: function(result) {
                SendMessage(UTF8ToString(callbackObjPtr),
                            UTF8ToString(callbackMethodPtr),
                            result);
            }
        });
    }
});

Hosting Requirements¶

HTTPS¶

WebGL builds must be served over HTTPS in production. Browsers block mixed content, which means:

• WebSocket connections to Nakama (wss://) require the page itself to be https://
• Non-secure origins cannot access navigator.mediaDevices (needed for voice)

CORS Headers¶

If quiz content or remote assets are hosted on a different origin (e.g., S3), the bucket must return proper CORS headers:

Access-Control-Allow-Origin: https://yourgame.example.com
Access-Control-Allow-Methods: GET, HEAD
Access-Control-Allow-Headers: Content-Type

SharedArrayBuffer Headers¶

If you enable Unity's multi-threaded WebAssembly (experimental), the host must set:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Recommended Hosting Providers¶

Example _headers file (Cloudflare Pages / Netlify):

/*
  Cross-Origin-Opener-Policy: same-origin
  Cross-Origin-Embedder-Policy: require-corp
  X-Content-Type-Options: nosniff

/Build/*
  Content-Encoding: br
  Content-Type: application/wasm

WebGL Template¶

IntelliVerseX provides a custom WebGL template at Assets/_IntelliVerseXSDK/WebGLTemplates/IntelliVerseX/:

WebGLTemplates/IntelliVerseX/
├── index.html          # Main page with ad containers and loader
├── style.css           # Responsive canvas styling
├── TemplateData/
│   ├── progress.js     # Custom loading bar
│   └── favicon.ico
└── ivx-bridge.js       # SDK ↔ browser bridge (ads, payments, analytics)

Select it in Player Settings → WebGL → Resolution and Presentation → WebGL Template.

CI/CD¶

WebGL builds are already configured in the project CI pipeline:

# .github/workflows/unity-tests.yml (excerpt)
- name: Build WebGL
  uses: game-ci/unity-builder@v4
  with:
    targetPlatform: WebGL
    buildMethod: BuildScript.PerformWebGLBuild

Post-Build Steps¶

1. Compress — Ensure Brotli .br files are generated (Unity does this automatically)
2. Deploy — Upload Build/ folder to your static host
3. Verify headers — curl -I https://yourgame.example.com/Build/game.wasm should return Content-Encoding: br
4. Smoke test — Open in Chrome, Firefox, Safari; check console for WebSocket connection

Debugging¶

Browser DevTools¶

• Console — Unity Debug.Log maps to console.log; filter by [IVX] prefix
• Network — Inspect Nakama HTTP/WebSocket traffic
• Memory — Chrome's Memory tab shows WASM heap usage
• Performance — Profile frame drops; look for JS ↔ WASM interop overhead

Development Build¶

Enable Development Build + Autoconnect Profiler in Build Settings for:

• Source maps (readable stack traces)
• Unity Profiler connection over WebSocket
• Debug.Assert is active

Troubleshooting¶