# 확장 — Unity · AI Game Developer Wiki

Unity MCP 확장은 Animation, Cinemachine, Input System, Navigation, ProBuilder, Splines, Terrain, Tilemap, Timeline 및 파티클에 AI 지원을 추가합니다.

이 페이지는 영어에서 기계 번역되었습니다. [영어 원문 읽기](https://ai-game.dev/docs/wiki/unity/extensions).

확장은 선택적 Unity 패키지로, AI 에이전트에게 Cinemachine 카메라, ProBuilder 메시, 2D 타일맵 같은 특정 Unity 기능을 알려줍니다. 프로젝트에서 사용하는 것만 설치하세요. 이 페이지에서는 열 가지 공식 확장과 각 확장이 추가하는 기능, 설치 방법을 설명합니다. 각 확장에는 [Unity 확장 카탈로그](https://ai-game.dev/docs/extensions/unity)의 상세 페이지도 있습니다.

## 확장의 동작 방식

Unity MCP 1.0.0(및 확장 버전 2.0.0)부터 확장은 **새로운 MCP 도구를 추가하지 않습니다**. 대신 기존 `rql-query` 및 `rql-mutate` 도구가 이해하는 새로운 소스, 함수, 타입 어댑터인 **RQL 모듈**을 제공합니다. 에이전트의 도구 목록 크기는 그대로 유지되고, 확장의 가이드는 생성되는 `unity-rql` 스킬에 추가되므로 패키지가 설치되고 스킬이 다시 생성되는 즉시 에이전트가 새로운 구문을 익히게 됩니다.

예를 들어 AI Tilemap이 설치되어 있으면 에이전트는 RQL을 통해 타일을 칠할 수 있습니다:

```text
objects | get components | where $ is Tilemap | call BoxFill("Assets/Tiles/Grass.asset", -5, -3, 5, 3)
```

각 확장은 코어 플러그인인 `com.ivanmurzak.unity.mcp`와 기반이 되는 Unity 패키지에 의존합니다. 확장을 설치하면 두 가지가 함께 설치됩니다. 모두 Unity 2022.3 이상을 지원합니다.

## 공식 확장

| 확장 | 패키지 id | 기반 | RQL 추가 사항 |
| --- | --- | --- | --- |
| AI Animation | `com.ivanmurzak.unity.mcp.animation` | Animation 모듈 | `animation` 소스; AnimationClip, AnimatorController, Animator 타입 |
| AI Cinemachine | `com.ivanmurzak.unity.mcp.cinemachine` | `com.unity.cinemachine` | `cinemachine` 소스; CinemachineCamera, CinemachineBrain |
| AI InputSystem | `com.ivanmurzak.unity.mcp.inputsystem` | `com.unity.inputsystem` | `input` 소스; InputActionAsset |
| AI Navigation | `com.ivanmurzak.unity.mcp.navigation` | `com.unity.ai.navigation` | `navigation` 소스; NavMeshSurface, NavMeshLink, NavMeshAgent |
| AI Particle System | `com.ivanmurzak.unity.mcp.particlesystem` | Particle System 모듈 | ParticleSystem과 그 모듈, 커브, 그레이디언트 |
| AI ProBuilder | `com.ivanmurzak.unity.mcp.probuilder` | `com.unity.probuilder` | `probuilder` 소스 및 함수; ProBuilderMesh |
| AI Splines | `com.ivanmurzak.unity.mcp.splines` | `com.unity.splines` | `splines` 소스; SplineContainer |
| AI Terrain | `com.ivanmurzak.unity.mcp.terrain` | Terrain 모듈 | `terrain` 소스; 높이 함수; Terrain, TerrainData |
| AI Tilemap | `com.ivanmurzak.unity.mcp.tilemap` | Tilemap 모듈 및 2D Tilemap Extras | `tilemap` 소스 및 함수; Tilemap, RuleTile |
| AI Timeline | `com.ivanmurzak.unity.mcp.timeline` | `com.unity.timeline` | `timeline` 소스; TimelineAsset, 트랙, 클립, PlayableDirector |

각 모듈의 정확한 소스, 함수, 호출은 해당 [카탈로그 페이지](https://ai-game.dev/docs/extensions/unity)와 에디터 내부의 `rql-schema`에서 확인할 수 있습니다.

## AI Game Developer 창에서 설치

1. **Window > AI Game Developer — MCP**를 엽니다.
2. **Extensions** 섹션으로 스크롤합니다.
3. 원하는 확장 옆의 **Install**을 클릭합니다.

이 창은 OpenUPM 스코프 레지스트리와 패키지를 최신 OpenUPM 버전으로 `Packages/manifest.json`에 추가합니다. 그런 다음 Unity가 이를 해석하고 임포트합니다.

## unity-mcp-cli로 설치

```bash
unity-mcp-cli install-extension --list
unity-mcp-cli install-extension Tilemap ./MyUnityProject
```

id는 카탈로그 이름(`Tilemap`, `Cinemachine`, `ProBuilder`, …) 또는 패키지 id(`com.ivanmurzak.unity.mcp.tilemap`)일 수 있으며, 대소문자를 구분하지 않고 일치시킵니다. 경로는 기본값이 현재 폴더입니다. 이 명령은 최신 OpenUPM 버전을 확인하고, 설치된 버전이 더 높으면 다운그레이드하지 않으며, 확장이 이미 최신 상태이면 아무 작업도 하지 않습니다. 버전을 고정하려면 `--extension-version <version>`을 사용하세요(CLI 버전을 출력하는 `--version`이 아닙니다). 이후 Package Manager가 해석할 수 있도록 Unity를 열거나 포커스하세요.

## OpenUPM으로 설치

```bash
openupm add com.ivanmurzak.unity.mcp.cinemachine
```

[Unity-MCP 저장소](https://github.com/IvanMurzak/Unity-MCP/tree/main/extensions)의 각 확장 README에는 해당 확장용 `.unitypackage` 설치 프로그램 링크도 있으며, [코어 설치 프로그램](https://ai-game.dev/ko/docs/wiki/unity/installation#installer)과 같은 방식으로 동작합니다.

## 데스크톱 앱으로 설치

[AI Game Dev 앱](https://ai-game.dev/docs/app)은 열려 있는 프로젝트에 Unity 확장을 설치할 수도 있습니다. 이때 각 확장 자체의 OpenUPM 버전을 사용하며, 이는 코어 플러그인 버전과 별개입니다. [앱 문서](https://ai-game.dev/ko/docs/wiki/app)를 참고하세요.

## 설치 후

- 스킬을 다시 생성하세요(창의 **Skills > Generate** 또는 `unity-mcp-cli setup-skills <agent>`). 그러면 에이전트의 `unity-rql` 스킬에 새 모듈이 포함됩니다.
- 에이전트가 새 타입을 모르는 것 같으면 `rql-schema`에서 시작하도록 요청하세요. 예: "rql-schema를 사용해 cinemachine 소스가 무엇을 제공하는지 확인한 다음, Player를 위한 팔로우 카메라를 추가해 줘."
- `tilemap-set-tile`이나 `cinemachine-camera-create` 같은 이전 튜토리얼의 도구 이름은 더 이상 존재하지 않습니다. 각 확장의 README에서 이에 해당하는 RQL 항목을 확인할 수 있습니다.

## 업데이트 및 제거

확장은 코어 플러그인과 별도로 버전이 관리됩니다. Package Manager에서 업데이트하거나 `install-extension`을 다시 실행하세요. 제거는 다른 패키지와 마찬가지로 Package Manager에서 하면 됩니다. 코어 플러그인과 확장을 최신 버전으로 함께 유지하세요. 확장은 필요한 최소 코어 버전을 선언합니다.

## 직접 작성하기

프로젝트 코드에서 직접 도구를 추가하거나([Custom tools](https://ai-game.dev/ko/docs/wiki/unity/custom-tools) 참고), [커스텀 RQL 어댑터](https://ai-game.dev/docs/rql/custom-adapters)로 RQL에 자신만의 타입을 알려줄 수 있습니다. 저장소의 [확장 가이드](https://github.com/IvanMurzak/Unity-MCP/blob/main/docs/dev/extensions.md)에서는 공식 확장이 어떻게 만들어지고 테스트되는지 설명합니다.

## 관련 페이지

- [Unity 확장 카탈로그](https://ai-game.dev/docs/extensions/unity) 및 [모든 확장](https://ai-game.dev/docs/extensions).
- [도구와 RQL](https://ai-game.dev/ko/docs/wiki/unity/tools-and-rql).

---

Source (HTML): https://ai-game.dev/ko/docs/wiki/unity/extensions

Machine-translated (ko) from the English page: https://ai-game.dev/docs/wiki/unity/extensions