easy.dialog v.3.0.0

Работа с интерпретатором

Подключение интерпретатора

Чтобы использовать интерпретатор диалогов "easy.dialog", вам необходимо подключить его к своей игре вместе с сопутствующими библиотеками.

Если вы скачали архив со страницы релизов, то в папку со своей игрой из этого архива распакуйте папку lib. Jна и содержит модуль "easy.dialog", а так же библиотечки "easy.database" и "easy.math".

Теперь в своей игре для подключения модулей напишите эти три команды:

Внимание!!! При подключении библиотек учтите, что к игре добавляются только те локации, названия которых в них отсутствуют. Просмотрите список локаций в подключаемых библиотеках, чтобы предупредить совпадения имён.

Добавление таблицы диалогов в игру

В процессе работы генератор создаёт файл формата qsps, который содержит три локации:

• dialogs_table — на этой локации размещается вся таблица диалогов, включая все объекты диалогов, ролей и реплик. Эта локация предназначена для загрузки в память таблицы диалогов. В зависимости от настроек генератора строки таблицы на этой локации могут быть сгруппированы в блоки условий с проверкой, какое число передано нулевым аргументом (args[0]). Это число соответствует номеру группы строк. Если строки разбиты на группы, загрузить всю таблицу диалогов в память, просто обратившись к локации dialogs_table не получится.
• dialogs_init — эта локация необходима для инициализации таблицы диалогов в базе данных игры. То есть она проводит необходимую подготовку, чтобы модуль мог работать с диалогами.
• dialogs_load — с помощью этой локации вы можете одномоментно загрузить в память всю таблицу диалогов. Использовать её следует только если диалогов немного, или они небольшие.

Все три локации вам нужно скопировать в свою игру, или сконвертировать файл .qsps в .qsp и подключить как библиотеку.

Когда в игру подключены, или встроены все три локации, нужно сделать следующее:

1. Необходимо инициализировать базу данных в игре, введя, например, на самой первой локации команду @edb.init. Если вы уже пользуетесь "easy.database" в своей игре, значит вы уже это сделали.
2. Далее нужно инициализировать в базе данных таблицу диалогов, введя команду @dialogs_init.
3. Затем таблицу диалогов нужно загрузить в память. Для этого можно воспользоваться командой @dialogs_load, или последовательно обращаясь к dialogs_table, передавая ей аргументом номер выгружаемой группы строк.

Вот как это выглядит в игре с примерами диалогов, котороя поставляется вместе с модулем:

Воспроизведение диалога

Для воспроизведения диалога в нужном месте следует вызвать команду @dialog.int, указав аргументом уникальное название диалога, которое вы прописывали ему в файлах edsynt перед генерацией.

Пример вызова диалога из гиперссылки:

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

Встраивание диалога в Основное описание

В отличие от первой версии модуля, текущая версия работает только с окном основного описания. То есть она не "запоминает" и не "восстанавливает" содержимое прочих окон.

Чтобы диалог не замещал собой весь текст в окне основного описания, а встраивался в него, необходимо перед воспроизведением диалога вывести в основное описание два специальных тега:

Обратите внимание, что классы прописаны для обоих тегов: и открывающего и зыкрывающего. Это сделано специально, чтобы не перегружать QSP при поиске тегов в тексте. Любой HTML-рендер исправит неверно записанный закрывающий тег самостоятельно.

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

Если нужно скрыть какой-то текст на время интерпретации диалога, но не выводить вместо него диалог, используйте другие специальные теги:

Например, таким образом можно скрывать ссылки на вызов диалога из основного описания.

Пример описания, в которое встраивается диалог, можно посмотреть в игре с примерами диалогов на локации место;банк в "диалоге Чешира".

Составные части интерпретатора диалогов

Теоретически интерпретатор должен работать без вашего вмешательства в его поведение, однако иногда вмешательство необходимо. Например, в "диалоге Арагорна" через уничтожение массива $DIALOG_BUTTONS производится очистка списка кнопок перед закрытием диалога, чтобы игрок не мог ничего нажимать.

На подобный случай здесь и собраны пояснения различных элементов интерпретатора диалогов.

Общее назначение глобальных временных массивов

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

• $DIALOG_VALUE — основной массив, сохраняющий различные настройки диалога на время сеанса.
• $DIALOG_REPLIC_LOG — массив, сохраняющий лог диалога на время сеанса.
• $DIALOG_BUTTONS — массив, сохраняющий список кнопок во время сеанса.

Управление через внешние глобальные переменные

Эти переменные сохраняют своё значение даже когда диалог закрыт, поэтому они влияют на поведение всех диалогов в игре.

Будьте внимательны!

• GAME_VALUE['dialogs_log_size'] - число реплик, которые сохраняются в логе. Если не указано, то сохраняется сто реплик, включая скрытые.
• GAME_VALUE['dialogs_timer_interval'] - интервал задержки перед выводом следующей фразы из блока фраз. Если не указано равен 500 мс.
• $GAME_VALUE['dialogs_true_goto'] — должен содержать код, который выполнится при закрытии диалога (перед удалением временных массивов). Если код не прописан, при закрытии диалога просто очищается окно основного описания и восстанавливается тот текст, который был сохранён перед открытием диалога.
Здесь может пригодиться команда goto $curloc, так как в процессе воспроизведения диалога значения некоторых переменных могут измениться, и это повлияет на описание локации.

Значения DIALOG_VALUE

Значения в DIALOG_VALUE сохраняются только на время воспроизведения диалога.

• $DIALOG_VALUE['screen_main'] — в этой переменной сохраняется вид окна основного описания до воспроизведения диалога. Из него же потом восстанавливается текст в окне основного описания, когда диалог завершается.
• $DIALOG_VALUE['screen_now'] — в этой переменной содержится "снимок" экрана вместе с размещённым в нём диалогом. Данный снимок обновляется при интерпретации реплики, и только после этого выводится на экран.
• $DIALOG_VALUE['dialog_id'] — здесь временно сохраняется первичный ключ строки, в которую прописан объект Диалог.
• $DIALOG_VALUE['root_id'] — первичный ключ корневой реплики.
• DIALOG_VALUE['default_screen_replics_number'] — число фраз, одновременно видимых на экране. По умолчанию — 10.
• $DIALOG_VALUE['default_replics_repeat'] — схема повторения реплик. Стандартный режим: 'cicle'.
• $DIALOG_VALUE['default_replics_shuffle'] — порядок вывода реплик. Стандартный режим: 'straight'.
• DIALOG_VALUE['default_buttons_length'] — Максимальная длина текста в кнопке. Стандартное значение 128.
• DIALOG_VALUE['timer_start'] — переключатель, запускающий таймер, когда необходимо выводить фразы из блока.
• DIALOG_VALUE['timer_next_refresh'] — в этой переменной сохраняется предельное пороговое время, после которого должна быть выведена фраза из блока фраз. Изменять не рекомендуется.
• $DIALOG_VALUE['del_btns_list'] — список удалённых с экрана кнопок. Пока идентификатор реплики присутствует в этом списке, кнопка этой реплики не будет выводиться на экран. Переменная очищается при воспроизведении пассивной реплики.
• $DIALOG_VALUE['del_replics_list'] — список реплик, удалённых из текущего воспроизведения диалога. Пока идентификатор реплики присутствует в этом списке, эта реплика не будет воспроизводиться. Тем не менее реплики удалённые таким образом доступны для воспроизведения, если использовать их метку.
• $DIALOG_VALUE['fix_btns_list'] — список зафиксированных реплик.

Назначение локаций модуля:

Назначение локаций можно посмотреть в исходном коде модуля в репозитории: https://github.com/AleksVersus/easy.dialog.

Отладчик

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

Подключение отладчика

Чтобы задействовать в своей игре встроенный в "easy.dialog" отладчик, пропишите в нужном месте, например, на самой первой локации, команду:

Соответственно для отключения отладчика достаточно выполнить команду:

Использование отладчика

Чтобы воспользоваться отладчиком, введите в строке ввода ключевое слово eid и соответствующую команду отладчика, а затем нажмите клавишу ввода ("Enter ↵").

Команды отладчика

Все команды отладчика должны начинаться с ключевого слова eid. Ниже представлен список команд без указания этого слова.

• help — вывод справки по отладчику.
• run - выполнить следующий после run текст, как строку кода QSP. Пример:
eid run *pl 'Яблок в корзине <<apples>>'
При выполнении данной команды на экране появится строчка текста, с подставленным в неё значением переменной.
• version - проверить текущую версию модуля. Версия модуля возвращается в текстовом формате.
• clr - очистить окно дополнительного описания.
• print — вывести в дополнительное описание всю таблицу диалогов. При больших размерах таблицы это может занять время или подвесить игру.
• refs - вывести в окно дополнительного описание таблицу с короткими именами диалогов.
• log - вывести в окно дополнительного описание сохранённый лог реплик (содержимое $DIALOG_REPLIC_LOG).
• html - включить/отключить распознавание HTML в плеере.
• INDEX_DIALOG_VALUE= — если ввести текстовый индекс, а затем поставить знак равенства, в окно дополнительного описания будет выведено значение из массива DIALOG_VALUE под указанным индексом. Используемые модулем ячейки перечисленны в разделе Значения DIALOG_VALUE.

  Пример. С помощью следующей команды, введённой в строку ввода, можно получить в окне дополнительного описания первичный ключ корневой реплики:

  eid root_id=