MagnetismHeroes 개발 인계

2026-10-06 최신 사용자 승인: 효과음·배경음악 없이 첫 버전을 진행하고 T7을 마무리한 뒤 T8을 수행한다. 기존 음원 선택 대기는 해제됐다. 아래 효과음·음악 포함·선정·반복/믹싱 기준은 후속 범위로 이동하며 한국어 음성 44개·시각 연출·오프라인 및 저장/규칙 기준은 유지한다. 기획 초기의 환경 상태 설명은 실제 최신 검증 기록을 대신하지 않는다.

문서 역할과 우선순위

문서	역할
`.dryforge/spec.md`	게임 동작·범위·30개 스테이지·검증 기준의 기준 문서
`.dryforge/plan.md`	구현 작업 대상, 순서, 검증 방법을 제안하는 개발 계획
`.dryforge/handoff.md`	문서 사용법, 반드시 지킬 경계, 프로젝트 배경

동작이 충돌하면 기획서가 우선한다. 기획서의 사용자 의도를 바꾸려면 사용자와 먼저 조정한다. 계획의 파일 배치와 작업 순서는 같은 기획을 실현하는 범위에서 수정할 수 있다. 기존 코드가 생겨도 구현 방식의 참고이며 게임의 목적을 대체하지 않는다.

실행 개요

첫 개발 단계이며, 작업 폴더에 기존 게임 코드는 없다. 공통 프로젝트와 순수 C# 규칙을 준비한 뒤 1번 수 세기 퍼즐의 입력·화면·저장을 연결하고 Android에서 첫 실행을 확인한다. 이후 합체·분리 → 저장·자유 놀이 확장 → 30개 스테이지·도움 → 카툰·한국어 연출 → 최종 전체 검증으로 진행한다. 각 단계에서 플레이 가능한 이전 결과를 유지한다. 세부 작업과 의존 관계는 개발 계획을 따른다. 프로젝트 초기화와 단계별 실행 장면 연결은 실행 담당자가 맡고, 같은 장면을 여러 작업에서 동시에 수정하지 않는다. 첫 퍼즐부터 최소 자산의 포함·재생을 확인하고, 세 테마와 전체 배치를 연결한 뒤 최종 자산을 마감한다.

현재 문서는 기획 결과다. Unity의 Android Build Support, SDK·NDK·OpenJDK와 Android Studio 및 가상 기기 설치는 확인했다. 게임 코드, 프로젝트 패키지 설치, APK 제작, 가상 기기 실행은 아직 수행하지 않았다. 기존 Git 이력과 .gitignore는 이 문서 작성에서 변경하지 않는다. 사용자가 문서를 확인한 뒤 이 대화에서 dryforge:go를 호출하여 개발을 시작한다.

반드시 지킬 경계

구 하나의 값은 1이고 합체·분리로 총량이 달라지지 않는다. 숫자 표시와 실제 개수가 일치해야 한다.
모양이나 풀이 순서로 정답을 제한하지 않는다. 분리할 구들이 서로 떨어져 있어도 두 친구로 모은다.
수 세기는 전부 찾고 직접 모은 뒤 각각 눌러 세야 한다. 이미 센 구를 중복으로 세지 않는다.
기획서의 30개 스테이지와 순서를 그대로 구현한다. 더 적은 스테이지를 완성 결과로 제시하지 않는다.
실패 점수·목숨·시간제한을 추가하지 않는다. 성공 후 같은 공간에서 자유롭게 놀게 한다.
미완료 퍼즐은 스테이지별로 각각 저장하고, 최근 자유 놀이는 전체에서 하나만 저장한다. 완료 기록은 재플레이로 취소하지 않는다.
한국어 소리와 자산을 포함한 오프라인 안드로이드 체험판이다. 서버·광고·결제·사용자 추적을 도입하지 않는다.
APK 생성과 Android 가상 기기 실행·진행·복원은 구분하여 검증한다. 가상 기기를 실행하지 못했으면 그 항목을 통과로 표시하지 않는다.
실제 손가락 조작·실제 기기 가독성·성능은 기기 준비 후 검사한다. iOS 지원과 앱 스토어 배포는 이번 완료 범위가 아니다.
기획을 바꾸지 않는 구현·튜닝은 개발자가 판단한다. 새로운 놀이 규칙·저장 범위·플랫폼 범위 변경은 사용자와 먼저 조정한다.
순수 C# 규칙과 Unity 연결을 분리하고 URP·Input System·uGUI·TextMeshPro를 사용한다. 고정 ScriptableObject 자산과 JSON 플레이 저장을 혼용하지 않는다.
첫 퍼즐부터 Android를 검증한다. 조기 검사나 에디터 검사만으로 최종 APK 검증을 통과 처리하지 않는다. 각 기능의 합격 사례와 실행 증거를 남긴다.
합체 영웅은 개별 자석 구·대표 얼굴과 마스크·빛나는 연결부·자력 망토로 표현한다. 변신으로 구의 기본 크기나 아이가 만든 배치를 바꾸지 않으며, 분리 시 두 묶음으로 모으는 조정은 R04를 따른다. 장식이 구·숫자·선택·계수 표시와 입력을 가리지 않게 한다.
배경 테마 3개를 제작한다. Unity·Blender를 함께 사용하고 실제 2D 자산에도 AI 이미지를 활용한다. 효과음·음악은 사용자 선택 절차를 따른다. 음성은 conda qwen3-tts의 로컬 Qwen3-TTS를 정비해 GPU·1.7B CustomVoice·한국어 Sohee로 제작한다. 임시·미선택 파일과 미검수 출력은 최종 완료가 아니다.
숫자 음성은 계수 순서대로 들리고 같은 보드의 성공 후에도 마지막 숫자가 보존되어야 한다. 조작·성공 판정을 소리에 종속시키지 않는다. 화면 전환·일시 정지·복원 때 오래된 음성·연출이 남지 않게 한다.

별도로 남길 의도

실행에 필요한 사용자 의도는 기획서와 계획에 담았다. 대화를 다시 읽어야만 알 수 있는 추가 규칙은 없다. 처음의 20개 안은 합체·분리 개념을 충분히 반복하기 위해 30개로 확장되었으며, 초기의 모든 모바일 플랫폼 동시 제작은 첫 단계 안드로이드 제작으로 좁혀졌다. 실행 중 이전 안을 다시 적용하지 않는다.

프로젝트 배경

실행 범위가 아닌 프로젝트 맥락이다. 이 절은 개발 방향과 향후 프로젝트 안내 문서의 배경으로 사용한다. 구현할 항목과 완료 기준은 기획서에 따른다.

1. 정체성

5~7세가 숫자를 직접 만져 보는 체험형 3D 퍼즐 게임이다. 자석 구 하나를 1로 삼고, 친구들을 합체·분리하며 수량과 숫자를 연결한다. 모바일 가로 화면에서 손가락으로 다루는 장난감 같은 경험을 지향한다. Numberblocks의 수량을 드러내는 캐릭터 표현이 참고이며, 구 자석을 직접 조작하는 것이 이 게임의 중심이다.

캐릭터의 중심 문장은 ‘아이가 붙인 모양이 영웅의 몸이 되고, 연결되는 순간 대표 표정과 자력 망토가 완성된다’이다. 붙으면 하나의 영웅 팀, 나뉘면 함께 돕는 두 팀으로 표현한다. 변신을 보면서도 같은 구들이 보존된다는 사실을 따라갈 수 있게 한다. 특정 모양이나 더 큰 수를 상위 등급 영웅으로 취급하지 않는다.

첫 체험판은 한국어·안드로이드·오프라인·혼자 플레이로 한정한다. 광고와 결제는 없다. 30개 스테이지로 수집·계수·합체·분리를 반복하고, 성공 후 같은 공간에서 자유롭게 놀게 한다. 사용자에게 중요한 것은 실제 수의 의미와 조작의 자유이며, 빠른 정답이나 실패 점수는 목표가 아니다.

2. 놀이의 개념과 규칙

자석 구: 값 1인 최소 단위다. 합체·분리·이동으로 소실되거나 복제되지 않는다. 자유 놀이에서만 꺼내거나 반납할 수 있다.
친구: 하나 이상의 구로 된 묶음이다. 대표 얼굴 하나와 묶음 개수 표시를 가진다. 합체하면 한 친구가 되고, 분리하면 선택한 구와 남은 구가 각각 한 친구가 된다. 이전 묶음의 정체성보다 구성 구의 보존이 중요하다.
합체 영웅의 표현: 기존 구 표면의 대표 얼굴·얇은 마스크, 접촉부의 빛, 묶음 뒤 리본형 망토로 구성한다. 안정 상태에서 얼굴·숫자·망토는 묶음마다 하나다. 합체 시 한 팀으로 통합되고 분리 시 각 팀에 생긴다. 짧은 포즈와 흔들림은 구의 정체성·기본 배치·계수 기록을 바꾸지 않으며 장식은 확정 상태에서 다시 만들 수 있다.
입체 놀이터: 한 화면에서 회전·확대하며 둘러보는 작은 공간이다. 자석은 공중에 뜨고 모든 방향으로 붙일 수 있다. 탐험은 사물 뒤·위의 자석을 찾아 끌어오는 행동이며 보행 캐릭터나 넓은 월드는 없다.
배경 테마: 서로 다른 세 장소의 외형을 작은 입체 세트와 주요 소품으로 구성한다. 소품은 공유할 수 있으며 테마와 배치는 고정 스테이지 정의에서 정한다. 테마가 학습 목표·정답 조건을 바꾸지 않고 성공 후 놀이와 복원에서도 유지된다.
학습 음성과 음원: 화면의 계수·시범·도움에 대응하는 제작 파일이다. 숫자 발화는 순서를 지키며 입력·진행 상태를 소유하지 않는다. 효과음·음악의 최종 선택은 사용자가 한다. 사용자가 설치한 Qwen3-TTS 환경에서 실행 담당자가 대본을 파일로 생성·검수한다. 선택 전 임시 파일로 구현을 진행할 수 있지만 최종 품질·사용권 검수가 끝나야 완성으로 취급한다.
수 세기 퍼즐: 목표만큼의 자석을 모두 모아 하나씩 눌러 센다. 단순히 목표 숫자를 표시하는 것만으로 끝나지 않는다. 구별 계수 기록은 배치가 바뀌거나 앱을 다시 열어도 유지된다.
구성 퍼즐: 준비된 친구들을 목표 개수의 친구들로 바꾼다. 전체 묶음 구성만 같으면 모양과 풀이 순서는 자유다. 2와 2는 4 하나와 다르다.
나누기 선택: 한 친구 안의 원하는 구들을 고른다. 서로 떨어진 구도 고를 수 있으며, 분리 후 양쪽을 각각 한 묶음으로 모은다. 0개나 전체 선택으로 빈 친구를 만들지 않는다.
도움: 찾거나 셀 구 하나, 또는 목표에 접근할 첫 행동을 알려준다. 대신 실행하거나 사용 횟수로 불이익을 주지 않는다.
완료와 자유 놀이: 성공하면 기록을 남기고 다음 번호를 열지만 화면을 강제로 바꾸지 않는다. 같은 친구들로 자유 놀이를 하며 최대 10개까지 꺼내거나 반납한다. 빈 놀이판도 다시 채울 수 있다.
퍼즐 저장: 각 스테이지의 현재 미완료 상태를 따로 보존한다. 완료한 스테이지를 다시 풀다가 멈춘 상태와 과거 완료 기록은 함께 존재할 수 있다.
자유 놀이 저장: 최근 하나만 보존한다. 퍼즐별 저장과 혼합하지 않는다. 새로운 자유 놀이로 넘어가면 이전 자유 놀이 저장을 교체한다.
학습 흐름: 1~~5 세기 5개 → 합치기 4개·분리하기 4개·혼합 2개 → 6~~10 세기 5개 → 합치기 4개·분리하기 4개·혼합 2개. 스테이지는 순서대로 열리며 완료한 곳은 다시 플레이할 수 있다.

3. 기술 방향

Unity 6를 사용한다. 작업 환경에서 확인한 설치 버전은 6000.6.3f1이며 기존 게임 코드는 없다. 다른 버전으로 옮겨야 한다면 도구 호환성 이유와 영향을 먼저 확인한다.
클라이언트 하나에서 입력을 순서대로 처리하고 수학 상태를 확정한다. 온라인 공유 상태와 서버 API가 없으므로 분산 동기화는 필요하지 않다.
수량·합체·분리·계수·목표 판정과 진행 제어는 순수 C#으로 작성한다. Unity 객체는 입력·3D 배치·표현·파일 저장의 연결을 담당한다. 규칙을 화면 없이 검사할 수 있게 하며 렌더링·물리 효과 때문에 구의 개수가 바뀌지 않게 한다.
URP·Input System·uGUI·TextMeshPro를 사용한다. 프리팹과 Inspector에서 카툰 캐릭터·화면을 제작한다. 큰 UI 문서 프레임워크보다 현재 게임의 Unity 제작 흐름을 우선한다.
명시적 상태 머신, Presenter, 저장 인터페이스와 시작 지점의 직접 의존성 연결을 사용한다. 범용 DI·이벤트·MVVM 프레임워크는 도입하지 않는다. 상태 머신은 화면·조작의 유효 전이를 드러내고 Presenter는 수학 규칙을 소유하지 않는다.
스테이지의 고정 초기 구성·목표·배치는 ScriptableObject로 제작하고 런타임 순수 C# 정의로 변환한다. 플레이 중 배치와 완료 기록은 원본 자산과 분리한다.
저장은 기기 내 앱 전용 파일의 JSON 버전 1로 처리한다. 퍼즐별 배치·수집·계수·카메라와 최근 자유 놀이를 복원한다. 저장 인터페이스는 파일 없이 진행 제어를 검사하기 위한 경계이며 사용자 계정·클라우드·여러 사용자 프로필은 없다.
한국어 소리와 화면 자산을 앱에 포함한다. 실행 중 네트워크, 마이크, 연락처, 위치 정보가 필요한 기능을 만들지 않는다. 자산의 출처와 사용 범위를 기록한다.
Unity에서 자석 구·표현·효과를, Blender에서 입체 배경 소품을 만든다. AI 이미지도 실제 얼굴·UI 그림·텍스처에 사용하며 한글·숫자 표시는 TMP에서 처리한다. 제작 원본과 FBX·PNG·WAV 등 Unity 입력 파일을 분리하고 사용 조건·생성/수정·검수 기록을 남긴다.
음원 요청 목록과 Qwen3-TTS 대본·생성 프로필·파일 규격을 실행 담당자가 준비한다. 효과음·음악의 최종 선정은 사용자가 한다. conda qwen3-tts 환경을 재사용하고 GPU·Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice·Korean·Sohee로 로컬 생성한다. 제작 환경과 원본/생성 이력은 Unity 코드 밖에 두고 채택한 WAV만 게임에 연결한다. 모델 다운로드·음성 생성은 개발 실행 단계에서 수행한다.
Qwen3-TTS 패키지와 클래스 import는 확인했으나 현재 PyTorch는 CPU 구성이다. 기존 환경을 무조건 재설치하지 않고 GPU 실행에 필요한 변경만 수행한 뒤 모델 로딩·실제 추론·청각 품질을 각각 확인한다. 개발 도구가 준비되지 않아 임시 파일로 진행한 상태와 최종 음성 완료를 구분한다.
작은 퍼즐을 입력부터 저장까지 완성하며 확장한다. Unity 에디터의 EditMode·PlayMode 검사를 기능마다 수행하고, 첫 퍼즐의 Android 설치·실행·복원을 확인한 뒤 전체 Android 검증을 마지막에 반복한다. 실제 기기 검증은 이번 결과와 분리한다.
요구사항에서 기능별 합격 사례를 먼저 정하고 정상·무효·경계·복원을 검사한다. 테스트 실행 수와 실패·미실행 여부, 소스 상태·APK 식별 정보·기기·로그를 남긴다. 테스트가 없거나 검사하지 못한 결과를 성공으로 처리하지 않는다.
Core와 Unity 실행 코드, Editor 도구와 테스트의 참조 경계를 지킨다. C# 이름 규칙과 프리팹·씬의 단독 작성 규칙은 계획에 기록한다. 조작 임계값·흡착 거리·연출 시간은 플레이 감각을 보고 조정하는 값이다. 실제 기기 성능 합격은 기기 준비 후의 범위다.
파일 배치·직렬화 라이브러리·그림/음원 편집 도구·미술 조정값은 위 동작을 보존하는 구현 선택이다. 제작용 AI 이미지는 허용하되 새 게임 서버·런타임 AI·클라우드 TTS·승인 없는 유료 자산 구매·배포는 도입하지 않는다.

4. 향후 범위

생활 속 문제를 돕는 영웅 세계관을 확장할 수 있다. 자석을 생활 장치에 연결하는 미션과 소풍 열차는 검토 아이디어이며, 장치 배치를 새로운 성공 조건으로 넣는 것은 별도 기획 대상이다. 이번 합체 영웅 외형 반영으로 R07의 30개 목표와 모양·위치에 무관한 판정을 바꾸지 않는다.
실제 안드로이드 스마트폰·태블릿에서 손가락 조작, 가독성, 성능 검증과 조정.
아이폰·아이패드용 빌드 및 Mac/Xcode·실제 기기를 통한 검증.
곱셈·나눗셈 등 수학 개념 확장. 이번 분리하기를 나눗셈 학습으로 간주하지 않는다.
영어, 광고·결제, 계정·동기화, 작품 여러 개 보관함, 자유 탐험 월드는 이번에 구현할 기능이 아니다. 향후 도입 여부도 별도 설계 대상이다.

16 KiB Raw Blame History