Импорт проектов Pokemon Essentials

Есть проект Pokemon Essentials, над которым вы работаете месяцами или годами? Essentials Importer из OpenMon преобразует данные вашего проекта PE v20, v21 и v21.1 в формат OpenMon — сохраняя вашу работу и открывая доступ к полной платформенной поддержке Unity и коммерческому лицензированию.

Второй снимок экрана — цель всего конвейера: 667 / 667 Monsters, которых можно просматривать по видам, приёмам, способностям, предметам, типам и характерам, — из проекта, который час назад был скриптами на Ruby и текстовыми файлами PBS.

Доступно в редакциях Indie, Pro, Source и Studio (в Indie и Pro — в скомпилированном виде).

Проверено на реальном проекте v21.1

Импортёр был запущен без интерфейса на полном проекте Pokemon Essentials v21.1 (релиз 2023-07-30) и преобразовал каждый список от начала до конца с нулём ошибок:

Данные	Результат
Виды	898 / 898 преобразовано, 0 ошибок — применено 335 переопределений форм, связано 422 эволюций
Приёмы	Создано 150 новых ассетов Move, 590 сопоставлено с существующей библиотекой приёмов
Способности	72 создано, 195 сопоставлено
Предметы	Создано 315 ассетов Item, 378 сопоставлено
Тренеры	20 тренеров с заполненными командами (обработано 72 типа тренеров)

Все 898 видов преобразованы в настоящие ScriptableObject MCE — формы и цепочки эволюции связаны — без фатальных ошибок. Это главное заявление импортёра: проверено на полном реальном проекте v21.1, а не на синтетическом тестовом наборе. 227 предупреждений, сопровождавших запуск, — это все уведомления о честной деградации (эффекты приёмов без точного шаблона MCE — см. Приёмы ниже), но никак не молчаливая потеря данных.

Что импортируется

Essentials Importer обрабатывает следующие типы данных:

Данные PE	Эквивалент в OpenMon	Статус
PBS/pokemon.txt	ScriptableObject MonsterEntry	Поддерживается (898/898 на реальном v21.1)
PBS/pokemon_forms.txt	Ассеты Form + переопределения DataByFormEntry	Поддерживается (применено 335 переопределений)
PBS/moves.txt	ScriptableObject Move	Поддерживается, честное сопоставление эффектов
PBS/types.txt	Ассеты MonsterType + таблица эффективности	Поддерживается
PBS/abilities.txt	ScriptableObject Ability	Поддерживается (на уровне ассетов)
PBS/items.txt	ScriptableObject Item	Поддерживается (создаются конкретные SO)
PBS/trainers.txt	TrainerDefinition + CharacterData + Roster + Bag	Поддерживается
PBS/encounters.txt	ScriptableObject WildEncountersSet	Поддерживается
Спрайты монстров	Боевые Material + Sprite значков	Поддерживается (по формам + варианты по полу)
Файлы карт (.rxdata)	Сцены Unity с GridController	Поддерживается (требует проверки на уровне проекта)
Изображения тайлсетов	Атласы спрайтов Unity	Поддерживается
Команды событий карты	Узлы CommandGraph	Поддерживается (бои с тренерами подключены)
Аудиофайлы	AudioClip с конфигурацией AudioManager	Прямое копирование

Что требует ручной работы

Некоторые возможности PE не имеют прямого автоматического преобразования. Мы документируем это как честные ограничения по замыслу, а не оставляем их двусмысленными:

• CommonEvents.rxdata — общие события вне области действия по замыслу. Они не импортируются; переносите общую логику событий в CommandGraph или C# вручную.
• Поведение способностей — ассеты способностей создаются или клонируются, но импортированная способность работает лишь настолько богато, насколько богата реализация MCE, на которую она отображена. Пользовательским способностям и способностям из плагинов нужна соответствующая реализация Ability в MCE.
• Сложные скрипты на Ruby — пользовательские скрипты PE за пределами стандартных команд событий нужно переносить на C# или CommandGraph вручную.
• Данные, специфичные для плагинов — сторонние плагины PE хранят данные в нестандартных форматах.
• Пользовательские макеты интерфейса — оконная система PE принципиально отличается от Unity UI.
• Анимированные боевые спрайты — PE использует другой формат анимации; спрайты импортируются как статичные кадры, которые можно собрать заново.

Предварительные требования

Перед импортом убедитесь, что у вас есть:

1. Установленный OpenMon (редакция Indie или выше) — см. Руководство по установке
2. Папка вашего проекта PE, доступная на диске (та, что содержит PBS/ и Data/)
3. Резервная копия вашего проекта Unity. Мастер говорит об этом сам: импортёр экспериментальный, предоставляется «как есть», а некоторые функции частичные (Items) или не реализованы (Common Events).

Версию Essentials (v20, v21 или v21.1) вы не выбираете: импортёр определяет её при сканировании проекта.

Пошаговый импорт

Шаг 1: Откройте импортёр

В Unity откройте OpenMon Hub (Tools > MCE > OpenMon Hub) → вкладка Importer → Import Wizard.

Starting Map Picker, расположенный ниже на той же вкладке, — шаг, который чаще всего упускают: он определяет, на какой карте появится игрок после главного меню. Без него в остальном успешному импорту просто негде начаться.

В окне мастера отображаются:

• PE Project Folder — корневая папка вашего проекта (та, что содержит PBS/, Data/, Graphics/), с кнопкой Browse
• Project Name — имя этого импорта (например, FRLG или Emerald). Оно задаёт имя папки вывода, поэтому несколько импортов могут жить рядом
• Imported Projects — импорты, которые уже есть в этом проекте Unity
• Import Categories — переключатель для каждого типа данных
• Map Display Mode — рисовать импортированные карты в 2D (плоско, вид сверху) или в 2.5D (под наклонной камерой). Каждую карту можно изменить позже в Display Mode per Map
• Output Folder и Overwrite Existing Assets

Шаг 2: Выберите и просканируйте проект PE

Нажмите Browse и перейдите в папку вашего проекта Pokemon Essentials, затем нажмите Scan Project. Импортёр проверяет структуру папок, показывает определённую Version и сообщает, что нашёл:

PBS/pokemon.txt        -- 898 species detected
PBS/moves.txt          -- 740 moves detected
PBS/types.txt          -- 19 types detected
PBS/abilities.txt      -- 267 abilities detected
PBS/items.txt          -- 693 items detected
PBS/pokemon_forms.txt  -- 339 form overrides detected
PBS/trainers.txt       -- 20 trainers detected

(Показанные числа взяты из реального проекта v21.1 2023-07-30, на котором проверялся импортёр.)

Сканирование также выполняет глубокое сканирование автотайлов проекта. Если все изображения, которые называет тайлсет, есть в проекте, сканирование завершается строкой [OK] Missing: 0 - All autotile images found!. Отсутствующее изображение пока не оценивается: это происходит, когда карты уже разобраны (см. примечание о коде возврата в разделе о командной строке и легенду журнала на шаге 5).

Шаг 3: Выберите, что импортировать

В Import Categories есть переключатель для каждого из пунктов: Species, Moves, Items, Abilities, Types, Trainers, Encounters, Maps, Sprites, Follower Sprites, Audio и Connections.

Для первого импорта мы рекомендуем импортировать по этапам:

1. Первый проход: Types, Abilities, Moves, Species (только данные, без карт)
2. Второй проход: Items, Trainers, Encounters
3. Третий проход: Maps и Audio
4. Четвёртый проход: проверьте события и интеграцию сцен (ниже)

Такой поэтапный подход позволяет проверить каждый слой данных, прежде чем строить на нём следующий.

Шаг 4: Запустите импорт

Мастер работает фазами, и у каждой есть собственная кнопка:

Кнопка	Что она делает
PARSE DATA	Фазы 1–2: читает текстовые файлы PBS, а также карты и тайлсеты .rxdata в соответствии с определённой версией Essentials. В вашем проекте пока ничего не создаётся.
CONVERT TO MCE	Фаза 3: превращает разобранные данные в ScriptableObject и сцены MCE в папке вывода. Доступна после успешного разбора.
FULL IMPORT (Parse + Convert)	Разбор, преобразование и интеграция за один раз.
INTEGRATE SCENES (Phase 6)	Подключает импортированные сцены к рантайму MCE: регистрирует их в менеджере сцен, подключает каждый SceneInfo, размещает триггеры варпов, связывает наборы встреч и добавляет сцены в Build Settings. Запускайте после импорта (полный импорт уже делает это).

Всё записывается в Assets/ImportedGames/<Project Name>/, а подробный журнал импорта показывает успехи, предупреждения и элементы, требующие внимания.

Шаг 5: Просмотрите журнал импорта

Журнал классифицирует результаты:

• [OK] — данные успешно преобразованы
• [WARN] — данные преобразованы, но с допущениями (например, эффект приёма без точного шаблона MCE, клонированный по категории), либо остаток, при котором ничего не теряется (тайлсет называет изображение автотайла, которого нет в проекте, но ни одна карта этот тайлсет не использует)
• [ERR] — данные, которые не удалось преобразовать автоматически (включая изображение автотайла, которое называет тайлсет, используемый хотя бы одной картой, и которого нет в проекте)

Шаг 6: Сделайте игру играбельной

После интеграции используйте Starting Map Picker, если хотите другую стартовую карту. Кнопки мастера Restore MCE Original Demo и Restore Imported Demo переключают Build Settings между сценами демо и импортированными сценами.

Разрушительная кнопка

DELETE ALL IMPORTED PROJECTS удаляет все папки и профили импортированных проектов. Сделайте резервную копию, прежде чем её нажимать.

Шаг 7: Переименуйте для коммерческого использования

Этот шаг критичен для коммерческих релизов.

Ваш проект PE, вероятно, использует специфичные для Pokemon имена монстров, персонажей и предметов. Их необходимо заменить оригинальными, прежде чем вы сможете продавать игру. Используйте Database Browser, чтобы просмотреть и переименовать импортированные данные:

1. Откройте OpenMon Hub (Tools > MCE > OpenMon Hub) → вкладка Database → Database Browser
2. Выполните поиск по импортированной базе видов
3. Переименуйте отображаемое имя каждой записи в ваше оригинальное имя
4. Поскольку ассеты связаны через ссылки на объекты, таблицы встреч, команды тренеров и цепочки эволюции продолжают работать после переименования

Названия приёмов и способностей, как правило, можно безопасно оставить как есть (они описывают механику, а не интеллектуальную собственность), но имена монстров, имена персонажей и названия предметов со специфичным для Pokemon брендингом необходимо изменить.

Что конвейер импортирует, шаг за шагом

Parse (фазы 1–2) читает по порядку: типы, способности, приёмы, предметы, виды, тренеров, встречи, соединения карт, метаданные карт, тайлсеты и карты.

Convert (фаза 3) затем выполняет эти шаги (каждый пропускается, если его категория выключена):

1. Просканировать уже существующие ассеты MCE, чтобы подходящие использовались повторно, а не дублировались.
2. Создать недостающие приёмы и способности клонированием и настройкой.
3. Преобразовать виды вместе с их формами и эволюциями (к этому моменту все приёмы и способности уже существуют).
4. Сообщить о несопоставленных ссылках.
5. Связать спрайты из папки Graphics/ PE и спрайты последователей, если они есть в проекте.
6. Перестроить центральную базу данных монстров; преобразовать типы; убедиться, что существуют 25 характеров; экспортировать предметы и тренеров.
7. Нарезать тайлсеты на ассеты тайлов Unity и запечь автотайлы.
8. Преобразовать карты в сцены Unity и подключить их соединения.
9. Преобразовать встречи в ассеты WildEncountersSet.
10. Импортировать аудио (BGM, BGS, ME, SE), спрайты персонажей мира, изображения battleback и спрайты тренеров.
11. Извлечь варпы и данные событий и преобразовать команды событий в CommandGraph.

Integrate (фаза 6) регистрирует, подключает и добавляет сцены так, как описано в таблице выше.

Как преобразуется каждый тип данных

Спрайты и боевые материалы

Настоящие пакеты Essentials называют спрайты монстров по INTERNALNAME, а не по номеру в дексе. SpriteLinker сопоставляет файлы спрайтов по внутреннему имени, связывает графику по формам и учитывает варианты по полу: поле графики по умолчанию содержит спрайт для самки или бесполого ({name}_female.png), а отдельное поле переопределения для самца содержит базовый спрайт.

Принципиально важно, что линкер создаёт боевые Material для каждой из четырёх сторон (Front, Back, Front-Shiny, Back-Shiny), а также спрайт значка. Боевая модель MCE ссылается на спрайты через Material (флипбук-шейдер), поэтому без этого шага импортированный монстр был бы невидим в бою. Связывание спрайтов выполняется, когда вы импортируете с включёнными спрайтами.

Приёмы (честное сопоставление эффектов)

Эффекты приёмов берутся из FunctionCode Essentials. Импортёр сопоставляет 307 различных FunctionCode с конкретными шаблонами приёмов MCE (проверено в MoveConverter.FunctionCodeTemplates) — сопоставление расширялось несколькими партиями, включая остаточный проход, охватывающий двухходовые/заряжаемые атаки и приёмы, меняющие силу.

Любой FunctionCode, которого нет в таблице, деградирует честно: приём всё равно создаётся, клонируется по своей категории урона, и записывается видимое предупреждение (unmapped FunctionCode '…'. Cloned by category only.). Это сделано намеренно — деградация никогда не бывает молчаливой. Некоторые коды сознательно оставлены без сопоставления, когда точного шаблона MCE не существует, потому что честный запасной вариант лучше неверного клона.

Предметы

ItemConverter создаёт конкретные Item ScriptableObject MCE для каждого разобранного предмета (повторно используя любой существующий MCE Item с совпадающим именем — для идемпотентности) и экспортирует исходные данные PE в JSON для справки. Эффекты предметов, которые MCE не может смоделировать, записываются как предупреждения, а предмет всё равно создаётся как инертный предмет сумки.

Тренеры

Повторяющиеся блоки Pokemon = SPECIES,level в trainers.txt разбираются правильно (распространённая ловушка — дублирующиеся ключи сохраняются, а не сворачиваются). TrainerConverter создаёт для каждого тренера TrainerDefinition, CharacterType, CharacterData, Roster и Bag. События карты, вызывающие pbTrainerBattle(:TYPE, "Name"), подключаются к соответствующему импортированному TrainerDefinition, поэтому импортированные тренеры доходят до настоящих боёв в рантайме.

Встречи

EncounterConverter строит ассеты WildEncountersSet и разрешает виды по исходному, прописному и нормализованному именам — включая виды, в именах которых есть знаки препинания или символы пола, — поэтому таблицы встреч связываются с нужным монстром даже при неудобных внутренних именах.

Формы и эволюции

Переопределения форм создают или переиспользуют ассеты Form и данные DataByFormEntry; отсутствие базового вида вызывает предупреждение и не засчитывается как успех. Подключение эволюций выполняется вторым проходом (после создания всех ассетов видов), чтобы цели разрешались, и идемпотентно перестраивает список эволюций при повторном импорте. Конвертер сопоставляет полный набор заголовков методов эволюции v21.1 — уровень, время суток, пол, предмет, удерживаемый предмет, обмен, известный приём, нахождение в команде и варианты с критическим ударом — с командами эволюции MCE.

Импорт из командной строки

Две точки входа запускают импортёр без открытия мастера. Они различаются тем, сколько делают.

Полный импорт: ImportarCompletoDesdeCli

Выполняет весь конвейер мастера — данные, карты, встречи, аудио, спрайты, варпы, события и интеграцию сцен — точно так же, как кнопка FULL IMPORT:

Unity.exe -batchmode -projectPath . \
  -executeMethod OpenMon.MCE.EssentialsImporter.Editor.EssentialsImporterWizard.ImportarCompletoDesdeCli \
  -essentialsProyecto "D:/Games/MyEssentialsProject" \
  -essentialsNombre "MyGame" \
  -essentialsModo 2.5D

Аргумент	Значение
-essentialsProyecto <папка>	Проект Essentials (должен содержать PBS/ и Data/)
-essentialsNombre <имя>	Имя импорта. Результат попадает в Assets/ImportedGames/<имя>/
-essentialsModo <2D или 2.5D>	Необязательно. Как рисуются карты; если не указан — 2D

Он отказывается писать поверх существующей папки вывода: конвейер пишет и перезаписывает там данные, и то, что там было, было бы потеряно. Выберите другое -essentialsNombre или вынесите старую папку из проекта. Он также отказывается работать, если папки проекта не существует или в ней нет PBS/ или Data/.

Редактор завершается сам с кодом возврата 0, если сцены были созданы и ни одной строки [ERR] не записано, 1 в остальных случаях и 2, если не смог запуститься (отсутствует аргумент, неизвестный режим, проект не найден, папка вывода уже существует). Строки его журнала начинаются с [EssentialsCompleto].

Тайлсет, который называет изображение автотайла, отсутствующее в проекте, оценивается после разбора карт. Это [ERR] только в том случае, если этот тайлсет использует хотя бы одна карта. Если его не использует ни одна карта, это [WARN] ("no map uses that tileset, so nothing is lost"), и импорт не завершается ошибкой.

Импорт только данных: EssentialsHeadlessImport

Для CI или когда вам нужна только база данных (виды, приёмы, предметы...) и не нужны карты, EssentialsHeadlessImport запускает конвейер данных без окна:

Unity.exe -batchmode -quit -projectPath . \
  -executeMethod OpenMon.MCE.EssentialsImporter.Editor.EssentialsHeadlessImport.RunCli

RunCli читает входные данные из переменных окружения:

Переменная	Значение	По умолчанию
MCE_IMPORT_PROJECT	Корень проекта Essentials	./Pokemon Essentials v21.1 2023-07-30
MCE_IMPORT_OUTPUT	Папка вывода относительно Unity	Assets/ImportedGames/_v21batch
MCE_IMPORT_SPRITES	Связывать спрайты и последователей (false, 0, no или off пропускает их)	включено
MCE_IMPORT_REBUILD_DB	Перестроить MonsterDatabaseInstance проекта (false оставляет его нетронутым)	включено

Сначала он очищает предыдущую папку вывода, чтобы запуск был детерминированным, затем записывает компактный отчёт в одну строку на раздел в Logs/v21-batchmode-summary.txt и завершается с кодом 0 при успехе или 1 при ошибке.

Из C# вместо этого можно вызвать EssentialsHeadlessImport.Run(projectPath, outputPath, importSprites, rebuildDatabase); он возвращает ImportSummary с реальными числами (созданные, сопоставленные и пропущенные виды, приёмы, предметы, способности и тренеры).

Он импортирует типы, способности, приёмы, предметы, виды с их формами и метриками, спрайты, последователей, характеры и тренеров и перестраивает базу данных. Он сознательно пропускает карты, сцены, тайлсеты, автотайлы, сцены встреч, аудио, медиа мира/battleback/тренеров, графы команд событий и интеграцию сцен — каждый пропуск записывается в SkippedSteps итогового отчёта.

Большие импорты запускайте из командной строки

Полный импорт с генерацией спрайтов выполняет многоминутную синхронную работу AssetDatabase. Запускайте его в пакетном режиме при закрытом редакторе, а не интерактивно, чтобы долгая работа с ассетами не блокировала редактор. Интерактивные импорты лучше подходят для поэтапных проходов только с данными.

Об импорте дампов картриджей (HeartGold / SoulSilver, FireRed, Black / White) и их профилях игр см. Импортированные игры и профили игр.

Чек-лист после импорта

После импорта пройдите по этому списку:

• Проверьте данные видов в Monster Database Editor
• Выборочно проверьте эффективность типов в Type Chart Editor
• Проведите несколько боёв с импортированными монстрами и приёмами
• Пройдитесь по импортированным картам и проверьте столкновения тайлов
• Проверьте события NPC и ход диалогов
• Замените все специфичные для Pokemon имена оригинальными
• Добавьте собственные спрайты для переименованных монстров
• Настройте таблицы встреч под прогрессию вашей игры
• Настройте систему сохранений под формат сохранений вашей игры

Частые проблемы импорта

«Species X has an unknown ability»

PE допускает пользовательские способности через плагины. Если импортёр не распознаёт способность, он сопоставляет её с заглушкой. Создайте в OpenMon пользовательский ассет Ability, соответствующий этому поведению.

«Map tile Y has no matching collision type»

PE использует некоторые свойства тайлов, которые не сопоставляются напрямую с GridController в OpenMon. Импортёр создаёт тайл, но помечает его для ручного назначения столкновений.

«Evolution method Z not supported»

OpenMon поддерживает 37 типов эволюции, но плагины PE могут добавлять собственные. Они записываются как предупреждения для ручной реализации.

Зачем переходить?

Усилия на импорт и переименование — единовременные затраты. Что вы получаете:

До (PE)	После (OpenMon)
Только Windows	7+ платформ
Только фан-игра	Коммерческий релиз
Нет мультиплеера	Доступны 25 классов онлайн-сервисов
Скрипты на Ruby	C# с полной поддержкой IDE
Нет автоматических тестов	Фреймворк тестирования NUnit
Ручное развёртывание	Конвейер сборки Unity
Разрешение 320x240	Любое разрешение

Годы вашего творческого труда — мир, который вы построили, монстры, которых вы придумали, история, которую вы написали, — заслуживают того, чтобы дойти до самой широкой аудитории на лучшей из возможных технологий.

Получить помощь

• Discord: Присоединяйтесь к сообществу OpenMon — в канале #essentials-import есть специальная поддержка
• Документация: просмотрите полную библиотеку руководств с рабочими процессами, специфичными для OpenMon
• Issues: сообщайте об ошибках импорта на GitHub