chore: Update platform-specific handling and improve macOS build script for better clarity and functionality

Author: juicycleff

README.md

@@ -260,7 +260,7 @@ Game Engine (Unity/Unreal)
 |----------|--------------|-------|--------|--------|
 | Android  | ✅ Ready     | ✅ Ready | 🚧 WIP | Stable |
 | iOS      | ✅ Ready     | ✅ Ready | 🚧 WIP | Stable |
-| Web      | ✅ Ready     | 🚧 WIP | ⏳ Planned | Beta   |
+| Web      | ✅ Ready     | ✅ Ready | ⏳ Planned | Stable   |
 | macOS    | ✅ Ready     | 🚧 WIP | ⏳ Planned | Beta   |
 | Windows  | ✅ Ready     | 🚧 WIP | ⏳ Planned | Beta   |
 | Linux    | ✅ Ready     | 🚧 WIP | ⏳ Planned | Beta   |

engines/unity/dart/lib/src/unity_controller_web.dart

@@ -3,8 +3,8 @@ import 'dart:async';
 import 'dart:html' as html;
 // ignore: deprecated_member_use, avoid_web_libraries_in_flutter
 import 'dart:js' as js;
-// ignore: deprecated_member_use, avoid_web_libraries_in_flutter
-import 'dart:ui' as ui;
+// ignore: avoid_web_libraries_in_flutter
+import 'dart:ui_web' as ui_web;
 import 'package:flutter/foundation.dart';
 import 'package:gameframework/gameframework.dart';
 
@@ -47,6 +47,7 @@ class UnityControllerWeb implements GameEngineController {
   bool _disposed = false;
 
   html.DivElement? _container;
+  html.CanvasElement? _canvas;
   js.JsObject? _unityInstance;
 
   /// Message queue for messages sent before Unity is ready.
@@ -68,46 +69,52 @@ class UnityControllerWeb implements GameEngineController {
   }
 
   void _setupContainer() {
+    _canvas = html.CanvasElement()
+      ..id = '${_containerId}-canvas'
+      ..style.width = '100%'
+      ..style.height = '100%'
+      ..style.display = 'block';
+
     _container = html.DivElement()
       ..id = _containerId
       ..style.width = '100%'
       ..style.height = '100%'
-      ..style.position = 'relative';
+      ..style.position = 'relative'
+      ..append(_canvas!);
   }
 
   /// Register an HtmlElementView factory so Flutter Web can render the Unity container.
   void _registerPlatformViewFactory(int viewId) {
-    // ignore: undefined_prefixed_name, avoid_dynamic_calls
-    // ignore: deprecated_member_use
-    ui.platformViewRegistry.registerViewFactory(
+    ui_web.platformViewRegistry.registerViewFactory(
       'com.xraph.gameframework/unity_$viewId',
       (int id) => _container!,
     );
   }
 
   void _setupMessageHandler() {
-    // Register global message handler that Unity can call
-    js.context['FlutterUnityReceiveMessage'] = (
-      String target,
-      String method,
-      String data,
-    ) {
-      _handleUnityMessage(target, method, data);
-    };
+    // Register global message handler that Unity can call.
+    // Must use js.allowInterop so Dart closures are correctly wrapped for JS→Dart
+    // parameter passing across the Wasm/JS boundary.
+    js.context['FlutterUnityReceiveMessage'] = js.allowInterop(
+      (String target, String method, String data) {
+        _handleUnityMessage(target, method, data);
+      },
+    );
 
     // Register scene load handler
-    js.context['FlutterUnitySceneLoaded'] = (
-      String name,
-      int buildIndex,
-    ) {
-      _handleSceneLoaded(name, buildIndex);
-    };
+    js.context['FlutterUnitySceneLoaded'] = js.allowInterop(
+      (String name, int buildIndex) {
+        _handleSceneLoaded(name, buildIndex);
+      },
+    );
   }
 
   void _handleUnityMessage(String target, String method, String data) {
     if (_disposed) return;
 
     _messageController.add(GameEngineMessage(
+      target: target,
+      method: method,
       data: data,
       timestamp: DateTime.now(),
       metadata: {
@@ -219,9 +226,12 @@ class UnityControllerWeb implements GameEngineController {
         _emitProgress(0.3 + (progress * 0.6));
       });
 
-      // Call createUnityInstance with progress callback
+      // Call createUnityInstance with the canvas element (not the div wrapper).
+      // Unity's framework.js patches canvas.getContext (Safari WebGL2 fix) which
+      // requires an actual <canvas> element — passing a <div> causes
+      // "canvas.getContextSafariWebGL2Fixed is not a function".
       final instancePromise = createUnityInstance.apply([
-        _container,
+        _canvas,
         config,
         progressCallback,
       ]);
@@ -286,6 +296,27 @@ class UnityControllerWeb implements GameEngineController {
   }
 
   /// Flush all queued messages to Unity.
+  /// Encode a message as the JSON envelope FlutterBridge.ReceiveMessage expects.
+  /// This matches the native iOS/Android format so MessageRouter can dispatch
+  /// via [FlutterMethod] attributes regardless of C# method name casing.
+  String _makeEnvelope(String target, String method, String data) {
+    // Escape the data string for embedding in JSON.
+    final escapedData = data
+        .replaceAll('\\', '\\\\')
+        .replaceAll('"', '\\"')
+        .replaceAll('\n', '\\n')
+        .replaceAll('\r', '\\r')
+        .replaceAll('\t', '\\t');
+    return '{"target":"$target","method":"$method","data":"$escapedData"}';
+  }
+
+  /// Call unityInstance.SendMessage directly without envelope wrapping.
+  /// Used internally for messages that are already formatted as envelopes
+  /// (e.g. pause/resume routing to FlutterBridge.ReceiveMessage directly).
+  void _callUnityDirect(String gameObject, String method, String data) {
+    _unityInstance?.callMethod('SendMessage', [gameObject, method, data]);
+  }
+
   void _flushMessageQueue() {
     if (_messageQueue.isEmpty) return;
 
@@ -297,10 +328,12 @@ class UnityControllerWeb implements GameEngineController {
 
     for (final msg in messages) {
       try {
+        // Route through FlutterBridge.ReceiveMessage so MessageRouter handles
+        // [FlutterMethod] dispatch — same path as native iOS/Android.
         _unityInstance?.callMethod('SendMessage', [
-          msg.target,
-          msg.method,
-          msg.data,
+          'FlutterBridge',
+          'ReceiveMessage',
+          _makeEnvelope(msg.target, msg.method, msg.data),
         ]);
       } catch (e) {
         debugPrint('Failed to flush queued message ${msg.target}.${msg.method}: $e');
@@ -326,7 +359,15 @@ class UnityControllerWeb implements GameEngineController {
     }
 
     try {
-      _unityInstance!.callMethod('SendMessage', [target, method, data]);
+      // Route through FlutterBridge.ReceiveMessage so MessageRouter handles
+      // [FlutterMethod] dispatch — same path as native iOS/Android.
+      // Direct unityInstance.SendMessage(target, method, data) bypasses the
+      // router and requires exact C# method names (case-sensitive on WebGL).
+      _unityInstance!.callMethod('SendMessage', [
+        'FlutterBridge',
+        'ReceiveMessage',
+        _makeEnvelope(target, method, data),
+      ]);
     } catch (e) {
       throw EngineCommunicationException(
         'Failed to send message to Unity WebGL: $e',
@@ -354,8 +395,9 @@ class UnityControllerWeb implements GameEngineController {
 
     try {
       // Unity WebGL doesn't have direct pause API, so we send a message
-      // to the FlutterBridge in Unity which calls NativeAPI.Pause(true)
-      await sendMessage('FlutterBridge', 'ReceiveMessage',
+      // to the FlutterBridge in Unity which calls NativeAPI.Pause(true).
+      // Use _callUnityDirect — the JSON is already a proper envelope.
+      _callUnityDirect('FlutterBridge', 'ReceiveMessage',
           '{"target":"NativeAPI","method":"Pause","data":"true"}');
       _isPaused = true;
 
@@ -378,7 +420,7 @@ class UnityControllerWeb implements GameEngineController {
     if (!_isReady) return;
 
     try {
-      await sendMessage('FlutterBridge', 'ReceiveMessage',
+      _callUnityDirect('FlutterBridge', 'ReceiveMessage',
           '{"target":"NativeAPI","method":"Pause","data":"false"}');
       _isPaused = false;
 

engines/unity/plugin/Editor/FlutterBuildScript.cs

@@ -350,8 +350,8 @@ private static void ConfigureWebGLSettings(bool isDevelopment)
         }
 
         /// <summary>
-        /// Build for macOS - exports as Xcode project (source) only. IL2CPP is required.
-        /// The game-cli builds the Xcode project and assembles UnityFramework.framework.
+        /// Build for macOS - exports as Xcode project (source) when IL2CPP is available,
+        /// or as .app bundle when using Mono. The game-cli handles both cases.
         /// </summary>
         [MenuItem("Game Framework/Build macOS")]
         public static void BuildMacos()
@@ -378,33 +378,49 @@ public static void BuildMacos()
                 Directory.CreateDirectory(buildPath);
             }
 
-            // Configure macOS settings; require IL2CPP for Xcode project export
+            // Configure macOS settings (attempts IL2CPP + Xcode project)
             bool isIL2CPP = ConfigureMacOSSettings();
-            if (!isIL2CPP)
+
+            // When IL2CPP is active, request an Xcode project export (mirrors iOS).
+            // With Mono, Unity only produces a .app bundle; the CLI will extract
+            // UnityFramework from it and warn the user to switch to IL2CPP.
+            bool xcodeProjectRequested = false;
+            if (isIL2CPP)
             {
-                Debug.LogError("macOS build requires IL2CPP scripting backend.");
-                Debug.LogError("Install Mac Build Support (IL2CPP) via Unity Hub > Installs > your version > Add Modules.");
-                Debug.LogError("Then set Edit > Project Settings > Player > macOS > Other Settings > Scripting Backend to IL2CPP.");
-                EditorApplication.Exit(1);
-                return;
+                try
+                {
+                    EditorUserBuildSettings.SetPlatformSettings("OSXUniversal", "CreateXcodeProject", "true");
+                    xcodeProjectRequested = true;
+                    Debug.Log("Requested Xcode project export (IL2CPP + CreateXcodeProject)");
+                }
+                catch (System.Exception e)
+                {
+                    Debug.LogWarning($"SetPlatformSettings failed (Unity 6 Build Profiles may override): {e.Message}");
+                }
             }
 
-            // Request Xcode project export (mirrors iOS; game-cli assembles UnityFramework from build products)
-            try
+            // Determine the output path.
+            // For Xcode project: the build path is used as the project directory.
+            // For .app binary: Unity expects the path to end with .app.
+            string appName = PlayerSettings.productName;
+            if (string.IsNullOrEmpty(appName)) appName = "UnityGame";
+
+            string locationPath;
+            if (xcodeProjectRequested)
             {
-                EditorUserBuildSettings.SetPlatformSettings("OSXUniversal", "CreateXcodeProject", "true");
-                Debug.Log("Requested Xcode project export (CreateXcodeProject=true)");
+                // Xcode project mode: Unity puts the .xcodeproj inside this directory
+                locationPath = buildPath;
             }
-            catch (System.Exception e)
+            else
             {
-                Debug.LogWarning($"SetPlatformSettings failed (Unity 6 Build Profiles may override): {e.Message}");
+                // .app mode: Unity needs a path ending in .app
+                locationPath = Path.Combine(buildPath, appName + ".app");
             }
 
-            // Always export to build path as Xcode project directory
             BuildPlayerOptions buildPlayerOptions = new BuildPlayerOptions
             {
                 scenes = GetScenes(),
-                locationPathName = buildPath,
+                locationPathName = locationPath,
                 target = BuildTarget.StandaloneOSX,
                 options = BuildOptions.None
             };
@@ -414,7 +430,9 @@ public static void BuildMacos()
                 buildPlayerOptions.options |= BuildOptions.Development;
             }
 
-            Debug.Log($"Building to: {buildPath}");
+            Debug.Log($"Building to: {locationPath}");
+            Debug.Log($"Xcode project requested: {xcodeProjectRequested}");
+            Debug.Log($"IL2CPP: {isIL2CPP}");
             Debug.Log($"Development: {isDevelopment}");
             Debug.Log($"Streaming Enabled: {streamingEnabled}");
 
@@ -425,7 +443,7 @@ public static void BuildMacos()
             {
                 Debug.Log($"macOS build succeeded: {summary.totalSize} bytes");
 
-                // Verify Xcode project was produced; fail if not
+                // Verify output type
                 bool hasXcodeProj = false;
                 foreach (string dir in Directory.GetDirectories(buildPath))
                 {
@@ -439,11 +457,10 @@ public static void BuildMacos()
 
                 if (!hasXcodeProj)
                 {
-                    Debug.LogError("Build did not produce an Xcode project. A .app bundle was produced instead.");
-                    Debug.LogError("Enable 'Create Xcode Project' in Build Profiles (Edit > Project Settings > Build) for macOS.");
-                    Debug.LogError("Then re-run the build.");
-                    EditorApplication.Exit(1);
-                    return;
+                    Debug.LogWarning("Build produced .app instead of Xcode project.");
+                    Debug.LogWarning("This can happen when using Mono or when CreateXcodeProject is overridden by Build Profiles.");
+                    Debug.LogWarning("For best results, set IL2CPP as the scripting backend and enable 'Create Xcode Project' in Build Profiles.");
+                    Debug.Log("The game-cli will extract UnityFramework from the .app bundle as a fallback.");
                 }
 
                 EditorApplication.Exit(0);

example/lib/main.dart

@@ -153,7 +153,7 @@ class _UnityExampleScreenState extends State<UnityExampleScreen>
 
   // UI State
   bool _isPanelExpanded = false;
-  bool _showMiniHud = true;
+  final bool _showMiniHud = true;
   late AnimationController _panelAnimationController;
   late Animation<double> _panelAnimation;
 
@@ -294,7 +294,7 @@ class _UnityExampleScreenState extends State<UnityExampleScreen>
         child: Row(
           mainAxisSize: MainAxisSize.min,
           children: [
-            Icon(
+            const Icon(
               Icons.speed,
               color: Colors.amber,
               size: 18,
@@ -420,7 +420,7 @@ class _UnityExampleScreenState extends State<UnityExampleScreen>
                 padding: const EdgeInsets.symmetric(horizontal: 20),
                 child: Row(
                   children: [
-                    Icon(Icons.speed, color: Colors.amber, size: 20),
+                    const Icon(Icons.speed, color: Colors.amber, size: 20),
                     const SizedBox(width: 8),
                     Expanded(
                       child: SliderTheme(
@@ -602,7 +602,7 @@ class _UnityExampleScreenState extends State<UnityExampleScreen>
             const SizedBox(width: 4),
             Text(
               label,
-              style: TextStyle(color: Colors.white54, fontSize: 11),
+              style: const TextStyle(color: Colors.white54, fontSize: 11),
             ),
           ],
         ),