[오픈소스 사용법] nxnative — 스위치 게임 코드를 에뮬레이터 없이 맥·아이폰 앱으로 다시 묶는 도구
· 바이브코드 운영팀
닌텐도 스위치와 애플 칩은 둘 다 ARM64 명령어를 써요. nxnative는 이 점을 이용해, 내가 가진 스위치 게임을 애플 실리콘 맥, 아이폰, 아이패드에서 도는 앱으로 다시 묶어 주는 오픈소스예요. 게임 코드를 하나씩 번역해서 흉내 내지 않고, 게임 자체의 코드를 애플 칩에서 바로 실행해요. 닌텐도 전용 부분만 바꿔 끼우는 방식이라서 에뮬레이터보다 가볍게 돌아간다고 소개돼요.
어떻게 돌아가나요
스위치 게임이 기대하는 것들을 nxnative가 하나씩 대신 채워 줘요.
| 스위치에 있던 것 | nxnative가 하는 일 |
|---|---|
| 게임 프로그램(ARM64) | 애플 커널이 허락하지 않는 일부 명령만 고쳐 쓰고, 나머지는 그대로 실행해요 |
| 스위치 운영체제(Horizon) | 작은 대리 프로그램(호스트)이 파일, 메모리, 입력, 소리, 영상 요청에 대신 답해요 |
| 닌텐도 그래픽 API(NVN) | 애플의 Metal 위에 다시 만들어요 |
| 셰이더(그래픽 칩용 작은 프로그램) | Ryujinx의 변환 코드로 바꾼 뒤 빌드할 때 Metal용으로 미리 컴파일해요 |
이 방식은 디아블로 II: 레저렉션을 모바일에서 돌린 d2r-mobile 프로젝트에서 나왔고, nxnative는 그 일반적인 부분을 가져와 여러 게임에 쓸 수 있게 넓힌 프로젝트예요. 게임마다 "프로필"(그 게임에 맞는 상수와 셰이더 표)이 따로 있어서, 프로필이 있는 게임일수록 잘 돌아가요.
이럴 때 쓰세요
- 내가 가진 스위치 게임을 맥북에서 네이티브 앱처럼 열어 보고 싶을 때
- 아이폰 15 Pro 이상이나 M1 이후 아이패드에서 내 스위치 게임을 돌려 보고 싶을 때
- 스위치에서 30fps로 제한된 게임을 더 높은 프레임으로 돌려 보고 싶을 때. 일부 게임은 지정한 업데이트 버전으로 포장하면 60fps를 목표로 해요(프로젝트가 밝힌 수치예요)
- 에뮬레이터와 "기계어를 그대로 돌리는" 방식이 어떻게 다른지 코드로 보고 싶은 개발자
준비물
| 항목 | 내용 |
|---|---|
| 빌드할 Mac | 애플 실리콘, macOS 26.6 이상, Xcode 27.2, Homebrew, Python 3.12 이상(arm64 버전) |
| 아이폰 | A17 Pro 칩 이상(아이폰 15 Pro 이상), iOS 26 이상 |
| 아이패드 | M1 칩 이상, iPadOS 26 이상 |
| 디스크 | 게임 크기의 약 2배 + 10GB |
| 게임 파일 | 내가 가진 게임의 .nsp .xci .nsz .xcz(업데이트, DLC 포함 가능) |
| 키 | 스위치 1 게임은 내 콘솔의 prod.keys. 스위치 2 게임은 키가 필요 없어요 |
게임 파일과 키를 구하는 방법은 이 글에서 다루지 않아요. 저장소도 게임 데이터를 하나도 담고 있지 않고, 내가 가진 것을 쓰라는 입장이에요. 아이폰용 앱은 Xcode의 iOS 플랫폼(Xcode → Settings → Components)과 AltStore, Sideloadly, LiveContainer 같은 사이드로드 도구도 필요해요.
설치
저장소에 있는 방법은 터미널 명령이에요. 처음 한 번만 하면 돼요. Xcode 27.2를 먼저 선택해 두세요.
sudo xcode-select -s /Applications/Xcode.app
xcodebuild -downloadComponent MetalToolchain
git clone https://github.com/seedds/nxnative.git && cd nxnative
brew install xcodegen zstd glslang
python3 -m pip install lz4 "capstone>=5,<6" fonttools nsz zbic "backports.zstd; python_version < '3.14'"
터미널이 불편하면 커뮤니티 프런트엔드를 쓸 수 있어요. 다른 사람이 만든 별도 프로젝트라서 문의와 버그는 각 저장소로 보내야 해요.
- NX2Apple: 맥 빌더 + 아이폰/아이패드와 공유하는 게임 라이브러리
- NX Play: 맥 라이브러리, 기기 설치, 세이브 동기화
- NxNative Launcher: 안내식 빌드와 컨트롤러 매핑
- LumaNX: 맥 게임 빌더, IPA 내보내기
- GameCase: LiveContainer 기반 iOS 게임 라이브러리
처음 실행해 보기
1) 게임을 폴더에 넣기
게임 하나당 폴더 하나에 본편과 업데이트, DLC를 같이 넣어요.
~/Games/MarioWonder/
Super Mario Bros. Wonder [010015100B514000][v0].nsp
Super Mario Bros. Wonder [010015100B514800][v327680].nsp
2) 맥 앱으로 빌드하기
--platform mac-app을 붙이면 Finder에서 열 수 있는 맥 앱이 만들어져요. YOUR_KEYS 자리에는 내 키 파일 경로를 넣어요.
python3 scripts/build_ipa_from_nsp.py ~/Games/MarioWonder -k ~/keys/YOUR_KEYS --platform mac-app
첫 빌드는 30~60분 걸려요. 셰이더를 전부 변환하고 컴파일하기 때문이에요. 같은 게임을 다시 빌드하면 훨씬 빨라요. --platform mac-app을 빼면 아이폰/아이패드용 IPA가 게임 폴더에 생기고, 이걸 AltStore 같은 도구로 설치해요. 도구에 Increased Memory Limit 옵션이 있으면 켜세요. 큰 게임에 필요해요.
3) 스위치 2 게임
스위치 2 게임은 NSP가 아니라 .nup 파일 하나(또는 그 파일들이 든 폴더)로 빌드하고 키는 필요 없어요. 지금은 맥에서만 테스트됐고, 아이폰과 아이패드는 아직 시험하지 않았다고 해요.
python3 scripts/build_ipa_from_nsp.py ~/Games/DonkeyKongBananza.nup --platform mac-app
README에는 맥 게임 플레이 테스트를 통과한 스위치 2 게임 16개가 올라 있어요(동키콩 바난자, 마리오 카트 월드, 포켓몬 포코피아 등). 프로필이 없는 게임은 "조사(survey)"를 거쳐 임시 프로필로 빌드하는데, 이 경우 시작하지 않을 수 있어요.
자주 쓰는 옵션과 화면
| 옵션 | 하는 일 |
|---|---|
--platform mac-app | 맥 앱(.app)으로 만들기 |
--romfs separate | 게임 파일을 IPA에서 빼서 IPA를 작게 만들기(큰 게임용). 스크립트가 알려 주는 복사 명령을 한 번 실행해요 |
--shader-files | AltServer로 설치할 때 함께 쓰기(2GiB 이상 파일을 못 올리기 때문이에요) |
--language (-l) | 게임 언어 지정. -l ja처럼 코드나 이름으로 |
--icon <이미지> | 앱 아이콘 지정(폴더로 빌드하면 아이콘이 없어요) |
--show-fps | 화면 왼쪽 위에 프레임 표시 |
--no-motion | 모션(자이로) 입력 없이 포장 |
--package v<N> | 스위치 2 파일 안에서 다른 버전 고르기 |
- 시작 전 설정 화면: 프레임, 해상도, 휴대/독 모드, 언어, 진동 등을 고르고 Play를 누르면 선택이 기억돼요. 맥에서는 창으로 떠요.
- 터치 조작(아이폰): 화면 위 가운데 톱니바퀴 메뉴에서 2D/3D 조작 배치를 바꿔요. 3D에서는 화면 오른쪽 3분의 1을 쓸어 카메라를 움직여요. 컨트롤러를 연결하면 터치 조작이 숨겨져요.
- 저장과 로그: 아이폰에서는 파일 앱의 게임 이름 아래
save/,log.txt. 맥 로그는~/Library/Logs/nxnative/에 있어요. - 컨트롤러: 홈 버튼을 2초 누르면 종료 확인이 떠요. 저장하지 않은 진행은 사라져요.
- 처음 보는 장면에서 잠깐 끊기는 것은 정상이에요. 그래픽을 한 번 컴파일하고 기억해 두는 과정이에요.
알아둘 점
- 프로필이 있는 게임만 안정적이에요. 프로필은 게임의 특정 버전에 묶여 있어서, 게임이 업데이트되면 다시 작업이 필요할 수 있어요. 게임별 상태는 저장소의 게임 노트(
dm/games)에서 확인하세요. - 온라인 플레이와 amiibo는 안 돼요. (TechPowerUp, Adafruit 보도)
- 구형 아이폰은 안 돼요. 게임 텍스처가 BC 압축이라 오래된 아이폰 칩이 읽지 못해요.
- 성능 수치는 대부분 개발자와 사용자가 직접 잰 값이에요. 맥마다 달라요. 프랑스 매체 iPhoneSoft가 M2 Pro(16GB) 맥북 프로에서 오카리나 오브 타임(스위치 2판)을 처음 빌드하는 데 약 1시간 20분이 걸렸고, 이후 30fps로 안정적이었지만 배터리 상태에서는 장면에 따라 프레임이 크게 떨어졌다고 전했어요. 전원을 연결하고 쓰세요.
- 앱은 남에게 주지 마세요. 완성된 앱에는 게임이 통째로 들어 있어서, 공유는 게임을 배포하는 일이에요. 프로젝트 개발자도 이 선을 분명히 그었다고 알려져 있어요(서울리안 영상 설명).
- 법적 위험은 남아 있어요. nxnative는 닌텐도와 관계가 없는 프로젝트예요. 닌텐도는 스위치 에뮬레이터 유즈(yuzu)와 2024년 240만 달러 합의를 한 전례가 있고, 11월 16일 기준 기사들은 nxnative에 대한 닌텐도의 공식 입장이나 이 저장소를 지목한 삭제 요청이 확인되지 않았다고 전했어요. 앞으로 어떻게 될지는 알 수 없고, 내 게임과 내 기기에서 개인적으로 쓰는 범위를 지키는 게 안전해요.
- 개발에 AI 코딩 도구가 많이 쓰였다는 점이 이 커뮤니티에서 논쟁거리라는 얘기도 있어요(Andrew Tsai 영상).
관련 영상
한국어 영상이 있어서 먼저 소개해요.
아이폰에서 에뮬 없이 스위치 게임을?! AI 코딩이 뒤흔든 아이폰과 스위치 게임 — 서울리안 SEOULiAN (한국어). 스위치와 아이폰이 같은 ARM 계열이라는 점, nxnative가 대신 채우는 부분(보호 영역, 운영체제, 그래픽), 직접 돌려 본 후기와 법적으로 지켜야 할 선을 설명해요. 10월 24일 기준으로 촬영한 영상이라 지금은 지원 게임 수가 더 많아요.
ANY Switch Game Can Now Run Natively on Mac — Andrew Tsai (영어). 맥에서 쓰는 방법과 M1 맥북 에어(8GB)에서 몬스터 헌터 라이즈가 60fps로 도는 시험을 보여 줘요. 게임 영상은 법적 이유로 보여 주지 않는다고 말해요. 영상 앞부분은 게임 광고(협찬)예요.
더 보기
- 바이브코드 오픈소스 상세: nxnative
- 저장소: seedds/nxnative (MIT 라이선스, 별 약 1.6만 개)
- 작동 원리 문서: docs/development.md, 조작과 설정: docs/playing.md
- 기사: TechPowerUp, XDA Developers, 디지털포커스
확인한 날짜 · 버전: 2026-11-19, 저장소 README 커밋 a4c8297 기준(별도 릴리스 버전은 확인하지 못했어요).
글이 도움이 되었다면 좋아요를 눌러 주세요.
출처: