Skip to content

t1k:unity:web:interop

FieldValue
Moduleweb
Version2.32.3
Efforthigh
Tools—

Keywords: browser-api, callbacks, dllimport, iframe, interop, javascript, jslib, unity web interop, webgl

/t1k:unity:web:interop

Create a narrow, typed boundary between Unity C# and the host browser. Keep browser behavior out of gameplay code and provide an explicit non-Web fallback.

  • The browser capability and product behavior are defined.
  • Payload shape, ownership, error behavior, user-gesture requirement, and callback lifecycle are recorded.
  • Consent, security, monetization, and host-page contracts are approved when relevant.

Generate a reviewable .jslib and C# wrapper plan:

Terminal window
bun .claude/skills/t1k-unity-web-interop/scripts/scaffold-web-interop.cjs \
BrowserShare <unity-project-root> --namespace Company.Game.Platform

When running from this source repo, use the module-local path under .claude/modules/web/skills/t1k-unity-web-interop/.

The scaffold is dry-run by default. Add --apply only after reviewing the paths and generated contract. Existing files are never overwritten, and all targets are preflighted before any write.

  1. Define the smallest C# interface the game needs; do not expose a generic arbitrary-JavaScript executor.
  2. Scaffold or manually create:
    • Assets/Plugins/WebGL/<Feature>.jslib;
    • Assets/Scripts/Platform/Web/<Feature>BrowserInterop.cs.
  3. Guard native calls with UNITY_WEBGL && !UNITY_EDITOR and return an explicit unsupported result elsewhere.
  4. Marshal strings at the call boundary and never retain Emscripten heap pointers in JavaScript.
  5. For JavaScript-to-Unity callbacks, validate the target object/method contract and payload before calling SendMessage.
  6. For async browser APIs, use correlation IDs, one terminal result, timeout/cancellation, and cleanup on scene/domain teardown.
  7. Preserve required user gestures for clipboard, audio, fullscreen, share, and permission APIs.
  8. Validate CSP, iframe sandbox/permissions policy, origin checks, and unavailable/denied behavior.
  9. Re-run /t1k:unity:web:audit, build, and /t1k:unity:web:validate.

Read references/interop-contracts.md before adding callbacks, promises, host messaging, or privileged browser APIs.

  • Capability and supported/unsupported platform behavior.
  • C# API, exported JavaScript symbols, payload schema, and ownership rules.
  • Callback/promise lifecycle, timeout, cancellation, and error mapping.
  • User-gesture, permission, CSP, iframe, and origin requirements.
  • Generated/changed files and non-Web fallback.
  • Editor/build/browser verification evidence.
  • Never evaluate arbitrary strings as JavaScript.
  • Never embed tokens, credentials, personal data, or signed URLs in source or logs.
  • Never call a privileged browser API outside its required user gesture.
  • Never trust postMessage, query-string, storage, or host-page payloads without origin/schema validation.
  • Never overwrite an existing bridge or silently replace mobile behavior.

Only the scaffold step (scripts/scaffold-web-interop.cjs) is mechanical; the interop contract and its safety boundaries are design work and stay on the reasoning tier (t1k-unity-base-developer). A cheap-tier t1k-fact-fetcher may run the scaffold and report the files it created.