Пользовательское руководство по эксплуатации комплекса локализации DDLC-модификаций

Об истоках продукта

Этот продукт — результат личной инициативы основателя проекта. Мы с гордостью заявляем, что разработка и доработка велась и ведётся в сотрудничестве с руководством команды перевода TheOneTranslator.

Об этом руководстве

Данное пособие ориентировано на конечных пользователей: переводчиков, мододелов и контент-менеджеров. В этом документе вы найдете исчерпывающую информацию для эффективного взаимодействия с программой.

📖 Внимание: Настоятельно рекомендуем прочитать данное руководство полностью и до самого конца перед началом работы. Пропуск даже одного технического нюанса или предупреждения может привести к критическим ошибкам при сборке ваших проектов.

1. Обзор Интерфейса и Органов Управления

Графическая оболочка приложения спроектирована таким образом, чтобы минимизировать рутинные действия и предоставить полный контроль над процессом декомпиляции и патчинга в один клик.

Главное рабочее пространство

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

• TOP_PANEL // Конфигурация путей и параметров
• ├ Выбор рабочих директорий (Ресурсы / Целевой мод)
• ├ Ввод локализованного названия проекта (+ автоподбор по кнопке «ОК»)
• └ Переключатели архитектуры движка (Auto / 6-7 / 8)
• CENTER_PANEL // Управление модулями автоматизации
• └ Интерактивная зона. Кнопки-переключатели шагов конвейера с цветовой индикацией статуса (Цветная = Активен / Серая = Пропущен).
• BOTTOM_PANEL // Информационная консоль логов
• └ Защищенное от записи окно потокового вывода. Агрегирует системные статусы и маркеры прогресса в режиме реального времени.

2. Подробное Описание Функциональных Элементов

Выбор рабочих директорий

Программа требует указания двух ключевых путей через стандартный проводник:

• Папка ресурсов: Каталог, где хранятся системные файлы автоматизации (шрифты, резервный скрипт декомпилятора и две версии специализированных библиотек декомпиляции un.rpyc под разные поколения Ren'Py).
• Папка мода: Корневая директория модификации, которую необходимо перевести или проанализировать (программа сама найдет внутри нее подпапку game и все вложенные архивы).

Интеллектуальный блок именования проекта

Поле «Название модификации» снабжено умной кнопкой «ОК»:

• Ручной ввод: Вы можете самостоятельно вписать любое имя для папки перевода.
• Автоматический режим: Если вы оставите поле пустым и нажмете «ОК», программа мгновенно проанализирует выбранный путь к моду, определит название его корневой папки, очистит его от лишних символов и автоматически подставит в поле.

Ручной селектор версий Ren'Py

Две выделенные кнопки позволяют жестко ограничить логику декомпиляции под конкретную архитектуру:

• Ren'Py 6/7: Переводит утилиту в режим работы с Python 2.7 (актуально для старых модов и классического DDLC).
• Ren'Py 8: Переводит утилиту в режим работы с Python 3 (актуально для современных модов и новейших графических движков).
• Если кнопки не нажаты, система применит встроенный алгоритм автоопределения на основе структуры файлов.

3. Модульная Система Сборки

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

🎛️ Управление модулями (Интерактивные переключатели)

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

🎨 Яркий, цветной режим

(Цвет подстраивается под тему героини)

ВКЛЮЧЕН

Модуль полностью активен. Все его внутренние задачи будут выполнены утилитой строго по очереди.

🌫️ Серый, блеклый режим

(Цвет кнопки сливается с панелью)

ОТКЛЮЧЕН

Модуль временно деактивирован. Программа полностью пропустит этот шаг, не затрагивая связанные с ним файлы.

💡 Пример использования: Если вам нужно только вскрыть игровые архивы мода для изучения сценария, но вы не планируете прямо сейчас менять шрифты или переводить меню — просто покликайте по остальным карточкам, чтобы они стали серыми. Оставьте активным (цветным) только модуль RPA Extract и нажимайте кнопку старта.

Описание четырех столпов автоматизации

1. RPA Extract (Распаковка и Декомпиляция): Отвечает за вскрытие тяжелых архивов модификации (scripts.rpa, images.rpa и др.). Программа извлекает их содержимое во временный буфер, находит все скомпилированные файлы сценария .rpyc и превращает их в читаемый текстовый код .rpy.
2. Font Remap (Замена шрифтов): Автоматически сканирует весь текстовый код игры, находит упоминания оригинальных английских шрифтов и переписывает ссылки на локализованные кириллические шрифты из вашей папки ресурсов. Это решает проблему «кракозябр» и пустых квадратов в диалогах.
3. Text Assets (Локализация интерфейса): Берет на себя перевод системного меню. Модуль сверяется со встроенным словарем замен (rules.yaml) и мгновенно переводит кнопки «Новая игра», «Настройки», «Сохранить», а также имена главных персонажей (Сайори, Моника, Юри, Нацуки).
4. Clean Up (Очистка билда): Санитарный модуль. После завершения работы он удаляет терабайты временных индексных файлов, кэш движка и остаточные скомпилированные скрипты, оставляя вам кристально чистую рабочую папку с готовым переводом.

4. Визуальные Темы Оформления

Программа имеет встроенную систему кастомизации. Каждая тема меняет интерфейс, подстраивая его под цветовую палитру и настроение одной из четырех героинь Литературного Клуба.

• Тема «Monika»: Фирменный изумрудно-зеленый акцент. Консоль и активные элементы подсвечиваются мягким зеленым цветом, создавая атмосферу контроля и порядка.
• Тема «Sayori»: Небесно-голубые тона, контрастирующие с теплыми коралловыми элементами. Делает интерфейс ярким и дружелюбным.
• Тема «Yuri»: Глубокий, загадочный темно-фиолетовый интерфейс с приглушенными неоновыми акцентами для сосредоточенной работы в ночное время.
• Тема «Natsuki»: Пастельно-розовая цветовая гамма с яркими точечными акцентами, делающая рабочее пространство максимально контрастным.

Смена темы происходит мгновенно при выборе в выпадающем списке и не требует перезапуска приложения. Вместе с темой меняется и интеграция в ваш профиль Discord (Rich Presence), отображая остальным пользователям, под чьим «покровительством» вы сейчас переводите мод.

5. Двухуровневый Мониторинг

Чтобы пользователь не гадал, зависла программа или обрабатывает большой архив, в утилиту внедрена система разделения информации.

Встроенная мини-консоль (Для контроля «на лету»)

Расположена в нижней части главного окна. В нее выводятся только понятные и лаконичные статусы с использованием смайликов-индикаторов:

• 🔍 [SCAN] — Программа ищет файлы или анализирует структуру.
• ✨ [STATIC] — Успешно отработал резервный метод декомпиляции.
• ❌ [ERROR] — Критическая ошибка, требующая внимания пользователя.
• Консоль защищена от случайного ввода текста, строки прокручиваются автоматически по мере продвижения сборки.

Дисковый лог-файл (Для разбора полетов)

Если в процессе декомпиляции что-то пошло не так (например, архив поврежден или заблокирован антивирусом), на диске в рабочей папке создается файл session.log. В него записывается абсолютно каждое действие программы, включая технические сообщения операционной системы и детальные отчеты об ошибках. Его необходимо передавать разработчику утилиты в случае обнаружения системных сбоев.

6. Работа с Результатами

После завершения работы активных модулей в корневой папке программы появятся две важнейшие директории с результатами анализа.

Папка untranslated/ (Поиск пропущенного текста)

Сюда система автоматически изолирует все строки интерфейса, меню, настроек и всплывающих окон, которые были обнаружены в коде модификации, но не подошли ни под одно правило автоматического перевода из конфигурации rules.yaml.

• Структуризация по файлам: Весь найденный контент распределяется по отдельным текстовым документам, имена которых полностью соответствуют исходным скриптам (например, screens.txt, options.txt).
• Точечная привязка: Внутри каждого файла фиксируются точные номера строк из оригинального кода и сам исходный текст, требующий локализации.
• Сценарий использования: Инструмент полностью избавляет от необходимости вручную перебирать системные файлы новеллы. Переводчику достаточно открыть сгенерированные отчеты, скопировать оставшиеся без перевода элементы интерфейса и внести их в общую базу замен.

Папка story_maps/ (Карта сюжета модификации)

Этот модуль отвечает за аудит логики новеллы и визуализацию структуры её сценария. Внутри директории конкретного мода система генерирует три взаимодополняющих формата данных:

• Текстовая карта (.txt): Облегченный структурированный документ, отображающий строгую хронологию скриптов. Он показывает, с какого файла начинается игра, как работают развилки, какие сюжетные переходы (jump и call) связывают файлы между собой и в каких точках сценарий разветвляется на индивидуальные руты.
• Графическая интерактивная карта (.html): Полноценный визуальный веб-интерфейс, открывающийся в любом браузере. Карта представляет собой динамический интерактивный граф:
• Узлы (Ноды): Каждый блок на карте — это отдельный файл сценария со списком содержащихся в нем ключевых меток (label).
• Связи (Стрелки): Визуализируют направления переходов между скриптами, позволяя сразу определить, куда ведут выборы игрока.
• Панель управления: Включает инструменты масштабирования (зум кнопками или колесиком мыши), центрирование холста и «умный» поиск по файлам или меткам с автоматической фокусировкой камеры.

7. Пошаговый Алгоритм Работы

/AUTOBUILDER_RW # Корневой каталог программного комплекса │ ├── /logs # Системные журналы и отладочные данные │ └── session.log # Детализированный лог сессии (трассировки, дампы декомпилятора) │ ├── /setup # Конфигурация автоматизации │ └── rules.yaml # База правил замен, патчинга интерфейса и имен персонажей │ ├── /story_maps # Результаты анализа сюжета модификаций │ ├── [Имя_Мода]_map.txt # Текстовая хронология и граф развилок сценария │ └── [Имя_Мода]_map.html # Интерактивная графическая карта с поиском для браузера │ ├── /untranslated # Результаты работы сканера интерфейса (UI Scanner) │ └── [Имя_Мода]_miss.txt # Файлы с пропущенными строками меню и номерами строк из кода │ ├── /Ресурсы # Техническая папка статических компонентов │ ├── fonts │ │ ├── DejaVuSans.ttf │ │ ├── Montserrat-Bold.otf │ │ └── Roboto-Regular.ttf # Набор локализованных кириллических шрифтов (.ttf / .otf) │ ├── un.rpyc_v1 (RenPy8) # Байт-код декомпилятора для версий движка на Python 3 │ ├── un.rpyc_v1 (RenPy7) # Байт-код декомпилятора для версий движка на Python 2.7 │ ├── unrpyc.py # Резервный автономный скрипт декомпиляции сценариев │ └── TheOne.png # Обязательный графический ассет (логотип TheOneTranslator) │ └── AutoBuilder_v1.0.exe # Основной исполняемый файл (скомпилированный контроллер GUI)

Для успешной локализации модификации придерживайтесь следующей последовательности действий:

Подготовка: Запустите программу. Поместите файлы кириллических шрифтов и актуальный rules.yaml в вашу папку ресурсов.

⚠️ ВАЖНОЕ ПРИМЕЧАНИЕ: Если в скачанном моде полностью отсутствует рабочий .exe файл для запуска новеллы, вам необходимо взять файлы модификации и вставить их в папку оригинальной чистой DDLC с заменой всех файлов.

• Указание путей: Нажмите кнопку обзора напротив поля «Игра» (выберите папку с новеллой) и «Ресурсы» (выберите папку ресурсов).
• Именование: Кликните на кнопку «ОК» рядом с полем названия, чтобы программа сама перехватила имя папки мода, либо введите свое уникальное название.
• Кастомизация: Выберите любимую тему оформления (кнопки персонажей в верхней панели), чтобы настроить интерфейс под себя.
• Настройка модулей: По умолчанию все четыре модуля (RPA Extract, Font Remap, Text Assets, Clean Up) включены. Если вам нужно просто распаковать архивы без очистки — отключите ненужные модули кликом мыши (они должны стать серыми).
• Выбор движка: В блоке «Версия Ren'Py» выберите соответствующую версию движка.
• Важное уточнение: Ошибки RenPy о том, что файл un.rpyc не может быть загружен в некоторых модах — это нормальное явление, так как они зависят от версии движка, поэтому всегда выбирайте подходящую версию Ren'Py (6, 7 или 8) для корректной работы.
• Ren'Py 8: использование инжектора v2 и запуск через .exe.
• Ren'Py 6/7: использование инжектора v1 и запуск через .exe.
• Старт: Нажмите большую кнопку «Инициировать сборку» в нижней части окна.
• Контроль: Наблюдайте за логами в мини-консоли. Дождитесь финального сообщения о завершении работы.
• Итог: Перейдите в папки untranslated и story_maps для оценки структуры мода и доработки пропущенных строк интерфейса.

8. Важные Правила Безопасности и Системные Требования

Жесткое табу на вмешательство: Во время работы конвейера сборки ни в коем случае не трогайте саму программу и файлы обрабатываемого мода. Не перемещайте файлы, не открывайте их в сторонних редакторах и не пытайтесь запустить игру до окончания процесса. Дайте утилите монопольно завершить все дисковые операции.

Требования к среде (Python): Для корректного функционирования бэкенда утилиты строго необходим Python версии 3.13.

• При установке интерпретатора обязательно должна быть отмечена галочка «Add Python to PATH».
• Если у вас установлена более старая версия или галочка PATH была пропущена — обязательно выполните чистую переустановку Python, иначе автоматизация отработает некорректно.

9. Особенности пользования программой

⚠️ КРИТИЧЕСКИ ВАЖНОЕ ПРАВИЛО ПРИ ЗАПУСКЕ: Как только утилита запустит процесс инжекции и откроет окно игры — КАТЕГОРИЧЕСКИ НЕЛЬЗЯ ТРОГАТЬ МОД! Не кликайте по окну игры, не пытайтесь свернуть его или закрыть вручную. Программа все делает полностью в автоматическом режиме: она сама дождется генерации скриптов, сама закроет процесс игры через триггер и продолжит пайплайн. Любое ручное вмешательство на этом этапе намертво сломает структуру файлов и приведет к дубликатам или ошибкам в переводе!

⚡ Что делать, если мод не запускается сразу? Если после завершения автоматизации вы пытаетесь запустить локализованный мод, а он не открывается с первого раза — это абсолютно нормально.

В чем причина? В процессе работы программа выполняет колоссальный объем задач: от тяжелых операций с файловой системой до стремительного исправления артефактов и чистки дубликаций мусорного кода. Дополнительно: Теперь инструмент делает до 3 автоматических попыток инжекции кода для каждого .exe файла. Если новые скрипты .rpy обнаруживаются уже после первой попытки, утилита мгновенно завершает цикл, экономя время сборки.

Важно: Из-за такой интенсивной нагрузки операционная система просто не успевает мгновенно «отпустить» дескрипторы файлов и папок.

Решение проблемы Не нужно паниковать или перезапускать процесс заново. Просто подождите несколько секунд и повторите попытку. Со второго раза мод гарантированно запустится в штатном режиме.

0. Обратная Связь

💡 Важное примечание: Самостоятельное решение проблем Не все ошибки являются критическими багами самой утилиты, и многие из них можно оперативно решить локально с помощью ИИ. Если вы столкнулись с непонятным поведением или ошибкой, рекомендуется скопировать текст проблемы и обратиться к актуальным нейросетям (обязательно используйте свежие модели с доступом к интернету). Зачастую они могут быстро проанализировать логи и подсказать решение без необходимости ждать ответа от поддержки.

🔍 Пример: Почему ошибка «внезапно» появляется только после распаковки

Отличный маркер того, что проблему стоит сначала показать ИИ — ситуации, когда в архиве всё работало, а после распаковки начались вылеты. Вот как это выглядит на практике:

• До распаковки: mod_assets.rpa ← файл autofocus.rpyc запакован внутри архива. Ren'Py спокойно читает готовый .rpyc из архива — всё работает ОК, так как скомпилированный байткод движком уже «переварен».
• После распаковки: mod_assets/MPT/autofocus.rpy ← теперь скрипт лежит в папке в виде исходного кода. Ren'Py пытается перекомпилировать его заново и падает на строке 267.

В чем логика: Сама утилита-распаковщик отработала корректно, но обнажила старую ошибку в коде скрипта, которую движок раньше просто игнорировал, используя готовый кэш. Нейросеть мгновенно считает этот контекст по логу ошибки, объяснит причину и выдаст исправленную строку кода быстрее, чем разработчик успеет прочитать ваше сообщение.

Если же ошибка не решается:

📬 Контакты для связи:

• Telegram: @rootWin
• Discord: rootWin
• Reddit: Кнопка с прямой ссылкой на официальное сообщество встроена прямо в пользовательский интерфейс программы.

📋 Что ОБЯЗАТЕЛЬНО должно быть в баг-репорте:

Если решить проблему с помощью ИИ не удалось, для максимально быстрого исправления подготовьте и отправьте разработчику следующий пакет данных:

• Лог-файл программы: Физический файл истории работы, который находится в директории logs корневой папки утилиты.
• Ошибки Ren'Py: Текст или файлы логов ошибок (traceback.txt, log.txt), если сам движок новеллы выдает их при попытке запуска мода.
• Скриншоты приложения: Снимки главного окна программы в момент возникновения проблемы (с развернутой консолью логов).
• Скриншоты файловой структуры: Снимки папок с файлами самой программы и скриншоты содержимого папки обрабатываемого мода (каталог game), чтобы было видно исходные расширения ассетов.