By Published on

UE5 + Pico Neo3 全流程部署指南

UE5 + Pico Neo3 全流程部署指南

Android 10 / SDK 29 / Unreal Engine 5.4+ 实战手册

01. 环境准备与先决条件

🛠️ 核心软件栈

软件名称用途关键说明
Android StudioSDK/NDK 管理含 ADB 工具链
Android NDK原生代码编译需 r23b 或更高版本
PICO Developer Center设备管理与调试✅ 强烈推荐
PICO SDK for UnrealUE 插件提供手柄、Passthrough 支持

⚙️ 环境变量 (Windows)

确保以下路径已添加到系统 PATH 中：

%ANDROID_HOME%\platform-tools %ANDROID_HOME%\tools %ANDROID_HOME%\ndk\23.1.7779620 (具体版本视安装而定)

02. Unreal Engine 项目配置

🔌 插件安装

  1. 下载 PICO Unreal Plugin 并解压到 YourProject/Plugins/PICOXR/。
  2. 重启 UE，打开 Edit > Plugins，启用 PICO XR Plugin。
  3. 设置 Device Type 为 PICO Neo3。

📱 Android 平台设置

路径：Project Settings > Platforms > Android

Min SDK Version29Neo3 仅支持到 Android 10
Target SDK Version30官方推荐
NDK API Levelandroid-29需与 Min SDK 匹配
Texture FormatASTCPico 推荐格式
⚠️
关键警告：串流预览崩溃问题
若使用串流预览，必须在 Editor Preferences > Rendering 中将 Default RHI 改为 DirectX 11。默认的 DirectX 12 会导致编辑器崩溃。

03. 打包与部署流程

📦 打包步骤

在 UE 中执行：File > Package Project > Android > Android (ASTC)。

输出文件包括：

  • ProjectName-arm64.apk
  • main.1.com.Company.Project.obb (如启用 OBB)

📂 OBB 资源部署 (关键)

OBB 文件必须手动推送到指定目录，否则应用启动会黑屏。

# 1. 创建目录 adb shell mkdir -p /sdcard/Android/obb/com.YourCompany.YourProject

2. 推送文件 (注意文件名必须包含 main.版本号)

adb push “D:\Path\To\main.1.com.YourCompany.YourProject.obb” /sdcard/Android/obb/com.YourCompany.YourProject/

✅
验证命令：
adb shell ls -l /sdcard/Android/obb/com.YourCompany.YourProject/
确保文件存在且大小与本地一致。

04. 常见问题与排查 (Troubleshooting)

❌ INSTALL_FAILED_OLDER_SDK
APK 的 MinSDK 高于设备系统版本。请确保 UE 设置中 Min SDK Version = 29。
⏳ 启动卡在加载页/黑屏
通常是 OBB 缺失或路径错误。请检查 /sdcard/Android/obb/包名/ 下是否有对应的 .obb 文件。
💥 UE 串流预览崩溃
DirectX 12 兼容性问题。请切换 RHI 为 DirectX 11。
📉 射线无法点击 UI
Widget Interaction 组件的 Interaction Distance 太短。根据 UI 距离增加该值（如设为 2000）。

05. 性能优化与规范

  • OBB 2GB 限制：
    Android 单个 OBB 文件限制为 2GB。UE 会自动将超大项目拆分为多个 PAK 文件，无需手动处理。
  • GPU 内存分配失败 (Crash)：
    若日志出现 kgsl_sharedmem_alloc failed，通常是纹理或视频过大。建议视频压制到 2K，纹理限制在 2048x2048 以内。
  • 文件权限问题：
    直接 Push 到系统目录可能失败。建议先 Push 到 /sdcard/Download/，再通过 adb shell mv 命令移动。