文档；

README.md

@@ -1 +1,148 @@
-"Unity 集成iOS工程"
+# UnityFramework Pod
+
+Unity iOS Framework 打包为 CocoaPods，支持真机和模拟器。
+
+## 特性
+
+- ✅ 支持真机运行（完整 Unity 运行时）
+- ✅ 支持模拟器运行（空壳实现，用于开发调试）
+- ✅ XCFramework 格式，自动处理不同平台
+- ✅ 简单的升级流程
+
+## 架构支持
+
+| 平台 | 架构 | 说明 |
+|------|------|------|
+| 真机 | arm64 | 完整的 Unity 运行时 |
+| 模拟器 | arm64, x86_64 | 空壳实现，方便开发 |
+
+## 使用方法
+
+### 在 Podfile 中引入
+
+#### 使用 Git 仓库（推荐）
+
+```ruby
+pod 'UnityFramework', :git => 'https://gitea.sdws.shop/xim/flutter_unity_pod.git', :tag => '1.0.7'
+```
+
+#### 使用本地路径（开发调试）
+
+```ruby
+pod 'UnityFramework', :path => '/path/to/flutter_unity_pod'
+```
+
+### 安装
+
+```bash
+cd ios
+pod install
+```
+
+## 升级 Framework
+
+当有新的 Unity Framework 导出时，使用自动化脚本升级：
+
+```bash
+./upgrade_framework.sh /path/to/new/UnityFramework.framework
+```
+
+详细步骤请参考 [UPGRADE_GUIDE.md](./UPGRADE_GUIDE.md)
+
+## 项目结构
+
+```
+flutter_unity_pod/
+├── UnityLibrary/
+│   └── UnityFramework.xcframework/      # 主 XCFramework
+│       ├── ios-arm64/                    # 真机版本
+│       │   └── UnityFramework.framework/
+│       └── ios-arm64_x86_64-simulator/   # 模拟器版本
+│           └── UnityFramework.framework/
+├── simulator_stub/
+│   └── UnityFrameworkStub.m              # 模拟器空壳实现
+├── build_xcframework.sh                  # 初始构建脚本
+├── upgrade_framework.sh                  # 升级脚本
+├── UPGRADE_GUIDE.md                      # 升级指南
+└── UnityFramework.podspec                # Pod 配置文件
+```
+
+## 开发说明
+
+### 模拟器行为
+
+模拟器版本是空壳实现，所有 Unity 相关方法都会返回空或不执行。当尝试在模拟器运行 Unity 时，会输出日志：
+
+```
+UnityFramework: Simulator stub - Unity not available
+```
+
+在 Flutter 代码中也有检测：
+
+```dart
+// lib/common/utils/unitygame/unity_game_manager.dart:997-1004
+if (Platform.isIOS) {
+  final isSimulator =
+      Platform.environment.containsKey('SIMULATOR_DEVICE_NAME') ||
+          Platform.environment.containsKey('SIMULATOR_UDID');
+  if (isSimulator) {
+    showToast('Unity 游戏仅支持真机运行，请在真机上体验。');
+    return;
+  }
+}
+```
+
+### 构建流程
+
+1. 编译模拟器空壳（arm64 + x86_64）
+2. 合并真机 framework
+3. 创建 XCFramework
+4. 打包为 CocoaPod
+
+## 版本历史
+
+### 1.0.7 (2024-11-25)
+- 升级到 XCFramework
+- 添加模拟器支持
+- 简化配置，移除架构排除
+
+### 1.0.6
+- 初始版本
+- 仅支持真机
+
+## 故障排除
+
+### 模拟器构建失败
+
+确保 XCFramework 包含模拟器架构：
+
+```bash
+lipo -info UnityLibrary/UnityFramework.xcframework/ios-arm64_x86_64-simulator/UnityFramework.framework/UnityFramework
+```
+
+### 真机构建失败
+
+检查真机 framework 是否完整：
+
+```bash
+ls UnityLibrary/UnityFramework.xcframework/ios-arm64/UnityFramework.framework/
+```
+
+### Pod install 失败
+
+清理缓存重试：
+
+```bash
+pod cache clean UnityFramework --all
+rm -rf Pods Podfile.lock
+pod install
+```
+
+## License
+
+MIT
+
+## 联系方式
+
+- 仓库：https://gitea.sdws.shop/xim/flutter_unity_pod
+- 问题反馈：请创建 Issue