# 확장 — Unreal Engine · AI Game Developer Wiki

Control Rig, Enhanced Input, GAS, Landscape와 Water, Niagara, PCG를 위한 선택적 Unreal MCP 확장입니다. 각 확장이 추가하는 기능과 설치 방법을 설명합니다.

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

확장은 Unreal MCP가 더 많은 엔진 시스템을 다룰 수 있게 해줍니다. 각 확장은 자체 버전과 릴리스를 가진 별도의 선택적 Unreal 플러그인입니다. 프로젝트에서 사용하는 것만 설치하세요.

모든 확장은 [Unreal-MCP 저장소](https://github.com/IvanMurzak/Unreal-MCP)에 있으며 [Unreal 확장 페이지](https://ai-game.dev/docs/extensions/unreal)에 나열되어 있습니다.

## 확장의 동작 방식

각 확장은 **RQL 모듈**입니다. 자체적인 MCP 도구를 추가하지는 않습니다. 대신 핵심 `rql-query`, `rql-mutate`, `rql-schema` 도구에 소스, 오퍼레이션, 멤버를 추가하고(참고: [도구](https://ai-game.dev/ko/docs/wiki/unreal/tools#rql)), `unreal-rql` 스킬에 에이전트가 사용법을 익힐 수 있는 섹션을 추가합니다. 에이전트의 도구 목록은 짧게 유지되면서 활용 범위는 넓어집니다.

리플렉션은 이미 로드된 모든 엔진 타입의 프로퍼티를 노출하므로, 확장이 없어도 에이전트는 예를 들어 Niagara 컴포넌트의 에셋을 설정할 수 있습니다. 확장은 리플렉션이 보여주지 않는 것, 예컨대 Niagara 시스템을 이미터와 함께 나열하거나 랜드스케이프를 조형하는 기능을 추가합니다.

## 요구 사항

- Unreal Engine **5.7 이상**(확장 테스트 스위트는 5.7과 5.8에서 검증됨).
- 같은 프로젝트에 Unreal MCP **0.26.0 이상**.
- C++ 툴체인. 확장은 소스 형태로 제공되며 프로젝트와 엔진에 맞게 컴파일됩니다.
- 각 확장이 기반으로 하는 엔진 플러그인. 설치 프로그램이 자동으로 활성화해 줍니다.

어떤 확장도 다른 확장을 필요로 하지 않습니다.

## 여섯 가지 확장

| 확장 | 확장 id | 엔진 플러그인 | 추가하는 기능 |
| --- | --- | --- | --- |
| AI ControlRig | `com.ivanmurzak.unreal-ai-control-rig` | ControlRig | 본, 컨트롤, 투본 IK 솔버로 릭을 생성하고 Control Rig 블루프린트와 컴포넌트를 조회 |
| AI EnhancedInput | `com.ivanmurzak.unreal-ai-enhanced-input` | EnhancedInput | Input Action과 Mapping Context를 조회하고, 액션과 컨텍스트를 생성하며 키를 매핑 |
| AI GAS | `com.ivanmurzak.unreal-ai-gas` | GameplayAbilities | 어빌리티, 이펙트, 어트리뷰트 세트 클래스와 부여된 어빌리티를 조회하고 액터에 어빌리티를 부여 |
| AI Landscape | `com.ivanmurzak.unreal-ai-landscape` | Water | 랜드스케이프를 생성, 조형, 페인팅하고 랜드스케이프, 물 지형, 워터 존을 조회 |
| AI Niagara | `com.ivanmurzak.unreal-ai-niagara` | Niagara | Niagara 시스템과 그 이미터를 조회하고 레벨에 시스템을 배치 |
| AI PCG | `com.ivanmurzak.unreal-ai-pcg` | PCG | PCG 그래프와 컴포넌트를 조회하고 컴포넌트를 추가하며 생성을 실행 |

각 확장의 현재 릴리스는 0.2.0입니다.

### 각 RQL 모듈에 포함된 내용

| 확장 | 소스 | 오퍼레이션 |
| --- | --- | --- |
| AI ControlRig | `controlRigs`, `controlRig` | `CreateRig`, `AddBone`, `AddControl`, `AddTwoBoneIK` |
| AI EnhancedInput | `inputActions`, `inputContexts`, `enhancedInput` | `CreateAction`, `CreateContext`, `AddMapping`, `RemoveMapping`, `AddActionEvent`, `AddMappingContextOnBeginPlay` |
| AI GAS | `gasAbilities`, `gasEffects`, `gasAttributeSets`, `gas` | `GrantAbility` |
| AI Landscape | `landscapes`, `waterBodies`, `waterZones`, `landscape` | `Create`, `Sculpt`, `Paint`, `CreateLayerMaterial` |
| AI Niagara | `niagaraSystems`, `niagara` | `SpawnSystem` |
| AI PCG | `pcgGraphs`, `pcg` | `AddComponent`, `Generate` |

이 이름들을 외울 필요는 없습니다. 에이전트가 `rql-schema`와 스킬에서 읽어갑니다. 에이전트의 쿼리를 읽을 때 도움이 됩니다.

## unreal-mcp-cli로 설치

먼저 Unreal Editor를 종료한 뒤 다음을 실행하세요.

```bash
unreal-mcp-cli install-extension com.ivanmurzak.unreal-ai-niagara ./YourProject
```

이 명령은:

1. 확장 인덱스에서 확장 id를 조회하고 최신 GitHub 릴리스를 찾습니다.
2. 플러그인을 `<project>/Plugins/<PluginName>/`에 배치합니다(예: `Plugins/UnrealAINiagara/`).
3. `.uproject`에서 확장과 해당 엔진 플러그인을 활성화합니다.
4. 컴파일은 다음 에디터 실행 시로 미루거나, `--build`로 즉시 컴파일합니다.

다시 실행해도 안전합니다. 같은 버전이 이미 설치되어 활성화되어 있으면 아무것도 바뀌지 않습니다. 버전을 지정하지 않는 한 설치된 확장을 다운그레이드하지 않습니다.

유용한 플래그:

- `--version 0.2.0`은 정확한 릴리스를 설치합니다.
- `--build`는 즉시 컴파일합니다(Windows, macOS, Linux).
- `--source <dir>`은 로컬 폴더에서 설치하며, 오프라인 머신과 CI에 유용합니다.
- `--force`는 최신 상태여도 다시 설치합니다.

확장 id, 표시 이름 또는 플러그인 폴더 이름으로 설치할 수 있습니다.

## 에디터 또는 앱에서 설치

- **에디터에서:** AI Game Developer 창의 **Extensions** 섹션에 설치된 확장이 나열되며, **Refresh catalog** 후에는 사용 가능한 확장도 표시됩니다. **Install**과 **Update**는 확장을 다운로드합니다. 새 확장은 빌드될 때까지 "Installed · needs editor restart to compile"로 표시되며, \*\*Compile (Live Coding)\*\*을 사용할 수도 있습니다.
- **AI Game Dev 앱에서:** 사이드바의 확장 작업(또는 앱 CLI의 `/install-extension`)을 사용하세요. 앱이 최신 릴리스를 선택합니다. [Projects and engines](https://ai-game.dev/ko/docs/wiki/app/projects-and-engines#extensions)를 참고하세요.

## 확장 켜기/끄기

Extensions 섹션에 있는 각 설치된 확장에는 활성화 토글이 있습니다. 끄면 에디터를 재시작하지 않아도 에이전트에서 해당 확장의 추가 기능이 즉시 제거됩니다. 선택한 상태는 에디터 세션 간에 유지됩니다.

## 예시 프롬프트

- "프로젝트의 모든 Niagara 시스템을 나열하고 NS\_Fire의 이미터를 보여줘." (AI Niagara)
- "불리언 Input Action IA\_Jump와 Mapping Context IMC\_Default를 만들고 스페이스 바를 매핑해줘." (AI EnhancedInput)
- "Hero 액터에 GA\_Fireball을 부여해줘." (AI GAS)
- "랜드스케이프를 만들고 그 위에 잔디 레이어를 페인팅해줘." (AI Landscape)
- "ForestVolume 액터에 PCG\_Forest를 사용하는 PCG 컴포넌트를 추가하고 생성해줘." (AI PCG)
- "세 본 체인과 그 위에 투본 IK가 있는 릭을 만들어줘." (AI ControlRig)

## 나만의 확장 만들기

모든 Unreal 플러그인은 Unreal MCP를 포크하지 않고도 자체 RQL 모듈, 도구, 프롬프트, 리소스를 추가할 수 있습니다. [Custom tools](https://ai-game.dev/ko/docs/wiki/unreal/custom-tools)를 참고하세요.

---

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

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