Техническая документация AG VN Engine

Справочник функций ядра, синтаксиса скриптов и структуры проектов

1. Архитектура и структура директорий (PC)

PC-версия движка исполняется на Python 3 с использованием аппаратного ускорения OpenGL/DirectX и интеграцией 3D-модулей.

Root/
├── ave3d.py              # Исполняемый файл 3D-модуля и визуализации сцен
├── game.py               # Главная точка входа новеллы
├── engine/
│   ├── engine_config.ini # Конфигурация разрешения, звука и рендера
│   └── scripts/
│       ├── 3d_bridge.py  # Мост между 2D-сценами и 3D-пространством
│       ├── vn_func.py    # Базовые функции диалогов и сценария
│       ├── saves.py      # Система слотов сохранений и автосейвов
│       └── mods.py       # Загрузчик пользовательских модификаций
└── game/
    ├── content/          # Ассеты, CG и текстуры персонажей
    └── plot/
        ├── ru/           # Русскоязычные скрипты глав (.py)
        └── en/           # Англоязычные скрипты глав (.py)

2. Синтаксис диалогов и текста: dialog()

Базовая функция вывода реплики персонажа в текстовое окно:

# dialog(id_реплики, "Имя говорящего", "Текст реплики", цвет_имени, эффект_текста)
dialog(1, "Субару", "Куда подевались все остальные?", white, shake)
dialog(2, "Эмилия", "Мы здесь, не переживай.", white, none)
dialog(3, "", "В лесу раздался протяжный гул...", white, typewriter)

Параметры эффектов: none (стандартный вывод), shake (тряска окна диалога), typewriter (посимвольная печать).

3. Фоны и спрайты персонажей

Установка фона сцены и размещение спрайтов персонажей на экране:

# Установка фонового изображения
set_background(1, "bg_camp_night")

# Вывод спрайта: slot (1 - лево, 2 - центр, 3 - право), имя ассета
set_image(1, slot=2, name="emilia_smile")

# Плавная смена выражения лица
set_image(2, slot=2, name="emilia_surprised")

# Очистка слота
clear_image(3, slot=2)

4. Ветвления сюжета и переходы: go_to_plot()

Переход между файлами глав сюжета осуществляется функцией go_to_plot() с автоматическим подтягиванием текущего языка:

# go_to_plot(текущий_id, "имя_файла_сюжета", целевой_id)
# Загрузит 'game/plot/{current_lang}/chapter_two.py' и начнёт с шага 1:
go_to_plot(10, "chapter_two", 1)

# Вызов интерактивного меню выборов:
dialog_py(11, "if_choice_ui('Помочь Эмилии', 'Остаться на месте')", next=False)

5. Аудиосистема

Управление фоновой музыкой (BGM), звуковыми эффектами (SFX) и окружением:

play_music(1, "music/theme_sad.ogg", loop=True, fadein=1.5)
play_sound(2, "sounds/door_creak.wav")
stop_music(3, fadeout=2.0)

1. Архитектура и ограничения AG VN ENGINE Portable (PSP)

Портативная ветка движка собрана под кастомное окружение Python 2.x для PlayStation Portable с вызовами нативных C-библиотек psp2d, pspmp3, pspogg.

PSP_Game/
├── EBOOT.PBP             # Исполняемый бинарник PSP Homebrew
├── python.zip            # Минимизированный рантайм стандартной библиотеки
├── script.py             # Главный цикл инициализации экрана и фреймбуфера
├── sfont.py              # Быстрый битмап-рендер шрифтов для консоли
├── engine/
│   ├── fonts/            # Текстурные атласы шрифтов (font.png, font_big.png)
│   ├── ui/               # Текстуры диалоговых плашек
│   └── scripts/
│       ├── vn_func.py    # Парсер сценария и вызовы диалогов
│       ├── save_sys.py   # Сохранение на карту Memory Stick Duo (/PSP/SAVEDATA/)
│       └── audio.py      # Аппаратный плеер pspmp3/pspogg
└── game/
    ├── image/            # Фоны строго 480x272 и спрайты PNG с альфа-каналом
    └── plot/
        └── plot.py       # Основной сценарий новеллы

2. Память и медиа-требования под PSP

• Разрешение фонов: Строго 480x272 пикселей (нативное разрешение дисплея консоли). Изображения большего размера вызовут переполнение VRAM.
• Спрайты: Оптимизированные 8-bit / 24-bit PNG с прозрачностью. Не храните неиспользуемые спрайты в оперативной памяти.
• Аудио: Форматы OGG или MP3 с постоянным битрейтом 96–128 kbps, 44.1 kHz. Стерео или моно.

3. Скрипт сценария (plot.py на PSP)

Пример кода из игры Zomereid: How it Was Before:

# game/plot/plot.py
set_background(1, "game/image/background/bg_street.png")
play_music(1, "game/music/theme.ogg")

dialog(1, "Рейли", "Акитаро, как ты себя чувствуешь?", white)
dialog(2, "Акитаро", "Всё в порядке, просто немного шумит в ушах.", white)

# Выбор кнопками D-Pad консоли:
choice(3, [
    ("Пойти в класс", 4),
    ("Остаться во дворе", 8)
])

4. Система сохранений на Memory Stick Duo

Сохранения пишутся в стандартную структуру данных PSP, совместимую со встроенным системным меню консоли:

# Вызов экрана быстрого сохранения по кнопке SELECT/START
from engine.scripts.save_sys import save_game, load_game

save_game(slot=1)
load_game(slot=1)