TUI Novel Engine

TUI Novel Engine — минималистичный движок для создания текстовых визуальных новелл, работающий в терминале (TUI). Он позволяет разрабатывать интерактивные истории с использованием YAML-файлов для описания сцен, поддерживает сохранения, анимации и гибкую конфигурацию в форматах JSON или YAML.

Основные возможности

• Текстовый интерфейс (TUI): Игра запускается прямо в терминале с эффектом печати текста.
• YAML-сцены: Простое описание сюжета и выборов в YAML-файлах.
• Сохранения: Поддержка сохранений в форматах Pickle и JSON.
• Анимации: Встроенные терминальные анимации (спиннер, точки, прогресс-бар).
• Конфигурация: Настройки игры в JSON или YAML, включая путь к сохранениям и задержку текста.
• Условия и действия: Гибкая система условий для выбора и действий в сценах (например, добавление монет, установка флагов).
• Интерактивные настройки: Изменение параметров игры (формат конфига, задержка текста) во время игры.

---

Требования

• Python 3.6+
• Библиотека pyyaml для работы с YAML-файлами:

  pip install pyyaml

• (Опционально) simpleaudio для звуковых эффектов:

  pip install simpleaudio

---

Установка

1. Склонируйте репозиторий или скачайте проект:

   git clone https://github.com/deadboizxc/tui_novel.git
   cd tui_novel

2. Установите зависимости:

   pip install pyyaml

3. (Опционально) Для звуковых эффектов установите simpleaudio:

   pip install simpleaudio

---

Структура проекта

tui_novel/
├── engine/                 # Основной код движка
│   ├── __init__.py
│   ├── actions.py         # Обработка действий в сценах
│   ├── animations.py      # Терминальные анимации
│   ├── conditions.py      # Проверка условий для выборов
│   ├── config.py          # Управление конфигурацией
│   ├── main.py            # Главный игровой цикл
│   ├── state.py           # Управление состоянием игры
│   ├── story_loader.py    # Загрузка YAML-сцен
│   └── ui.py              # Интерфейс и взаимодействие
├── story/                 # Папка с YAML-файлами историй
│   └── intro.yaml         # Пример истории
├── saves/                 # Папка для сохранений
│   └── save1.dat          # Пример файла сохранения
├── config.json            # Файл конфигурации (или config.yaml)
└── run.py                 # Точка входа

---

Запуск

1. Убедитесь, что вы находитесь в корневой папке проекта (tui_novel/).

2. Запустите игру:

   python run.py

   Или, если проект используется как модуль:

   python -m tui_novel.engine.main

3. При запуске, если существуют сохранения, вам будет предложено загрузить одно из них.

---

Формат историй (story/*.yaml)

Истории описываются в YAML-файлах в папке story/. Имя файла становится префиксом для сцен, а ключи внутри файла — именами сцен. Полное имя сцены формируется как prefix.scene.

Пример story/intro.yaml

start:
  text: "Вы просыпаетесь в странном месте..."
  actions:
    - animate:
        type: "dots"
        text: "Загрузка мира"
        duration: 2
  choices:
    - text: "Оглядеться"
      next: "look"
    - text: "Продолжить спать"
      next: "sleep"
look:
  text: "Вы видите старый дом вдали."
  choices:
    - text: "Идти к дому"
      next: "house"
      conditions:
        - coins: 50
    - text: "Вернуться назад"
      next: "start"

Поля сцены

• text: Текст, отображаемый в сцене.
• actions: Список действий (например, добавление монет, анимации).
• choices: Варианты выбора с указанием следующей сцены (next) и условий (conditions).
• conditions: Условия для отображения сцены или выбора (например, наличие монет или флагов).

---

Модули движка

main.py

• Основной игровой цикл.
• Загружает историю, инициализирует состояние игры (GameState).
• Управляет переходами между сценами и обрабатывает ввод пользователя.
• Поддерживает команды:
  • [s]: Открыть настройки.
  • [v]: Сохранить игру.
  • [l]: Загрузить игру.
  • [q]: Выйти (с возможностью сохранения).

state.py

• Класс GameState хранит:
  • current: Текущая сцена.
  • history: История посещённых сцен.
  • flags: Булевы флаги (например, met_npc).
  • stats: Счётчики (например, coins).
• Поддерживает сохранение и загрузку в форматах Pickle или JSON.

config.py

• Управляет настройками игры, хранящимися в config.json или config.yaml.
• Пример конфигурации:

  {
    "save_format": "pickle",
    "config_format": "json",
    "save_dir": "saves",
    "type_delay": 0.1
  }

• Функции: load_config(), save_config().

actions.py

• Обрабатывает действия в сценах:
  • add_coin: Добавляет монеты.
  • set_flag: Устанавливает флаг.
  • animate: Запускает анимацию.
  • jump: Переход к другой сцене.
  • set_save_format, set_config_format, set_save_dir: Изменение настроек.

animations.py

• Реализует три типа анимаций:
  • spinner: Крутящийся символ (/|-\).
  • dots: Точки (., .., ...).
  • bar: Прогресс-бар.
• Пример вызова анимации:

  actions:
    - animate:
        type: "bar"
        text: "Загрузка"
        duration: 4

conditions.py

• Проверяет условия для отображения выборов или сцен (например, наличие монет или флагов).

story_loader.py

• Загружает все YAML-файлы из папки story/ и формирует словарь сцен с ключами вида prefix.scene.

ui.py

• Реализует интерфейс:
  • type_text(): Вывод текста с эффектом печати.
  • prompt_choice(): Меню выбора.
  • prompt_save()/prompt_load(): Управление сохранениями.
  • prompt_settings(): Интерактивные настройки (папка сохранений, формат, задержка текста).

---

Сохранения

• Сохранения хранятся в папке, указанной в конфигурации (по умолчанию saves/).
• Поддерживаемые форматы: Pickle (.dat) и JSON (.json).
• Меню сохранения/загрузки позволяет:
  • Создать новое сохранение.
  • Перезаписать существующее.
  • Загрузить сохранение.

---

Анимации

Анимации добавляют визуальный эффект в терминале. Пример вызова в сцене:

actions:
  - animate:
      type: "spinner"
      text: "Подключение"
      duration: 2

Поддерживаемые типы:

• spinner: Крутящийся символ.
• dots: Последовательность точек.
• bar: Прогресс-бар.

---

Звуковые эффекты (опционально)

Для эффекта печатной машинки:

1. Установите simpleaudio:

   pip install simpleaudio

2. Добавьте в ui.py код для проигрывания звука (см. исходный README).
3. Поместите файл type.wav в папку assets/sfx/.

---

Пример игры

Создайте файл story/example.yaml:

start:
  text: "Вы стоите перед таинственным лесом."
  actions:
    - animate:
        type: "dots"
        text: "Осматриваюсь"
        duration: 2
    - add_coin: 10
  choices:
    - text: "Войти в лес"
      next: "forest"
    - text: "Обойти лес"
      next: "bypass"
forest:
  text: "Темнота леса поглощает вас..."
  choices:
    - text: "Идти дальше"
      next: "deeper"
      conditions:
        - coins: 5
    - text: "Вернуться"
      next: "start"

Запустите игру:

python -m engine.main

---

Настройки

В меню настроек ([s]) можно изменить:

• Папку сохранений (save_dir).
• Формат сохранений (json или pickle).
• Формат конфигурации (json или yaml).
• Задержку печати текста (type_delay).

---

Планы на будущее

• Добавить звуковую систему (эффекты печати, фоновая музыка).
• Поддержка ASCII-изображений для сцен.
• Автоматический выбор языка интерфейса.
• Импорт сохранений между версиями игры.
• Расширенные условия и действия (например, сложные вычисления).
• Поддержка скриптов для динамических сцен.

---

Разработка и эксперименты

TUI Novel Engine создан для:

• Обучения созданию текстовых игр.
• Быстрого прототипирования интерактивных историй.
• Экспериментов с TUI и YAML-форматом.

Если вы хотите внести вклад, начните с создания новых YAML-историй или расширения функционала движка.

---

Лицензия

MIT License.

---

Контакты

Создано для обучения и экспериментов. Если у вас есть вопросы или предложения, создайте issue в репозитории или свяжитесь с автором.

---