【Flutter】Flutter + Unity 插件结构与通信接口封装

关联文档：【方案分享】Flutter +Unity 跨平台三维渲染架构设计全解：插件封装、通信机制与热更新机制—— 支持 Android/iOS/Web 的 3D 内容嵌入与远程资源管理，助力 XR 项目落地

—— 支持 Android/iOS/Web 的 3D 内容嵌入与远程资源管理，助力 XR 项目企业级开发落地
适用场景：三维内容（模型/动画/场景）需要跨平台（Android/iOS/Web）展示，UI 用 Flutter 实现，Unity 作为底层 3D 渲染引擎，支持热更新、场景管理与统一接口通信。

---

Flutter + Unity 插件结构与通信接口封装

1. 插件封装的目标

为了将 Unity 跨平台三维渲染能力集成至 Flutter 应用中，我们需要封装一套统一的插件结构，屏蔽 Android/iOS/Web 三端差异，同时提供一致的 Dart API 与通信机制。

目标如下：

• 实现统一的插件入口与注册流程
• 管理 Unity 实例生命周期（初始化、销毁、复用）
• 建立 Dart 与 Unity 的通信桥梁
• 提供跨端一致的功能调用接口与事件回调机制

---

2. 插件结构总览

Flutter 插件包的典型结构如下：

flutter_unity_plugin/
├── lib/
│   └── flutter_unity_plugin.dart  # Dart API 封装
├── android/
│   └── src/...                    # Android 平台代码
├── ios/
│   └── Classes/...               # iOS 平台代码
├── web/
│   └── unity_web_view.dart       # Web 平台 iframe 管理
├── example/
│   └── demo_app/                 # 示例项目
├── pubspec.yaml

---

3. Dart 层封装设计

3.1 UnityWidget

核心组件为 UnityWidget，用于在页面中嵌入 Unity 渲染视图：

class UnityWidget extends StatefulWidget {
  final void Function(UnityController)? onUnityCreated;
  ...
}

3.2 UnityController

用于操作 Unity 实例和通信：

class UnityController {
  Future<void> send(String method, Map<String, dynamic> params);
  Future<void> dispose();
  Stream<UnityEvent> get onUnityMessage;
}

---

4. 通信机制封装

4.1 Dart ↔ Native 通信

使用标准的 MethodChannel 和 EventChannel 实现：

static const MethodChannel _channel = MethodChannel('flutter_unity_plugin');
static const EventChannel _eventChannel = EventChannel('flutter_unity_plugin/events');

调用示例：

await _channel.invokeMethod('sendMessage', {
  'object': 'GameManager',
  'method': 'LoadScene',
  'message': json.encode(params),
});

事件监听：

_eventChannel.receiveBroadcastStream().listen((data) {
  final event = UnityEvent.fromJson(data);
  _eventController.add(event);
});

4.2 Native ↔ Unity 通信

Android：

UnityPlayer.UnitySendMessage("GameManager", "LoadScene", message);

iOS：

UnityFramework.getInstance()?.sendMessageToGO(withName: "GameManager", functionName: "LoadScene", message: message)

Web（postMessage）：

unityInstance.SendMessage('GameManager', 'LoadScene', message);

---

5. 跨平台通信协议设计

使用统一结构的 JSON 通信协议：

5.1 Flutter → Unity

{
  "cmd": "loadScene",
  "params": {
    "sceneName": "lobby",
    "userId": "abc123"
  }
}

5.2 Unity → Flutter

{
  "event": "sceneLoaded",
  "scene": "lobby",
  "timestamp": 1710000000
}

可封装为 Dart 类以便类型安全：

class UnityEvent {
  final String event;
  final Map<String, dynamic> payload;
}

---

6. 生命周期与状态管理

插件建议实现如下生命周期方法：

• initUnity() 初始化 Unity 实例
• sendMessage() 通信
• pauseUnity() 暂停渲染（如切后台）
• resumeUnity() 恢复渲染
• disposeUnity() 销毁 Unity 实例，释放资源

状态管理建议结合 Provider 或 Bloc 实现，统一监听 Unity 渲染状态。

---

7. 示例代码片段

final unityController = UnityController();

await unityController.send('loadScene', {
  'sceneName': 'museum',
  'theme': 'dark'
});

unityController.onUnityMessage.listen((event) {
  print('Received event from Unity: ${event.event}');
});

---