nxnative: 같은 ARM64라도
그대로 실행할 수 없는 이유

초판 분석 기준: 공식 저장소 ID 1416502082, 커밋 93578abad6704ae95fbf60e80027469f145b02cf. README·개발 문서와 rewriter·loader·그래픽 번역기·iOS 프로젝트·테스트 코드를 읽었습니다. 게임, 키, 빌드 도구를 설치하거나 실행하지 않았으며 성능과 호환성은 제작자의 보고와 코드 관찰을 구분합니다.

1프로젝트 한줄 요약

nxnative는 Switch의 ARM64 실행 코드를 Apple ARM64에서 실행하도록 사전 변환하고, Horizon 운영체제 서비스와 NVN 그래픽을 대신 구현해 게임별 iOS IPA를 만드는 도구입니다. 사용자가 제공한 게임 파일과 키를 입력으로 삼는 패키징 경로가 있으며, 저장소에는 게임 자체가 없다고 README가 명시합니다.

README의 “에뮬레이터가 아니다”는 표현은 CPU 명령어를 매번 해석하는 대신 게임 코드를 직접 실행한다는 뜻으로 읽어야 합니다. 운영체제와 GPU까지 원래대로 실행한다는 뜻은 아닙니다. 실제 dm/host/hle_*.c는 커널·파일·입력·오디오 등의 동작을 대체하고, dm/gfx는 그래픽 호출을 Metal로 재구현합니다.

2왜 주목받는가

기술적으로 흥미로운 지점은 세 가지입니다. 첫째, Switch와 Apple 기기가 같은 AArch64 계열이라는 공통점을 이용하되 서로 다른 ABI와 시스템 환경만 변환합니다. 둘째, Maxwell GPU 셰이더를 오프라인에서 SPIR-V와 Metal 라이브러리로 바꿔 단말에서 처리할 일을 줄입니다. 셋째, 게임별 예외를 공통 호스트에 무작정 섞는 대신 프로필과 build ID에 연결합니다.

기존 CPU 에뮬레이션을 쓰는 도구와 비교하면, 이 프로젝트의 학습 가치는 “모든 하드웨어를 가상화하는가”보다 어떤 연산은 그대로 두고 어떤 경계만 대체할 수 있는가에 있습니다. 그렇다고 성능 우위를 일반화할 수는 없습니다. README의 플레이 가능·60fps 목록은 특정 기기·게임 버전에 관한 제작자 보고이며 이 분석에서 재측정하지 않았습니다.

코드의 출발점도 중요합니다. README는 jhaizhou-ops/d2r-mobile의 범용 부분을 복사해 시작했고 수정이 양방향으로 오간다고 밝힙니다. Ryujinx는 셰이더 번역 라이브러리로 포함됩니다. 전체 Ryujinx 앱을 iOS에 옮긴 프로젝트로 이해하면 구조를 놓칩니다.

3기술 스택 전체 지도

클라우드 백엔드나 모델 API가 필요한 구조는 아닙니다. 대신 Mac의 개발 도구, 상당한 저장 공간, 호환 Apple 단말, 사용자의 입력 자료가 필요합니다. 외부 코드를 저장소에 함께 둔다고 해서 Xcode·.NET 등 전체 도구까지 포함되는 것은 아닙니다.

4아키텍처 심화 분석

1. 같은 명령어 집합과 같은 ABI는 다릅니다

patch_nso.py의 머리 주석은 변환 대상을 구체적으로 적습니다. Apple 커널이 사용하는 x18, 서로 다른 스레드 포인터 레지스터, svc 시스템 호출, 타이머 읽기, 스택 정렬을 보정합니다. 예를 들어 Horizon의 스레드 상태를 Apple의 pthread TSD(Thread-Specific Data)에 대응시키고, 시스템 호출 지점을 호스트의 gate로 연결합니다. 명령어 집합이 같아도 프로세스가 기대하는 주변 계약이 다르기 때문입니다.

2. 버전별 패치를 원본 바이트와 묶습니다

공통 변환과 특정 빌드 수정은 구분됩니다. sdk_patches.py와 게임별 patches.py의 CUTS는 build ID에 연결되며, 같은 build ID가 중복 등록되면 멈춥니다. 아래는 실제 검사 부분입니다.

# dm/tools/patch_nso.py:80-85
BUILD_ID = d[0x40:0x50].hex()
cuts = list(PATCHES['CUTS'].get(BUILD_ID, []))
for off, ob, nb, why in cuts:
    ob, nb = bytes.fromhex(ob), bytes.fromhex(nb)
    assert len(ob) == len(nb) and IMG[off:off + len(ob)] == ob, \
        f'cut original bytes mismatch {off:#x}: {bytes(IMG[off:off + len(ob)]).hex()}'
    IMG[off:off + len(nb)] = nb

이 검사는 다른 버전의 코드를 같은 오프셋이라는 이유만으로 덮어쓰는 사고를 막습니다. 모든 변환 결과의 정확성을 증명하는 검사는 아닙니다. 개발 문서는 등록되지 않은 게임 버전도 해당 버전의 입력에서 파생 프로필을 만들 수 있지만, 검증된 버전용 수정은 다른 build ID에 적용하지 않는다고 설명합니다.

3. loader는 코드와 데이터의 수명도 나눕니다

loader.c는 모듈 매핑·스레드 슬롯·gate 등록·심볼 재배치·세그먼트 권한을 맡습니다. 머리 주석은 코드와 패치 영역을 복사한 뒤 읽기/실행 권한으로 고정하고 이후에는 데이터만 쓴다고 명시합니다. iOS에서는 이 코드가 서명된 실행 세그먼트에 들어가야 합니다. 단순히 다운로드한 ARM64 파일을 앱 실행 중 임의로 붙이는 설계와는 다른 제약입니다.

4. GPU 호출은 기록한 뒤 Metal로 재생합니다

dm/gfx/README.md에서 nvn/hle_nvn.c는 인터페이스·명령 기록, nvn/nvn_mtl.m는 제출 시 재생을 담당합니다. 게스트가 GPU 완료를 관측하는 시점은 Metal command buffer가 실제 끝난 뒤여야 합니다. CPU가 빨리 돌아가더라도 동기화 의미가 틀리면 렌더링과 게임 상태가 어긋납니다.

셰이더 번역기 dmsh_xlate/Program.cs는 코드만으로 알 수 없는 텍스처 차원·출력 타입·작업 그룹 크기를 프로필의 shader_facts.tsv에서 공급받습니다. 번역 체인 해시는 라이브러리 디렉터리와 reflection에 기록되고 호스트가 불일치한 결과를 거부합니다. 캐시를 빠르게 만드는 것과 잘못된 캐시를 쓰지 않는 것이 함께 설계돼 있습니다.

2026-10-27 개정: 실행 설정과 셰이더 회귀 차단

커밋 9bdef355ab3254d9a39f074f032ba41a2092705b에서는 첫 실행 설정을 Game·Controls·Performance 한 화면으로 묶고, 사용자가 기본값과 다르게 선택한 값만 저장합니다. 새 빌드의 기본값은 별도 선택이 없던 설정에 반영되며, Documents/env.txt가 화면보다 우선합니다. docs/settings.md가 이 우선순위와 초기화 동작을 설명합니다.

MetalFX 업스케일링은 선택 기능입니다. nvn_mtl.m은 Metal 4 큐와 GPU 지원을 확인하고, 지원하지 않는 기기·크기는 기존 보간으로 처리합니다. 그림을 키울 때 GPU 시간·발열 비용이 추가되며, 문서는 iPhone에서 Standard와 비교한 동일 조건의 열 비용은 아직 측정하지 않았다고 밝힙니다.

빌드 스크립트는 이전 빌드에서 번역됐던 셰이더가 새 변환 체인에서 실패하면 기본적으로 중단합니다. shader_regressions.py는 같은 게임의 이전 빌드 보고와 현재 보고에서 성공→실패가 된 키를 대조하고, logs/shader_regressions.log에 남깁니다. 이전 보고가 없거나 한쪽에 키가 없으면 회귀로 세지 않으므로 모든 셰이더의 정확성을 보장하는 검사는 아닙니다.

# 현재 빌드 설정의 기본값 (실행 예제가 아닌 코드 발췌)
ALLOW_SHADER_REGRESSIONS = False
# 기존 성공 셰이더가 실패하면 BuildError
# --allow-shader-regressions는 누락된 셰이더를 포함하지 않고 진행하는 예외

PSO_GPUS / --gpu로 GPU별 파이프라인 기반 아카이브도 미리 만들 수 있습니다. iOS 기본 선택은 게임 프로필의 Metal 4 설정에 따르고, Mac 앱은 로컬 GPU를 기본으로 합니다. 처음 실행 때의 준비를 줄이는 대신 패키지 크기·첫 빌드 시간이 늘어납니다. Homebrew의 .NET 런타임 위치를 찾아 DOTNET_ROOT를 맞추는 처리와 NSZ 입력의 키 파일 전달도 수정됐습니다.

새 Xenoblade Chronicles 3 2.2.1 프로필은 Mac의 초반 전투·이동 확인과 iOS 빌드 성공을 구분해 기록합니다. iOS 실제 실행·후반 메모리 최대치·DLC 렌더링은 미검증입니다. 패키지가 만들어졌다는 이유만으로 단말 호환을 확정하지 않습니다.

2026-10-28 개정: Mac 설정창과 프런트엔드 계약

이번 소스는 7e0f59712b0cad3101543b47c06bd76150f845b6입니다. Mac 앱은 시작 전에 자체 설정창을 표시하고, Finder·Dock·외부 프런트엔드가 같은 preferences 저장소의 launcher.<env> 문자열을 사용합니다. 실행 환경 → 사용자 env.txt → 번들 env.txt → 저장 선택 → 테스트 기본값 순으로 먼저 설정한 값이 이깁니다. DM_LAUNCHER=0은 창만 건너뛰며 저장 선택은 적용하고, DM_SAVED_CHOICES=0은 저장 선택 적용을 건너뜁니다.

dm/games/settings.py는 launcher.json에 schema:1을 씁니다. base는 렌더 스케일의 docked/handheld 기준 크기, level은 첫 화면 우선 표시, needs는 상위 설정값에 따른 하위 항목 조건입니다. schema 1은 선택 필드만 늘리고 알 수 없는 필드는 무시하는 계약이며, 새 kind는 schema 2가 필요합니다.

게임 프로필·settings.tsv
  → settings.py → launcher.json / Info.plist의 DMSettings
  → 앱 설정창 또는 별도 프런트엔드
  → 동일 preferences → launcher.c의 값 검사 → 게임 실행

README가 안내하는 NX2Apple은 nxnative 위에 구축한 별도 커뮤니티 Mac 앱입니다. 현재 호스트 로그는 사람용 진단 문자열이며 안정된 실행 이벤트 API로 보장하지 않습니다. 빌드 JSON 이벤트는 종료 코드·stderr와 함께 읽어야 합니다.

압축 NSZ/XCZ 입력은 현재 Python의 nsz 패키지가 없을 때 PATH의 nsz 또는 nsz-cli-macos-arm64 실행파일도 찾습니다. 독립 실행파일은 --keys 지원을 검사하므로 nsz 5.0+가 필요합니다. 임시 출력은 성공과 파일 존재를 확인한 뒤 옮깁니다. 이 분석에서는 입력 게임·키나 변환 도구를 실행하지 않았습니다.

2026-10-28 저녁 개정: RomFS 분리와 빌드 조건

고정 소스 6c4a81d40d200bbfe65ad0027ab093405367ada6는 --romfs separate로 게임 데이터 RomFS를 IPA에서 분리하는 경로를 제공합니다. 기본은 bundle이며, 분리하면 앱 재빌드마다 대용량 게임 데이터를 다시 묶거나 전송할 필요가 줄어듭니다. 게임 데이터·키는 사용자가 직접 제공해야 하고 저장소에는 들어 있지 않습니다.

# 별도 입력 자료와 로컬 개발 환경이 준비된 독자용 예시
python3 scripts/build_ipa_from_nsp.py ~/Games/MyGame \
  -k ~/keys/prod.keys --romfs separate

빌드가 출력한 scripts/push_romfs.sh 명령으로 해당 게임 버전의 데이터를 한 번 복사합니다. 앱은 자신을 빌드한 이미지와 데이터의 정체성이 맞는지 확인하므로 다른 버전의 RomFS를 이름만 바꿔 재사용하는 흐름이 아닙니다.

README의 현재 기준은 macOS 26.6+·Xcode 27.1·arm64 Python 3.12+입니다. 첫 빌드 시간과 디스크 여유 수치는 제작자 안내이며 기기·게임·캐시에 따라 달라집니다. 실습은 먼저 Python 스크립트의 ROMFS 기본값·인수 파싱·출력 경로를 읽고 bundle/separate의 데이터 배치를 비교하는 것으로 시작합니다. 이 분석에서 변환·서명·게임 실행을 수행하지 않았습니다.

근거: 빌드 입력과 RomFS 선택 · 별도 데이터 전송 절차. 앞선 날짜의 설정·프런트엔드 계약은 각 블록의 SHA를 보존합니다.

5디렉토리 구조 해부

nxnative/
├─ scripts/build_ipa_from_nsp.py  단계 조율·진행 이벤트
├─ dm/
│  ├─ tools/                    실행 파일 분석·rewrite
│  │  └─ tests/                 패키징·진행·패치 회귀 사례
│  ├─ host/                     loader·Horizon 서비스·단말 IO
│  │  └─ tests/                 메모리·로더 등 합성 테스트
│  ├─ gfx/
│  │  ├─ nvn/                   NVN 인터페이스와 Metal 재생
│  │  ├─ vk/ · gl/              다른 그래픽 API의 호환 층
│  │  └─ tools/                 셰이더 분리·번역·캐시 체인
│  ├─ games/                    title ID별 프로필·빌드별 수정
│  ├─ ios/                      XcodeGen·앱 셸·패키징 도구
│  └─ third_party/              출처·라이선스가 함께 든 외부 소스
└─ docs/                        development·reference·agents

처음에는 개별 게임의 긴 셰이더 표보다 patch_nso.py 머리 주석 → loader.c → dm/gfx/README.md 순으로 읽는 편이 낫습니다. docs/reference는 스레드·서비스·메모리·렌더링 주제를 보충하고, docs/agents는 bring-up과 고장 증상을 연결합니다. 외부 문서의 에이전트 지시문은 이 분석을 위한 실행 권한으로 취급하지 않았습니다.

6학습 포인트

7하드웨어 / 시스템 요구사항

README의 지원 목록 밖 게임은 잠정 설정으로 IPA가 만들어져도 실행되지 않을 수 있습니다. 알려진 한계에는 amiibo·온라인 기능 부재와 특정 게임의 소리·그래픽 결함이 있습니다. MIT라는 사실을 모든 입력 게임이나 변환 결과의 재배포 허가로 확대해서는 안 됩니다.

8직접 해볼 수 있는 실습 과제

8-1. 분석 대상과 파이프라인 지도를 고정하기 기초

공식 저장소를 확보한 로컬 디렉터리에서 다음 읽기 명령을 실행합니다. git show는 현재 체크아웃 상태와 무관하게 지정 커밋의 파일을 읽습니다.

PIN=93578abad6704ae95fbf60e80027469f145b02cf
git cat-file -t "$PIN"
git ls-tree --name-only "$PIN"
git show "$PIN:docs/development.md"

완료 기준: 첫 결과가 commit인지 확인하고, 개발 문서에서 빌드 시점과 단말 실행 시점의 일을 각각 세 개 적습니다. 객체가 없으면 현재 HEAD를 같은 분석 대상으로 간주하지 않습니다.

8-2. 원본 바이트 검사와 버전 경계 찾기 중급

git show "$PIN:dm/tools/patch_nso.py"
git show "$PIN:dm/host/loader.c"

BUILD_ID·CUTS·cut original bytes mismatch와 tsd_check를 찾습니다. 완료 기준: ① 다른 build ID, ② 같은 ID인데 원본 바이트 불일치, ③ Apple TSD 배치 불일치가 각각 어디서 처리되는지 파일과 조건으로 기록합니다. 실행 파일을 수정하거나 키를 준비할 필요가 없습니다.

8-3. 셰이더 경로와 캐시 무효화 표 만들기 중급

git show "$PIN:dm/gfx/README.md"
git show "$PIN:dm/gfx/tools/dmsh_xlate/Program.cs"

완료 기준: 입력·도구·출력을 Maxwell → SPIR-V → MSL → metallib 네 칸에 채우고, translation chain version 불일치와 게임 프로필 변경을 구분합니다. 같은 GPU 코드라도 텍스처 차원 정보가 빠지면 왜 기본값으로 안전하게 처리할 수 없는지 설명합니다.

8-4. 진행 이벤트를 로그 뷰어의 입력으로 설계하기 심화

git show "$PIN:dm/tools/tests/test_nsp_progress.py"

테스트 Json.test_events에서 기대 이벤트 순서를 읽어 작은 상태 전이 표를 만듭니다. 완료 기준: stage·progress·stage_end를 구분하고, 작업량 미상인 null과 실패한 ok:false를 화면에 어떻게 나타낼지 정합니다. 외부 게임 입력 없이 파이프라인 UI의 계약을 공부할 수 있습니다. 테스트를 실제 실행했다는 뜻은 아닙니다.

8-5. 현재 설정 계약 읽기 · 중급

PIN=7e0f59712b0cad3101543b47c06bd76150f845b6
git show "$PIN:docs/frontends.md"
git show "$PIN:dm/games/settings.py"
git show "$PIN:dm/mac/launcher.c"

완료 기준: 알 수 없는 선택 필드와 kind를 구분하고, 저장된 값이 새 빌드의 선택지에 없을 때의 처리, 두 DM_* 스위치의 차이를 적습니다. 앞의 초판 고정 예제와 이번 커밋을 구분합니다.

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

2026-10-27 개정 원본: 9bdef355 고정 소스 · 설정 우선순위와 비용 · Xenoblade Chronicles 3 검증 범위.

2026-10-28 현재 검토: docs/frontends.md · docs/launcher.schema.json · dm/games/settings.py · dm/mac/launcher.c · scripts/build_ipa_from_nsp.py. 아래 초판 링크와 이전 검토 블록은 각 날짜의 근거를 보존합니다.

• 공식 저장소 · 공식 repository ID metadata
• README: 지원 범위·요건·알려진 한계
• 개발 문서: 파이프라인·메모리·테스트
• ARM64 rewriter · 모듈 loader
• 그래픽 record/replay와 번역 체인 · 셰이더 번역기
• iOS 프로젝트 설정 · 진행 이벤트 테스트
• MIT 라이선스 · 외부 코드·라이선스 목록

2026-10-28 커밋 7e0f5971까지 대조해 Mac 설정·프런트엔드 계약·NSZ 조건을 갱신했습니다. 10-27의 셰이더 회귀·MetalFX·게임별 검토는 해당 날짜의 근거로 남겼습니다. 기존 날짜의 검토 블록은 그때의 이력입니다. 호환 목록·시간·프레임률은 upstream 보고이며 독립 실행 검증을 수행하지 않았습니다.