Document verified Android game architecture, rules and development procedures

2026-10-07 03:15:08 +09:00
parent ea2ad4506c
commit 2d45e11120
30 changed files with 676 additions and 0 deletions
@@ -0,0 +1,17 @@
+# 규칙과 Unity의 분리
+
+## 배경
+
+자석의 수량·소속·중복 계수·분리 경계와 이어하기는 화면과 관계없이 정확해야 한다. 카툰 연출을 바꾸면서 수학 상태가 달라지지 않게 해야 하고, 초기 퍼즐 하나부터 Android까지 연결하며 확장한다.
+
+## 결정
+
+순수 C# 규칙·진행 제어와 Unity 입력·화면·파일 연결을 분리한다. 상태는 명시적 enum과 전이로 관리하고 Presenter·저장 인터페이스·시작 코드의 직접 연결을 사용한다. MonoBehaviour는 실제 장치·렌더링을 연결한다.
+
+## 대안
+
+MonoBehaviour 안에 규칙까지 모으면 첫 화면 구현은 빠르지만 규칙·저장 검사를 Unity 객체 수명에 묶는다. 범용 DI·이벤트·MVVM 프레임워크는 연결을 자동화하지만 최대 10구의 단독 게임에서 추적·디버깅 부담을 늘린다. 두 대안 대신 작은 직접 연결을 선택했다.
+
+## 결과
+
+연결 코드를 직접 작성하는 비용이 생기고 화면의 Transform이나 충돌 이벤트를 규칙 상태로 취급할 수 없다. 규칙 검사는 씬 없이 가능하며 장식·프리팹 변경을 수학 판정과 분리할 수 있다. 다만 입력과 실제 화면 연결은 별도 PlayMode·Android 검증이 필요하다.
@@ -0,0 +1,17 @@
+# 고정 스테이지를 Inspector에서 제작
+
+## 배경
+
+스테이지는 초기 묶음·목표뿐 아니라 자석과 장식의 3D 배치·테마 참조를 가진다. 같은 규칙으로 30개를 실행하고 제작 배치를 플레이 결과가 덮어쓰지 않아야 한다.
+
+## 결정
+
+ScriptableObject를 Inspector에서 제작하고 시작할 때 순수 C# 정의로 복사한다. 플레이 중 구·소속·카메라는 별도 상태와 JSON으로 유지한다. 번호마다 씬이나 정답 로직을 복제하지 않는다.
+
+## 대안
+
+외부 JSON으로 고정 정의를 만들면 Unity 밖 편집은 쉬워지지만 3D 배치와 자산 참조를 별도로 관리해야 한다. 처음부터 모든 배치를 코드 builder로 관리하면 생성은 빠르지만 Inspector의 미술 조정을 재실행으로 잃을 수 있다. 현재 Unity 제작 흐름을 우선했다.
+
+## 결과
+
+Unity 자산 GUID·Inspector 참조와 정의 변환 검사를 함께 유지한다. 실행 중 원본 자산을 저장 공간으로 사용할 수 없다. 데이터가 유효해도 실제 발견·조작 가능성은 에디터와 APK에서 따로 확인해야 한다.
@@ -0,0 +1,17 @@
+# 퍼즐별 로컬 기록과 최근 자유 놀이
+
+## 배경
+
+아이들이 여러 퍼즐을 오가고 완료한 곳도 다시 풀 수 있다. 중단한 배치까지 이어야 하며 두 퍼즐의 진행과 최근 자유 놀이가 서로 덮이지 않아야 한다. 계정 없이 오프라인으로 혼자 플레이한다.
+
+## 결정
+
+JSON 버전 1에서 번호별 미완료 상태, 감소하지 않는 완료 기록, 본 시범과 자유 놀이 한 상태를 보관한다. 저장 인터페이스로 파일 접근을 분리하고 전체 검증·임시 파일 교체·유효 백업 복구를 사용한다.
+
+## 대안
+
+모든 플레이를 한 슬롯에 저장하면 단순하지만 다른 퍼즐로 이동할 때 배치를 잃는다. 자유 놀이를 번호별 여러 슬롯에 보관하면 작품을 더 남길 수 있지만 사용자가 정한 ‘최근 하나’와 다른 보관·선택 기능이 필요하다. 계정·클라우드는 기기 간 복구를 제공하지만 오프라인 단독 체험판에 인증·서버·동기화를 추가한다.
+
+## 결과
+
+완료 번호의 재플레이 미완료 상태와 완료 기록이 동시에 존재할 수 있다. 자유 놀이 새 진입은 이전 하나를 교체한다. 기기 손실·앱 데이터 삭제 후 원격 복구는 불가능하다. 스키마 변경에는 기존 유효 저장의 처리 결정을 먼저 해야 하며 unsupported 버전을 최신 형식으로 조용히 읽을 수 없다.
@@ -0,0 +1,17 @@
+# 로컬에서 미리 제작한 학습 음성
+
+## 배경
+
+숫자와 안내는 5~7세가 듣기 쉽고 문구 수정이 가능해야 한다. 사용자가 설치한 conda `qwen3-tts`와 GPU·1.7B CustomVoice·한국어 Sohee 구성을 선택했다. 앱은 네트워크 없이 동작해야 한다.
+
+## 결정
+
+제작 PC의 Qwen3-TTS로 WAV를 생성하고 대본·고정 모델 revision·프로필·원본·편집본·청취 승인 해시를 연결한다. 앱은 채택된 파일만 포함한다. 제작 성공과 청취 승인을 구분한다.
+
+## 대안
+
+직접 녹음은 따뜻한 말투를 제어할 수 있지만 문구마다 녹음 참여가 필요하다. CPU·0.6B는 환경 준비가 가볍지만 제작 시간과 말투 지시의 차이가 있다. 목소리 설계·복제는 독자성을 늘리지만 일관성 검수를 추가한다. 온라인 TTS·런타임 생성은 오프라인 동작과 파일 품질의 고정 인수에 맞지 않는다.
+
+## 결과
+
+GPU와 모델은 새 제작에 필요하지만 Unity 플레이·빌드에는 필요 없다. 실행 중 임의의 새 문장을 즉석 발화할 수 없고 새 안내는 후보 제작·청취·채택을 거쳐야 한다. 같은 seed도 바이트 재현이나 발음을 보장하지 않는다. 수정된 ‘여덟’과 나머지 승인 파일을 다시 생성하지 않고 정확한 채택본을 유지한다.
@@ -0,0 +1,17 @@
+# Unity·Blender·AI 얼굴의 혼합 제작
+
+## 배경
+
+친구는 아이가 만든 구 배열을 유지하면서 표정·마스크·연결 빛·망토로 변신해야 한다. 배경은 세 테마로 구별되며 숫자는 실제 수량과 대응해야 한다. 사용자는 Unity+Blender와 실제 2D 자산의 AI 활용을 선택했다.
+
+## 결정
+
+Unity에서 공유 구·대표 얼굴 배치·숫자·효과·프리팹을 만들고 Blender에서 작은 배경 소품을 제작한다. AI 이미지의 실제 채택은 투명 얼굴 atlas이며 한국어·숫자는 TMP로 표시한다. 원본과 Unity 입력 파일을 분리하고 출처·생성 입력·수정·검수·사용 조건을 보존한다.
+
+## 대안
+
+Unity 기본 도형만 사용하면 제작 부담은 줄지만 배경 소품 표현이 제한된다. AI를 참고 시안에만 쓰고 실제 2D를 직접 제작하면 세밀한 통제는 쉬워지지만 사용자가 허용한 제작 속도 이점을 쓰지 못한다. 숫자마다 고정 몸체를 모델링하면 캐릭터는 뚜렷하지만 아이가 붙인 모양을 유지할 수 없다.
+
+## 결과
+
+FBX 방향·피벗·콜라이더와 PNG alpha·구 위의 표정 위치를 각각 검수해야 한다. 생성 이미지에 독점권을 주장하거나 도구가 공개하지 않은 모델 ID를 추측할 수 없다. 얼굴 장식은 별도 머리나 구가 아니며 숫자를 그림에 굳히지 않는다. 테마 소품·배치의 다양성은 학습 정답 조건을 늘리는 근거가 아니다.
@@ -0,0 +1,9 @@
+# 설계 결정
+
+| 결정 | 선택과 비용 |
+|---|---|
+| [0001 규칙과 Unity 분리](0001-rules-boundary.md) | 화면 없이 규칙을 검증하고 연결 코드를 직접 유지한다. |
+| [0002 고정 스테이지 자산](0002-stage-authoring.md) | Inspector의 공간 편집을 사용하고 별도 플레이 JSON을 유지한다. |
+| [0003 로컬 이어하기](0003-local-progress.md) | 퍼즐별 슬롯과 자유 놀이 하나를 저장하고 기기 간 복구는 제공하지 않는다. |
+| [0004 미리 제작한 학습 음성](0004-prebaked-voice.md) | 수정 가능한 로컬 TTS를 쓰고 실제 파일 청취·채택을 거친다. |
+| [0005 혼합 자산 제작](0005-hybrid-assets.md) | Unity 표현·Blender 소품·AI 얼굴을 결합하고 각 원본·검수를 유지한다. |
@@ -0,0 +1,3 @@
+# 미해결 문제
+
+2026-10-07 통합본의 규칙·화면 연결·저장·AVD 진행 검증 범위에서 재현되는 미해결 결함은 없다. 발견한 입력 검사·저장 관찰·녹음 수명 문제는 수정 후 실제 사례로 확인했다. 실기기 사용성·성능과 iOS는 아직 검사하지 않았으며 관찰된 결함으로 기록하지 않는다.
@@ -0,0 +1,24 @@
+# 현재 구현과 검증 범위
+
+2026-10-07. 한국어·Android·가로 화면·오프라인 체험판을 구현했다. 수 세기 10개와 합체·분리·혼합 20개, 순차 해금·재플레이·도움·시범·성공 후 자유 놀이가 연결됐다. 자유 놀이는 공급·묶음 반납·빈 보드와 10개 한도를 지원한다. 미완료 퍼즐별 저장과 최근 자유 놀이 하나, 손상 파일 복구를 구현했다.
+
+Unity 자석 구·얼굴/마스크·연결 빛·망토, Blender 소품 13개, 정원·구름·별 작업실 세 테마, 실제 AI 생성 얼굴 6표정과 한국어 UI가 포함됐다. 로컬 Qwen3-TTS의 숫자·안내 44개는 사용자 청취 승인 파일을 채택했다. 효과음·배경음악은 사용자의 첫 버전 제외 결정에 따라 포함하지 않았으며 미완료 자산으로 간주하지 않는다.
+
+## 확인된 결과
+
+통합 `dev`의 `ea2ad4506ce2288f7777c0eb017833723679f487`에서 네 검증 명령의 실제 종료가 모두 0이었다. EditMode 100/100, PlayMode 47/47이며 실패·건너뜀·미확정이 없다. Android 최종 검사 226개와 하위 정상 진행 151개·경계 37개·빠른 계수 39개·콘텐츠 69개가 통과했다. 하위 수를 서로 독립적인 제품 기능 수로 합산하지 않는다.
+
+새 저장에서 1~30을 실제 입력으로 순서대로 해결했으며 완료 기록을 미리 주입하지 않았다. 서로 다른 두 미완료 퍼즐과 최신 자유 놀이의 배치·부분 계수·카메라가 강제 종료 뒤 각각 복원됐다. 별도 경계 상태로 10개 제한·반납·재공급·빈 보드·취소·손상 복구·오프라인 전체 숫자 발화·마지막 발화 보존을 검사했다.
+
+원본은 `artifacts/verification/Final`이며 고정 사본은 `artifacts/verification/T8/BaseEa2`에 2,527개 파일과 SHA 목록으로 보존했다. 별도 원본 대조 `artifacts/verification/T8/independent-base-evidence-ea2.json`의 234개 확인도 통과했다. 최종 APK는 `artifacts/android/MagnetismHeroes.apk`, SHA-256 `0D341465FD2DC4809DF8FA423490A9CFB3BA755220A8685479399CACBD9BDDE8`다. 실제 설치본과 같은 해시이며 승인 44개 PCM과 필요한 고지 3개의 정확한 포함을 확인했다.
+
+검증 환경은 Unity 6000.6.3f1과 API37의 2400×1080 AVD다. 음성의 실제 재생과 대표 화면, Editor의 스마트폰·태블릿 비율 검증은 수행했지만 모든 기기·모든 시점의 가독성을 증명한 것은 아니다. 이전 검사 실패는 별도 증거로 남기고 통과 결과로 바꾸지 않았다.
+
+## 남은 확인과 확장
+
+1. 실제 Android 스마트폰·태블릿을 준비해 손가락 이동/선택/핀치, 작은 화면 가독성·안전 영역과 최대 구·소품 상태의 프레임·메모리·발열·배터리를 측정한다. AVD 결과는 이를 대신하지 않는다.
+2. 5~7세의 실제 사용으로 도움 이해·중복 계수 표시·분리 선택 난도를 관찰하고 학습 목적에 맞춰 조정한다. 현재 학습 효과를 검증한 실험은 없다.
+3. iPhone·iPad는 Mac/Xcode와 실제 기기를 확보한 뒤 별도 빌드·조작·저장 검증을 수행한다. 스토어 배포·서명·AAB 준비도 후속 범위다.
+4. 생활 장치·소풍 열차 등 영웅 미션과 곱셈·나눗셈 확장은 검토 아이디어다. 정해진 장치 배치나 새 성공 조건을 현재 퍼즐에 이미 구현한 것으로 취급하지 않는다.
+
+효과음·배경음악 추가는 후속 요청과 사용자 파일 선정으로 진행한다. 추가 언어, 계정·동기화, 여러 작품 보관함, 넓은 탐험 월드, 광고·결제는 현재 구현 범위가 아니며 도입 여부부터 별도로 결정한다. 현재 승인 범위의 실행을 막는 미해결 문제는 없다.