149 lines
3.3 KiB
Markdown
149 lines
3.3 KiB
Markdown
# 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
|