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

Содержимое тега — рассматриваемый текст, место вхождения которого обозначено тегами или тегом. Может использоваться понятие "значение тега". Числовое значение здесь условно обозначается [#значение], а текстовое - [$значение]. Вместо слова "значение" может употребляться "число", "текст", "шестнадцатеричное число", и другие слова и словосочетания. Если содержимое тега принимает конечное число значений, это будет показано перечислением этих значений через вертикальную черту в квадратных скобках [одно значение|второе значение|третье значение].

Команда — слово или группа слов, которые провоцируют выполнение определённых операций или действий, запуск механизмов.

Конструкция — текст, записанный по определённым правилам.

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

Герой — персонаж, которым непосредственно управляет игрок.

Актёр — персонаж, которым игрок не может управлять непосредственно.

Текст реплики — фраза героя или актёра, которая будет выведена на экран после обработки реплики. Текст реплики (иногда называется просто "фраза") - единственное содержимое реплики, которое не нужно облекать в специальные конструкции, или помещать между тегами.

Интерпретация реплики — процесс извлечения всех конструкций и текста реплики из реплики, а так же выполнение конструкций и команд, воспроизведение фразы в виде текста, выводимого на экран. За интерпретацию реплики отвечает процедура dialog.replic.int.

Пустая реплика — реплика, в которой отсутствует фраза.

Узел — реплика, в которую вложена другая реплика.

Родительская реплика — так называется узел по отношению к реплике, которая в него вложена. Реплика "F" - родительская реплика реплики "A". Ещё называется родителем. Всякий узел является родителем вложенной в него реплики.

Дочерняя реплика — так называется реплика по отношению к реплике, в которую она вложена. Реплика "A" - дочерняя реплика реплики "F". Всякая реплика, вложенная в узел, является дочерней.

Корень — текст, помещённый вне тегов реплик. Может называться также корневой репликой, нулевой репликой, начальной репликой или заголовком диалога.

Дефолтное значение — значение тега, которое было указано в заголовке диалога, либо значение по умолчанию.

Значение по умолчанию — значение, которое будет возвращено механизмом модуля easy.dialog, если не указано, или ошибочно указано другое значение. Значения по умолчанию встроены в движок.

Уровень — счёт вложений реплик, степень вложения реплики. Если реплика вложена в корень - первый уровень. Если реплика вложена в реплику, вложенную в корень, - второй уровень. И так далее. Верхним уровнем при этом считается корень.

Ответвления — одноуровненвые реплики, вложенные в один и тот же узел.

Ветка — ответвление вместе со всеми вложенными в него репликами.

Финал — реплика, в которую не вложено ни одной другой реплики. Называется так же финальной репликой, конечной репликой, или последней репликой.

Тело диалога — текст, содержащий хотя бы одну реплику помимо корня.

Теги, конструкции, команды

{:[$текст]:} — теги, между которыми записываются реплики неиграбельных персонажей (далее: актёры, неписи, NPC, персонажи). Текст реплики выводится на экран автоматически. Теги реплики актёра.

[:[$текст]:] — теги, между которыми записываются реплики персонажа, которым управляет игрок (далее - герой). Выводятся на экран в виде доступных игроку действий. При выборе действия, на экран выводится текст реплики. Теги реплики героя.

npc="[$настройки]" — конструкция, в которую помещаются настройки вывода фраз актёра.

hero="[$настройки]" — конструкция, в которую помещаются настройки форматирования и формирования фраз героя.

Настройки формирования и форматирования фраз актёров и героя:

name:[$значение]:name — двойной тег установки имени актёра или героя (в зависимости от того, в какую конструкцию помещено). Если указать пустое значение (между двоеточиями нет ничего), имя не будет выводиться. Если не указывать, будет выводиться имя, указанное в родительской реплике, либо дефолтное имя. Значением может быть любое сочетание пробельных и непробельных символов. Не рекомендуется использовать символ перевода строки.

ncolor:[$значение] — одиночный тег настройки цвета имени актёра или героя (в зависимости от того, в какую конструкцию помещено). Значением может выступать запись из шести шестнадцатеричных цифр. Формат цвета как в html: rrggbb. Если не указывать, или оставить значение пустым, будет выводиться значение родительской реплики, или дефолтное.

fcolor:[$значение] — одиночный тег настройки цвета непосредственно фразы актёра или героя (в зависимости от того, в какую конструкцию помещено). Значением может выступать запись из шести шестнадцатеричных цифр. Формат цвета как в html: rrggbb. Если не указывать, или оставить значение пустым, будет выводиться значение родительской реплики, или дефолтное.

nattrib:[$значение] — одиночный тег настройки стиля начертания шрифта имени актёра или героя (в зависимости от того, в какую конструкцию помещено). Значением выступают команды аттрибутов, в любом количестве. Если не указывать, или оставить значение пустым, будет выводиться значение родительской реплики, или дефолтное.

fattrib:[$значение] — одиночный тег настройки стиля начертания шрифта фразы актёра или героя (в зависимости от того, в какую конструкцию помещено. Значением выступают команды аттрибутов, в любом количестве. Если не указывать, или оставить значение пустым, будет выводиться значение родительской реплики, или дефолтное.):

-b — команда аттрибута, применяющая жирность к тексту.
-i — команда аттрибута, применяющая курсив к тексту.
-n — команда аттрибута, отменяющая жирность и курсив.

Аттрибуты считываются в обратном порядке, начиная с последнего, таким образом происходит и применение. Допустим, мы не хотим, чтобы имя героя отображалось курсивом, но продолжало отображаться жирным шрифтом. Пишем "natrib:-b-n". Сначала шрифт вернётся к нормальному виду, потом будет применена жирность. Если указать "natrib:-n-b", то сначала будет применена жирность, а потом шрифт вернётся к нормальному виду.

tire:[$значение] — одиночный тег, значение которого определяет символ, выводимый перед фразой (знак мыслеотделительный, знак перед прямой речью). Если не указано, выводится значение родительской реплики, или дефолтное. Если тег и его значение отделяются от остального текста пробелами, можно указывать только непробельные символы. Чтобы использовать пробельные символы в качестве знака перед прямой речью, следует поместить тег и его значение в круглые скобки:
(tire:[$значение])

Чтобы перед прямой речью не ставилось никаких знаков, следует использовать команду nope:
tire:nope

replics="[$настройки]" — конструкция, в которую помещаются настройки выбора, обработки и вывода реплик.

Настройки выбора, обработки и вывода реплик актёров и героя:

repeat:[one|once|cicle] — одиночный тег, значение которого определяет настройки повтора фраз актёра из ответвлений. Можно использовать три команды:

one — всё время диалога будет выводиться фраза только одного из ответвлений.
once — всякий раз будет выводиться фраза из ответвления, фраза которого ещё не выводилась. Когда такие ответвления закончатся, будет выводиться фраза ответвления, фраза из которого выводилась последний раз.
cicle — всякий раз будет выводиться фраза из следующего ответвления. Когда закончатся ответвления, фразы из которых ещё не выводились, выбор следующего ответвления пойдёт с начала.

repeat:[random|straight] — одиночный тег, значение которого определяет настройки выбора следующего ответвления для реплик актёра. Можно использовать две команды:

random — случайный выбор ответвления.
straight — выбор следующего ответвления в порядке очереди, в которой они записаны в теле диалога.

iffing:[$условия]:iffing — сдвоенный тег, значение которого используется в качестве условия вывода реплики.

act-name:[$текст]:act-name — сдвоенный тег, значение которого используется в качестве названия действия при интерпретации реплики героя.

frase-block:[$текст]:frase-block — конструкция вывода блока последовательных фраз. Между тегами размещается набор строк, каждая из которых считается отдельной фразой. При этом если в начале фразы выставлен тег <npc-name>, к ней применяются настройки фразы актёра, если же в начале фразы выставлен тег <hero-name>, к ней применяются настройки фразы героя.

dynamic-code:[$текст]:dynamic-code — между этими тегами помещается обычный код QSP, который будет выполнен во время интерпретации реплики.

levelup:[#число] — команда в виде одиночного тега, которая "возвращает" интерпретатор на несколько уровней вверх по узлам.

leveljump:[$метка] — команда в виде одиночного тега, которая отправляет интерпретатор к реплике, содержащей указанную метку. Метка указывается в значении тега.

marker:[$метка] — одиночный тег, значение которого считается меткой реплики.

closeup — команда, наличие которой в интерпретируемой реплике приведёт к закрытию диалога.

selectact.delete — команда, наличие которой в интерпретируемой реплике приведёт к удалению текущего действия из списка без обновления списка.

 — открывающий и закрывающий теги комментария. В комментарии можно помещать всё, кроме фраз актёров и героя и других комментариев. Комментарии можно размещать в любом месте диалога, но не между тегами dynamic-code: :dynamic-code и iffing: :iffing. При наличии внутри комментариев описанных выше тегов и комманд, следует отделять их от тегов комментария хотя бы одним пробелом. Текст комментариев не выводится на экран.

Планируемые решения

bwaiting:[#миллисекунды] — настройка задержки вывода на экран фраз из блока фраз. В настоящий момент задержка существует, но не настраивается из-под диалога. Предшествует каждой отдельной фразе в т.ч. и без указания тегов <npc-name> и <hero-name>.

bwaiting:[#миллисекунды] — настройка задержки вывода на экран текста реплики.

selectreplic.delete — команда удаления реплики из диалога. Реплика удаляется из текущего диалога. Если закрыть и вновь открыть диалог, реплика вновь появится в ветке.

selectreplic.kill — команда удаления реплики из диалога. Реплика удаляется из диалога насовсем. То есть если закрыть диалог, а потом вновь открыть, реплика не появится в ветке.

act-close="[$настройки]" — конструкция, в которую помещаются настройки стандартного действия закрытия диалога. Стандартное действие - это действие, которое будет появляться в списке действий постоянно.

act-up="[$настройки]" — конструкция, в которую помещаются настройки стандартного действия, возвращающего на несколько узлов вверх. В частности такое действие должно возвращать к последнему узлу, где обновлялся список действий.

Возможно будет введена конструкция описания стандартных действий/реплик героя, которые должны повторяться на протяжении всей ветки диалога. act-standart="[$настройки]" - вместо настроек перечисляются метки стандартных реплик. Сами реплики располагаются в скрытой ветке.

Конструирование диалога

Конструирование реплик

Каждая реплика, за исключением корневой, должна быть помещена в теги реплики:

Реплики могут включать в себя следующие элементы:

При этом, всё, кроме текста реплики и комментариев, можно помещать внутри комментариев. Можно и не помещать.

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

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

Комментирование

Для того, чтобы писать комментарии в теле диалога и в его заголовке, была введена конструкция комментариев из html. Комментарии представляют собой запись между открывающим тегом "". Эти теги так и называются: теги комментария. Название "тег комментария", если не уточняется открывающий или закрывающий, означает тоже самое.

Комментарии могут быть как однострочными, так и многострочными.

Отделять содержимое комментария от его тегов следует хотя бы одним пробельным символом или переводом строки.

Нельзя размещать комментарии внтури комментариев. Запись

 текст комментария -->

недопустима.

Недопустимо также использовать комментарии между тегами dynamic-code: :dynamic-code и iffing: :iffing, поскольку между ними помещается чистый код QSP.

В тегах act-name: :act-name, в конструкциях блоков фраз, а также в самих фразах комментарии допустимы, поскольку игнорируются html-рендерером QSP-плеера как нормальные html-комментарии.

Все команды и конструкции реплики, кроме фразы, допустимо и желательно помещать в комментарии. Лучше всего - в один. В таких комментариях будет игнорироваться весь текст, помимо текста самих конструкций и настроек.

Внутри конструкций настроек (npc="[$настройки]", hero="[$настройки]", replics="[$настройки]") допустимо произвольное комментирование без использования тегов комментария. Весь текст, помимо тегов настроек и их значений, будет проигнорирован механизмом извлечения настроек. Необходимо лишь отделять значение тегов от произвольного текста хотя бы одним пробелом, символом перевода строки или табуляции.

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

Конструирование настроек

В настоящей версии модуля для настроек предусмотрены три конструкции. Конструкции npc="[$настройки]" и hero="[$настройки]" сходны по своему содержанию и используют одинаковые команды и теги. Конструкция replics="[$настройки]" предполагает другой набор команд и тегов. Однако правила записи всех треёх конструкций одинаковы.

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

npc='[$настройки]'
hero='[$настройки]'
replics='[$настройки]'

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

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

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

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

Если в тексте настроек не указан какой-либо из тегов, его значением будет считаться значение, полученное от родительской реплики или дефолтное значение. Если это заголовок диалога, значением тега будет принято значение по умолчанию.

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

Теги и их значения

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

Игнорируются все переводы строк и пробельные символы непосредственно после открывающего тега и непосредственно перед закрывающим для:

Все переводы строк и пробельные символы сохраняются при получении и обработке значений для:

Это связано всего лишь с методами распознавания содержимого.

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

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

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

Таким образом в одиночные теги можно помещать только непробельные символы.

Однако, если одиночный тег и его содержимое заключены в скобки, причём между открывающей скобкой и тегом нет пробелов и переводов строки, в значении тега можно использовать и пробелы и переводы строки.

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

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

Составление диалогов

Диалоги составляются из реплик актёров и/или героя.

Для чередования реплик - одни реплики вкладываются в другие. Сначала интерпретируется родительская реплика, а потом - все реплики-ответвления, являющиеся её дочерними репликами. При этом реплики актёра интерпретируются полностью, и фразы выводятся автоматически, а реплики героя интерпретируются частично и выводятся в виде действий. Когда игрок выбирает действие, реплика, на которой основано это действие, интерпретируется полностью.

Реплики, которые не содержат фразы, не выводятся на экран, однако их содержимое интерпретируется, как и содержимое реплик, которые содержат фразы.

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

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

Как отмечено выше, если не указана фраза реплики, реплика интерпретируется, но на экран ничего не выводится. Эта особенность позволяет создавать скрытые ветки. Для этого ветка размещается в пустой реплике героя. Пустые реплики героя не выводятся в виде действий.

Чтобы пустая реплика героя всё же выводилась на экран в виде действия, название действия следует поместить между тегами act-name: :act-name.

Все фразы выводятся на экран с сохранением перевода строк. Следует учитывать это при организации диалога.

Значения по умолчанию

Значения по умолчанию - это различные значения переменных настроек оформления и прочего, принимаемые тогда, когда явно заданные значения отсутствуют или ошибочны. Значения по умолчанию вшиты в механизм получения настроек.

Ниже перечислены настройки и значения по умолчанию.

Имя
Указывается между тегами name: :name
по умолчанию, и для актёра и для героя: пустое значение, отсутствует, name::name.

Цвет имени
Указывается после тега ncolor:
по умолчанию, для актёра: чёрный, ncolor:000000
по умолчанию, для героя: серый, ncolor:888888.

Аттрибуты имени
Указывается после тега nattrib:
по умолчанию, для актёра: жирный, nattrib:-b
по умолчанию, для героя: жирный курсив, nattrib:-b-i.

Цвет фразы
Указывается после тега fcolor:
по умолчанию, для актёра: чёрный, fcolor:000000
по умолчанию, для героя: серый, fcolor:888888.

Аттрибуты фразы
Указывается после тега fattrib:
по умолчанию, для актёра: нормальный, fattrib:
по умолчанию, для героя: курсив, fattrib:-i.

Знак мыслеотделительный. Знак перед прямой речью
Указывается после тега tire:
по умолчанию, для актёра и героя: тире отбитое пробелами, tire: — .

Режим повтора ответвлений
Указывается после тега repeat:
по умолчанию (только для актёрских реплик): по-кругу, непрерывное, repeat:cicle.

Режим выбора следующего ответвления
Указывается после тега shuffle:
по умолчанию (только для актёрских реплик): случайным образом, shuffle:random.

Подключение и использование

Файл модуля easy.dialog.qsp поставляется вместе с файлом библиотеки easy.math.qsp и работает только при наличии оного. Для использования модуля и библиотеки, оба файла подключаются к основному файлу игры:

(в архиве оба файла помещены в папку "lib". При подключении к игре вместо "lib/" следует использовать настоящий относительный путь до файлов модуля и библиотеки.)

Желательно включение режима распознавания html-тегов (usehtml = 1).

Диалоги для модуля пишутся в виде текстовых констант, или значений текстовых переменных. После чего константа или значение переменной передаются в качестве нулевого аргумента локации dialog.int. Вызывать локацию следует через команду gosub:

При вызове dialog.int будет очищено основное описание, список действий и дополнительное описание. После того как диалог будет закрыт, и описания и список действий восстановятся.

При интерпретации реплики игнорируется преформатирование (символы пробелов и табуляций перед строками; строки не содержащие непробельных символов до первыой строки, содержащей непробельные символы, и после последней строки, содержащей непробельные символы).

easy.dialog.qsp v 1.0

Краткое описание

Термины и понятия