Как установить и использовать 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-играми нативно или из WSL2.

На macOS и Linux агент всё равно может тестировать в игре системными средствами захвата (screencapture, ffmpeg, xdotool), но ничего не настроено заранее. Полевые заметки про xEdit под Linux или HL2 через Wine на macOS показывают, что это возможно.

Установка по агентам: сравнение

Любой способ ставит одни и те же навыки (формат Agent Skills), MCP-сервер fal и CLI um.

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, а настройки MCP — из .codex/config.toml.

Gemini CLI

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

Манифест расширения — gemini-extension.json; инструкции берутся из GEMINI.md, который ссылается на AGENTS.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 или клонируйте репозиторий и откройте его: Cursor сам прочитает AGENTS.md и .cursor/mcp.json.

OpenCode

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

opencode.json подключает навыки и MCP-сервер fal.

Любой другой агент

# только навыки, в папку навыков вашего агента
npx skills add https://github.com/rehan-remade/universal-modder

# или целиком: запустите агента внутри клона
git clone https://github.com/rehan-remade/universal-modder

Отдельная установка CLI um

Установка плагина и клонирование уже добавляют 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 с примерами. См. справочник по CLI um.

Ключ API fal

Получите ключ на fal.ai/dashboard/keys (нужно пополнить баланс; ключ показывается один раз — сохраните его). На нём работают и MCP-сервер fal, и 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. Выберите простую игруПроще всего начать с игр, у которых есть популярный лоадер: Terraria (tModLoader), Stardew Valley (SMAPI), Minecraft (Fabric/Forge), игры на Unity с BepInEx и на Unreal с UE4SS. Смотреть библиотеку игр.
2. Сначала попросите разведку
   промптКопировать

   На каком движке моя Terraria, моддил ли её кто-нибудь (поищи в базе знаний) и каким путём ты бы пошёл? Пока ничего не меняй.

3. Дайте сделать бэкап и лабораториюАгент снимает снапшот сохранений через um backup create, берёт отдельный профиль или мир и спрашивает перед установкой лоадера.
4. Сделайте один срез
   промптКопировать

   Добавь один бумеранг, который четыре раза отскакивает между врагами и возвращается. Сначала временный спрайт, а когда заработает в игре — спрайт из fal.

5. Проверьте и только потом расширяйтеЗапустите игру, посмотрите своими глазами и лишь затем просите большего. Длинные проекты ведутся в MODLOG.md; в новой сессии скажите «прочитай MODLOG.md и продолжай».

Решение проблем

Добавление маркетплейса падает с ошибкой Git / SSH

Маркетплейсы плагинов клонируются через Git. Если на компьютере нет SSH-ключа GitHub, скажите Git использовать HTTPS для GitHub:

git config --global url."https://github.com/".insteadOf [email protected]:

Навыки не появились после установки

Выполните /reload-plugins (Claude Code) или перезапустите агента. Проверьте в /plugin, что плагин включён.

um: command not found

Откройте новый терминал после установки плагина или поставьте CLI через uv tool install, как выше, и убедитесь, что ~/.local/bin есть в PATH (uv tool update-shell).

um fal пишет, что нет ключа

FAL_KEY должен быть задан в окружении, из которого запущен агент. Перезапустите агента после setx или правки профиля оболочки.

um win не запускается

Он управляет только Windows-играми — из Windows или WSL2. На macOS/Linux тестируйте в игре вручную.