Cursor + Unity 게임 개발: 완전한 통합 가이드

Unity는 가장 인기 있는 게임 엔진 중 하나이며, Cursor의 AI 기능과 결합하면 게임 개발 워크플로우를 크게 가속화할 수 있습니다. 이 가이드는 프로젝트 구성부터 AI 지원 스크립팅까지 Unity 개발을 위한 Cursor 설정에 필요한 모든 것을 다룹니다.

사전 요구 사항

시작하기 전에:

• Unity 2022.3 LTS 이상 설치됨
• Cursor Pro 플랜(대형 프로젝트에 권장)
• .NET SDK(C# 언어 서버 지원용)
• Scripts 폴더가 있는 Unity 프로젝트

1단계: Unity에서 C# 프로젝트 파일 생성

Cursor는 IntelliSense와 AI 컨텍스트 이해를 위해 .csproj 파일이 필요합니다.

외부 도구 활성화

1. Unity 에디터 열기
2. Edit > Preferences(Windows) 또는 Unity > Settings(macOS)로 이동
3. External Tools로 이동
4. External Script Editor를 Cursor로 설정(또는 Cursor 실행 파일 찾아보기)
5. Generate .csproj files for: 체크
   • Registry packages
   • Build-in packages
   • Local packages
   • Embedded packages
6. Regenerate project files 클릭

대안: 수동 VS Code 패키지

Cursor가 목록에 표시되지 않는 경우:

1. Unity에서 Visual Studio Code Editor 패키지 설치:
   • Window > Package Manager
   • "Visual Studio Editor" 검색
   • 최신 버전 설치/업데이트
2. External Script Editor를 Visual Studio Code로 설정
3. 프로젝트 파일 재생성

2단계: Cursor에서 Unity 프로젝트 열기

방법 1: Unity에서

1. Unity의 Project 창에서 C# 스크립트를 더블클릭
2. Unity가 프로젝트를 로드하여 Cursor를 엽니다

방법 2: 직접 열기

# Unity 프로젝트로 이동
cd ~/MyUnityProject

# Cursor에서 열기
cursor .

방법 3: .sln 파일 사용

# 솔루션 파일을 직접 열기
cursor MyUnityProject.sln

3단계: IntelliSense 구성

C# Dev Kit 확인

1. Cursor에서 확장 프로그램 열기(Cmd/Ctrl + Shift + X)
2. C# Dev Kit가 설치되어 있는지 확인
3. 설치되어 있지 않다면 마켓플레이스에서 설치

프로젝트 로딩 확인

Unity 프로젝트를 연 후:

1. C# 언어 서버가 로드될 때까지 기다림(상태 표시줄에 로딩 표시)
2. 스크립트 파일 열기
3. transform.을 입력하여 IntelliSense 테스트 — Unity API 제안이 표시되어야 함

IntelliSense 문제 해결

IntelliSense가 작동하지 않는 경우:

# 명령줄에서 프로젝트 파일 재생성
# macOS의 경우
/Applications/Unity/Hub/Editor/2022.3.x/Unity.app/Contents/MacOS/Unity \
  -quit -batchmode -projectPath ~/MyUnityProject

# 캐시된 프로젝트 파일 삭제
rm -rf ~/MyUnityProject/.vscode
rm -f ~/MyUnityProject/*.sln
rm -f ~/MyUnityProject/Assembly-CSharp*.csproj

그런 다음 Unity의 External Tools 설정에서 재생성하세요.

4단계: Cursor의 Unity 규칙

.cursor/rules/unity-development.mdc 생성:

---
description: 'Cursor의 Unity 개발 가이드라인'
globs: ['Assets/**/*.cs']
alwaysApply: true
---

# Unity 개발 규칙

## 코드 스타일
- 공개 메서드 및 속성에 PascalCase 사용
- 비공개 필드에 camelCase 사용(밑줄 접두사)
- 인스펙터 노출을 위해 공개 필드 대신 SerializeField 사용
- Awake() 또는 Start()에서 컴포넌트 참조 캐싱

## 성능
- Update()에서 GetComponent() 사용 피하기 — Start()에서 캐싱
- 자주 인스턴스화되는 객체에 오브젝트 풀링 사용
- RaycastAll보다 RaycastNonAlloc 선호
- Update() 체크 대신 시간 기반 작업에 코루틴 사용

## 패턴
- 공유 데이터/구성에 ScriptableObjects 사용
- 게임 로직은 MonoBehaviours에서, 데이터는 ScriptableObjects에서 구현
- 느슨한 결합을 위해 Events/Actions 사용
- 상속보다 컴포지션 선호

5단계: AI 지원 Unity 스크립팅

컴포넌트 생성

프롬프트 예시:

다음 기능이 있는 2D 플랫포머용 플레이어 컨트롤러 스크립트 생성:
- 가속/감속이 있는 부드러운 이동
- 버튼 길게 누르기에 따른 가변 점프 높이
- 관대한 점프를 위한 코요테 타임
- 레이캐스트를 사용한 지면 감지
- 새 입력 시스템 사용

MonoBehaviours 리팩토링

프롬프트 예시:

이 PlayerController를 다음을 사용하도록 리팩토링:
1. 상태 머신 패턴(Idle, Run, Jump, Fall 상태)
2. 이동 매개변수용 ScriptableObject
3. 이벤트 기반 체력 시스템
4. 입력 처리와 이동 로직 분리

에디터 도구 생성

다음 기능이 있는 커스텀 에디터 창 생성:
- 콜라이더가 없는 씬의 모든 GameObject 목록
- BoxCollider 또는 SphereCollider 추가 버튼 표시
- 레이어별 객체 수 표시
- "모두 선택" 버튼 있음

6단계: Cursor에서 Unity 디버깅

디버거 연결

1. Cursor에 Unity 확장 프로그램 설치
2. Cursor에서 Unity 프로젝트 열기
3. F5를 누르거나 Run > Start Debugging로 이동
4. Unity Debugger 선택
5. Unity에서 플레이 모드 진입
6. 중단점이 이제 적중됨

콘솔 통합

Cursor의 터미널을 사용하여 배치 모드로 Unity 실행:

# 명령줄에서 Unity 테스트 실행
Unity -batchmode -quit -projectPath ~/MyUnityProject -executeMethod BuildScript.RunTests

7단계: Unity MCP 서버(고급)

고급 통합을 위해 Unity MCP 서버 사용:

설정

1. Unity MCP 패키지 설치:

# Unity Package Manager에서
# git URL에서 추가: https://github.com/unity-mcp/server.git

2. Cursor MCP 설정에서 구성:

{
  "mcpServers": {
    "unity": {
      "command": "dotnet",
      "args": ["run", "--project", "path/to/unity-mcp"]
    }
  }
}

할 수 있는 것

• 씬 계층 구조 쿼리
• GameObject 생성/수정
• 컴포넌트 속성 조정
• Cursor에서 빌드 및 테스트

예시:

[@unity] 위치 (0, 5, 0)에 "EnemySpawner"라는 이름의 새 GameObject를 생성하고 스폰 간격이 2초인 MonoBehaviour 스크립트를 추가하세요.

모범 사례

프로젝트 구조

Assets/
  Scripts/
    Core/           # 게임 매니저, 싱글톤
    Player/         # 플레이어 관련 스크립트
    Enemies/        # 적 AI 및 컨트롤러
    UI/             # UI 컨트롤러 및 매니저
    Utils/          # 확장 메서드, 헬퍼
  ScriptableObjects/
    PlayerData/     # 플레이어 구성
    EnemyData/      # 적 구성
    LevelData/      # 레벨 설정
  Editor/           # 커스텀 에디터 도구

버전 관리

.gitignore에 추가:

# Unity
[Ll]ibrary/
[Tt]emp/
[Oo]bj/
[Bb]uild/
[Bb]uilds/
[Ll]ogs/
[Uu]ser[Ss]ettings/

# Cursor
.cursor/
.vscode/

성능 프로파일링

Cursor를 사용하여 성능 분석:

이 Update() 메서드를 검토하고 성능 문제를 식별:
[코드 붙여넣기]

다음을 사용한 최적화 제안:
1. 오브젝트 풀링
2. 캐시된 참조
3. 효율적인 데이터 구조

일반적인 문제 및 해결 방법

문제	해결 방법
IntelliSense가 작동하지 않음	Unity에서 .csproj 파일 재생성
중단점이 적중되지 않음	Unity가 플레이 모드인지 확인
Unity API 제안 누락	C# Dev Kit 설치 여부 확인
프로젝트 로딩 지연	Library/ 폴더를 Cursor 인덱싱에서 제외
AI가 Unity 외 코드 제안	.cursor/rules/에 Unity 규칙 추가

빠른 명령

작업	명령
프로젝트 파일 재생성	Unity > Edit > Preferences > External Tools > Regenerate
Cursor에서 스크립트 열기	Unity에서 스크립트 더블클릭
디버거 연결	Cursor에서 F5
Unity API 검색	Cursor 채팅에서 @ 기호 사용

관련 리소스

• Cursor C# Dev Kit 가이드
• Cursor 규칙 효과적으로 사용하기
• Cursor로 대형 프로젝트 처리하기