t1k:unity:web:interop
| Field | Value |
|---|---|
| Module | web |
| Version | 2.32.3 |
| Effort | high |
| Tools | — |
Keywords: browser-api, callbacks, dllimport, iframe, interop, javascript, jslib, unity web interop, webgl
How to invoke
Section titled “How to invoke”/t1k:unity:web:interopImplement Unity Web Browser Interop
Section titled “Implement Unity Web Browser 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.
Preconditions
Section titled “Preconditions”- 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.
Scaffold
Section titled “Scaffold”Generate a reviewable .jslib and C# wrapper plan:
bun .claude/skills/t1k-unity-web-interop/scripts/scaffold-web-interop.cjs \ BrowserShare <unity-project-root> --namespace Company.Game.PlatformWhen 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.
Workflow
Section titled “Workflow”- Define the smallest C# interface the game needs; do not expose a generic arbitrary-JavaScript executor.
- Scaffold or manually create:
Assets/Plugins/WebGL/<Feature>.jslib;Assets/Scripts/Platform/Web/<Feature>BrowserInterop.cs.
- Guard native calls with
UNITY_WEBGL && !UNITY_EDITORand return an explicit unsupported result elsewhere. - Marshal strings at the call boundary and never retain Emscripten heap pointers in JavaScript.
- For JavaScript-to-Unity callbacks, validate the target object/method contract and payload before
calling
SendMessage. - For async browser APIs, use correlation IDs, one terminal result, timeout/cancellation, and cleanup on scene/domain teardown.
- Preserve required user gestures for clipboard, audio, fullscreen, share, and permission APIs.
- Validate CSP, iframe sandbox/permissions policy, origin checks, and unavailable/denied behavior.
- 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.
Required output
Section titled “Required output”- 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.
Safety boundaries
Section titled “Safety boundaries”- 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.
Executed by
Section titled “Executed by”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.