easy.dialog

Краткое описание модуля. Страница вторая

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

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

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

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

• {:[$текст]:} - для реплик актёра.
• [:[$текст]:] - для реплик героя.

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

• текст реплики
• конструкции настроек ( npc="[$настройки]" , hero="[$настройки]" , replics="[$настройки]" )
• конструкцию условия вывода реплики ( iffing:[$условия]:iffing )
• конструкцию динамического кода, выполняемого при интерпретации реплики ( dynamic-code:[$текст]:dynamic-code )
• конструкцию блока фраз ( frase-block:[$текст]:frase-block )
• конструкцию для замены имени действия ( act-name:[$текст]:act-name )
• команды levelup:[#число] , leveljump:[$метка] , closeup , selectact.delete
• тег метки marker:[$метка]
• комментарий - один или несколько

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

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

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

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

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

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

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

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

 <!-- текст комментария <!-- текст вложенного комментария --> текст комментария -->
 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• тегов реплик {: :} и [: :]
• тегов iffing: :iffing
• тегов dynamic-code: :dynamic-code
• тегов frase-block: :frase-block

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

• тегов name: :name
• тегов act-name: :act-name
• тегов <!-- -->

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

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

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

 frase-block:

    Фраза

    frase-block:

       фраза фраза фраза

    :frase-block

    Ещё одна фраза

 :frase-block

 

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

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

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

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

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

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

 <!--ncolor:888888-->
 

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

Можно использовать запись

 <!-- ncolor:888888 -->
 

или

 <!--(nolor:888888)-->
 

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

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

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

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

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

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

 [:

    А если я захочу выбрать вариант вопроса, который исчез?

    <!-- действие которое должно удаляться после выбора selectact.delete -->

    {:

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

       мы вернёмся к общему списку вопросов. Если хочешь, ты можешь сделать это прямо сейчас.

    :}

    [:

       <!-- действие, которое должно появиться без очистки списка действий -->

       То есть, я могу спросить что-то другое?

       {:

          Да, конечно, спрашивай, что хочешь.

          <!-- leveljump:other_question -->

       :}

    :]

 :]
 

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

Чтобы пустая реплика героя всё же выводилась на экран в виде действия, название действия следует поместить между тегами 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 и работает только при наличии оного. Для использования модуля и библиотеки, оба файла подключаются к основному файлу игры:

addqst 'lib/easy.math.qsp'
addqst 'lib/easy.dialog.qsp' 

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

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

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

gosub 'dialog.int', $переменная_диалог
gosub 'dialog.int', '
   {:Короткий диалог
      [:Короткое действие:]
   :}' 

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

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