Universal Modder 시작하기

Universal Modder는 AI 코딩 에이전트가 PC 게임 모드를 조사하고 제작하고 테스트하도록 돕는 오픈 소스 도구 모음입니다. 스킬, um이라는 Python CLI, 게임별 작업 기록, 에셋 생성용 fal 연동으로 구성됩니다. 이 글에서 다루는 원본 프로젝트는 GitHub의 rehan-remade/universal-modder(영문)입니다.

처음에는 소유한 게임에서 작은 변경 하나를 만드는 것이 좋습니다. 엔진과 모드 로더를 확인하고 테스트 세이브를 보호한 뒤, 임시 이미지로 기능을 만들고 실행 중인 게임에서 검증하세요. 이름의 “Universal”은 폭넓은 접근 방식을 뜻하며 모든 게임과 버전의 호환성을 보장하지 않습니다.

2026년 10월 9일, 커밋 8370faa와 패키지 버전 0.2.0을 기준으로 자료를 확인했습니다. 문서와 소스에 기반한 가이드이며 예제 모드 실행이나 OmniaKey 전체 연동 테스트는 하지 않았습니다. 아래 외부 자료는 영문입니다.

어떤 기능이 들어 있나요

프로젝트 README는 다음 구성 요소를 구분합니다.

저장소는 Claude Code, Codex, Cursor, Gemini CLI, Copilot, OpenCode의 설치 방법을 안내합니다. 이는 에이전트 연동 방법이지 모든 운영체제에서 모든 게임 작업이 된다는 뜻은 아닙니다. Windows 게임 제어 도구는 Windows에서 직접 사용하거나 WSL을 통해 사용하는 환경을 대상으로 합니다.

Claude Code에 설치하기

README에 명시된 준비물은 Git, Python 3.10 이상, ffmpeg입니다. uv 사용을 권장하며, 3D 모델을 스프라이트로 렌더링할 때는 Blender도 필요합니다. 제작하려는 기능에 맞는 환경부터 준비하세요.

Claude Code 안에서 다음 두 명령을 순서대로 입력합니다.

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

터미널 셸 명령이 아니라 Claude Code 플러그인 명령입니다. 활성화 전에 소스와 요청 권한을 확인하세요. 다른 에이전트에서는 원본 README의 해당 설치 절차를 사용합니다.

프로젝트는 플러그인 및 저장소 복제 방식에 CLI 실행기를 제공합니다. 별도 터미널에서 um을 찾을 수 없다면 문서에 나온 독립 설치 방법은 다음과 같습니다.

uv tool install git+https://github.com/rehan-remade/universal-modder
um --help

이 명령은 저장소에서 CLI를 설치합니다. 코딩 에이전트나 fal 계정까지 설정하지는 않습니다. 명령은 소스와 대조했으며 이 글을 작성하면서 실제 설치를 실행하지는 않았습니다.

파일을 수정하기 전에 게임부터 확인하기

다음 예제의 Terraria를 게임 이름이나 설치 폴더로 바꾸세요.

um scan --list
um kb search "Terraria"
um scan "Terraria" --json

게임 조사 가이드에 따르면 스캐너는 파일을 읽어 엔진 단서, 설치된 로더, 세이브 위치, 가능한 구현 방법을 보고합니다. 라이브러리 목록에 없는 게임은 폴더 경로를 직접 지정할 수 있습니다.

스캔 결과는 계획을 세울 자료이며 안전성이나 지원 여부를 증명하지 않습니다. 보호 프로그램이 게임 폴더 밖에 있을 수 있고 런처가 엔진 판정을 혼동시킬 수 있다는 점도 문서에 나옵니다. 최신 커뮤니티 로더 문서와 게임의 모드 정책을 함께 확인하세요.

정확한 게임 및 로더 버전, 세이브와 로그 위치, 수정할 내용, 복원 방법을 MODDING_PLAN.md에 기록하도록 요청하세요. 진행 상황은 MODLOG.md에 남깁니다. 기존 로더나 공식 모드 인터페이스로 구현할 수 있다면 그 경로를 우선합니다.

첫 모드 요청과 완료 기준

결과를 눈으로 확인하기 쉬운 작은 기능을 선택하세요. 다음은 이 글에서 제안하는 요청 예시이며 테스트를 마친 모드는 아닙니다.

로컬 Terraria 테스트 환경에서 설치된 tModLoader 버전에 맞춰 장식용 아이템 하나를 계획해 주세요. 먼저 게임과 로더를 확인하고 임시 이미지와 버려도 되는 테스트 월드를 사용하세요. 수정 전에 대상 경로와 백업·복원 절차를 제시하세요. 아이템을 얻고 게임에서 확인하고 모드를 제거하는 방법까지 설명하세요. 유료 에셋 생성이나 공개 전에는 먼저 물어보세요.

프로젝트의 전체 작업 절차는 임시 에셋으로 작은 기능 하나를 완성한 뒤 확장하라고 권합니다. 이를 다섯 가지 확인 항목으로 정리할 수 있습니다.

1. 로드: 지정한 로더로 게임이 실행되고 로그에서 모드를 확인할 수 있습니다.
2. 표시: 지정한 테스트 장면에 아이템이나 변경 사항이 나타납니다.
3. 동작: 컴파일 성공에 그치지 않고 요청한 행동이 실제로 구현됩니다.
4. 저장: 테스트 월드를 저장하고 다시 불러와도 예상대로 동작합니다.
5. 복원: 모드를 비활성화하고 백업을 복원하면 예상한 상태로 돌아갑니다.

이 검증을 통과한 뒤 최종 스프라이트, 음향, 소개 영상을 만드세요. 생성된 이미지나 성공한 빌드만으로 게임 호환성을 입증할 수는 없습니다.

어떤 게임 예제가 있나요

저장소 예제는 버전 조건이 붙은 출발점입니다. 제작자가 기록한 결과와 자신의 PC에서 확인한 결과를 구분하세요.

• Terraria / tModLoader: Fal Arsenal의 원래 작업 환경은 Terraria 1.4.4, tModLoader 2026.07의 싱글 플레이입니다. README는 멀티플레이를 테스트하지 않았다고 명시합니다. 별도 테스트 월드를 사용하세요.
• Age of Empires II DE: 문명 예제에는 에셋 생성과 스프라이트 변환이 포함됩니다. 기존 문명 슬롯을 대체하며 새 슬롯을 제한 없이 추가할 수 있다는 증거는 아닙니다.
• Minecraft × GTA V: GTA V 스토리 모드에서 실행 중인 두 게임을 결합합니다. 문서에 기록된 테스트 대상은 Steam의 GTA V Legacy 빌드 3889입니다. GTA Online이나 다른 에디션까지 지원한다고 해석하면 안 됩니다.

엔진 가이드 → 버전이 명시된 게임 예제 → 자신의 게임 내 테스트 순으로 근거를 확인하세요. Unity나 Unreal 가이드가 있다는 이유만으로 해당 엔진의 모든 게임을 지원하는 것은 아닙니다.

무료인가요, fal이 꼭 필요한가요

도구 모음의 소스는 MIT 라이선스로 제공됩니다. 전체 제작 비용은 코딩 모델 이용, 에셋 생성, 빌드와 테스트에 쓰는 로컬 하드웨어 및 도구로 나누어 생각해야 합니다.

fal에는 모델과 설정에 따른 별도의 모델 요금이 있습니다. 인증 문서는 FAL_KEY를 사용합니다. 실제 키는 에이전트를 시작하는 환경에 비공개로 설정하세요. 다음 값은 자리표시자입니다.

Bash 또는 Zsh:

export FAL_KEY="YOUR_FAL_API_KEY"

Windows PowerShell:

$env:FAL_KEY = "YOUR_FAL_API_KEY"

OmniaKey 키를 포함한 코딩 모델용 자격 증명은 fal 키가 아닙니다. 플러그인 설치로 두 서비스의 청구가 합쳐지지 않습니다. 일괄 생성을 승인하기 전에 에셋 모델과 생성 수량을 확인하고, 모드 파일이나 배포 압축 파일에 키를 넣지 마세요.

임시 이미지나 직접 만든 에셋으로 시작할 수 있습니다. 프로젝트의 에셋 가이드는 fal 키 없이 로컬 ComfyUI에서 이미지를 만드는 um comfy도 안내합니다. 제공되는 이미지 작업 방식이 fal의 오디오·3D·비디오 전체 기능을 대체하는 것은 아니며, 로컬 하드웨어와 모델 설정도 따로 필요합니다.

처음 시도했는데 실패한다면

한 번에 한 계층만 확인하세요.

• um을 찾지 못함: 게임 로더를 점검하기 전에 터미널 PATH와 CLI 독립 설치를 확인합니다.
• 게임을 감지하지 못함: 설치 폴더를 직접 지정하고 최신 커뮤니티 문서와 대조합니다.
• fal 인증 실패: 에이전트 프로세스에 올바른 계정의 FAL_KEY가 전달되었는지 확인합니다. 코딩 에이전트 로그인 성공은 fal 인증을 보장하지 않습니다.
• 빌드는 성공했지만 모드가 안 뜸: 에셋을 다시 만들기 전에 게임·로더 버전, 설치 경로와 로더 로그를 확인합니다.
• 게임에서 이미지가 이상함: 프롬프트를 바꾸기 전에 크기, 투명도, 프레임 배치와 방향이 게임 요구에 맞는지 살펴봅니다.

실패 로그와 최소 재현 절차를 프로젝트 기록에 남기면 다음 디버깅에서 무엇을 검증할지 분명해집니다.

온라인 사용과 배포는 가능한가요

프로젝트의 사용 범위를 따르세요. 소유한 게임을 대상으로 오프라인 테스트나 허용된 관리 환경을 우선하고, 안티치트·DRM·소유권 검사를 우회하지 않습니다. 보호된 온라인 클라이언트에 코드를 주입하는 행위는 프로젝트 규칙에서 금지합니다. 개인 서버라고 클라이언트 보호나 배급사 제한이 사라지지는 않습니다.

배포 전에는 게임 약관과 에셋·도구 라이선스를 검토하세요. 도구 모음의 MIT 라이선스는 게임 파일, 추출 에셋, 디컴파일된 소스의 재배포 권한을 주지 않습니다. 자신의 작업물을 배포하고 설치 방법, 테스트한 버전, 제거 절차를 적으세요.

코딩 모델 연결은 Claude Code 연결 가이드와 OmniaKey의 현재 요금을 참고하세요. fal과 별도로 연결을 설정한 후 실제 모드 작업은 자신의 환경에서 검증해야 합니다.