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 얼굴을 결합하고 각 원본·검수를 유지한다. |