huayuehua15-netizen/unity-gameplay-dev

Unity 플레이 개발 스킬 (1인칭 / Unity 6 / URP)

경로 규칙 (먼저 읽으세요): 이 파일에서 scripts/, references/, assets/는 모두 이 SKILL.md 파일이 위치한 디렉터리를 기준으로 합니다. 스크립트를 실행하기 전에 해당 디렉터리로 이동하세요. 호스트에 따라 설치 위치가 다릅니다: Claude Code 플러그인은 플러그인 디렉터리 아래에, Cursor/Codex는 install.ps1에 의해 <프로젝트>/skills/game-dev/<스킬명>/에 설치됩니다. 확실하지 않으면 glob을 사용하여 이 SKILL.md의 절대 경로를 찾은 후 절대 경로로 스크립트를 호출하세요. 프로젝트 루트에서 python scripts/xxx.py를 직접 실행하면 file-not-found 오류가 발생합니다.

개요

이 스킬은 GDD 사양과 3D 에셋을 플레이 가능한 게임 기능으로 변환합니다: MCP를 사용하여 Unity에서 스크립트 생성/수정, 컴포넌트 할당, 애니메이션 및 UI 구성, Play 모드 진입 검증, 테스트 실행, 빌드 생성을 수행합니다. 기본 기술 스택: Unity 6 (6000.x LTS, 6000.3 호환), URP, UGUI, 새 Input System, Cinemachine 3 (선택 사항), 싱글 플레이어, 멀티플레이어 없음.

경계

• 하는 일: 플레이 로직, 컨트롤러, 상호작용, UI, 인벤토리/대화/저장, AI, 오디오, 테스트, 빌드 및 성능 진단.
• 하지 않는 일: 3D 에셋 제작/임포트/머티리얼 (unity-blender-mcp 스킬에 위임); 멀티플레이어 네트워킹 (Netcode); 셰이더 직접 작성 (효과 선택에 대한 조언만 제공).
• 대상 프로젝트는 1인칭을 사용합니다; 3인칭/탑뷰는 동일한 아키텍처(상태 머신, 입력, 상호작용, UI는 변경되지 않음)를 사용하며, 컨트롤러와 카메라 분기만 다릅니다. references/02를 참조하세요.
• 2D 프로젝트: 아키텍처 계층(상태 머신/이벤트 버스/저장/인벤토리/UI 스택)은 그대로 사용할 수 있지만, 캐릭터 제어, 물리, 내비게이션, 성능 예산은 반드시 교체해야 합니다. references/11-2d-gameplay.md를 참조하세요. 3D의 CharacterController + NavMesh를 2D에 사용하지 마십시오.

사전 환경

• Unity 6000.x (6000.0 LTS는 2026년 10월까지 지원, 이후 6000.3 LTS로 업그레이드해야 함; 코드는 둘 다 호환).
• 필수 패키지: com.unity.inputsystem (새 입력 시스템), com.unity.ugui (UGUI), com.unity.ai.navigation (NavMesh 베이킹), com.unity.test-framework (테스트, 스캐폴딩 시 --tests와 함께 자동 작성); 선택 사항: com.unity.cinemachine, URP com.unity.render-pipelines.universal.
• 패키지 설치는 MCP manage_packages로 수행하거나, 스캐폴딩 시 자동으로 manifest를 작성합니다(Input System / UGUI / 테스트 프레임워크, 버전은 에디터 내장 및 메인라인 폴백 테이블에 따라 해석); 설치 후 Project Settings → Active Input Handling을 Both로 설정합니다(스캐폴딩 시 activeInputHandler: 2를 작성합니다).
• 버전 확인: 프로젝트의 ProjectSettings/ProjectVersion.txt; API가 확실하지 않으면 unity_docs / unity_reflect를 사용하고, 익숙하지 않은 API를 기억에 의존하여 작성하는 것을 금지합니다.

표준 워크플로 (GDD에서 플레이 가능한 기능까지)

프로세스 A: 새 프로젝트/신규 엔지니어링 처음부터 구축

1. 버전 및 파이프라인 확인: manage_editor로 에디터 버전 읽기; 프로젝트가 URP인지 Built-in인지 확인(머티리얼 및 후처리 효과가 다름).
2. 스캐폴딩 실행: python scripts/new_gameplay.py --out "<프로젝트>/Assets/Game" --namespace <게임명>, 프레임워크 코드, asmdef, 테스트 어셈블리를 생성하고 Input System 종속성을 자동으로 추가합니다; Unity를 한 번 열어 패키지를 다운로드한 후 다시 실행하여 asmdef GUID를 다시 채워야 합니다.
   • ⚠️ 첫 번째 컴파일 시 CS0234/CS0246 (UnityEngine.InputSystem을 찾을 수 없음) 오류는 예상된 동작입니다. 스캐폴딩이 잘못된 것이 아닙니다: 새 프로젝트는 아직 패키지를 다운로드하지 않았기 때문에 InputSystem의 asmdef GUID를 읽을 수 없습니다. Unity를 한 번 열어 패키지 다운로드 → 스캐폴딩 다시 실행 → GUID 다시 채우기 → 다시 컴파일하면 오류가 없습니다.
   • Unity 6000.0.84f1에서 실제 테스트 완료: 다시 실행 후 컴파일 오류 0, InventoryTests 3/3 통과.
3. 씬 가이드 오브젝트 설치: references/01에 따라 시작 씬(GameManager, AudioManager, UIManager, EventSystem, Canvas)을 구축하고 manage_gameobject / manage_components를 사용합니다.
4. 기능 순서대로 구현: 입력 → 1인칭 컨트롤러 → 상호작용 → HUD → 구체적인 게임플레이 시스템 → AI → 오디오/VFX (순서는 아래 '기능 개발 순서' 참조).
5. 기능별 검증: 각 기능 완료 시마다 Play 모드 수동 테스트 + EditMode/PlayMode 테스트 작성, references/00의 검증 사이클 참조.
6. 내비게이션/베이킹/빌드: NavMesh 베이킹, 씬을 Build에 포함, 빌드 전 체크리스트, references/08, references/09 참조.

프로세스 B: 단일 기능 개발 (가장 일반적)

GDD의 해당 페이지(캐릭터/상호작용/시스템/대화/애니메이션 사양) 읽기 → 수정할 스크립트와 컴포넌트 나열 → 템플릿 선택 또는 새로 만들기 → MCP 편집 사이클에 따라 구현 → Play 검증 → 테스트 추가 → 기능 완료 정의 업데이트.

프로세스 C: 문제 해결 및 최적화

컴파일/실행 오류는 references/10 확인; 프레임 드롭/끊김은 references/08의 Profiler 프로세스 따르기; MCP 작업 실패 시 references/00의 폴백 계획 참조.

MCP 편집 사이클 (코드를 변경할 때마다 준수)

1. refresh_unity로 먼저 디스크 동기화; read_console로 시작점에 오류가 없는지 확인.
2. 스크립트 생성: create_script; 스크립트 수정: script_apply_edits 우선 사용(구조화된 메서드 수준 편집), 사소한 변경만 apply_text_edits 사용; 수정 후 validate_script 실행.
3. refresh_unity로 컴파일 트리거 → read_console로 컴파일 결과 확인 (CS 오류가 있으면 즉시 수정, 오류가 있는 상태로 계속 진행하지 않음).
4. 컴포넌트 할당/참조 연결: manage_components / manage_gameobject; 애니메이션은 manage_animation 사용; UI는 manage_gameobject 사용 (UI Toolkit인 경우 manage_ui 사용).
5. Play 모드 진입 검증: manage_editor로 playmode 전환, read_console로 런타임 예외 확인; 시점/조작감은 find_gameobjects로 Transform 상태를 읽어 확인하고, 필요한 경우 execute_code로 Game View 스크린샷 촬영.
6. 충돌하지 않는 여러 작업은 batch_execute로 병합; 각 기능 종료 전에 manage_scene으로 저장.

기능 개발 순서 (스캐폴딩 이후)

1. 입력 InputReader (스캐폴딩에서 이미 생성됨) → 씬에서 Player에 할당, WASD/마우스로 움직임 확인
2. 1인칭 PlayerLook + FirstPersonController (걷기, 달리기, 점프, 앉기, 착지)
   - 2D 프로젝트는 `PlatformerController2D` 사용 (`--dimension 2d` 시 자동 생성, 3D 전용 파일은 생성되지 않음)
3. 상호작용 Interactor + 문/픽업 아이템 (조준선 UI 연결)
4. HUD + 메뉴 패널 스택 (UIManager, ESC로 일시 정지)
5. 게임플레이 시스템: Health/인벤토리/대화 (GDD에 따라 선택)
6. 저장 SaveSystem (이미 만든 시스템을 ISaveable에 연결)
7. 적 AI: NavMesh 베이킹 + EnemyAI + 감지
8. 오디오 AudioManager + 믹서; VFX (파티클/머즐 플래시/히트)
9. 성능 Profiler로 프레임 고정; 빌드 생성 (references/08, 09)

스캐폴딩 및 템플릿

python scripts/new_gameplay.py --out "D:/MyProject/Assets/Game" --namespace MyGame
#   --no-tests: 테스트 어셈블리를 생성하지 않음
#   --editor-data "Editor/Data 경로": Input System 버전 해석 (전달하지 않으면 버전 폴백 테이블 사용)

템플릿 목록 (assets/templates/). 템플릿에는 {{NS}} 네임스페이스 플레이스홀더가 포함되어 있으므로 수동으로 복사할 때는 먼저 바꾸거나 new_gameplay.py를 직접 실행하여 자동 생성해야 합니다. 그렇지 않으면 컴파일할 수 없습니다:

모듈	파일	용도
Core	PersistentSingleton / StateMachine / EventBus / GameManager / GameEvents	싱글톤, 상태 머신, 이벤트 버스, 게임 흐름 (메뉴/게임/일시 정지/로딩)
Input	InputReader	새 Input System 코드화 캡슐화, 키보드+마우스+게임패드
Player	FirstPersonController / PlayerLook / PlatformerController2D	3D: CharacterController 이동, 마우스 시점, 달리기/점프/앉기. 2D: Rigidbody2D 플랫폼 점프 (coyote time / jump buffer / 가변 점프 높이 포함)
Interaction	InteractableBase / Interactor / PickupItem	조준선 상호작용, 픽업 예제
Systems	Health / Inventory / SaveSystem / DialogueRunner / ObjectPool / AudioManager	생명, 인벤토리, JSON 저장, 선형 대화, 오브젝트 풀, 오디오
AI	EnemyAI / EnemyPerception	NavMesh 순찰/추적/공격 상태 머신 + 시야 원뿔 감지
UI	UIPanel / UIManager / HUDController	패널 스택, HUD 체력바/알림/자막
Tests	InventoryTests (+ asmdef)	인벤토리 로직 테스트 예시, run_tests로 실행 가능

참조 문서 색인 (필요시 로드)

• references/00-mcp-code-workflow.md: MCP 47개 도구를 게임플레이 작업별 매핑, 편집 사이클, Play 검증, 테스트, MCP 없는 경우 폴백
• references/01-architecture.md: 디렉터리 구조, asmdef, 네이밍 규칙, 데이터 중심 설계, 참조/이벤트/싱글톤 사용 경계, ScriptableObject
• references/02-input-and-fp-controller.md: Input System 적용, Player 프리팹 계층, 1인칭 이동/시점 파라미터 테이블, 3인칭/탑뷰 분기
• references/03-interaction-animation.md: 상호작용 계층, Animator 상태 머신/Blend Tree/루트 모션, 애니메이션 이벤트, Humanoid 연동
• references/04-ui-ugui.md: Canvas/EventSystem 설정, 패널 스택, HUD, 일시 정지, 입력 전환
• references/05-gameplay-systems.md: 체력/인벤토리/대화/저장/오브젝트 풀 사용 및 확장 규칙, 데이터 정의
• references/06-ai-navigation.md: NavMesh 베이킹, 적 구성, 순찰 지점, 감지 파라미터 튜닝, 상태 확장
• references/07-audio-vfx.md: AudioMixer 그룹화, 오디오 풀, 음악 페이드, 파티클/VFX Graph 선택
• references/08-performance.md: 60fps 예산, Profiler/Frame Debugger 프로세스, 일반적인 핫스팟
• references/09-build-release.md: 빌드 설정, 씬 목록, Steam/Deck 확인, 저장 호환성
• references/10-troubleshooting.md: 컴파일/널 참조/실행 순서/입력/내비게이션/UI 일반 오류 대조표
• references/11-2d-gameplay.md: 2D 프로젝트를 할 때 먼저 읽으세요. 2D 패키지 설치, Sprite 임포트, Physics2D 및 레이어 매트릭스, 2D 플랫폼 점프 (coyote time/jump buffer), Tilemap 및 Composite 충돌, 픽셀 퍼펙트 카메라, overdraw 및 Batch 기준의 2D 예산 (삼각형 예산 테이블은 2D에 무의미).

2D 프로젝트 주의: 이 스킬의 C# 템플릿은 기본적으로 3D 1인칭(CharacterController, NavMesh)입니다. 2D는 차원에 독립적인 부분(EventBus, StateMachine, Inventory, SaveSystem, Health, ObjectPool, UIManager, AudioManager)을 재사용하고, 컨트롤러, 내비게이션, 물리, 성능 예산은 references/11에 따라 다시 작성하세요.

철칙

• 수치는 GDD에서: 이동 속도, 점프력, 데미지, 판정 프레임, 시야 거리는 모두 Inspector에서 노출되어야 하며 GDD 페이지와 일치해야 합니다. GDD에 없는 값은 【확인 필요】로 표시하고, 임의로 숫자를 지어내는 것을 금지합니다.
• 모든 단계는 검증 가능해야 함: 코드를 수정한 후 컴파일 오류가 없어야 하고, Play 모드에서 실제 테스트를 수행해야 합니다. 조작감 관련(이동/시점/공격)은 Transform/상태 증거를 반드시 기록해야 하며, "아마 될 것"이라고 말하는 것을 금지합니다.
• 가짜 컴파일 금지: validate_script 또는 read_console을 통과하지 못하면 완료된 것으로 간주하지 않습니다. 현재 환경에서 검증할 수 없는 경우 명확히 선언하고 결과를 조작하지 않습니다.
• 데이터와 로직 분리: 조정 가능한 수치는 SerializeField/ScriptableObject 사용; 프레젠테이션 계층은 이벤트를 구독하고 시스템 클래스에 작성하지 않습니다.
• 네이밍 규칙: 클래스는 PascalCase; 파일 이름은 주 클래스 이름과 일치; 씬/프리팹은 Level_01_, PF_Player; 상수에 중국어 포함 금지; Console에 CS 경고가 나타나면 수정해야 합니다.
• 작은 단위로 커밋: 하나의 기능은 하나의 커밋; 수정 전 저장/백업; 위험한 작업(삭제, 대량 컴포넌트 수정)은 먼저 영향을 받는 오브젝트를 나열합니다.

기능 완료 정의 (DoD)

• 구현된 로직이 GDD 페이지와 일치하고, 수치를 추적할 수 있음 (업계 기본값은 주석 처리)
• 컴파일 오류 및 경고 없음 (read_console 스크린샷/읽기 결과 증명)
• Play 모드 실제 테스트 통과: 입력, 상태 전환, 상호작용, 피드백이 모두 재현 가능
• 단위 테스트 가능한 로직에 테스트 존재 (run_tests 통과)
• 관련 참조/컴포넌트/계층 구성 완전함 (프리팹을 빈 씬에 드래그하여 즉시 사용 가능, 수동 임시 연결에 의존하지 않음)
• 저장에 새 필드가 추가된 경우 버전 번호 처리; 새 씬이 Build에 포함됨
• 성능에 새로운 핫스팟 없음 (목표 60fps, 모바일/Deck은 08 참조)