비공식 가이드입니다. nxnative 개발자가 운영하는 사이트가 아니며 Nintendo, Apple과도 관련이 없습니다. 이 사이트는 파일, 게임, 키, 앱을 일절 제공하지 않습니다. 코드는 GitHub에 있습니다.

English · Español · 한국어

nxnative 사용법

nxnative 사용은 세 단계입니다. Mac에서 내 게임으로 앱을 만들고, iPhone이나 iPad에 설치하고, 플레이합니다. 공식 절차를 순서대로 정리했습니다. 내 게임 파일과 키가 이미 있다고 가정하며, 이 사이트는 그것을 구하는 방법을 다루지 않습니다.

광고

1단계: nxnative와 도구 설치 (한 번만)

macOS 26.6 이상, Xcode 27.1, Homebrew가 있는 Mac에서 실행합니다(Python 3.12 이상 사용):

xcodebuild -downloadComponent MetalToolchain
git clone https://github.com/seedds/nxnative.git && cd nxnative
brew install xcodegen zstd glslang
brew install --cask dotnet-sdk
python3 -m pip install lz4 capstone fonttools "backports.zstd; python_version < '3.14'"

2단계: 게임 하나를 폴더에 넣기

게임마다 폴더 하나에 본편과, 있다면 업데이트와 DLC를 넣습니다. 압축된 NSZ, XCZ 파일도 되며 스크립트가 한 번 변환합니다. 폴더 안의 가장 최신 버전이 패키징됩니다.

3단계: 스크립트 실행

python3 scripts/build_ipa_from_nsp.py ~/Games/MarioWonder -k ~/keys/prod.keys

같은 폴더에 IPA가 생깁니다. 유용한 옵션: -o는 출력 경로, --app-name은 앱 이름, --language는 게임 언어, --show-fps는 프레임 레이트 표시, --platform mac-app은 Mac 앱 생성입니다. 전체 목록은 -h로 확인하세요. 첫 빌드는 30~60분 걸리고, 이후에는 입력이 바뀌지 않은 단계를 재사용하므로 스크립트가 IPA 옆에 남기는 작은 .idx 파일을 보관하세요.

광고

4단계: IPA 설치

AltStore, Sideloadly, LiveContainer 같은 사이드로드 도구로 설치합니다. 도구가 지원하면 Increased Memory Limit 권한으로 서명해 iOS가 큰 게임을 종료하지 않게 하세요. 앱에는 게임의 이름, 아이콘, 버전이 붙습니다. Apple 개발자 계정이 있으면 --prepare-xcode를 써서 Xcode에서 설치할 수도 있습니다.

큰 게임은 --romfs separate를 쓰면 게임 파일이 IPA에서 빠지고, 휴대폰으로 한 번만 복사하는 명령이 출력됩니다. IPA가 작아지고 다시 빌드도 빨라집니다. iOS가 압축을 풀지 못할 만큼 IPA가 클 때도 도움이 됩니다.

5단계: 플레이

  • 설정 화면. 게임이 시작되기 전에 게임, 조작, 성능으로 묶인 스크롤 화면에서 게임이 지원하는 항목을 고릅니다. 프레임 레이트, 렌더 배율, TV 모드·휴대 모드, 업스케일링, 언어, FPS 표시, 진동이 있고, 테스트 당시 설정으로 되돌리는 버튼도 있습니다. Play를 누르세요. 각 항목 설명: nxnative 설정 설명(영어).
  • 터치 조작. 위쪽에서 2D와 3D 레이아웃을 전환합니다. 3D에서는 화면 오른쪽 3분의 1을 쓸어 카메라를 움직입니다. 컨트롤러를 연결하면 터치 조작이 숨겨집니다.
  • 진동. iPhone 햅틱이나 호환 컨트롤러를 쓰며, 켜기·끄기와 세기를 따로 설정합니다.
  • 모션. 자이로가 있는 컨트롤러(DualSense, DualShock 4)가 게임의 모션 조작을 담당하고, 자이로가 없는 컨트롤러를 쓰면 iPhone 자체 자이로를 사용합니다. 모션이 이상하면 --no-motion으로 패키징하세요.
  • 세이브와 로그는 파일 앱의 앱 이름 아래에 있습니다. 문제가 생기면 프로젝트에서 log.txt를 요청합니다.
  • Mac에서는 게임 앱이 시작 전에 창으로 설정을 보여 줍니다. 로그는 ~/Library/Logs/nxnative/에 있습니다.

더 쉬운 방법: NX2Apple

NX2Apple은 명령줄 없이 게임을 iPhone, iPad, Mac용으로 만들어 주고, Mac 게임을 라이브러리로 관리하며 설정과 함께 실행하는 커뮤니티 Mac 앱입니다. 게임 파일을 더 작게 패키징해 IPA도 가벼워집니다. 별도 프로젝트입니다.

컨트롤러가 필요한가요?

필수는 아닙니다. 모든 앱에 2D·3D 터치 조작이 있습니다. 컨트롤러를 연결하면 터치 조작이 숨겨지고 모든 버튼을 쓸 수 있습니다. USB-C인 iPhone 15 Pro 이상에서는 GameSir G8 Plus MFi처럼 휴대폰에 끼우는 컨트롤러가 가장 편합니다(USB-C, GameSir 표기 기준 Apple 인증). 컨트롤러에 자이로가 없으면 iPhone 자체 자이로를 씁니다. Mac이나 손에 든 컨트롤러로 모션 조작을 하려면 DualSense 또는 DualShock 4가 맞습니다. 자세한 내용은 컨트롤러 가이드(영어)에 있습니다.

광고

사용법 관련 질문

빌드는 얼마나 걸리나요?

첫 빌드는 30~60분 걸립니다. 이후 빌드는 입력이 바뀌지 않은 단계를 재사용하므로, 호스트만 바뀐 업데이트 후에는 1분 정도입니다. 이를 위해 IPA 옆에 있는 작은 .idx 파일을 지우지 마세요.

게임 언어를 바꿀 수 있나요?

네. 패키징할 때 --language로 고릅니다(예: -l ko 또는 -l Korean). 게임에 들어 있는 언어여야 합니다. 다시 빌드하지 않고 설정 화면에서 바꿀 수도 있습니다.

세이브 파일은 어디에 있나요?

파일 앱에서 앱 이름 아래 save/ 폴더에 있습니다. 일부 사이드로드 도구는 다시 설치한 앱에 새 데이터 폴더를 주므로, 진행 상황을 유지하려면 save/와 pso_user.tsv를 옮겨 복사하세요.

처음에 끊기는 이유는 무엇인가요?

새 장면이 처음 나올 때 앱이 그래픽을 컴파일하고 다음 실행을 위해 기억합니다. 처음 방문할 때 잠깐 끊기는 것은 정상입니다.

Mac에서 플레이할 수 있나요?

네. --platform mac-app으로 패키징하면 Finder에서 여는 Mac 앱이 만들어집니다(Apple silicon).

개발자용 자세한 내용은 공식 개발 가이드(영어)에 있습니다. 게임 목록(영어)도 참고하세요.

광고