MagnetismHeroes/docs/architecture.md

시스템 구성

MagnetismHeroes는 기기 한 대에서 실행하는 오프라인 클라이언트다. Unity 장면 하나가 시작·선택·퍼즐·자유 놀이 화면과 입체 놀이터를 함께 유지한다. 서버나 원격 저장소를 거치지 않아 화면, 수학 상태, 로컬 저장의 일치가 가장 중요한 연결 경계다.

구성	책임과 연결 방향
Core	Unity 참조 없는 C# 데이터·수학 규칙·진행 제어. 저장 인터페이스를 선언하며 입력·렌더링·파일 구현에는 의존하지 않는다.
UnityRuntime의 시작 연결	고정 스테이지를 C# 정의로 변환하고 파일 저장 구현을 진행 제어에 직접 전달한다. 화면과 입력의 수명을 연결한다.
입력·카메라	Input System 포인터·터치를 해석하고 UI 판정과 3D Raycast로 조작 대상을 결정한다. 미리보기와 확정 명령을 구분해 Core에 전달한다.
화면·연출	Presenter가 확정 상태를 URP의 구·연결 빛·얼굴·망토와 uGUI·TextMeshPro 화면으로 표현한다. 음성 플레이어는 재생 큐만 소유한다.
고정 스테이지	Inspector에서 제작한 ScriptableObject가 초기 구성·목표·배경 참조를 제공한다. 플레이 결과는 원본 자산으로 돌아가지 않는다.
파일 저장	Core의 인터페이스를 구현해 JSON 상태 전체를 검증·교체·복구한다. GameObject나 애니메이션을 저장하지 않는다.
Editor	프로젝트 자산 제작과 Android 빌드를 담당한다. Editor 전용 어셈블리이며 런타임은 참조하지 않는다.
제작 원본·도구	Blender·로컬 Qwen3-TTS·이미지 생성으로 FBX·PNG·WAV를 제공한다. 도구·모델·캐시는 앱 실행의 의존성이 아니다.

flowchart LR
    I[터치·버튼] --> U[입력과 시작 연결]
    U --> C[진행 제어와 수학 규칙]
    C --> P[Presenter·UI·3D]
    C --> S[저장 인터페이스]
    S --> F[기기의 JSON 파일]
    U --> V[앱에 포함된 음성 재생]
    A[고정 스테이지 자산] --> U

3과 2인 친구를 붙이는 경우, 입력 계층이 접촉 후보와 이동량을 미리 보여준 뒤 놓는 순간 두 묶음 ID를 전달한다. 진행 제어가 규칙을 호출하고 확정 결과를 받아 목표를 판단한다. 성공이면 완료 기록·미완료 상태 제거·같은 보드의 자유 놀이 상태를 한 번에 저장한다. Presenter는 결과에서 대표 얼굴과 숫자 5를 다시 만든다. 콜라이더 접촉 수나 흔들리는 Transform이 정답을 결정하지 않는다.

카메라·선택·연출은 같은 수명을 갖지 않는다. 카메라 조작의 확정값은 저장으로 넘어가지만 분리 선택과 끌기 중간 위치는 입력 계층 안에 남는다. 연출은 상태에서 재생성하며, 화면 전환과 일시 정지에서 미리보기·지난 음성을 정리한다. 같은 보드의 성공 전이에서는 숫자 큐를 유지하므로 학습 발화 완료와 게임 성공은 서로 기다리지 않는다.

컴파일 방향은 UnityRuntime → Core, Editor → Core·UnityRuntime이다. 의존성은 시작 지점에서 직접 연결하고 화면·제스처는 명시적 상태로 표현한다. 이 규모에서는 범용 DI 컨테이너·전역 이벤트 버스·MVVM·ECS를 전제로 하지 않는다.