Universal Modder 설치 및 사용법

요구 사항

사전 준비 한 번에 설치

winget install Git.Git Python.Python.3.12 astral-sh.uv Gyan.FFmpeg
winget install BlenderFoundation.Blender   # 선택, 3D → 스프라이트용

brew install git python ffmpeg uv
brew install --cask blender                 # 선택

sudo apt install git python3 python3-venv ffmpeg
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows, macOS, Linux: 어디서 무엇이 되나

툴킷 대부분은 크로스 플랫폼입니다. 실행 중인 게임을 조작하는 부분(실행, 스크린샷, 입력, 게임 소리만 담는 창 녹화)은 Windows 중심입니다. 게임이 대부분 Windows에 있기 때문입니다. 에이전트는 Windows 게임을 네이티브로, 또는 WSL2에서 조작할 수 있습니다.

macOS와 Linux에서도 OS 기본 캡처 도구(screencapture, ffmpeg, xdotool)로 게임 안에서 테스트할 수는 있지만 미리 연결된 것은 없습니다. Linux에서 xEdit을 실행하거나 macOS에서 Wine으로 HL2를 실행한 필드 노트가 그것이 가능함을 보여 줍니다.

에이전트별 설치 비교

어떤 방법이든 같은 스킬(Agent Skills 형식), fal MCP 서버, um CLI가 설치됩니다.

Claude Code

셸이 아니라 Claude Code 세션 안에서 실행하세요:

/plugin marketplace add rehan-remade/universal-modder
/plugin install universal-modder@universal-modder

모든 폴더에서 쓸 수 있도록 user 범위를 고르고, 안내가 나오면 /reload-plugins를 실행합니다. Claude Desktop 사용법과 스킬 호출법을 포함한 전체 안내는 Universal Modder + Claude Code 페이지에 있습니다.

OpenAI Codex

codex plugin marketplace add rehan-remade/universal-modder
codex plugin add universal-modder@universal-modder

Codex는 .agents/skills에서 스킬을, .codex/config.toml에서 MCP 설정을 읽습니다.

Gemini CLI

gemini extensions install https://github.com/rehan-remade/universal-modder

확장 매니페스트는 gemini-extension.json이며, 지시는 AGENTS.md를 가리키는 GEMINI.md에서 옵니다.

VS Code + GitHub Copilot

1. 설정을 열고 chat.plugins.enabled를 켭니다.
2. 명령 팔레트에서 Chat: Install Plugin From Source를 실행합니다.
3. https://github.com/rehan-remade/universal-modder를 붙여 넣습니다.

MCP 설정은 .vscode/mcp.json에 있습니다.

Cursor

Cursor Marketplace에서 설치하거나, 저장소를 clone해서 열면 됩니다. Cursor가 AGENTS.md와 .cursor/mcp.json을 자동으로 읽습니다.

OpenCode

git clone https://github.com/rehan-remade/universal-modder
cd universal-modder
opencode

opencode.json이 스킬과 fal MCP 서버를 추가합니다.

그 밖의 에이전트

# 스킬만 에이전트의 스킬 폴더에 설치
npx skills add https://github.com/rehan-remade/universal-modder

# 전체 사용: clone한 폴더 안에서 에이전트 실행
git clone https://github.com/rehan-remade/universal-modder

um CLI만 따로 설치

플러그인 설치와 clone은 이미 um을 PATH에 넣어 줍니다. 다른 곳에서 스킬을 쓰거나 일반 터미널에서 um을 쓰고 싶다면 도구로 설치하세요. GitHub에서 설치하며 PyPI에는 없으므로 pip install universal-modder로는 설치되지 않습니다.

uv tool install git+https://github.com/rehan-remade/universal-modder
# 또는
pipx install git+https://github.com/rehan-remade/universal-modder

모든 명령 그룹에 예시가 담긴 --help가 있습니다. um CLI 레퍼런스를 참고하세요.

fal API 키 설정

fal.ai/dashboard/keys에서 키를 발급받으세요(크레딧 충전이 필요하고, 키는 한 번만 표시되니 저장해 두세요). fal MCP 서버와 um fal 모두 이 키로 작동합니다.

export FAL_KEY="your-key"
# 영구 설정
echo 'export FAL_KEY="your-key"' >> ~/.zshrc   # 또는 ~/.bashrc

setx FAL_KEY "your-key"
# 새 터미널을 열고 에이전트를 재시작

키가 없나요? um comfy로 로컬 ComfyUI 서버에서 이미지를 만들 수 있습니다. 오디오, 3D, 영상은 여전히 fal이 필요합니다. 가격은 비용 페이지에 있습니다.

설치 확인

um --help
um kb search "terraria"       # 기존 필드 노트 (저장소 밖에서도 작동)
um scan --list                # 이 컴퓨터에서 찾은 게임
um fal price fal-ai/trellis-2 # FAL_KEY 작동 확인

첫 세션: 되돌릴 수 있는 작은 변경 하나

1. 쉬운 게임 고르기인기 로더가 있는 게임이 가장 편합니다: 테라리아(tModLoader), 스타듀 밸리(SMAPI), 마인크래프트(Fabric/Forge), BepInEx를 쓰는 Unity 게임, UE4SS를 쓰는 언리얼 게임. 게임 라이브러리 보기.
2. 먼저 정찰 요청
   프롬프트복사

   내 테라리아는 어떤 엔진이야? 누가 모딩해 본 적 있어? (지식 베이스 검색해 줘) 어떤 경로로 갈 거야? 아직 아무것도 바꾸지 마.

3. 백업과 실험 환경 맡기기에이전트는 um backup create로 세이브 스냅숏을 만들고, 별도 프로필이나 월드를 쓰며, 로더를 설치하기 전에 물어봅니다.
4. 조각 하나 만들기
   프롬프트복사

   적 사이를 네 번 튕긴 뒤 돌아오는 부메랑을 하나 추가해 줘. 처음엔 임시 스프라이트로 하고, 게임에서 작동하면 fal로 스프라이트를 만들어 줘.

5. 확인 후 확장게임을 실행해서 직접 본 다음에 더 요청하세요. 긴 프로젝트는 MODLOG.md에 기록됩니다. 새 세션에서는 "MODLOG.md 읽고 이어서 해 줘"라고 하면 됩니다.

문제 해결

마켓플레이스 추가 중 Git / SSH 오류

플러그인 마켓플레이스는 Git으로 clone됩니다. 컴퓨터에 GitHub SSH 키가 없다면 GitHub에 HTTPS를 쓰도록 Git을 설정하세요:

git config --global url."https://github.com/".insteadOf git@github.com:

설치 후 스킬이 보이지 않음

/reload-plugins(Claude Code)를 실행하거나 에이전트를 재시작하세요. /plugin에서 플러그인이 켜져 있는지 확인하세요.

um: command not found

플러그인 설치 후 새 터미널을 열거나, 위처럼 uv tool install로 CLI를 설치하고 ~/.local/bin이 PATH에 있는지 확인하세요(uv tool update-shell).

um fal이 키가 없다고 함

FAL_KEY는 에이전트를 실행한 환경에 설정되어 있어야 합니다. setx나 셸 설정을 바꾼 뒤에는 에이전트를 재시작하세요.

um win이 실행되지 않음

Windows나 WSL2에서 Windows 게임을 조작할 때만 씁니다. macOS/Linux에서는 게임 안에서 직접 테스트하세요.