Как использовать скрипты в Questsmith

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

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

Поддержка сценариев и видимость

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

Обзор интерфейса скриптов

Откройте раздел скриптов внизу вкладки Details при редактировании поддерживаемого сценария.

• Библиотека: Общие помощники и константы, доступные другим скриптам.
• Ввод: Выполняется в хуке жизненного цикла onInput.
• Контекст: Выполняется в хуке жизненного цикла onModelContext.
• Вывод: Выполняется в хуке жизненного цикла onOutput.

Для скриптов вне библиотеки последняя строка должна вызывать modifier(text).

Панель тестирования скрипта

• Ввод: Редактируемая тестовая нагрузка для моделирования поведения скрипта.
• Отправить: Отправляет скрипт + библиотеку + ввод на сервер для выполнения.
• Вывод: Показывает возвращенный текст, stop, журналы, state и storyCards.

Панель журналов консоли

• Показывает последние журналы из ваших собственных тестовых приключений, запущенных из этого сценария.
• Поток в реальном времени, удобно при разделенных вкладках (редактор + тест).
• Журналы хранятся 15 минут.

Хуки жизненного цикла

API скриптов предоставляет три хука, каждый работает в изолированной песочнице.

• onInput
• onModelContext
• onOutput

Ограничения выполнения: 16 MB памяти и таймаут 2 секунды на каждый хук.

Доступные параметры

Эти значения можно использовать напрямую в области видимости скрипта:

• text: Ввод игрока, текст контекста модели или текст вывода в зависимости от хука.
• history: Массив последних действий с полями text/rawText/type.
• storyCards: Массив карт приключения (старый псевдоним worldInfo по-прежнему поддерживается).
• state: Постоянный объект для пользовательской памяти скрипта между ходами.
• info: Служебные метаданные, например actionCount, characterNames, maxChars, memoryLength.

Заметки об объекте state

• Изменяйте state напрямую (без helper-функции).
• state.memory поддерживает переопределения context, authorsNote и frontMemory.
• state.placeholders хранит значения вопросов/ответов плейсхолдеров сценария и сохраняется между ходами.
• state.message может показываться игрокам в зависимости от поддержки клиента.

Доступные функции

• log
• addStoryCard
• removeStoryCard
• updateStoryCard

Контракт возврата

Обычно скрипты должны возвращать объект, например:

return { text: 'Новый текст' }
return { stop: true }

• text: Заменяет текстовый поток хука (ввод, контекст модели или вывод).
• stop: Останавливает продвижение цикла. Используйте осторожно и осознанно.

Важное поведение ошибок

• Возврат пустого текста в onInput вызывает ошибку скрипта у игрока.
• Возврат пустого текста в onModelContext ведет себя так, будто скрипт не запускался.
• Возврат пустого текста в onOutput вызывает пользовательскую ошибку скрипта у игрока.
• Возврат stop в onOutput не рекомендуется.

Минимальный пример входного скрипта

const modifier = (text) => {
  let modifiedText = text

  if (text.includes('схватить меч')) {
    state.items = ['sword']
    state.memory = { context: 'У тебя есть меч.' }
    state.message = 'Ты получил меч!'
    log('Игроку добавлен меч')
    modifiedText = text + '\nТеперь у тебя также есть меч!'
  }

  return { text: modifiedText }
}

modifier(text)

Практические варианты применения

• Парсеры команд (пользовательские команды игрока).
• Отслеживание инвентаря или статуса в state.
• Динамические корректировки memory, authorsNote и frontMemory.
• Постобработка контекста и защитные ограничения.
• Автоматическое добавление/удаление Story Cards по событиям.

Лучшие практики

1. Начинайте с небольших скриптов и тестируйте каждый хук отдельно.
2. Сохраняйте детерминированность скриптов и избегайте тяжелых вычислений.
3. Используйте Library для переиспользуемой логики и констант.
4. Защищайтесь от неопределенных полей (history, placeholders, значения info).
5. По возможности предпочитайте добавочные изменения полной переписи текста.
6. Используйте Console Log в живых тестах и воспроизводите проблемы минимальным примером.

Для проблем со скриптами или запросов функций используйте канал Discord bugs/feature-requests и, если возможно, добавляйте воспроизводимые шаги.