Автоинициализация для модов Бесконечного Лета

Обзор

Модуль предоставляет класс autoInitialization_autoinit для автоматической инициализации ресурсов мода (аудио, шрифты, изображения, спрайты) для Бесконечного Лета. Он сканирует папку вашего мода, обрабатывает ресурсы и регистрирует их для использования в моде, либо записывает объявления в файл для инициализации через файл.

Быстрый старт

1. Поместите мод в папку game (настоятельно рекомендую, в поиске корневой папки мода предусмотрен поиск мода в подпапках, но лучше так не делать).
   • Имя папки мода должно быть уникальным и использоваться как параметр modID.
2. Организуйте ресурсы следующей структурой:

<modID>/
├── images/
│   ├── bg/ (опционально)
│   ├── sprites/
│   │   └── <distance>/
│   │       └── <character>/
│   │           └── <variant>/
│   │               ├── body.png (опционально)
│   │               ├── clothes/ (опционально)
│   │               ├── emo/ (опционально)
│   │               └── acc/ (опционально)
│   └── ...
└── ...

• images/: папка с изображениями.
• bg: пример подпапки с фонами (опционально, изображения могут лежать прямо в images).
• sprites/: подпапка со спрайтами. Спрайты организованы по дистанции distance (например normal, far, close, либо своё имя), далее по имени персонажа character (например dv, sl), далее по вариации цифрой (например поза 1), далее по файлам спрайта: body.png (тело, опционально), папки clothes (одежда, опционально), emo (эмоции, опционально), acc (аксессуары, опционально).
• Аудиофайлы могут располагаться в любой папке вашего мода — отдельная папка не требуется (но рекомендуется для порядка).

Подключение

init python:
    autoInitialization_mymod("mymod")

Параметры:

• modID: имя корневой папки вашего мода.
• modPostfix: опциональный постфикс, который добавляется к именам объявляемых ресурсов.
• write_into_file (по умолчанию False): если True, объявления ресурсов будут записаны в файл вместо инициализации скриптом.
• initialize_images (по умолчанию True): искать и регистрировать обычные изображения из images/ (кроме images/sprites).
• initialize_sprites (по умолчанию True): обрабатывать спрайты из images/sprites и все их комбинации.
• initialize_audio (по умолчанию True): искать и регистрировать аудио-файлы (.wav, .mp2, .mp3, .ogg, .opus)
• initialize_fonts (по умолчанию True): искать и регистрировать шрифты (.ttf, .otf).

Примечание: перечисленные флаги управляют только тем, какие этапы будут выполнены при сканировании/инициализации. Сам способ применения (немедленно или через файл) контролируется параметром write_into_file.

Пример настройки:

init python:
    autoInitialization_mymod(
        "mymod",
        modPostfix="mymod",
        write_into_file=False,
        initialize_images=True,
        initialize_sprites=True,
        initialize_audio=True,
        initialize_fonts=True
    )

Важные требования:

• Имя класса автоинициализации должно быть уникальным и содержать имя корневой папки мода (начинаться или заканчиваться на modID). Это предотвращает конфликты между модами. Если вы копируете файл autoinitialization.rpy в свой мод, переименуйте класс, например: autoInitialization_mymod, для избежания потенциального конфликта с авто-инитом из другого мода.
• Название объекта класса и название класса должны различаться.
• Не создавайте дубликаты автоинита, при создании ещё одного объекта класса автоинита автоматическая инициализации ресурсов будет произведена ещё раз, что может сказаться на производительности.

Использование инициализированных ресурсов

Изображения

имя_постфикс папка имя_постфикс папка подпапка имя_постфикс

Примеры:

example folder example folder subfolder example

Правила формирования имён изображений из подпапок images/ (кроме sprites/): к имени файла добавляются сегменты пути, начиная с первой папки внутри images/, затем постфикс modPostfix. Например, файл images/bg/sub/scene.webp станет именем bg sub scene<postfix>.

Спрайты

название спрайта_постфикс название спрайта_постфикс эмоция название спрайта_постфикс эмоция одежда название спрайта_постфикс эмоция одежда аксессуар

Примеры:

dv dv normal dv normal sport dv normal sport jewelry

Дополнительно про дистанции: имя дистанции добавляется в конец (как в БЛ). Для normal добавляется пустая строка (то есть без суффикса), для прочих — само имя дистанции (например close, far). Размеры спрайтов по дистанциям определяются автоматически по первому найденному изображению в папке дистанции, т.е. есть поддержка для собственных дистанций спрайтов.

При объявлении спрайты тонируются в зависимости от времени суток в игре.

Аудио

имя_постфикс

Пример:

grenade

Поддерживаемые расширения аудио: .wav, .mp2, .mp3, .ogg, .opus.

Запись в файл вместо инициализации скриптом

Если write_into_file=True, модуль создаст файл autoinit_assets.rpy в корне вашего мода (<modID>/autoinit_assets.rpy) со следующим содержимым:

• Блок init: с объявлениями:
  • для аудио: присваивание переменной пути к файлу (<имя_с_постфиксом> = "<путь>"),
  • для изображений и спрайтов: объявление через renpy.image("<имя>", <путь/Composite спрайта>).

Важно:

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

Логирование

При запуске автоинициализации мод:

• создаёт текстовый файл <modID>Logger.txt (только на Windows) с замерами времени выполнения основных этапов автоинициализации,
• в случае критической ошибки вызывает свой Traceback через renpy.error(...).

Кастомизация

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

Имена файлов и папок

self.NAMES = {
    "IMAGES_FOLDER": "your_image_folder_name", # Имя папки с изображениями, по умолчанию "images"
    "SPRITES_FOLDER": "your_sprite_folder_name", # Имя папки со спрайтами, по умолчанию "sprites"
    "ASSETS": "your_rpy_asset_file_name", # Имя .rpy файла с объявлёнными файлами, по умолчанию "autoinit_assets"
    "LOGGER": "your_rpy_file_name" # Имя файла-логгера, по умолчанию "Logger"
}

Расширения файлов для объявления

self.EXTENSIONS = {
    "IMAGE": ('.png', '.jpg', '.jpeg', '.webp', '.gif'), # изображения
    "AUDIO": (".wav", ".mp2", ".mp3", ".ogg", ".opus"), # аудио
    "FONT": (".ttf", ".otf") # шрифты
}

Оттенки для спрайтов

self.SPRITE_TINTS = {
    "sunset": "TintMatrix(Color(hls=(0.94, 0.82, 1.0)))", # вечерний оттенок при persistent.sprite_time == "sunset"
    "night": "TintMatrix(Color(hls=(0.63, 0.78, 0.82)))" # ночной оттенок при persistent.sprite_time == "night"
}