Best Practices

Лучшие практики создания качественных scenarios

Best Practices: Создание качественных сценариев

Проверенные паттерны и рекомендации для scenarios.

Структура scenario.yaml

Полная структура файла

# === МЕТАДАННЫЕ ===
id: unique-scenario-id
version: 1
type: branching-scenario  # или linear-scenario
title: "Название сценария"
description: "Краткое описание (1-2 предложения)"
topic: "область знаний"
time_minutes: 15
difficulty: 3  # 1-5
startNode: start

# === НАСТРОЙКИ ===
settings:
  allowBacktrack: false      # Можно ли вернуться назад
  showVariables: true        # Показывать переменные
  showHistory: true          # История выборов
  restartAllowed: true       # Кнопка "Начать сначала"
  saveProgress: true         # Сохранение прогресса

# === ПЕРЕМЕННЫЕ ===
variables:
  var_name:
    initial: 50
    min: 0
    max: 100
    label: "Название переменной"
    description: "Что она означает"

# === УЗЛЫ ===
nodes:
  - id: node1
    type: scene
    content: "..."
    choices: [...]

  - id: node2
    type: ending
    title: "..."
    content: "..."

Naming Conventions

ID узлов

Паттерны именования

Тип узла	Паттерн	Пример
Начало	`start`, `intro`, `awakening`	`awakening`
Сцена	`scene_`, `[topic]_scene`	`library_entrance`
Развилка	`choice_`, `decision_`	`choice_technology`
Checkpoint	`checkpoint_[topic]`	`checkpoint_week3`
Theory	`theory_[topic]`	`theory_loops`
Practice	`practice_[topic]`	`practice_redux`
Концовка	`ending_[type]`	`ending_success`

Variables Design

Правила для переменных

Типы переменных

1. Resource (Ресурс)

Что-то, что тратится и накапливается:

variables:
  money:
    initial: 1000
    min: 0
    max: 10000
    label: "Деньги"

  health:
    initial: 100
    min: 0
    max: 100
    label: "Здоровье"

Использование:

effects:
  money: -200    # Потратил
  health: -10    # Получил урон

2. Stat (Характеристика)

Качества, которые растут:

variables:
  wisdom:
    initial: 0
    min: 0
    max: 100
    label: "Финансовая мудрость"

  codeQuality:
    initial: 50
    min: 0
    max: 100
    label: "Качество кода"

Использование:

effects:
  wisdom: 15       # Стал мудрее
  codeQuality: 10  # Код улучшился

3. Relationship (Отношения)

Связи с персонажами или группами:

variables:
  family_bond:
    initial: 60
    min: 0
    max: 100
    label: "Связь с семьёй"

  reputation:
    initial: 50
    min: 0
    max: 100
    label: "Репутация"

4. Abstract (Абстрактное)

Философские или эмоциональные концепты:

variables:
  humanity:
    initial: 100
    min: 0
    max: 100
    label: "Человечность"

  inner_freedom:
    initial: 20
    min: 0
    max: 100
    label: "Внутренняя свобода"

Балансировка переменных

Правило 10-20-30:

Мелкие изменения: ±10
Средние изменения: ±20
Крупные изменения: ±30

choices:
  - text: "Небольшая трата (кофе)"
    effects:
      money: -10

  - text: "Средняя трата (обед)"
    effects:
      money: -20

  - text: "Крупная трата (наушники)"
    effects:
      money: -30

Content Writing

Длина контента

Тип узла	Рекомендуемая длина
Scene	50-150 слов
Theory	100-300 слов
Checkpoint	20-50 слов (сам вопрос)
Ending	150-300 слов

Стиль написания

1. Активный залог

# ✅ Хорошо
content: "Ты открываешь дверь и видишь..."

# ❌ Плохо
content: "Дверь была открыта тобой, и комната была увидена..."

2. Настоящее время

# ✅ Хорошо
content: "Грегор просыпается и понимает..."

# ❌ Плохо
content: "Грегор проснулся и понял..."

3. Эмоциональная вовлечённость

# ✅ Хорошо
content: |
  Твоё сердце бьётся быстрее. За дверью слышны шаги.
  **Что ты сделаешь?**

# ❌ Плохо
content: |
  Есть дверь. За ней кто-то. Нужно решить.

Форматирование Markdown

Используй Markdown для выразительности:

content: |
  **Понедельник, 1-е число**

  Мама даёт тебе 1000 рублей.

  "Вот твои карманные на месяц. Трать с умом!"

  *Целая тысяча!* На что бы её потратить...

  Впереди **4 недели**. Посмотрим, как ты справишься!

Элементы:

**жирный** — акценты
*курсив* — мысли, эмоции
"кавычки" — диалоги
Абзацы — разделение мыслей

Choices Design

Количество выборов

Качество выборов

1. Выборы должны быть значимыми

# ✅ Хорошо — выборы ведут к разным последствиям
choices:
  - text: "Купить наушники за 600₽"
    goto: bought_headphones
    effects:
      money: -600

  - text: "Не покупать — сэкономить деньги"
    goto: saved_money
    effects:
      wisdom: 10

# ❌ Плохо — выборы не влияют на сюжет
choices:
  - text: "Сказать 'Да'"
    goto: same_result

  - text: "Сказать 'Хорошо'"
    goto: same_result

2. Избегай ложных выборов

# ❌ Ложный выбор — все ведут к одному
choices:
  - text: "Вариант 1"
    goto: same_node
  - text: "Вариант 2"
    goto: same_node

# ✅ Правильно — хотя бы короткая развилка
choices:
  - text: "Вариант 1"
    goto: path_a
  - text: "Вариант 2"
    goto: path_b

# path_a и path_b могут потом сойтись, но дают разный опыт

3. Чёткие формулировки

# ✅ Хорошо — понятно, что выбираешь
choices:
  - text: "Спланировать бюджет на месяц"
  - text: "Сразу пойти в магазин"

# ❌ Плохо — неясно, к чему приведёт
choices:
  - text: "Вариант A"
  - text: "Сделать что-то"

Feedback для выборов

Давай мгновенную обратную связь:

choices:
  - text: "Отложить 100₽ в копилку"
    goto: week1_prepared
    effects:
      savings: 100
      money: -100
      wisdom: 10
    feedback: |
      **Правило 10%** — один из главных принципов финансовой грамотности.
      Даже небольшая подушка безопасности может очень выручить!

Testing Scenarios

Чеклист перед публикацией

Техники тестирования

1. Пройди все пути

Создай таблицу путей:

Путь	Описание	Концовка	Переменные
Путь 1	Всегда планирует, экономит	ending_success	money: 500, wisdom: 80
Путь 2	Импульсивные покупки	ending_broke	money: 0, wisdom: 20
Путь 3	Баланс	ending_neutral	money: 300, wisdom: 50

2. Проверь edge cases

Что если money = 0?
Что если все переменные максимальны?
Что если пользователь всегда выбирает первый вариант?

3. Проверь время прохождения

# Укажи реальное время
time_minutes: 15  # Не 5, если на самом деле 20!

Протестируй на реальных пользователях и измерь время.

Structure Patterns

Паттерн: Hub and Spokes (Хаб и спицы)

Центральный узел, от которого расходятся пути:

      spoke1
         |
  spoke2-HUB-spoke3
         |
      spoke4

Использование: Выбор специализации, направления обучения.

- id: hub
  content: "Выбери направление изучения"
  choices:
    - text: "Frontend"
      goto: frontend_path
    - text: "Backend"
      goto: backend_path
    - text: "DevOps"
      goto: devops_path

Паттерн: Funnel (Воронка)

Множество путей сходятся к одной точке:

A → \
B → MERGE → END
C → /

Использование: Разные подходы к одной проблеме.

# Разные пути решения
- id: approach_a
  goto: solution

- id: approach_b
  goto: solution

- id: approach_c
  goto: solution

# Общее решение
- id: solution
  content: "Независимо от подхода, ты пришёл к решению!"

Паттерн: Critical Path (Критический путь)

Один “правильный” путь, остальные — ошибки:

START → CHOICE
  ├─ Correct → Success
  ├─ Wrong1 → Fail
  └─ Wrong2 → Fail

Использование: Обучение процедурам, безопасности.

- id: emergency_choice
  content: "Человек без сознания. Что делать?"
  choices:
    - text: "Проверить дыхание"
      goto: correct_step_2
    - text: "Вызвать скорую"
      goto: wrong_order
    - text: "Начать массаж сердца"
      goto: wrong_no_check

Common Mistakes

1. Слишком много переменных

# ❌ Плохо — 10 переменных
variables:
  money: ...
  health: ...
  stamina: ...
  wisdom: ...
  charisma: ...
  intelligence: ...
  luck: ...
  karma: ...
  reputation: ...
  experience: ...

# ✅ Хорошо — 3-4 ключевые
variables:
  money: ...
  wisdom: ...
  health: ...

2. Слишком глубокое ветвление

# ❌ Плохо — 5 уровней вложенности
START → A → B → C → D → E → END

# ✅ Хорошо — 2-3 уровня с convergence
START → CHOICE → PATH → MERGE → END

3. Нет обратной связи

# ❌ Плохо — пользователь не понимает последствия
choices:
  - text: "Вариант A"
    goto: next
    effects:
      wisdom: -20

# ✅ Хорошо — объяснение
choices:
  - text: "Вариант A"
    goto: next
    effects:
      wisdom: -20
    feedback: |
      Импульсивное решение! В будущем подумай дважды.

4. Игнорирование условий

# ❌ Плохо — выбор доступен даже без денег
choices:
  - text: "Купить за 500₽"
    goto: buy_item

# ✅ Хорошо — условный выбор
choices:
  - text: "Купить за 500₽"
    goto: buy_item
    condition: "money >= 500"

  - text: "Не хватает денег..."
    goto: no_money
    condition: "money < 500"

Performance Tips

Оптимизация размера файла

Lazy Loading изображений

# ✅ Используй внешние URL
image: "https://source.unsplash.com/800x600/?library"

# Или относительные пути
image: "/images/scenarios/my-scenario/scene1.jpg"

# ❌ Не используй base64 embed
image: "data:image/png;base64,iVBORw0KG..."  # Слишком большой файл!

Accessibility

Текстовые альтернативы

Всегда добавляй описания к изображениям:

- id: scene_with_image
  type: scene
  image: "/images/library.jpg"
  content: |
    **Старая библиотека**

    Пыльные полки тянутся до потолка.
    Запах древних книг наполняет воздух.

Описание в content дублирует то, что на изображении.

Ясность выборов

# ✅ Хорошо — понятные последствия
choices:
  - text: "Потратить 100₽ на обед"
  - text: "Взять еду из дома (бесплатно)"

# ❌ Плохо — неясно
choices:
  - text: "Вариант 1"
  - text: "Вариант 2"

Проверка понимания

Следующие шаги

Примеры готовые сценарии целиком
Типы узлов вернись к типам узлов
Линейный или ветвящийся выбор типа сценария