# Universal Modder 사용법: 설치부터 게임 안 검증까지 첫 모드 만들기

> Universal Modder는 Claude Code·Codex에 설치하는 게임 모딩 도구입니다. 게임 안 자동 테스트는 Windows·WSL 전용이고, 기본 스프라이트는 fal 장당 약 $0.211입니다.

- Source: https://www.aifreeapi.com/ko/posts/universal-modder
- Language: ko
- Published: 2026-10-08
- Updated: 2026-10-08
- Publisher: AI Free API (https://www.aifreeapi.com)

Universal Modder는 혼자 실행하는 프로그램이 아니라, Claude Code나 Codex 같은 AI 코딩 에이전트에 설치해서 쓰는 게임 모딩 도구 묶음입니다. 쓰는 방법을 한 줄로 줄이면 이렇습니다. 사용 중인 에이전트에 플러그인을 설치하고, 직접 소유한 싱글플레이 게임 하나를 골라 Claude Code라면 `/universal-modder:mod-any-game`으로 "무엇을, 어디까지" 만들지 한 문장으로 요청합니다. 그러면 에이전트가 게임 엔진과 모드 로더를 조사하고, 세이브를 백업하고, 먼저 작게 동작하는 기능 하나를 만든 뒤 실제 게임을 띄워 동작을 확인합니다. 모드가 "완성"됐다는 기준은 코드가 빌드된 순간이 아니라 실행 중인 게임 안에서 직접 확인한 순간입니다.

시작하기 전에 세 가지 조건부터 맞춰 보는 편이 좋습니다.

- **유료 코딩 에이전트**: 플러그인 자체는 MIT 라이선스로 무료지만, 실제 작업은 Claude Code(유료 Claude 요금제 또는 API 결제 계정)나 Codex(ChatGPT 요금제 또는 API) 같은 에이전트가 합니다.
- **Windows 또는 WSL**: 게임 실행, 스크린샷, 마우스·키보드 자동 조작을 맡는 `um win`은 Windows 네이티브나 WSL이 아니면 실행을 거부합니다. macOS·Linux에서는 조사와 에셋 생성까지는 되지만 게임 안 테스트는 직접 해야 합니다.
- **안티치트 없는 오프라인 게임**: 온라인 게임 클라이언트에 코드를 주입하는 작업, 본인 소유가 아닌 게임은 도구가 거절합니다. 첫 대상으로는 Terraria(tModLoader)처럼 모드 로더가 자리 잡은 게임이 무난합니다.

스프라이트·3D 모델·효과음을 자동으로 만들려면 fal API 키가 따로 필요하고, 생성할 때마다 비용이 나갑니다. 기본 설정의 스프라이트 한 장은 2026년 10월 8일 fal 가격으로 약 $0.211입니다. 같은 날 기준 GitHub 저장소는 별 약 5,400개, 버전 0.2.0이며 정식 릴리스 없이 거의 매일 바뀌고 있으니, 아래 명령이 화면과 다르면 [README의 설치 표](https://github.com/rehan-remade/universal-modder#install)를 기준으로 삼으면 됩니다.

## Universal Modder의 정체: 앱이 아니라 코딩 에이전트용 플러그인

Universal Modder(GitHub 저장소 `rehan-remade/universal-modder`)는 2026년 9월 30일에 공개됐습니다. 화면이 있는 앱을 내려받아 버튼을 누르는 방식이 아니라, 이미 쓰고 있는 에이전트에게 모딩 방법을 가르치는 네 가지 구성요소로 되어 있습니다.

| 구성요소 | 하는 일 |
| --- | --- |
| 스킬(skills) | 에이전트가 읽는 작업 지침 파일입니다. 플레이어 실력을 뜻하는 말이 아닙니다. 핵심 스킬 `mod-any-game`이 전체 순서를 정하고, 정찰·리버스 엔지니어링·에셋·자동 조작·영상·배포를 맡는 보조 스킬이 붙어 있습니다. |
| `um` 명령줄 도구 | Python으로 만든 CLI입니다. 설치된 게임 찾기(`um scan`), 세이브 백업(`um backup`), 에셋 생성(`um fal`), 스프라이트 가공(`um sprite`), 게임 조작(`um win`), 배포 전 검사(`um publish check`), 지식 베이스 검색(`um kb`)을 합니다. |
| fal MCP 서버 | 에이전트가 fal의 이미지·3D·음성 모델을 직접 호출하게 해 줍니다. |
| 지식 베이스 | 다른 에이전트가 실제로 모딩하며 남긴 기록입니다. [INDEX](https://github.com/rehan-remade/universal-modder/blob/main/knowledge/INDEX.md)에는 2026년 10월 8일 기준 게임 노트 78건, 기법 노트 50건이 있습니다. |

지식 베이스의 각 노트에는 동작한 정확한 버전, 고른 경로와 이유, 확인 방법, "증상 → 원인 → 해결" 형식의 함정이 적혀 있습니다. 다만 노트가 있다고 해서 내 PC의 게임 버전에서 똑같이 된다는 보장은 아닙니다. 상태가 working인 노트도 있고 in-progress인 노트도 섞여 있습니다.

제작자 Rehan Sheikh는 X 프로필에 fal 엔지니어로 소개돼 있다고 [Post-Cutoff](https://postcutoff.com/e/2026-09-30-universal-modder-claude-code-game-modding/)가 전했습니다. 에셋 생성이 fal 유료 API에 기대고 있다는 점은 알고 시작하는 편이 좋습니다. 키가 없으면 `um comfy`로 로컬 ComfyUI 서버에서 이미지를 만들 수 있습니다.

원본은 GitHub 저장소입니다. universal-modder.org는 "오픈소스 프로젝트를 바탕으로 한 커뮤니티 허브"라고 스스로 밝히는 별도 사이트이고, README에는 모드 허브가 "곧 나온다(coming next)"고만 적혀 있습니다. 프로젝트의 [safety 문서](https://github.com/rehan-remade/universal-modder/blob/main/skills/mod-any-game/references/safety.md)도 화제가 된 모드의 "다운로드" 링크는 악성코드인 경우가 많으니 모드 로더는 공식 저장소와 공식 릴리스에서만 받으라고 경고합니다.

## 설치 전 체크리스트: 에이전트·Windows·게임·fal 키

아래 표에서 오른쪽 칸에 해당하는 항목이 있으면 설치 전에 먼저 해결하거나 기대치를 조정하는 편이 시간을 아낍니다.

| 확인할 것 | 그대로 진행해도 되는 경우 | 먼저 다시 생각할 경우 |
| --- | --- | --- |
| 코딩 에이전트 | Claude Code(Pro·Max·Team·Enterprise 요금제 또는 API 결제 Console 계정), Codex(ChatGPT 요금제 또는 API) | Gemini CLI를 개인 Google 계정 로그인으로 쓰려는 경우: 2026년 6월 18일부터 막혔습니다 |
| 운영체제 | Windows 네이티브 또는 WSL | macOS·Linux: `um win`이 동작하지 않아 게임 실행과 확인은 직접 해야 합니다 |
| 필수 프로그램 | Git, Python 3.10 이상, ffmpeg, (권장) uv | Blender는 3D 모델을 스프라이트로 렌더링할 때만 필요합니다 |
| 게임 | 본인 소유, 싱글플레이·오프라인 또는 직접 운영하는 서버, 모드 로더가 있음 | 온라인 + 안티치트 게임, 소유하지 않은 게임: 도구가 거절합니다 |
| 에셋 | fal 계정에 잔액을 충전하고 API 키 발급 | 키 없이: 로컬 ComfyUI(`um comfy`) 또는 직접 그린 그림 사용 |

**에이전트 고르기.** README 설치 표에는 Claude Code, Codex, Gemini CLI, VS Code/GitHub Copilot, Cursor, OpenCode가 올라 있고, 지식 베이스 노트 작성자에도 Claude Code, Codex, DeepSeek 모델을 쓴 OpenCode가 섞여 있습니다. 어느 쪽을 결제할지 아직 정하지 못했다면 [Claude Code vs Codex 2026: 지금 어떤 코딩 에이전트를 선택해야 할까?](/ko/posts/claude-code-vs-codex)를 먼저 보면 됩니다.

**Gemini CLI 사용자.** Google은 2026년 6월 18일부터 개인용 Gemini Code Assist, Google AI Pro, Google AI Ultra 사용자가 "Login with Google"로 Gemini CLI에 접속하는 경로를 막았습니다([Google 안내](https://developers.google.com/gemini-code-assist/docs/deprecations/code-assist-individuals)). README는 여전히 Gemini CLI를 지원 목록에 두고 있으므로, 지금도 인증이 되는 사람에게만 맞는 경로입니다. 어떤 경로가 아직 살아 있는지는 [Gemini CLI 종료 범위: 아직 되는 경로와 Antigravity CLI 이전 방법](/ko/posts/gemini-cli-deprecated)에서 확인할 수 있습니다.

**구독 대신 종량제 API로 Codex를 쓰려는 경우.** Codex는 `~/.codex/config.toml`에 외부 API를 연결해 쓸 수 있습니다. 예를 들어 laozhang.ai는 [Codex CLI 연결 문서](https://docs.laozhang.ai/scenarios/programming/codex-cli)에서 `base_url = "https://api.laozhang.ai/v1"`, `wire_api = "responses"`, 권장 모델 `gpt-6-sol` 설정을 안내합니다. 토큰 단위 과금이라 긴 모딩 세션이 얼마나 나올지 미리 알 수 없고, 이 경로로 게임 리버스 엔지니어링 품질을 확인한 자료도 아직 없습니다. 연결 전에 볼 점은 [Codex에 외부 모델 API를 연결할 때 확인할 네 가지 경계](/ko/posts/codex-third-party-api)에 정리돼 있습니다.

Windows에서는 필수 프로그램을 winget으로 한 번에 설치할 수 있습니다. Blender 줄은 3D 작업을 할 때만 실행하면 됩니다.

```powershell
winget install --id Git.Git -e
winget install Python.Python.3.12
winget install astral-sh.uv
winget install Gyan.FFmpeg
winget install BlenderFoundation.Blender
```

설치 후에는 터미널을 새로 열어야 PATH가 반영됩니다. `git --version`, `python --version`, `ffmpeg -version`이 모두 버전을 출력하면 준비가 끝난 것입니다.

## 에이전트별 Universal Modder 설치 명령

어느 에이전트로 설치하든 같은 스킬, fal MCP 서버, `um` CLI가 들어갑니다. 명령은 2026년 10월 8일 기준 README와 같습니다.

### Claude Code

Claude Code 입력창에서 두 줄을 차례로 실행합니다.

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

설치 전에 알아 둘 점이 세 가지 있습니다. 먼저 이 저장소는 Anthropic 공식 마켓플레이스가 아닌 서드파티 마켓플레이스이고, [Claude Code 플러그인 문서](https://code.claude.com/docs/en/plugins)에 따르면 플러그인이 실행하는 코드는 내 계정 권한으로 돌아갑니다. 다음으로 켜 둔 플러그인의 스킬 이름과 설명은 사용하지 않는 턴에도 매번 컨텍스트에 실려 사용량을 조금씩 씁니다. 모딩하지 않는 동안에는 `/plugin` 화면이나 셸의 `claude plugin disable`로 꺼 두면 됩니다. 마지막으로 브라우저의 claude.ai/code 같은 클라우드 세션은 로컬에 설치한 플러그인을 불러오지 않으므로, 게임이 설치된 PC의 터미널이나 데스크톱 앱에서 써야 합니다.

### Codex

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

Codex는 샌드박스와 승인 설정에 따라 에이전트가 PC에서 명령을 실행할 수 있는 범위가 달라집니다. 게임 폴더나 세이브 폴더에 쓰기 권한이 필요한 작업이 많으므로, 설정 방법은 [Codex 샌드박스와 config.toml: 승인·쓰기·네트워크 경계](/ko/posts/codex-config-toml)를 참고하세요.

### Gemini CLI

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

Windows PowerShell에서 `gemini` 명령이 실행되지 않으면 `gemini.cmd extensions install ...`처럼 `gemini.cmd`로 바꿔 실행합니다. Windows는 기본적으로 스크립트 실행이 꺼져 있어 `gemini.ps1`이 막히기 때문이라고 관리자가 설명했습니다.

### 그 밖의 에이전트와 um 단독 설치

| 에이전트 | 설치 방법 |
| --- | --- |
| VS Code / GitHub Copilot | 설정에서 `chat.plugins.enabled`를 켜고, 명령 팔레트의 **Chat: Install Plugin From Source**에 저장소 URL 입력 |
| Cursor | Cursor Marketplace 또는 저장소 클론(`AGENTS.md`와 `.cursor/mcp.json`을 읽음) |
| OpenCode | 저장소를 클론하고 그 안에서 `opencode` 실행 |
| 스킬만 설치 | `npx skills add https://github.com/rehan-remade/universal-modder` |
| 그 밖의 에이전트 | `git clone https://github.com/rehan-remade/universal-modder` 후 그 폴더에서 에이전트 실행 |

플러그인 설치나 클론을 하면 `um`도 PATH에 들어갑니다. 스킬만 설치했거나 여러 에이전트에서 같은 `um`을 쓰고 싶다면 따로 한 번 설치합니다.

```bash
uv tool install git+https://github.com/rehan-remade/universal-modder
# uv 대신 pipx: pipx install git+https://github.com/rehan-remade/universal-modder
```

### fal API 키 등록

fal.ai에서 계정을 만들고 잔액을 충전한 뒤 [API 키 페이지](https://fal.ai/dashboard/keys)에서 키를 발급합니다. 키는 환경 변수 `FAL_KEY`로 넘깁니다.

```powershell
# Windows PowerShell: 실행 후 터미널을 다시 열어야 적용됩니다
setx FAL_KEY "발급받은_키"
```

```bash
# macOS·Linux·WSL: ~/.zshrc 또는 ~/.bashrc에 추가
export FAL_KEY=발급받은_키
```

[VGTimes 가이드](https://vgtimes.com/guides/169605-how-to-mod-almost-any-game-with-claude-code.html)에 따르면 `um`은 프로젝트 폴더의 `.env` 파일에서도 키를 읽지만, Claude Code의 fal MCP 서버는 환경 변수에서만 읽습니다. `.env`에만 키를 넣었다면 `um fal`은 되는데 에이전트의 fal 도구 호출만 실패할 수 있으니 환경 변수로 등록해 두는 편이 안전합니다.

## 설치 확인: /plugin 목록, um --help, um kb search

설치 명령이 오류 없이 끝났다면 다음 세 가지로 실제로 불러와졌는지 확인합니다.

1. **에이전트 쪽**: Claude Code에서 `/plugin`을 열어 설치 목록에 universal-modder가 있는지 보고, 입력창에 `/universal-modder:mod-any-game`이 명령으로 인식되는지 확인합니다. Codex·Gemini CLI는 새 세션을 열고 "쓸 수 있는 스킬 목록"을 물어 `mod-any-game`이 있는지 확인합니다.
2. **CLI 쪽**: 새 터미널에서 `um --help`를 실행하면 `scan`, `fal`, `backup`, `kb` 같은 명령 그룹이 나옵니다. `um`을 찾을 수 없다고 나오면 위의 `uv tool install` 명령으로 따로 설치합니다.
3. **지식 베이스**: `um kb search "terraria"`를 실행해 Terraria 관련 노트가 검색되면 저장소 내용까지 정상적으로 읽히는 것입니다. Windows에서 여기서 인코딩 오류가 나면 아래 오류 절의 첫 항목을 보세요.

2026년 10월 6일 이전에 Claude Code로 설치했다면 업데이트가 반영되지 않았을 수 있습니다. `claude plugin update`를 실행해도 `already at the latest version (0.2.0)`만 나온다면, 플러그인을 한 번 제거했다가 다시 설치합니다.

## 첫 모드 만들기: 세이브 백업부터 게임 안 확인까지 8단계

예시로 Steam판 Terraria에 tModLoader로 무기 하나를 추가하는 흐름을 따라갑니다. 다른 게임이어도 순서는 같고, 각 단계는 `mod-any-game` [스킬 파일](https://github.com/rehan-remade/universal-modder/blob/main/skills/mod-any-game/SKILL.md)에 정해진 흐름을 따릅니다.

먼저 빈 작업 폴더를 하나 만들고 그 안에서 에이전트를 실행한 다음, 스킬을 직접 불러 요청합니다. 무엇을 만들지, 어디서만 쓸지, 무엇을 보면 완성으로 볼지를 함께 적어 두면 중간 질문이 줄어듭니다.

```text
/universal-modder:mod-any-game
게임: Terraria (Steam판), tModLoader로 오프라인 싱글플레이에서만 사용
아이디어: 적을 따라가는 유도 미사일 발사기 무기 1개 추가
완성 기준: 새 캐릭터와 새 월드에서 제작해 발사하는 모습을 스크린샷과 client.log로 확인
조건: 세이브는 먼저 백업하고, 마우스·키보드를 조작하기 전에 물어봐 줘
```

![Universal Modder 첫 모드 진행 순서: um scan으로 정찰, um backup create로 세이브 백업, MODLOG.md에 기록하며 작은 기능 하나 만들기, um win shot으로 게임 안 확인(Windows·WSL 전용)의 네 단계 카드](https://www.aifreeapi.com/posts/ko/universal-modder/img/first-mod-steps.webp)

1. **작업 일지 만들기.** 에이전트는 작업 폴더에 `MODLOG.md`를 만들고 경로, 파일 형식, 실패한 시도와 이유, 다음 할 일을 계속 적습니다. 대화 컨텍스트가 압축되면 일지에 없는 내용은 사라지므로, 다음 날 이어서 할 때는 같은 폴더에서 새 세션을 열고 "MODLOG.md를 읽고 이어서 해 줘"라고 하면 됩니다.
2. **정찰.** `um kb search "terraria"`로 다른 에이전트가 남긴 노트를 먼저 찾고, `um scan --list`로 설치된 게임 목록을, `um scan "Terraria"`로 엔진과 버전, 관리 코드(.NET 등)인지 네이티브인지, 안티치트, 설치된 모드 로더, 세이브 폴더, 추천 경로를 확인합니다.
3. **가장 가벼운 경로 고르기.** 데이터·에셋 교체로 끝나는 아이디어면 그 방법을, 모드 로더 API가 있으면 그 API를 씁니다. 코드 패치, 네이티브 후킹, 재구현은 앞의 방법으로 안 될 때만 갑니다. Terraria는 tModLoader의 아이템 API가 이 단계에 해당합니다. tModLoader는 무료 tModLoader 앱이 내 Steam 라이브러리에 있어야 실행되므로, 라이브러리에 추가하면 됩니다. 이 확인을 패치로 우회하는 작업은 도구가 하지 않습니다.
4. **세이브 백업과 실험용 공간.** 처음 모드를 넣고 실행하기 전에 `um backup create "<um scan이 알려 준 세이브 폴더>" --name terraria-saves`로 스냅숏을 만듭니다. 되돌릴 때는 `um backup restore`를 씁니다. tModLoader는 `-tmlsavedirectory` 옵션으로 실험용 세이브 폴더를 따로 둘 수 있어, 실제 캐릭터와 월드를 건드리지 않고 테스트할 수 있습니다. 스크린샷 좌표가 흔들리지 않도록 게임은 창 모드로 실행합니다.
5. **먼저 작게 동작하는 기능 하나.** 무기 여러 개와 보스를 한꺼번에 만들지 않고, 임시 그림을 쓴 무기 하나를 정의부터 게임 안 동작까지 끝까지 통과시킵니다. 이것이 로그와 스크린샷으로 확인된 다음에야 범위를 넓힙니다.
6. **에셋 만들기.** 비용이 드는 생성 전에는 `um fal price openai/gpt-image-2`처럼 단가를 먼저 확인합니다. 그다음 `um fal sprite "homing missile launcher, pixel art" --quality medium`처럼 생성하고, `um sprite`로 게임이 읽는 크기와 형식에 맞춥니다. 모든 생성 기록은 `fal_manifest.jsonl`에 남습니다.
7. **실제 게임 안에서 확인.** 에이전트는 `um win launch`로 게임을 띄우고 `um win shot`으로 스크린샷을 찍어 게임 로그와 함께 확인합니다. tModLoader의 로그는 `client.log`이고, BepInEx는 `BepInEx/LogOutput.log`, UE4SS는 `UE4SS.log`, Unity 게임은 `Player.log`, Minecraft는 `logs/latest.log`입니다. 자동 조작 중에는 마우스와 키보드를 건드리지 않아야 좌표가 어긋나지 않습니다. 같은 실패가 세 번 반복되면 에이전트는 멈추고, 알게 된 내용을 적은 뒤 방법을 바꾸거나 사용자에게 묻습니다.
8. **정리와 공유.** 다른 사람에게 줄 생각이라면 `um publish check <모드 폴더> --game "<게임 설치 경로>"`로 게임 원본 파일, 디컴파일한 코드, 유출된 키가 섞이지 않았는지 검사합니다. README에는 AI로 만들었다는 사실을 밝힙니다. 작업 기록을 지식 베이스 노트로 남기는 `um kb new`·`um kb check`·`um kb pr`은 사용자가 승인했을 때만 PR을 엽니다.

에이전트가 "빌드 성공"이라고 보고해도 거기서 끝내지 말고, 스크린샷과 로그를 직접 열어 봐야 합니다. 스킬 파일도 "실행 중인 게임이 판정 기준이고, 코드를 읽은 해석은 기준이 아니다"라고 적고 있습니다.

## Universal Modder 비용: 에이전트 요금과 fal 생성 단가는 따로 나갑니다

비용은 두 갈래입니다. 하나는 코딩 에이전트 요금이고, 다른 하나는 fal에서 에셋을 생성할 때마다 나가는 요금입니다.

`um fal`의 레시피별 기본 모델([um/fal.py](https://github.com/rehan-remade/universal-modder/blob/main/um/fal.py))과 2026년 10월 8일 fal 모델 페이지에 표시된 가격은 다음과 같습니다. fal의 가격이며 OpenAI나 Google에 직접 결제할 때의 가격과는 다릅니다.

| 작업 | 기본 모델 | fal 가격(2026-10-08) |
| --- | --- | --- |
| `um fal sprite` (투명 배경 스프라이트, 기본 1024×1024, 기본 품질 high) | [`openai/gpt-image-2`](https://fal.ai/models/openai/gpt-image-2) | 장당 high $0.211 / medium $0.053 / low $0.006 |
| `um fal image` (일반 이미지, 기본 1K) | [`fal-ai/nano-banana-2`](https://fal.ai/models/fal-ai/nano-banana-2) | 장당 $0.08 (2K는 1.5배, 4K는 2배) |
| `um fal sfx` (효과음) | [`fal-ai/elevenlabs/sound-effects/v2`](https://fal.ai/models/fal-ai/elevenlabs/sound-effects/v2) | 초당 $0.002 |
| `um fal model3d` (이미지 → 3D, 기본 해상도 1024p) | [`fal-ai/trellis-2`](https://fal.ai/models/fal-ai/trellis-2) | 모델 1개당 $0.30 (512p $0.25, 1536p $0.35) |

계산식은 **생성 개수 × fal 단가**입니다. 아래는 다시 생성하지 않았다고 가정한 예시입니다.

![um fal sprite로 1024×1024 스프라이트 10장을 만들 때의 비용 예시: high(기본값) 10 × $0.211 = $2.11, medium 10 × $0.053 = $0.53, low 10 × $0.006 = $0.06을 비례 막대로 비교한 그림](https://www.aifreeapi.com/posts/ko/universal-modder/img/fal-sprite-cost.webp)

- 기본 설정 스프라이트 10장: 10 × $0.211 = 약 $2.11
- 같은 10장을 `--quality medium`으로: 10 × $0.053 = 약 $0.53
- 같은 10장을 `--quality low`로: 10 × $0.006 = 약 $0.06
- Nano Banana 2 이미지 1K 10장: 10 × $0.08 = $0.80 (배경 제거가 필요하면 별도)
- 효과음 합계 30초: 30 × $0.002 = 약 $0.06

`um fal sprite`의 기본값이 high라서, 품질 옵션을 지정하지 않으면 medium보다 장당 약 4배 비싸게 생성됩니다. 픽셀 아트처럼 어차피 작게 줄여 쓰는 스프라이트라면 medium부터 시험해 보고 부족할 때 high로 올리는 편이 낫습니다. 실제 합계는 다시 생성한 횟수와 해상도에 따라 달라지고, 3D 모델과 영상은 위 예시에 들어 있지 않습니다. 3D 모델은 2026년 10월 8일 fal 가격으로 Trellis 2가 모델 1개당 512p $0.25, 1024p $0.30, 1536p $0.35이고, `um fal model3d`는 해상도를 바꾸지 않아 기본값 1024p인 $0.30이 적용됩니다. 여러 개를 한꺼번에 만들기 전에는 `um fal price fal-ai/trellis-2`나 fal 대시보드에서 현재 가격을 다시 확인하세요. fal도 가격은 바뀔 수 있다고 밝히고 있습니다.

투명 배경 스프라이트가 제대로 나왔는지 파일 단위로 확인하는 방법은 [GPT Image 2로 투명 PNG·WebP 만들기: API 요청과 파일 검증](/ko/posts/gpt-image-2-transparent-background)에 있습니다.

에이전트 요금은 모드 하나에 얼마라고 말할 수 있는 실측 자료가 없습니다. 정찰, 디컴파일한 코드 읽기, 게임 실행과 확인을 되풀이하는 긴 세션은 요금제 사용량을 빠르게 쓰고, 켜 둔 플러그인도 매 턴 컨텍스트를 조금씩 차지합니다. Claude 요금제별 차이는 [클로드 Pro·Max 사용량 한도 비교: 업그레이드해도 주간 제한은 남습니다](/ko/posts/claude-code-pricing-pro-vs-max)에서, 작업 중 한도에 걸렸을 때의 대처는 [Claude Code 속도 제한 완벽 가이드: 5시간·주간 한도와 429 진단·해결](/ko/posts/claude-code-rate-limit)과 [Codex 429로 재시도가 끝났다면: 어느 한도가 막았는지 찾기](/ko/posts/codex-rate-limits)에서 볼 수 있습니다.

## Universal Modder가 거절하는 게임과 요청

에이전트는 스킬 파일의 규칙에 따라 다음 작업을 하지 않습니다. 요청을 바꿔 말해도 마찬가지이고, 이 규칙은 계정 정지와 세이브 손상을 막기 위한 것입니다.

- **본인 소유가 아닌 게임**: 게임, ROM, ISO를 내려받지 않습니다. 내 설치본이나 내가 가진 디스크·카트리지에서 뽑은 데이터만 다룹니다.
- **온라인 + 안티치트 게임의 클라이언트**: EasyAntiCheat, BattlEye, Vanguard, 공식 서버의 VAC, Ricochet, ACE가 걸린 게임에는 코드를 주입하지 않습니다. [safety 문서](https://github.com/rehan-remade/universal-modder/blob/main/skills/mod-any-game/references/safety.md)는 EA Javelin, nProtect, XIGNCODE, mhyprot도 같은 정지 신호로 봅니다. 이런 게임은 공식 창작 도구, Workshop, 안티치트 없이 배포되는 공식 오프라인 모드, 내가 운영하는 서버만 대상이 됩니다.
- **치트**: 멀티플레이용 에임봇, ESP(벽 투시), 스피드 핵은 만들지 않습니다.
- **보호 장치 우회**: 안티치트, DRM(Denuvo, Steam stub), 소유권 확인을 끄거나 우회하지 않습니다. 모드 로더가 DRM을 지나 실행 파일을 패치해야 한다면 거기서 멈춥니다.
- **재배포**: 게임 원본 파일, 추출한 에셋, 디컴파일한 코드는 배포물에 넣지 않습니다. 내 코드와 내 에셋, 또는 사용자 PC의 원본에 적용하는 패치·변환 도구 형태로만 배포합니다.

VAC가 걸린 게임은 로컬 테스트를 `-insecure` 옵션으로 하고, 무언가 주입된 상태로는 공개 서버에 접속하지 않습니다. 또 에이전트는 마우스·키보드를 대신 조작하기 전, 게임 폴더에 모드 로더를 설치하기 전, 레지스트리나 그래픽 설정을 바꾸기 전, 무언가를 삭제하기 전, 배포하기 전에 사용자에게 먼저 묻습니다.

이 규칙은 도구 자체의 원칙이지 법률 자문이 아닙니다. safety 문서는 게임 에셋이 없어도 삭제 요청이 올 수 있다며 Take-Two가 GTA III·바이스 시티 리버스 엔지니어링 코드(re3, reVC)를 GitHub에서 내리게 하고 소송을 낸 2021년 사례, Activision이 H2M 모드 출시 하루 전 중지 요청을 보낸 2024년 사례를 듭니다. 유료 판매나 수익화는 위험을 크게 높이고, fal로 만든 에셋도 상업적으로 쓰려면 모델별 라이선스를 확인해야 합니다. AI 사용을 밝히지 않은 배포에 커뮤니티가 민감하게 반응하고, AI 프로젝트 자체를 금지하는 커뮤니티도 있습니다. 게임별 EULA와 퍼블리셔의 모드 정책은 따로 확인하세요.

## 자주 나는 설치·실행 오류와 해결법

GitHub 이슈와 PR에 올라온 문제 가운데 처음 쓰는 사람이 부딪히기 쉬운 것들입니다. 2026년 10월 8일 기준 상태이며, 일부는 이후 수정될 수 있습니다.

### um kb search에서 UnicodeEncodeError: 'charmap' codec

Windows에서 `um kb search`가 `UnicodeEncodeError: 'charmap' codec can't encode character`로 멈추는 문제입니다([#152](https://github.com/rehan-remade/universal-modder/issues/152)). 콘솔 인코딩이 cp1252인 환경에서 보고됐고, 검색 결과로 나온 노트에 그 인코딩으로 표현할 수 없는 문자가 있을 때 생깁니다. PowerShell에서 아래를 먼저 실행한 뒤 같은 명령을 다시 실행하면 됩니다.

```powershell
$env:PYTHONUTF8 = "1"
um kb search "terraria"
```

한국어 Windows 콘솔의 기본 인코딩은 cp949라서 같은 오류 문구가 그대로 나오는지는 확인된 바가 없습니다. 비슷한 인코딩 오류가 나면 같은 방법을 먼저 시도해 보세요.

### Failed to clone Git repository ... Error: spawn git ENOENT

Windows에서 Gemini CLI로 설치할 때 나오는 오류입니다([#109](https://github.com/rehan-remade/universal-modder/issues/109)). Git이 설치돼 있지 않거나 PATH에 없다는 뜻입니다. `winget install --id Git.Git -e`로 Git을 설치하고, 터미널을 새로 연 뒤 `git --version`이 버전을 출력하는지 확인하고 다시 설치합니다. PowerShell에서 `gemini` 자체가 실행되지 않으면 `gemini.cmd`로 실행합니다.

### claude plugin update가 already at the latest version (0.2.0)만 표시

초기 플러그인 설정에 버전이 `0.2.0`으로 고정돼 있어, 그 전에 설치한 Claude Code 사용자는 캐시된 사본에 머물렀습니다. 2026년 10월 6일 병합된 [PR #108](https://github.com/rehan-remade/universal-modder/pull/108)이 고정을 없앴지만, 이전 설치본은 한 번 제거 후 재설치해야 새 커밋을 받을 가능성이 높습니다.

### um scan --list에 Steam 게임이 하나도 안 보임

Steam을 Program Files가 아닌 `C:\Steam`이나 `D:\Steam`에 설치한 경우 Steam 라이브러리를 통째로 놓치는 문제가 있었습니다. 10월 6일 병합된 [PR #95](https://github.com/rehan-remade/universal-modder/pull/95)부터 레지스트리에서 Steam 위치를 읽으므로, 그 전에 설치했다면 플러그인이나 `um`을 업데이트(필요하면 재설치)한 뒤 다시 실행합니다.

### macOS·Linux에서 um win이 실행을 거부함

정상 동작입니다. `um win`은 Windows 네이티브나 WSL에서만 실행되고, 다른 환경에서는 대체 도구를 안내하는 메시지를 내고 멈춥니다. macOS나 Linux에서는 정찰, 지식 베이스, fal 생성, 스프라이트 가공까지 에이전트에게 맡기고 게임 실행과 확인은 직접 하는 방식이 현실적입니다.

### LM Studio 같은 로컬 모델로 돌리고 싶을 때

LM Studio Bionic에 대해 관리자는 "대체로 될 것"이라면서도 시험해 보지는 않았다고 답했습니다([#126](https://github.com/rehan-remade/universal-modder/issues/126)). 시험된 로컬 경로는 OpenCode에 LM Studio의 로컬 서버를 연결하는 방식이고, 관리자는 결과가 모델에 크게 좌우된다고 덧붙였습니다.

### 같은 실패가 세 번 반복되고 멈춤

오류라기보다 안전 장치입니다. 에이전트는 같은 실패가 세 번 나오면 멈추고, 지금까지 알아낸 내용을 `MODLOG.md`에 적은 뒤 다른 방법을 찾거나 사용자에게 묻습니다. 이때 게임 버전, 모드 로더 버전, 로그 파일 내용을 알려 주거나 더 가벼운 경로(예: 코드 패치 대신 데이터 교체)로 바꾸자고 하면 진전이 빠릅니다.

## 플러그인 없이 에이전트에게 시키면 안 될까: 차이는 작업 순서와 규칙

할 수는 있습니다. 일본 유튜브 채널 さつきのOSS研究室는 Claude Code에 플러그인 없이 직접 시킨 게임 3종의 개조 과제 8개가 모두 통과했고, 그동안 스킬은 한 번도 호출되지 않았다고 소개했습니다. 한 채널의 작은 표본이고 게임과 버전 조건은 공개 자료로 확인되지 않습니다.

그래도 플러그인을 쓰는 이유는 에이전트의 능력보다 작업 순서에 있습니다. 지식 베이스에서 같은 게임의 선례 찾기, `um scan`으로 안티치트와 세이브 폴더 확인, 수정 전 세이브 백업, 작은 기능 하나부터 게임 안에서 검증, 같은 실패 세 번이면 중단, 배포 전 `um publish check`, 다음 사람을 위한 기록까지가 한 흐름으로 묶여 있고, 위 거절 규칙도 함께 따라옵니다. 일반 문장으로 요청하면 에이전트가 스킬을 쓰지 않고 바로 코드를 고칠 수 있으므로, 이 흐름을 확실히 따르게 하려면 Claude Code에서는 `/universal-modder:mod-any-game`으로 직접 부르는 편이 확실합니다.

## Universal Modder 자주 묻는 질문

### Universal Modder는 무료인가요?

도구 자체는 MIT 라이선스로 무료입니다. 다만 작업하는 코딩 에이전트의 요금제나 API 요금이 들고, fal로 에셋을 생성하면 장당·초당 요금이 따로 나갑니다. 에셋을 직접 그리거나 로컬 ComfyUI(`um comfy`)를 쓰면 fal 비용은 없습니다.

### 맥에서도 Universal Modder를 쓸 수 있나요?

설치와 정찰, 지식 베이스 검색, 에셋 생성은 Python 도구라 macOS에서도 쓸 수 있습니다. 게임 실행·스크린샷·입력 자동화를 맡는 `um win`은 Windows와 WSL에서만 동작하므로, 게임 안 확인은 직접 해야 합니다. 지식 베이스에는 macOS에서 Wine으로 돌린 게임을 모딩한 노트도 있어, 게임에 따라 가능한 범위가 다릅니다.

### universal-modder.org가 공식 사이트인가요?

GitHub 저장소 README에는 그 사이트가 공식이라는 설명이 없고, 사이트 스스로 오픈소스 프로젝트를 바탕으로 한 커뮤니티 허브라고 소개합니다. 설치 명령과 소스는 `github.com/rehan-remade/universal-modder`를 기준으로 삼고, 다른 사이트에서 받은 모드 파일은 실행 전에 출처를 확인하세요.