MagnetismHeroes/docs/operations.md

# 실행과 제작 절차

## 프로젝트 열기

Unity Hub에서 저장소 루트를 Unity `6000.6.3f1`로 연다. Android Build Support와 해당 Editor의 SDK·NDK·OpenJDK가 설치되어 있어야 한다. 프로젝트의 Package Manager가 고정 패키지를 복원한 뒤 `Assets/MagnetismHeroes/Scenes/Main.unity`를 열고 Game View를 가로 비율로 설정해 Play한다. 캐릭터를 마우스 왼쪽으로 끌고 빈 공간을 쓸어 회전하며 휠로 확대·축소한다. 분리는 친구 선택 → ‘나누기’ → 구 선택 → 선택한 구 끌기 순서다. 에디터 마우스 경험은 실제 두 손가락 검증과 구분한다.

빌드만 할 때 Blender·conda·TTS 모델은 필요 없다. 이미 저장된 FBX·PNG·WAV를 사용한다. 초기 자산을 통째로 만드는 Editor builder는 완성 프로젝트의 실행 준비 명령이 아니다.

## 명령행 검증

PowerShell 7, Python, Unity CLI와 Android Studio의 platform-tools·emulator가 필요하다. Unity CLI가 PATH에 없다면 아래처럼 현재 설치 위치를 추가한다. 다른 PC에서는 실제 설치 경로로 바꾼다.

```powershell
Set-Location -LiteralPath C:/git/MagnetismHeroes
$env:PATH = 'C:/Users/baram/AppData/Local/Unity/bin;' + $env:PATH
git status --short
unity --help
```

열린 Editor와 배치 명령이 같은 프로젝트를 동시에 사용하지 않게 Editor를 종료한다. tracked 변경이 없는 검증 소스를 준비한 다음 아래 네 명령을 순서대로 실행하며 매번 `$LASTEXITCODE`와 결과 파일을 확인한다. 앞 단계 실패를 건너뛰고 완료로 표시하지 않는다.

```powershell
pwsh -NoProfile -File tools/verify.ps1 -Phase EditMode -Milestone Final
pwsh -NoProfile -File tools/verify.ps1 -Phase PlayMode -Milestone Final
pwsh -NoProfile -File tools/verify.ps1 -Phase AndroidBuild -Milestone Final
pwsh -NoProfile -File tools/verify.ps1 -Phase AndroidSmoke -Milestone Final
```

AndroidSmoke 전에 `Medium_Phone_API_37.0` AVD를 Android Studio Device Manager에서 실행한다. 검사 대상은 `emulator-5554`, 가로 2400×1080이며 에뮬레이터 gRPC 입력은 localhost:8554를 사용한다. SDK의 `adb devices`와 boot 완료를 확인한다. 현재 Final 입력 도구 일부는 `$LOCALAPPDATA/Android/Sdk`를 직접 사용하므로 이 SDK에 AVD와 adb가 있어야 한다. 다른 경로·해상도·실기기에는 입력 도구 조정이 필요하다.

**전체 Android 검사는 시험 앱 데이터를 초기화하고 별도 경계 상태도 준비한다. 이용자 데이터가 있는 실기기에 그대로 실행하지 않는다.** 정상 30개 순차 진행은 새 저장으로 시작하고 주입을 하지 않는다. 빠른 계수 등의 주입 사례는 별도 폴더에 기록한다. 입력·녹음·설치 작성자를 하나로 유지한다.

결과는 `artifacts/verification/Final`의 XML·phase JSON·로그·화면·PCM에 남는다. 빌드는 `artifacts/android/Final/MagnetismHeroes.apk`와 `artifacts/android/MagnetismHeroes.apk`를 만든다. 실제 설치는 같은 검사에서 수행한다. 재실행 전 이전 증거를 별도 폴더와 해시 목록으로 보존해 다른 소스·APK 결과가 덮이지 않게 한다.

## 환경값과 저장

| 값 | 사용 범위 |
|---|---|
| `MAGNETISM_APK_PATH` | 빌드 진입점에 넘기는 APK 출력 경로. 검증 wrapper가 해당 단계의 경로를 지정한다. |
| `ANDROID_SDK_ROOT` | 이를 사용하는 Android 보조 도구의 SDK 선택. 미지정 시 LOCALAPPDATA 기본 SDK를 사용한다. Final의 일부 입력 도구는 기본 경로를 직접 사용한다. |
| 로컬 AVD gRPC 토큰 | 개발 입력 연결용. 토큰을 문서·로그·프로필에 넣지 않는다. |

게임 저장은 `Application.persistentDataPath/progress.json`, Android 시험 앱에서는 `/sdcard/Android/data/com.magnetismheroes.game/files/progress.json`이다. `.bak`은 유효 백업, `.tmp`는 교체 전 작업 파일이며 읽기 복원에서 사용하지 않는다. 손상 원본 진단은 `.damaged-*` 사본으로 남는다. 정상 플레이 재시작은 시작 화면에서 원하는 이어하기를 선택한다. 새 게임 데이터가 필요한 검사는 AVD의 시험 앱 데이터만 초기화한다.

현재 APK는 ARM64 IL2CPP·가로 화면·minSdk26의 로컬 체험판이다. AVD의 x86_64 환경에서는 arm64 번역을 사용한다. 스토어 제출용 서명·AAB·게시 절차는 수행하지 않았고 현재 APK를 게시 준비 완료로 취급하지 않는다.

## 새 자산 제작

기존 `tools/models/build_playgrounds.py`는 과거 소품 원본과 13 FBX를 재작성하는 도구다. 현재 자연 테마를 실행하거나 검증하기 위해 재실행하지 않는다. 새 모델 제작 도구는 Blender `5.2.2 LTS`의 `tools/models/build_hero.py`와 `tools/models/build_meadow.py`이며 승인된 원본·FBX는 재생성 없이 사용한다. 새 후보를 만들 때만 별도 제작·검수 회차를 준비하고 기존 승인 바이트를 보존한다.

모델 채택은 원본 2개·FBX 23개의 사용자 승인 SHA와 실제 Unity 방향·재질·대표 장비·선택 경계를 확인한 뒤 수행한다. 대상이 제한된 `VisualUpgradeAssets.Apply`는 `MAGNETISM_VISUAL_APPROVAL`의 승인 JSON과 `MAGNETISM_VISUAL_EVIDENCE`의 별도 증거 경로를 요구하는 채택용 Editor API다. 정상 프로젝트 열기나 검사 전 준비 명령이 아니다. 후보 provenance의 과거 상태를 고쳐 승인으로 만들지 않고 별도 active-adoption에 원본·입력·도구·Unity 참조·검수 해시를 연결한다.

재검증 전에는 이전 Final의 로그·화면·PCM·APK 대응 기록을 해시 목록과 함께 고정 사본으로 보존한다. 같은 경로에 남은 과거 파일을 이번 결과로 세지 않는다. 현재 실행의 소스·UTC·설치 APK SHA가 맞는 phase/child 결과만 채택한다. 현재 원경 보정 전 제품의 증거 2,311개는 `artifacts/verification/VisualUpgrade/BeforeHorizonFix/manifest.json`, 그 이전 제품은 `VisualUpgrade/PreviousFinal/manifest.json`, 새 실행 연결은 `VisualUpgrade/FinalProduct/completion.json`에 있다. 이번 첫 Smoke의 환경 관찰 명령 실패 원문 1,257개는 `VisualUpgrade/HorizonFailedSmokeAttempt1/manifest.json`에 실제 종료 1로 보존했다. 소스·제품 732개 바이트·APK 동일성을 확인한 뒤 Smoke만 재실행했으며 다른 세 단계의 통과는 유지했다.

`VisualUpgradeAssets.ApplyHorizonContinuity`는 기존 30개 Stage의 FarHorizon x/z 반경만 27로 옮기는 대상 한정 Editor API다. 정상 실행 준비로 재실행하지 않는다. 해당 보정은 실제 메시의 중앙 24m 표본과 근접/전체 화면으로 확인했으며 모든 외곽·시점의 연속성을 주장하지 않는다. 승인 메시·재질·나머지 배치와 게임 카메라는 유지했다.

음성 제작은 conda `qwen3-tts`의 CUDA 환경과 고정 1.7B CustomVoice/Sohee를 사용한다. 이미 승인된 44개는 그대로 사용한다. 새 대본이 필요할 때만 선택 ID를 별도로 생성한다.

```powershell
conda run --no-capture-output -n qwen3-tts python tools/audio/generate_voice.py --catalog SourceAssets/Audio/Voice/voice-catalog.json --profile SourceAssets/Audio/Voice/qwen-profile.json --ids guide_collect
```

출력된 manifest 경로를 파일 검사에 전달하고 새 후보는 `artifacts` 아래 별도 target으로 내보낸다. 기존 runtime와 바이트가 다른 후보의 기본 경로 내보내기는 거부된다. 청취·형식 검수와 사용자 채택 전에는 승인본 교체나 재생성 완료 처리를 하지 않는다. 생성 원본은 실제 sample rate로, 게임 파일은 현재 44.1kHz mono PCM16으로 보존한다. GPU가 없으면 CPU·온라인 서비스로 자동 전환하지 않는다.

후보를 들을 때는 지정한 `--target`의 실제 WAV를 연다. selection의 `runtimeFile`은 게임에 채택할 예정 경로이며 별도 target의 출력 위치를 뜻하지 않는다. 채택 확인은 active-adoption과 정확한 승인 SHA로 수행한다.

얼굴 후보는 투명 PNG와 프롬프트·채택 해시를 남기고 숫자·한국어는 TMP로 유지한다. 실제 Unity 구 표면과 Android 화면에서 가장자리·표정·계수 표시를 확인한다. 모델·얼굴·음성·글꼴 교체 때는 해당 파일의 출처·조건·필요 고지가 APK에 유지되는지도 확인한다.

## 지면·여섯 풍경의 대상 한정 제작

이미 연결된 Main을 그대로 실행한다. 풍경을 제작할 때만 `PlaygroundSceneryAssets.Apply`로 자연 프리팹의 역할별 MeshCollider, 30개 시각 배치·접지와 GameApp의 바닥 연결을 갱신한다. 현재 플레이 경계는 중심 (0, 3.025, 0), 크기 (17, 6.95, 13)이며 구 반지름 여유는 이동 판정에서 적용한다. 기존 초기 구·목표·GUID와 승인 모델·재질을 보존하고 생성 diff를 확인한다. 이전 일괄 채택 API나 초기 builder를 정상 실행 준비로 호출하지 않는다.

`PlaygroundRestoreGeometryAssets.CreateCache`는 승인된 충돌 메시의 읽기 전용 정점·삼각형과 원본·meta 해시를 저장한다. 기존 캐시가 있으면 덮어쓰지 않고 거부한다. 필요한 제작 변경의 검수 후 `BindGameApp`으로 기존 프리팹 참조만 연결한다. FBX의 Read/Write나 import root를 바꾸는 대신 이 런타임 판정 자산을 사용한다.

Final 검사에서는 `MAGNETISM_VISUAL_EVIDENCE`, `MAGNETISM_DRAG_CAMERA_EVIDENCE`, `MAGNETISM_BENCHMARK_EVIDENCE`로 각각 Editor 표현·끌기·자원 자료의 별도 폴더를 지정할 수 있다. `MAGNETISM_NATIVE_FIXTURES`는 실제 Main에서 내보낸 초기 보드·충돌·시점·복원 경계 자료의 폴더다. 과거 자료를 새 검사의 출력으로 혼용하지 않는다. Editor의 모든 초기 173개 구 입력 검사와 Android 대표 입력·30개 정상 풀이를 구분한다.

Android 전체 검사를 실행할 때는 실행 담당자가 검사 전에 primary와 backup을 각각 pull하여 원래 유무·SHA를 기록한다. 내부 하위 도구의 정리는 정상30개 완료 상태를 양쪽 파일에 되돌리므로 검사 전 원본 두 파일의 독립 복구를 보장하지 않는다. 전체 검사 바깥의 정리 절차에서 각 원본을 독립적으로 복원·pull·SHA 대조하고, 원래 없던 파일은 새 주입 상태로 남기지 않는다. 이 외부 보존·복구 절차를 먼저 준비한 뒤 검사한다. 앱 PID와 실제 금색 버튼 화면이 준비됐는지 확인한 뒤 입력한다. `wm size` 전환 직후에는 실제 해상도가 안정됐는지 확인하고, ADB·Editor·녹음 소유자를 하나로 유지한다. 토큰은 기록하지 않는다.