Гид по Universal Modder
Начните с небольшого изменения и проверьте его в игре.
Universal Modder — открытый набор инструментов, который помогает ИИ-агентам для программирования исследовать, создавать и проверять моды для ПК-игр. В него входят навыки, консольная утилита um на Python, заметки по отдельным играм и интеграция с fal для генерации ресурсов. Исходный проект находится в rehan-remade/universal-modder на GitHub (на английском).
Для начала выберите небольшое изменение в игре, которой владеете: определите движок и загрузчик модов, сохраните резервную копию тестового сохранения, создайте функцию с временной графикой и проверьте её в запущенной игре. Слово «Universal» описывает широкий подход, но не гарантирует совместимость со всеми играми и версиями.
Источники проверены 9 октября 2026 года для коммита 8370faa и версии пакета 0.2.0. Это руководство по документации и исходному коду. Мы не запускали примеры модов и не проверяли весь процесс через OmniaKey. Внешние источники ниже — на английском языке.
Из чего состоит набор
В README проекта разделены следующие компоненты:
| Компонент | Задача | Что требуется отдельно |
|---|---|---|
| Навыки агента | Направлять исследование, разработку, подготовку ресурсов и тесты | Агент с работающим доступом к модели |
CLI um | Изучать установленные игры, обрабатывать спрайты, делать резервные копии и помогать с записью | Локальные зависимости и инструменты для выбранной игры |
| База знаний | Хранить версии, решения и ошибки прошлых проектов | Проверка на вашей установленной версии |
| Интеграция fal | Запрашивать изображения, 3D, аудио и видео | Отдельный ключ fal и бюджет на использование |
Репозиторий описывает установку для 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. Сначала изучи игру и загрузчик. Используй временную графику и ненужный тестовый мир. До изменения файлов перечисли затронутые пути, порядок резервного копирования и восстановления. Объясни, как получить предмет, проверить его в игре и удалить мод. Перед платной генерацией ресурсов или публикацией спроси меня.
В основном процессе проекта рекомендуется сначала довести до рабочего состояния одну маленькую функцию с временными ресурсами. Из этого получаются пять проверок:
- Загрузка: игра запускается с нужным загрузчиком, а мод определяется в журнале.
- Отображение: предмет или изменение видны в выбранной тестовой сцене.
- Поведение: результат соответствует запросу; успешной компиляции недостаточно.
- Сохранение: сохранение и повторная загрузка тестового мира работают ожидаемо.
- Возврат: отключение мода и восстановление копии возвращают ожидаемое состояние среды.
После этого можно делать окончательные спрайты, звук и демонстрационный ролик. Сгенерированная картинка или успешная сборка сами по себе не доказывают работоспособность в игре.
Для каких игр есть примеры
Используйте примеры как отправные точки с ограничениями по версиям. Результаты, описанные авторами, не заменяют проверку на вашем компьютере.
- Terraria / tModLoader: Fal Arsenal основан на одиночном проекте для Terraria 1.4.4 и tModLoader 2026.07. README прямо указывает, что мультиплеер не проверен. Используйте отдельный мир.
- Age of Empires II DE: пример цивилизации включает генерацию графики и преобразование спрайтов. Он занимает существующий слот цивилизации и не подтверждает возможность добавлять произвольные новые слоты.
- Minecraft × GTA V: пример объединяет две запущенные игры в сюжетном режиме GTA V. Документированная проверка относится к GTA V Legacy в Steam, сборка 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. Установка плагина не объединяет оплату этих сервисов. Перед пакетной генерацией проверьте модель и число результатов. Не включайте ключи в файлы мода или публикуемые архивы.
Начать можно с временной или собственной графики. В руководстве по ресурсам также описан um comfy для изображений с локального сервера ComfyUI без ключа fal. Встроенные сценарии для изображений не заменяют весь процесс работы fal с аудио, 3D и видео. Локальное оборудование и модели нужно подготовить отдельно.
Что проверять при сбое
Меняйте только один уровень за раз:
- Не найден
um: проверьте PATH терминала и отдельную установку CLI, прежде чем разбираться с загрузчиком игры. - Игра не обнаружена: передайте папку установки и сопоставьте вывод с актуальной документацией сообщества.
- Ошибка авторизации fal: убедитесь, что процесс агента получил
FAL_KEYнужного аккаунта. Успешный вход в агента ничего не доказывает об авторизации fal. - Сборка успешна, но мод не загружается: проверьте версии, путь установки и журнал загрузчика до повторной генерации ресурсов.
- Графика выглядит неправильно: проверьте размеры, прозрачность, раскладку кадров и ориентацию до изменения запроса к генератору.
Сохраните журнал ошибки и минимальные шаги воспроизведения. Это даст следующей попытке отладки конкретный предмет проверки.
Сетевая игра и публикация
Соблюдайте ограничения проекта: работайте с принадлежащими вам играми, предпочитайте офлайн-тесты или разрешённую среду под вашим контролем, не обходите античит, DRM и проверки владения. Правила проекта запрещают внедрение кода в защищённые сетевые клиенты. Частный сервер сам по себе не отменяет защиту клиента и ограничения издателя.
Перед публикацией проверьте условия игры и лицензии ресурсов и инструментов. MIT-лицензия набора не даёт права распространять игровые файлы, извлечённые ресурсы или декомпилированный код. Публикуйте собственную работу с инструкцией по установке, проверенными версиями и способом удаления.
Для подключения модели прочитайте руководство по подключению Claude Code и проверьте актуальные цены OmniaKey. Настройте эту часть отдельно от fal, затем проверьте реальный процесс создания мода в своей среде.