How tlabaltoh/tlabwebview works
1. What this repo is
- TLabWebView is a Unity package that embeds an Android browser component (WebView or GeckoView) into Unity UI by rendering the page into a texture and presenting it as uGUI.
- The package is split into a managed Unity/C# layer and an Android native plugin layer.
2. Top-level architectural boundary
- The main boundary is Unity runtime code in Runtime/ versus Android native code packaged as Plugins/Android/libTLabWebView-release.aar.
- C# code orchestrates browser instances, input, UI widgets, and capture strategy; the Android plugin owns the actual browser engine and platform-specific rendering.
3. Core runtime coordination
- BrowserManager is the scene-level entry point; the README says it should be added to a GameObject and it coordinates browser lifecycle for the scene.
- BrowserContainer appears to be the per-instance holder that binds a browser engine, rendering mode, and Unity-facing object graph.
- Browser, WebView, and GeckoView define the main browser abstraction and engine-specific implementations.
4. Browser abstraction and instance model
- IBrowser is the key interface boundary for browser engines.
- Browser/WebView/GeckoView are likely the managed façade over the Android component, while BrowserContainer and BrowserManager handle instance creation, reuse, and concurrent browsers.
- The README explicitly supports multiple browser instances running concurrently.
5. Rendering pipeline
- This plugin’s main function is to convert browser output into a Unity-consumable surface/texture.
- IOffscreen and FragmentCapture indicate the offscreen capture path from Android rendering into Unity.
- The README lists three capture/rendering methods that materially shape the architecture:
- HardwareBuffer: Android low-level, highest performance
- ByteBuffer: C# receives frames as byte arrays, default/stable path
- Surface: direct rendering to Android Surface, useful for layered composition use cases
6. Native plugin responsibilities
- NativePlugin is the C# bridge to the Android .aar.
- The native side is where browser creation, page loading, frame capture, and platform-specific browser interactions happen.
- Plugins/Android/copy.bat and the packaged AAR indicate the plugin is distributed as a prebuilt Android binary, not source in this repo.
7. Input and interaction flow
- Input flows from Unity UI/EventSystem into browser input adapters: BaseInputListener, BrowserInputListener, and BrowserInputField.
- This layer handles keyboard focus, touch interaction, and text entry mapping between Unity and the browser component.
- The README emphasizes support for keyboard input and touch interaction, which are central to the runtime behavior.
8. UI overlay widgets
- The Runtime/Widget/ subsystem provides Unity-side replacements for browser UI that Android browser engines don’t expose well or don’t support consistently.
- Widgets include AlertDialog, AuthWidget, ColorWidget, DateTimeWidget, NumberPicker, SelectWidget, and TextWidget.
- This forms a second UI boundary: browser page events can trigger native-style Unity widgets instead of relying only on browser-internal dialogs/forms.
9. Message passing and JS integration
- Runtime/Common.cs and sample scripts suggest a JS-to-C# bridge.
- For WebView, the README mentions window.tlab as the browser-side JavaScript interface.
- For GeckoView, that interface is not fully supported yet; pages send messages through window.postMessage with a special payload format instead. This is an important engine-specific integration boundary.
10. Sample and test subsystems
- Runtime/Sample/ and Runtime/Test/ are not core architecture, but they document and validate the plugin’s behavior.
- Samples cover browser usage, background rendering, download handling, focus interactions, local file loading, JS snippets, and widget scenarios.
- Tests such as BrowserAPITest, LoadUnloadTest, and OnMessageTest indicate the main integration seams: lifecycle, message routing, and cleanup.
11. Packaging and editor-time build integration
- Runtime/TLab.WebView.Runtime.asmdef and Editor/TLab.WebView.Editor.asmdef split runtime and editor concerns.
- Editor/Scripts/UnityWebViewPostprocessBuild.cs is the build-time hook that likely injects Android settings, dependencies, and packaging steps.
- Editor/MediationAdapterDependencies.xml suggests Android dependency management during build, not during runtime.
12. Assets and prefab-based entry points
- Resources/TLab/WebView/Browser.prefab is the primary reusable prefab that binds the runtime pieces into a drop-in UI component.
- Additional sample prefabs under Resources/TLab/WebView/Samples/ show concrete compositions for browser views and widgets.
- Samples/Scenes/ provides example Unity scenes that demonstrate the intended object graph and scene setup.
13. Platform and runtime constraints
- This is an Android-only runtime; the README notes it does not display pages in the Unity Editor.
- The supported graphics/runtime conditions matter architecturally: Android 10–14, Unity 2021/2022/6000, OpenGLES or Vulkan, with some rendering modes being more stable under OpenGLES.
- GeckoView requires higher Android/API and additional Gradle dependencies, making it a conditional backend rather than the default path.
14. External dependencies and permissions
- The package depends on a companion keyboard package (TLabVKeyborad) and, for GeckoView, external Android/Gradle dependencies plus a separate GeckoView AAR.
- Build-time flags and Android permissions control capabilities like cleartext traffic, camera/microphone access, and external storage downloads.
- These are not just configuration details: they affect whether the browser backend can access certain web features and file operations.
15. Overall data flow
- User input enters Unity UI → BrowserManager/BrowserContainer route it to the selected browser engine → Android native plugin executes browser actions and renders frames → frames are captured via the selected offscreen mode → Unity displays them as a texture in the prefab/UI.
- Browser-to-Unity communication flows back through JS messaging and callbacks, with widget overlays handling cases where browser engine behavior is insufficient or inconsistent.
Main entry points: Browser.cs Browser · BrowserContainer.cs Browser Container · NativePlugin.cs Native Plugin · BrowserInputListener.cs Browser Input
Components 22
Runtime
Unity managed browser orchestration, rendering, input, and widgets.
- Browser Manager · Scene-level entry point that coordinates browser lifecycle and instance wiring.
Runtime/BrowserManager.cs - Browser Container · Per-browser Unity-side container that binds engine, capture mode, and presentation.
Runtime/BrowserContainer.cs - Browser · High-level browser abstraction used by Unity code to drive page loading and state.
Runtime/Browser.cs - WebView · Managed implementation for the Android WebView-backed browser path.
Runtime/WebView.cs - GeckoView · Managed implementation for the GeckoView-backed browser path.
Runtime/GeckoView.cs - IBrowser · Interface boundary for browser engines and their Unity-facing operations.
Runtime/IBrowser.cs - Offscreen Capture · Abstraction for converting browser output into Unity-consumable frames.
Runtime/IOffscreen.cs - Fragment Capture · Unity-side capture implementation for browser rendering fragments and frame transfer.
Runtime/FragmentCapture.cs - Native Plugin · C# bridge to the packaged Android AAR for browser creation, loading, and capture.
Runtime/NativePlugin.cs - Input Layer · Base input listener layer that maps Unity events to browser interaction.
Runtime/BaseInputListener.cs - Browser Input · Browser-specific input handling for touch, focus, and keyboard interaction.
Runtime/BrowserInputListener.cs - Input Field · Unity text-entry bridge for browser forms and keyboard focus behavior.
Runtime/BrowserInputField.cs - Widgets · Unity-side replacement widgets for browser dialogs and form controls.
Runtime/Widget/Widget.cs - JS Bridge · Shared browser-to-Unity messaging and common integration helpers.
Runtime/Common.cs - Runtime asmdef · Unity assembly boundary for the runtime package.
Runtime/TLab.WebView.Runtime.asmdef
Android Plugin
Prebuilt Android browser engine and capture backend.
- Android AAR · Prebuilt Android plugin containing the actual browser engine and platform rendering.
Plugins/Android/libTLabWebView-release.aar - Copy Script · Build/distribution helper for moving the Android plugin into place.
Plugins/Android/copy.bat
Editor
Build-time integration and Android dependency setup.
- Postprocess Build · Editor build hook that injects Android packaging and dependency settings.
Editor/Scripts/UnityWebViewPostprocessBuild.cs - Deps XML · Editor-time Android dependency configuration for packaging and mediation.
Editor/MediationAdapterDependencies.xml - Editor asmdef · Unity assembly boundary for editor-only tooling.
Editor/TLab.WebView.Editor.asmdef
Samples
Example scenes and runtime usage patterns.
- Browser Prefab · Reusable Unity prefab that assembles the browser runtime components.
Resources/TLab/WebView/Browser.prefab - Sample Scenes · Unity scenes demonstrating setup, lifecycle, and interaction patterns.
Samples/Scenes/Mobile Sample.unity
Connections 24
- Browser Manager → Browser Container: creates · Manages per-instance browser containers for a scene.
- Browser Container → Browser: hosts · Binds the Unity container to the browser abstraction.
- Browser → IBrowser: implements · Concrete browser implementations satisfy the engine contract.
- Browser → WebView: webview mode · Selects the Android WebView backend when configured.
- Browser → GeckoView: gecko mode · Selects the GeckoView backend when configured.
- Browser Container → Offscreen Capture: captures · Connects browser output to the chosen offscreen capture path.
- Offscreen Capture → Fragment Capture: uses · Fragment capture is the Unity-side frame extraction path.
- Fragment Capture → Native Plugin: drives · Frame transfer and browser actions flow through the native bridge.
- Browser → Native Plugin: calls · Browser operations are delegated to the Android plugin bridge.
- Input Layer → Browser Input: routes to · Generic Unity input is specialized into browser interaction handling.
- Browser Input → Input Field: focuses · Text and keyboard focus are forwarded through the input field bridge.
- Browser Input → Browser Container: targets · Input is dispatched to the active browser instance container.
- Browser Container → Widgets: spawns · Browser events can open Unity overlay widgets.
- Widgets → JS Bridge: reports · Widget interactions feed back into the browser messaging layer.
- Browser → JS Bridge: messages · JS-to-C# communication is handled through the common bridge.
- JS Bridge → Native Plugin: bridges · Browser-side messaging is forwarded through native plugin callbacks.
- Postprocess Build → Deps XML: configures · Build hook applies Android dependency metadata.
- Postprocess Build → Android AAR: packages · Editor build process incorporates the Android binary plugin.
- Editor asmdef → Postprocess Build: contains · Editor assembly hosts build-time tooling.
- Copy Script → Android AAR: distributes · Packaging helper copies the prebuilt native plugin.
- Browser Prefab → Browser Manager: wires · Prefab assembles the main runtime entry point.
- Sample Scenes → Browser Prefab: demonstrates · Sample scenes show how the prefab is placed into a Unity scene.
- Runtime asmdef → Browser Manager: includes · Runtime assembly contains the managed browser stack.
- Android AAR → Native Plugin: backing engine · The bridge delegates to the packaged Android implementation.