TL;DR

  • Refract는 Android(Meta Quest) OpenXR 앱을 Windows PC의 Android Emulator에서 실행하고 PC VR 헤드셋으로 표시하는 실험적 도구임.
  • 에뮬레이터 내부의 Android OpenXR 런타임이 프레임을 PC로 보내고 헤드셋·컨트롤러 포즈를 돌려받으며, PC에서는 SteamVR을 통해 헤드셋으로 전달함.
  • 에뮬레이터에 로드되는 Vulkan 레이어가 양쪽 눈의 이미지를 공유하고, ARM64-to-x86_64 변환기가 x86_64 에뮬레이터 이미지에서 ARM64 전용 게임을 실행함.
  • Windows 11, Nvidia GPU, Android SDK·Emulator·NDK, CMake, Ninja, SteamVR이 필요하며 호환성은 문서화된 설정에 한정됨.
  • 게임 APK와 Meta SDK, Horizon OS 파일은 포함되지 않으며, 소유한 게임과 공개 샘플 테스트를 대상으로 하고 DRM·치트 방지·플랫폼 보안·스토어 제한·라이선스 조건 우회에는 사용하지 않도록 안내함.

작동 방식

  • Android Emulator에서 Android OpenXR APK를 실행하고, 다음 구성 요소를 거쳐 PC VR 헤드셋에 연결함.
  • Refract Android OpenXR 런타임(com.refract.openxrruntime)
  • Refract 프로토콜(포즈, 프레임, 입력)
  • Refract 뷰어 및 Windows 호스트 브리지
  • PC OpenXR 런타임(SteamVR)
  • 헤드셋
  • 에뮬레이터에 로드되는 Vulkan 레이어를 통해 양쪽 눈의 이미지가 공유됨.
  • 변환기가 x86_64 에뮬레이터 이미지에서 ARM64 전용 게임을 실행함.

저장소 구성

  • android-runtime/: Android OpenXR 런타임(네이티브)
  • android-runtime-apk/: 설치 가능한 런타임 APK 및 런타임 브로커
  • platform-sdk/: Meta Platform SDK 대체 구현(com.oculus.horizon 패키지)
  • protocol/: 포즈·이미지·입력 프로토콜 및 전송 방식
  • viewer/: 공유 눈 텍스처를 받아 표시하는 Windows 뷰어
  • host-bridge/: PC OpenXR 런타임용 호스트 브리지
  • launcher/: 데스크톱 런처(Tauri 및 Node 백엔드, GPL-3.0)
  • scripts/: 에뮬레이터 시작 및 게임 실행 스크립트
  • tools/: GPU 레이어, GLES 레이어, 변환기 패치, 프로브, 분석 도구
  • prebuilts/digitalis/: 사전 빌드된 ARM64-to-x86_64 변환기(Digitalis/Berberis)
  • tests/: 스모크 테스트 및 로더 프로브
  • docs/: 설정 가이드 및 설계 노트

시작하기

  • 요구 사항은 Windows 11, Nvidia GPU, Android Emulator와 NDK가 포함된 Android SDK, CMake, Ninja, SteamVR임.
  • 에뮬레이터 경로를 빌드하고 설정하며, 자세한 내용은 docs/windows_nvidia_emulator.md에 있음.
  • viewer\build.bat로 뷰어를 빌드함.
  • 게임을 시작할 때 docs/yeeps_setup.md에서 작동하는 전체 설정 예시를 확인할 수 있음. 예시 절차는 코어 6개와 숨김 모드로 에뮬레이터를 시작하고, TSC를 설정한 다음, two-gear 변환기 모드로 my-run 실행을 시작함.
  • 각 실행의 로그는 runs\<name>\에 기록됨.
  • 아키텍처, 상태, 빌드 세부 정보는 docs/overview.md에 있음.
  • 일부 스크립트에는 작성자의 Android SDK 경로(C:\Users\mixid\Android\Sdk)가 아직 고정되어 있으므로, 각자 사용하는 경로로 변경해야 함.

포함되지 않는 항목

  • 저장소에는 게임 APK, Meta SDK, Horizon OS 파일이 포함되지 않으므로, 소유한 게임의 APK와 third_party/ 아래에 둘 OpenXR 로더 AAR을 직접 제공해야 함.
  • ARM64 변환기는 Digitalis/Berberis(Apache-2.0, Refract 성능 패치 포함) 사전 빌드 버전이 prebuilts/digitalis/에 포함되어 있어 AOSP를 직접 빌드할 필요가 없음.
  • scripts\translator.ps1 -Use digitalis 명령으로 변환기를 에뮬레이터에 설치함.
  • Meta Platform SDK 대체 구현으로 엔타이틀먼트 검사를 통과하려면 소유한 게임을 scripts/owned_games.txt에 나열해야 하며, 형식은 scripts/owned_games.example.txt에서 확인할 수 있음.
  • Refract의 사용 대상은 소유한 앱과 공개 샘플 테스트임. DRM, 치트 방지, 플랫폼 보안, 스토어 제한 또는 애플리케이션 라이선스 조건을 우회하는 데 사용하지 않도록 안내함.

크레딧 및 라이선스

  • Refract는 Florian Reintgen의 AXRB를 기반으로 하며 코드의 상당 부분이 AXRB에서 비롯됨. 자세한 내용은 CREDITS.md에 있음.
  • Refract는 AXRB의 MIT 저작권 고지를 유지하는 MIT 라이선스로 배포됨.
  • 런처(launcher/)는 RiftLift에서 수정한 코드를 포함하므로 GPL-3.0-or-later 라이선스를 따름.