# 마크로스 얼티밋 프론티어 한글화 V32 기술 분석

## 1. 범위와 기준 원본

이 문서는 `Macross Ultimate Frontier (Japan).iso`를 기준으로 V32 한글화 패치를 분석·재현하기 위한 자료다. 원본 ISO 자체는 포함하지 않으며, 배포물은 xdelta 패치와 설치용 파일셋 패키지로만 구성한다.

| 항목 | 값 |
|---|---|
| 기준 원본 ISO | `Macross Ultimate Frontier (Japan).iso` |
| 원본 ISO 크기 | 1,237,843,968 bytes |
| 원본 ISO SHA-256 | `86E942C37F8EDAAF9ED1AC4E9292BBCACBEF331B7AEE6027FB896E015751B205` |
| V32 목표 ISO SHA-256 | `D50BCBA71C8615ECDC345C75A267A79C1AF9F281EF6B673504325821B3F0680A` |
| xdelta 패치 | `Macross_UF_Korean_V32.xdelta` |
| xdelta 패치 크기 | 3,179,561 bytes |

번역 원칙은 다음과 같다.

- 일본어 표기만 한글화한다.
- 이미 영어인 UI, 기체 코드, 버튼 표기, 약어는 유지한다.
- 컨트롤러 아이콘·애니메이션 스냅샷·장식 이미지는 번역 대상이 아니다.
- 이미지 텍스트는 원래 GIM 레이어 안에서 교체하고, 버튼·프레임·배경과 분리해 다룬다.

## 2. ISO 내부 구조

ISO9660 디렉터리를 직접 읽어 확인한 주요 위치다. 섹터 크기는 2,048 bytes다.

| 경로 | LBA | ISO 오프셋 | 크기 | 용도 |
|---|---:|---:|---:|---|
| `PSP_GAME` | 23 | 47,104 | 2,048 | 게임 루트 디렉터리 |
| `PSP_GAME/SYSDIR` | 24 | 49,152 | 2,048 | 실행 파일 디렉터리 |
| `PSP_GAME/SYSDIR/EBOOT.BIN` | 48 | 98,304 | 5,388,288 | PSP 실행 파일 |
| `PSP_GAME/SYSDIR/BOOT.BIN` | 56,080 | 114,851,840 | 5,387,948 | 보조 부트 영역 |
| `PSP_GAME/USRDIR/fileset.dat` | 고정 영역 | `0x0CBA0000` | 292,388,288 | 게임 리소스 파일셋 |

V32 ISO는 원본 ISO를 복사한 뒤 다음 두 바이트 영역만 교체한다.

1. `0x0CBA0000`부터 `fileset.dat` 전체를 V32 파일셋으로 교체한다.
2. `0x00018000`부터 `EBOOT.BIN` 전체를 V32의 복호화 ELF로 교체한다.

원본 ISO의 EBOOT는 `~PSP`로 시작하는 암호화된 형태이며, V32 EBOOT는 `0x7F ELF`로 시작하는 복호화 실행 파일이다. xdelta 자체의 왕복 검증은 완료했지만, 실제 PPSSPP 실행 검수는 별도 게임 플레이로 확인해야 한다.

## 3. fileset.dat 구조

`fileset.dat`은 파일을 단순히 이어붙인 구조가 아니라 PIDX/FSTS 계열의 번들 컨테이너다.

- 번들 안에 다수의 멤버가 들어 있다.
- 멤버는 RAIC 압축 상태로 저장된다.
- 교체 시에는 멤버를 해제하고 수정한 뒤 다시 RAIC 압축한다.
- 새 압축 데이터가 다음 멤버 시작점 전의 허용 공간을 넘으면 안 된다.
- V32는 원본과 파일셋 전체 크기가 완전히 같다.

원본과 V32를 대조한 결과는 다음과 같다.

| 항목 | 수량 |
|---|---:|
| 전체 멤버 인스턴스 | 65,203 |
| 원본 대비 변경 멤버 | 268 |
| 변경 GIM 이미지 레이어 | 178 |
| 변경 FES 전투 스크립트 | 82 |
| 변경 CSV | 7 |
| 변경 폰트 | 1 |

주요 변경 GIM 영역은 시스템 메뉴 43개, 갤러리 39개, 설정 38개, 상점 28개, 격납고 18개, 결과 화면 8개, 데이터 선택 4개다.

## 4. 이미지 UI: GIM 복합 레이어 처리

이 게임의 메뉴 글자는 한 장의 완성 이미지가 아니라 배경, 글자 레이어, 선택창, 버튼 아이콘이 별도 GIM으로 합성되는 경우가 많다.

### 핵심 방식

1. GIM의 팔레트·픽셀 인덱스를 유지한 채 일본어 픽셀만 지운다.
2. 기존 글자의 실제 잉크 경계를 측정해 한국어를 같은 중심에 배치한다.
3. 배경색을 추측해 큰 사각형을 덮지 않고, 일본어 글자 경계만 최소 범위로 지운다.
4. 투명 GIM은 투명도를 유지한다. 불투명 배경으로 미리 합성하면 아이콘 주변에 검은 사각형이 생긴다.
5. 버튼 스프라이트와 방향키·변형 아이콘은 번역하지 않고 원래 알파 채널을 그대로 합성한다.

### 컨트롤 키 편집 화면에서 발견한 문제와 수정

| 문제 | 원인 | 수정 |
|---|---|---|
| 방향키·변형 아이콘 주변의 검은 사각형 | 투명 스프라이트를 불투명 미리보기 바탕에 먼저 합성 | 원래 알파 채널로 직접 합성 |
| 왼쪽 4개 안내 줄의 칸선 손실 | 투명 텍스트 레이어가 불투명 블록으로 합성됨 | 투명 레이어로 복원하고 문구만 우측 보정 |
| 메뉴 표시·기체 표시 뒤 회색 침범 | 일본어 삭제 범위가 버튼 열까지 확장됨 | 버튼 열의 원래 검정 바탕을 보존하도록 삭제 규칙 수정 |
| 프레임이 계단처럼 보임 | 최근접 확대 미리보기 | 실제 게임 표시와 가까운 부드러운 확대 미리보기 사용 |

V31에서 설정/컨트롤 관련 GIM 38개를 추가로 교체했다. 영어 헤더(`FLIGHT TYPE`, `CONTROL TYPE`, `CUSTOM`, `RESET`)와 PSP 버튼 기호는 그대로다.

## 5. 글꼴과 Shift-JIS 도너 매핑

게임의 한글 표시는 일반적인 UTF-8 텍스트 삽입 방식이 아니다.

1. EBOOT의 문자표에는 Shift-JIS 코드가 들어 있다.
2. 기존에 거의 쓰이지 않는 한자 코드 위치를 선택한다.
3. 그 코드가 가리키는 `gpsp3_font14.fnt` 글리프를 한글 글리프로 교체한다.
4. 한국어 문자열을 쓸 때 해당 도너 Shift-JIS 코드를 사용한다.

이 방식의 장점은 게임의 원래 문자 처리와 폰트 로더를 바꾸지 않는다는 점이다. 이미 사용 중인 일본어 글리프를 덮어쓰지 않도록 원본 폰트와 현재 폰트의 글리프 시그니처를 비교해 예약 목록을 만든다.

| 버전 | 신규 한글 글리프 |
|---|---:|
| V30 | 643 |
| V32 격납고 추가 | 44 |
| V32 이전에 예약된 변경 글리프 | 1,551 |

## 6. 텍스트 한글화 범위

원본 ISO 기준으로 플레이어에게 보이는 일본어 텍스트를 분류해 점검했다. 영어, 내부 ID(`path`, `locate`, `formation`), 별 장식, 비텍스트 스냅샷은 제외했다.

| 텍스트 영역 | 완료 |
|---|---:|
| EBOOT 무기·설명·옵션 표기 | 2,355 / 2,355 |
| 전투 오퍼레이터 대사(FES) | 232 / 232 |
| 메뉴·미션·갤러리·격납고 CSV | 2,903 / 2,903 |
| 합계 | 5,490 / 5,490 |

### V32 격납고 완료 범위

대상은 `GameFlowHangarCreate/data/menu/text/nn_ext.csv`다.

- 기존 처리: 762개
- V32 신규 처리: 1,018개
- 실제 일본어 라벨 총계: 1,780개
- 잔여 일본어 라벨: 0개

V32에서 처리한 대표 패턴은 `캡처`, `프롤로그`, `크로니클`, `에필로그`, `캐릭터`, `오퍼레이터`, `기체`, `기타`와 작품별 표기다. `FB`, `F`, `D7`, `VF-X2`, `M3` 등 영문·기체 코드는 그대로 보존했다.

## 7. xdelta 생성과 검증

xdeltaUI 3.1에 포함된 xdelta 3.1.0을 사용했다.

```text
생성: xdelta.exe -e -f -9 -s 원본.iso 목표.iso Macross_UF_Korean_V32.xdelta
검증: xdelta.exe -d -f -s 원본.iso Macross_UF_Korean_V32.xdelta 검증.iso
```

검증 ISO의 SHA-256과 목표 ISO의 SHA-256을 비교해 완전히 같은지 확인했다.

| 검증 항목 | 결과 |
|---|---|
| 원본 ISO 크기 유지 | 성공 |
| V32 fileset.dat 쓰기 검증 | 성공 |
| V32 EBOOT.BIN 쓰기 검증 | 성공 |
| xdelta 역적용 | 성공 |
| 역적용 ISO 해시 = 목표 ISO 해시 | 성공 |
| xdelta ZIP 무결성 | 성공 |

저작권 보호를 위해 생성 중 사용한 검수용 ISO와 역적용 검수 ISO는 삭제했고, 배포물에는 xdelta·안내문·해시 매니페스트만 남긴다.

## 8. 재현용 주요 스크립트

| 스크립트 | 역할 |
|---|---|
| `build_v30_full_translation.py` | EBOOT, 전투 대사, 폰트 기반 V30 전체 번역 빌드 |
| `macross_settings_localization.py` | 설정·컨트롤 GIM 레이어 한글화 |
| `build_v31_controller_settings.py` | V30 기반 설정·컨트롤 V31 패키지 생성 |
| `build_v32_hangar_full.py` | 격납고 `nn_ext.csv`와 추가 폰트 V32 빌드 |
| `audit_v31_progress.py` | 원본 ISO 대비 V32 텍스트 진행률 감사 |
| `build_v32_xdelta.py` | V32 ISO 영역 교체, xdelta 생성, 역적용 해시 검증 |

## 9. 남은 검수 항목

텍스트 인벤토리 기준으로는 완료 상태다. 이후에는 실제 PPSSPP 플레이에서 다음을 확인하면 된다.

- ISO에서 복호화 ELF EBOOT가 정상 부팅되는지
- 긴 무기 설명·격납고 설명에서 줄바꿈과 글리프 폭이 자연스러운지
- 설정 화면의 투명 레이어, 버튼 열, 칸선이 겹치지 않는지
- 미발견 GIM 이미지에 일본어가 남아 있지 않은지
- 미션 진행 중 동적 대사·조건부 대사에 누락이 없는지

## 10. 관련 산출물

- `Macross_UF_Korean_V32_Hangar.zip`: 폴더 설치형 V32 패치
- `Macross_UF_Korean_V32_xdelta.zip`: xdeltaUI용 ISO 패치 배포물
- `Macross_UF_Korean_V32_xdelta_manifest.json`: 원본·목표·패치 해시
- `macross_korean_v32_progress_audit.json`: 원본 ISO 대조 진행률 감사 결과
- `macross_korean_v32_hangar_report.json`: 격납고 CSV·폰트 빌드 결과